Lotus Domino

Version 7

Domino Administrator Help

G210-2213-00
Note: Before using this information and the product it supports, read the information in "Notices" at the end of this document.

First Edition (December, 2005)

This edition applies to IBM® Lotus® Domino® Administrator 7 (product number L-GHUS-5RWNHM), and to all subsequent releases
and modifications, until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 1994, 2005. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents
Chapter 1. Deploying Domino . . . . . 1 Example of output with CIO enabled: . . . . 59
Guidepost for deploying Domino . . . . . . . 1 The Domino Server Setup program . . . . . . 59
Functions of Domino servers . . . . . . . . 1 Using Domino Off-Line Services (DOLS) and
Hierarchical naming for servers and users . . . 2 Domino Web Access . . . . . . . . . . . 61
Domino domains . . . . . . . . . . . . 3 Setting up DOLS on a server . . . . . . . 61
Partitioned servers . . . . . . . . . . . 4 Setting up Domino Web Access on a server . . . 63
Certifier IDs and certificates . . . . . . . . 5 Using the Domino Server Setup program . . . . 69
Domino server services . . . . . . . . . . 7 Indic language support in the Domino Server
Table of Domino naming requirements . . . . 8 Setup program . . . . . . . . . . . . 70
Building the Domino environment . . . . . . 9 Using automatic server setup on Linux on zSeries
and on UNIX . . . . . . . . . . . . . 70
Chapter 2. Setting Up the Domino Using the Domino Server Setup program locally 72
Using the Domino Server Setup program
Network . . . . . . . . . . . . . . 11 remotely . . . . . . . . . . . . . . 72
Lotus Domino and networks. . . . . . . . . 11 Creating a server setup profile . . . . . . . 74
NRPC communication . . . . . . . . . . 11 Using a server setup profile . . . . . . . . 76
Resolving server names to network addresses in Using silent server setup . . . . . . . . . 77
NRPC . . . . . . . . . . . . . . . 12 The Certification Log . . . . . . . . . . . 80
Network security . . . . . . . . . . . . 14 Server registration . . . . . . . . . . . . 81
NRPC and Internet connection security . . . . 14 Registering a server . . . . . . . . . . 82
Using a Domino passthru server as a proxy . . 14 Optional tasks to perform after server setup . . . 84
TCP/IP security considerations . . . . . . . 16 Creating an additional organization certifier ID 84
Mapped directory links and Domino data Creating an organizational unit certifier ID . . . 85
security . . . . . . . . . . . . . . . 16 Internet Site documents . . . . . . . . . 86
Planning the TCP/IP network . . . . . . . . 17 Starting and shutting down the Domino server . . 92
The default configuration . . . . . . . . . 17 To start the server . . . . . . . . . . . 93
Advanced configurations . . . . . . . . . 17 To shut down the server . . . . . . . . . 93
Changing a server’s IP address . . . . . . . 17 Starting Domino as an application or a Windows
Moving to IPv6 . . . . . . . . . . . . 17 service . . . . . . . . . . . . . . . . 93
NRPC name-to-address resolution over TCP/IP 17 Using instant messaging in the Domino Directory 94
Ensuring DNS resolves in TCP protocols . . . 19
Changing a server’s IP address . . . . . . . 22
IPv6 and Lotus Domino . . . . . . . . . 24
Chapter 4. Setting Up Server-to-Server
Advanced Domino TCP/IP configurations . . . 30 Connections . . . . . . . . . . . . 95
Planning the NetBIOS network . . . . . . . . 33 Planning server-to-server connections . . . . . . 95
Deciding whether to use NetBIOS services . . . 34 Remote (modem) access and server topology . . 96
How to tell if NetBIOS is active on a system . . 34 How a server connects to another server . . . 97
Server name-to-address resolution over NetBIOS 34 Replication and server topology . . . . . . 98
Setting up Domino servers on the network . . . . 35 Examples of server topology . . . . . . . 100
Setting up Notes named networks . . . . . . 36 Creating a LAN connection . . . . . . . . 104
Fine-tuning network port setup on a server. . . 36 Forcing a server connection to use a specific
Server setup tasks specific to TCP/IP . . . . . 42 protocol . . . . . . . . . . . . . . 105
Server setup tasks specific to NetBIOS . . . . 51 Setting up external domain lookups . . . . . 106
Internet connections . . . . . . . . . . . 108
Chapter 3. Installing and Setting Up Direct (leased-line) connection . . . . . . . 108
Proxy connections . . . . . . . . . . . 109
Domino Servers . . . . . . . . . . . 55 Creating a server-to-server Internet connection
Server installation . . . . . . . . . . . . 55 through a proxy server . . . . . . . . . 109
Installing Domino on Windows systems . . . . 55 Passthru servers and hunt groups . . . . . . 110
Entering system commands correctly . . . . . 56 Passthru Logging . . . . . . . . . . . 110
Using silent server installation to install Domino Hunt groups. . . . . . . . . . . . . 110
on Windows systems . . . . . . . . . . 56 Planning the use of passthru servers . . . . . 110
Using Domino’s express install . . . . . . . 58 Example of a passthru server topology . . . . 111
Using silent server install on UNIX systems . . 58 Setting up a server as a passthru server . . . 112
Concurrent I/O and Direct I/O not supported on Setting up a server as a passthru destination . . 113
Domino servers on AIX . . . . . . . . . . 59 Creating a passthru connection . . . . . . 113
Example of output with CIO disabled . . . . 59

iii
 Connecting a server to a hunt group . . . . 114
Planning for modem use . . . . . . . . . 116
Installing modems . . . . . . . . . . . 116
Modems and modem command files . . . . 116
Creating a Notes Direct Dialup connection . . 117
Creating a Network Dialup connection . . . . 118
Encrypting Network Dialup Connection
documents . . . . . . . . . . . . . 120
Coordinating dialup ISP connections between
servers . . . . . . . . . . . . . . 121
Coordinating Notes Direct Dialup connections
between servers . . . . . . . . . . . 123
Configuring a communication port . . . . . 125
Modifying modem command files and acquire
scripts . . . . . . . . . . . . . . . 127
Using acquire and login scripts . . . . . . 127
Writing and editing acquire and login scripts 128
Commands for acquire and connect scripts . . 129
Connecting Notes clients to servers . . . . . . 130
Requirements for connecting Notes clients to
remote servers over various access media . . . 130
Chapter 5. Setting up Domino and
DB2 . . . . . . . . . . . . . . . 133
Understanding Domino and DB2 -- Limited
Availability . . . . . . . . . . . . . . 133
DB2 Access Views . . . . . . . . . . . 134
Query views. . . . . . . . . . . . . 135
Enabling the Domino server to communicate with
DB2 and Domino authentication . . . . . . 136
the DB2 server procedures . . . . . . . . .
Benefits of using Domino with DB2 . . . . . 136
Domino and DB2 user accounts that are needed for
Domino and DB2 . . . . . . . . . . . . 137
Accounts required with Microsoft Windows . . 137
Accounts required with AIX/UNIX . . . . . 137
Using the Domino Web Administrator client with
Domino and DB2 . . . . . . . . . . . . 137
Databases created with Domino 7 . . . . . . 138
Database storage . . . . . . . . . . . 138
Databases not supported as DB2 enabled Notes
Mapping the DB2 ID to a Notes ID in the Domino
databases . . . . . . . . . . . . . . 138
server’s Domino Directory . . . . . . . . .
Compact database options are enabled for
Domino and DB2 . . . . . . . . . . . 140
Domino and DB2 supported platforms and
configurations . . . . . . . . . . . . . 141
Supported platforms and hardware and
DB2 groups . . . . . . . . . . . . . .
software requirements . . . . . . . . . 141
Supported configurations in Domino and DB2 142
Example of a local Domino and DB2
configuration . . . . . . . . . . . . 143
Example of a remote Domino and DB2
configuration that uses separate servers . . . 143
Example of a remote Domino and DB2
configuration that uses partitions . . . . . . 144
Installation and setup procedures. . . . . . . 146
Upgrading Domino 7 and DB2 . . . . . . .
Microsoft Windows . . . . . . . . . . 146
IBM AIX . . . . . . . . . . . . . . 146
All platforms . . . . . . . . . . . . 146
Installing the DB2 Access server . . . . . . 146
Domino server enablement and mapping Notes
and DB2 user IDs . . . . . . . . . . . 147
Creating the DB2 installation account . . . . 147
Creating the DB2 administrator and
administration server account . . . . . . . 147
Installing and setting up Domino and DB2 on
Microsoft Windows - Local configuration . . . 148
Installing and setting up Domino and DB2 and
the DB2 Access server on Microsoft Windows -
Local configuration . . . . . . . . . . 149
Installing and setting up Domino and DB2 on
Microsoft Windows - Remote configuration . . 150
Installing and setting up Domino and DB2 on
IBM AIX - Local configuration . . . . . . . 150
Installing and setting up Domino and DB2 and
the DB2 Access server on Microsoft Windows -
Remote configuration . . . . . . . . . . 152
Installing and setting up Domino and DB2 on
IBM AIX - Remote configuration . . . . . . 153
Installing and setting up Domino and DB2 and
the DB2 Access server on IBM AIX -- Remote
configuration . . . . . . . . . . . . 155
Setting up DB2 on Microsoft Windows . . . . 157
Installing and setting up Domino and DB2 and
the DB2 Access server on IBM AIX -- Local
configuration . . . . . . . . . . . . 157
Installing DB2 on IBM AIX . . . . . . . . 159
IBM AIX post-installation procedure . . . . . 160
Creating a server ID for the DB2 Access server 161
Installing the DB2 Access server on the DB2
server . . . . . . . . . . . . . . . 162
164
Enabling Domino access to a DB2 server . . . 164
Enabling a Domino server to communicate with
a DB2 server . . . . . . . . . . . . 165
NOTES.INI variables set by the DB2 Server
Enablement Tool . . . . . . . . . . . 168
Configuration variables modified during DB2
server enablement . . . . . . . . . . . 169
Manually creating the Domino server user and
other accounts on Microsoft Windows . . . . 170
171
Allowing anonymous access to Notes data . . 171
Mapping DB2 user names to Notes user names 172
Using formulas to create custom patterns in
user names . . . . . . . . . . . . . 172
173
DB2 group classes . . . . . . . . . . . 174
Managing DB2 groups and classes . . . . . 174
Locking a DB2 group . . . . . . . . . . 175
Unlocking a DB2 group . . . . . . . . . 175
Renaming a DB2 class . . . . . . . . . 175
Associating a DB2 group with a class . . . . 175
Moving a DB2 enabled Notes database to
another DB2 group . . . . . . . . . . 175
176
Prerequisites if you are running Domino 7, beta
1, 2, or 3 . . . . . . . . . . . . . . 176
Procedure - Upgrading when you have created
DB2 enabled Notes databases . . . . . . . 176
Procedure - Upgrading when you have not
created any DB2 enabled Notes databases . . . 177

iv Lotus Domino Administrator 7 Help

 Upgrading from a beta release to Domino 7 and Upgrading a user name from flat to hierarchical 247
DB2 . . . . . . . . . . . . . . . 177 Moving a user name in the name hierarchy . . 248
Upgrading the DB2 Access server . . . . . 177 Renaming a Web user . . . . . . . . . 252
Converting a 32-bit instance to a 64-bit instance Moving a user’s mail file and roaming files from
on IBM AIX . . . . . . . . . . . . . 178 the Domino Administrator or the Web
Upgrading to DB2 8.2.2 if you have a previous Administrator . . . . . . . . . . . . 253
version of DB2 already installed . . . . . . 179 Opening a user’s mail file . . . . . . . . 255
Maintaining the Domino and DB2 environment 180 Finding a user name in the domain with the
Adjusting buffer pool size . . . . . . . . 180 Domino Administrator or the Web
Copying a DB2 enabled Notes database to Administrator . . . . . . . . . . . . 255
another DB2 enabled Domino server . . . . 180 Broadcasting messages to Notes client users . . 256
Domino and DB2 XA transaction services . . . 181 Recertifying a user ID . . . . . . . . . 256
Moving a DB2 database container . . . . . 182 Recertifying a certifier ID or a user ID . . . . 258
Replicating an NSF to DB2 . . . . . . . . 182 Allowing multiple users to use the same data
Setting a DB2 server ID . . . . . . . . . 182 directory . . . . . . . . . . . . . . 260
Setting and modifying DB2 values in the Server License Tracking . . . . . . . . . . . 260
document . . . . . . . . . . . . . 183 Deploying the ″My Work″ Welcome page for
Setting DB2 Log File Size . . . . . . . . 184 Notes . . . . . . . . . . . . . . . 261
Setting, modifying or deleting the Domino
server user’s DB2 ID properties . . . . . . 184 Chapter 8. Setting Up and Managing
Validating DB2 user names . . . . . . . . 185 Groups . . . . . . . . . . . . . . 263
Administering the DB2 Access server . . . . . 185
Using groups . . . . . . . . . . . . . 263
Editing the DB2 Access server Connection
Using multiple group names . . . . . . . 263
document . . . . . . . . . . . . . 186
Creating and modifying groups . . . . . . 263
Removing a DB2 Access server . . . . . . 186
Managing groups . . . . . . . . . . . 268
Testing the DB2 Access configuration . . . . 186
Working with views in Domino and DB2 . . . . 187
Using federated data with query views . . . . 187 Chapter 9. Creating Replicas and
Setting the maximum number of rows in SQL Scheduling Replication . . . . . . . 275
queries . . . . . . . . . . . . . . 188 Replicas . . . . . . . . . . . . . . . 275
Building views of large databases . . . . . 188 Deciding when to create a replica . . . . . 275
Views categorized by numeric datatypes . . . 188 How server-to-server replication works . . . . 276
Domino and DB2 XA transaction services . . . 188 Guidelines for setting server access to databases 277
Setting up a database ACL for server-to-server
Chapter 6. Setting Up Notes Users replication . . . . . . . . . . . . . 278
Creating replicas using the Administration
and Clients . . . . . . . . . . . . 189
Process . . . . . . . . . . . . . . 279
Setting up Notes users . . . . . . . . . . 189
Table of replication settings . . . . . . . . 281
User registration . . . . . . . . . . . 189
Scheduling times for replication . . . . . . 286
Setting up client installation for users . . . . 217
Scheduling server-to-server replication . . . . 288
Custom welcome page deployment . . . . . 233
Customizing server-to-server replication . . . 290
Viewing replication schedules and topology
Chapter 7. Managing Notes Users . . 237 maps . . . . . . . . . . . . . . . 294
Managing users . . . . . . . . . . . . 237 Database.nsf.replicate statistics . . . . . . 295
Rename a user . . . . . . . . . . . . 237
Change user roaming status . . . . . . . 237 Chapter 10. Setting Up Calendars and
Move or open a user’s files . . . . . . . . 237
Delete a user name . . . . . . . . . . 237
Scheduling . . . . . . . . . . . . 297
Synchronizing Windows 2000 Active Directory Calendars and scheduling . . . . . . . . . 297
and Notes users . . . . . . . . . . . 238 Using clustered Free Time databases. . . . . 297
Changing Notes user names with the Example of scheduling a meeting . . . . . . 298
Administration Process . . . . . . . . . 238 Users in the same domain . . . . . . . . 298
Renaming a Notes user’s common or alternate Users in different domains . . . . . . . . 298
name . . . . . . . . . . . . . . . 239 Users in other calendar domains . . . . . . 299
Deleting a user name with the Domino Setting up scheduling . . . . . . . . . 299
Administrator . . . . . . . . . . . . 241 Setting up the Resource Reservations database 300
Deleting a user name with the Web Rooms and Resources Manager . . . . . . 302
Administrator . . . . . . . . . . . . 242 Creating Site Profile and Resource documents 302
Changing a roaming user to nonroaming . . . 243 Editing and deleting Resource documents . . . 306
Changing a nonroaming user to roaming . . . 244 Setting user access rights to edit and delete
Changing a user’s Internet address . . . . . 247 reservations . . . . . . . . . . . . . 309
Creating Holiday documents . . . . . . . 310

Contents v
 Collecting detailed information from user
calendars . . . . . . . . . . . . . . 312
Chapter 11. Using Policies . . . . . . 313
Policies . . . . . . . . . . . . . . . 313
Organizational and explicit policies . . . . . 313
Policy hierarchy and the effective policy . . . 314
Client policy lock-down . . . . . . . . . 316
Planning and assigning policies . . . . . . 317
Using policies to assign NOTES.INI or Location
document settings to Notes client users . . . 317
Notes application plug-in and policies . . . . 318
Creating policies . . . . . . . . . . . 318
Managing policies . . . . . . . . . . . 350
Chapter 12. Setting Up Domain Search 357
Domain Search . . . . . . . . . . . . . 357
Support for multiple languages . . . . . . 357
Domain Search and single-database full-text
search . . . . . . . . . . . . . . . 357
Implementing Domain Search . . . . . . . 357
Server configurations for Domain Search . . . . 358
Configuration for the Domain Catalog . . . . 358
Configurations for the Domain Index . . . . 358
Domain Search over a WAN . . . . . . . 358
Planning the Domain Index . . . . . . . . 359
The Domain Catalog . . . . . . . . . . 359
Assigning database categories for the Domain
Search form . . . . . . . . . . . . . 363
Estimating the size of the Domain Index . . . 363
Excluding attachments from the Domain Index 364
Domain Search security . . . . . . . . . 364
Creating and updating the Domain Index . . . . 365
To set the Domain Indexer task . . . . . . 365
Tuning Domain Indexer performance . . . . 366
Changing the location of Domain Index files 367
Deleting databases from the Domain Index . . 367
Backing up the Domain Index and Catalog . . 367
Customizing Domain Search forms . . . . . . 368
Results forms -- where do the document titles
come from? . . . . . . . . . . . . . 368
Setting up Notes users for Domain Search . . . . 368
Using Policies . . . . . . . . . . . . 368
Manual setup from a Notes workstation . . . 369
Setting up Web users for Domain Search . . . . 369
Using content maps with Domain Search . . . . 369
To assign content categories . . . . . . . 370
To view content categories . . . . . . . . 370
To change content categories . . . . . . . 370
Chapter 13. Setting Up Domino
Off-Line Services . . . . . . . . . . 373
Domino Off-Line Services . . . . . . . . . 373
Configuring the DOLS subscription . . . . . . 373
To edit the configuration document . . . . . 373
Overview of DOLS administrator tasks . . . . . 379
How DOLS works . . . . . . . . . . . . 380
Creating a DOLS Offline Security Policy document 384
Increasing security for DOLS subscriptions . . . 386
vi Lotus Domino Administrator 7 Help
Increasing the server’s output timeout for DOLS
downloads . . . . . . . . . . . . . . 387
Setting up agents for the DOLS subscription . . . 387
Optional tasks for DOLS administrators . . . . 388
Adding a directory catalog to a DOLS
subscription . . . . . . . . . . . . . 388
Viewing DOLS download information . . . . 389
Reducing DOLS download time with the client
installation CD . . . . . . . . . . . . 389
Reducing DOLS download time with selective
replication . . . . . . . . . . . . . 390
Web Control instructions for DOLS users . . . 391
DOLS troubleshooting and error messages . . . 391
Error messages . . . . . . . . . . . . 391
Chapter 14. Planning the Service
Provider Environment . . . . . . . . 393
Planning the xSP server environment . . . . . 393
The Domino service provider administrator . . 393
Ways to set up a service provider environment 393
Securing the service provider environment . . 394
Using Domino features in a hosted server
environment . . . . . . . . . . . . . 394
Planning the IP Address configurations in a
hosted environment . . . . . . . . . . 395
Planning the distribution of hosted organization
data . . . . . . . . . . . . . . . 397
Deciding which protocols and services to offer
in the xSP environment . . . . . . . . . 400
Deciding which applications to offer multiple
hosted organizations . . . . . . . . . . 401
Using activity logging for billing at hosted
organizations . . . . . . . . . . . . 401
Example of planning a hosted environment . . . 402
Chapter 15. Setting Up the Service
Provider Environment . . . . . . . . 405
Setting up the service provider environment . . . 405
Installing the first server or additional servers
for hosted environments . . . . . . . . . 405
Setting up a hosted organization . . . . . . 406
Setting up the Domino certificate authority for
hosted organizations . . . . . . . . . . 406
Using policies in a hosted environment . . . . 406
What happens when you register a hosted
organization? . . . . . . . . . . . . 407
Example of registering a hosted organization 414
Using Internet and Web Site documents in a
hosted environment . . . . . . . . . . 415
Global Web Settings documents and the service
provider environment . . . . . . . . . 417
Configuring activity logging for billing hosted
organizations . . . . . . . . . . . . 418
Chapter 16. Managing a Hosted
Environment . . . . . . . . . . . . 421
Maintaining hosted organizations . . . . . . 421
Using a browser to access a hosted
organization’s Web site . . . . . . . . . 421
 Adding a hosted organization to an additional Starting and stopping the Domino Console . . 477
server to provide new Web applications . . . 422
Restoring a hosted environment after a server Chapter 19. Using Domino with
crash . . . . . . . . . . . . . . . 422 Windows Synchronization Tools . . . 479
How the Domino service provider software
Setting up Domino Active Directory
responds to a DNS outage . . . . . . . . 422
synchronization . . . . . . . . . . . . 479
Deleting a hosted organization . . . . . . 423
To set up Domino Active Directory
Temporarily disabling services for a hosted
synchronization . . . . . . . . . . . 480
organization . . . . . . . . . . . . . 423
Enabling the Notes synchronization options . . 480
Enabling anonymous access to a hosted
Specifying Notes settings . . . . . . . . 481
organization’s database . . . . . . . . . 424
Mapping Active Directory fields and groups
Preventing users from viewing ADMIN4.NSF in
with Domino Directory fields and groups . . . 483
a hosted environment . . . . . . . . . 424
Mapping Active Directory containers to Notes
Moving a hosted organization to another server 424
certifiers and policies . . . . . . . . . . 484
Removing a hosted organization from a backup
Synchronizing users and groups . . . . . . 485
or load-balancing server . . . . . . . . . 427
Registering new users in Active Directory and
Managing Users at a hosted organization . . . 428
in Domino Directory simultaneously . . . . 486
Using the Resource Reservations database in a
Renaming Active Directory and Notes users and
hosted environment . . . . . . . . . . 429
groups . . . . . . . . . . . . . . 490
Viewing hosted organizations . . . . . . . 430
Deleting Active Directory and Notes users and
groups . . . . . . . . . . . . . . 490
Chapter 17. Setting Up the Disabling Active Directory synchronization prior
Administration Process . . . . . . . 431 to uninstalling the Domino Administrator . . . 491
The Administration Process . . . . . . . . 431
Administration servers . . . . . . . . . 431 Chapter 20. Planning Directory
The Administration Requests database . . . . 432 Services . . . . . . . . . . . . . 493
The Certification Log . . . . . . . . . . 432
Overview of Domino directory services. . . . . 493
Specifying the administration server for the
Using directory servers in a Domino domain 493
Domino Directory . . . . . . . . . . . 432
Planning LDAP features . . . . . . . . . 494
Setting up the Administration Process . . . . 433
Planning directory access control . . . . . . 496
Administration Process support of secondary
Planning new entries in the Domino Directory 497
Domino Directories . . . . . . . . . . 435
Planning the management of entries in the
Processing administration requests across
Domino Directory . . . . . . . . . . . 498
domains . . . . . . . . . . . . . . 435
Planning directory services for Notes clients . . 498
Setting up ACLs for the Administration Process 438
Planning directory services in a
The Administration Requests database . . . . 441
multiple-directory environment . . . . . . 499
Managing Administration Process requests . . 448
Planning internationalized directory services 503
Customizing the Administration Process . . . 450
Planning directory customization . . . . . . 504
Adminstration Process Statistics . . . . . . 453
Directory services terms . . . . . . . . . 504
Administration request messages . . . . . . 454

Chapter 21. Setting Up the Domino

Chapter 18. Setting Up and Using
Directory . . . . . . . . . . . . . 507
Domino Administration Tools . . . . 459
The Domino Directory . . . . . . . . . . 507
The Domino Administrator . . . . . . . . . 459
Setting up the Domino Directory for a domain 507
Installing the Domino Administrator . . . . 459
Using a central directory architecture in a
Setting up the Domino Administrator . . . . 459
Domino domain . . . . . . . . . . . 508
Starting the Domino Administrator . . . . . 459
Controlling access to the Domino Directory . . 512
Navigating Domino Administrator . . . . . 460
Corporate hierarchies . . . . . . . . . . 514
Selecting a server to administer in the Domino
Setting up Notes clients to use a directory
Administrator . . . . . . . . . . . . 460
server . . . . . . . . . . . . . . . 516
Setting Domino Administration preferences . . 461
Customizing the Directory Profile . . . . . 516
Tools and preferences for debugging in the
Scheduling replication of the Domino Directory 517
Domino Administrator . . . . . . . . . 466
Domino Administrator tabs. . . . . . . . 467
Web Administrator . . . . . . . . . . . 469 Chapter 22. Setting Up the LDAP
Setting up the Web Administrator . . . . . 470 Service . . . . . . . . . . . . . . 519
Starting the Web Administrator . . . . . . 473 The LDAP Service . . . . . . . . . . . . 519
Using the Web Administrator . . . . . . . 473 LDAP service features . . . . . . . . . 519
The Server Controller and the Domino Console . . 476 How the LDAP service works . . . . . . . 519
Starting and stopping the Server Controller . . 477 Setting up the LDAP service . . . . . . . 522

Contents vii
 Starting and stopping the LDAP service . . . 523 Picking the server(s) to run the Dircat task . . 613
Customizing the LDAP service configuration 524 Specifying the Domino Directories for the Dircat
Setting up clients to use the LDAP service . . . 539 task to aggregate . . . . . . . . . . . 614
Using LDAP to search a Domain index . . . . 540 Controlling which information is aggregated
Monitoring the LDAP service . . . . . . . 541 into a directory catalog . . . . . . . . . 614
RFCs supported by the LDAP service . . . . 543 Full-text indexing directory catalogs . . . . . 619
Planning issues specific to Extended Directory
Chapter 23. Managing the LDAP Catalogs . . . . . . . . . . . . . . 620
Schema . . . . . . . . . . . . . . 545 Planning issues specific to condensed Directory
Catalogs . . . . . . . . . . . . . . 622
LDAP Schema . . . . . . . . . . . . . 545
Multiple directory catalogs . . . . . . . . 624
Attributes . . . . . . . . . . . . . 545
Overview of setting up a condensed Directory
Object classes . . . . . . . . . . . . 545
Catalog . . . . . . . . . . . . . . 625
Abstract object classes . . . . . . . . . 545
Overview of setting up an Extended Directory
Structural object classes . . . . . . . . . 545
Catalog . . . . . . . . . . . . . . 630
Auxiliary object classes . . . . . . . . . 546
The Dircat task . . . . . . . . . . . . 633
Syntaxes . . . . . . . . . . . . . . 546
Opening the configuration document for a
The Domino LDAP schema . . . . . . . . 546
directory catalog . . . . . . . . . . . 635
The schema daemon . . . . . . . . . . 548
Monitoring directory catalogs . . . . . . . 635
Domino LDAP Schema database . . . . . . 549
Methods for extending the schema . . . . . 551
Guidelines for extending the schema . . . . 552 Chapter 27. Setting Up Extended
Extending the schema using the Schema ACLs . . . . . . . . . . . . . . . 637
database . . . . . . . . . . . . . . 553 Extended ACL . . . . . . . . . . . . . 637
Deleting schema elements from the Schema How other database security features restrict
database . . . . . . . . . . . . . . 556 extended ACL access settings . . . . . . . 637
Schema-checking . . . . . . . . . . . 556 Elements of an extended ACL . . . . . . . 638
Searching the root DSE and schema entry . . . 557 Extended ACL access settings . . . . . . . 638
Extended ACL subject . . . . . . . . . 643
Chapter 24. Using the ldapsearch Extended ACL target . . . . . . . . . . 645
Utility . . . . . . . . . . . . . . . 559 Extended ACL examples. . . . . . . . . 650
Extended ACL guidelines . . . . . . . . 652
ldapsearch Utility . . . . . . . . . . . . 559
Setting up and managing an extended ACL . . 653
Table of ldapsearch parameters . . . . . . 559
Using search filters with ldapsearch . . . . . 561
Using ldapsearch to return operational Chapter 28. Overview of the Domino
attributes . . . . . . . . . . . . . . 562 Mail System . . . . . . . . . . . . 659
Examples of using ldapsearch . . . . . . . 562 Messaging overview . . . . . . . . . . . 659
Supported routing, format, and access protocols 660
Chapter 25. Setting Up Directory The Domino mail server and mail routing . . . 661
Assistance . . . . . . . . . . . . 565 How mail routes in a Domino system . . . . 663
Domino mail files . . . . . . . . . . . 664
Directory Assistance . . . . . . . . . . . 565
Mail clients . . . . . . . . . . . . . 665
How directory assistance works . . . . . . 565
Mail security . . . . . . . . . . . . 666
Directory assistance services . . . . . . . 566
Working with other mail systems in your
Directory assistance concepts . . . . . . . 572
organization . . . . . . . . . . . . . 667
Setting up directory assistance . . . . . . . 582
Mail performance and monitoring . . . . . 667
Directory assistance examples . . . . . . . 599
The Domino Directory and mail routing . . . 667
Monitoring directory assistance . . . . . . 603
Overview of routing mail using Notes routing 669
Overview of routing mail using SMTP . . . . 671
Chapter 26. Setting Up Directory The Domain Name System (DNS) and SMTP
Catalogs . . . . . . . . . . . . . 605 mail routing . . . . . . . . . . . . . 674
Directory Catalogs . . . . . . . . . . . . 605 Examples of using multiple MX records . . . 675
Condensed Directory Catalogs. . . . . . . 605
Directory catalogs on servers compared to Chapter 29. Setting Up Mail Routing 677
directory assistance for individual Domino Planning a mail routing topology . . . . . . . 677
Directories . . . . . . . . . . . . . 607 Connection topologies for mail routing . . . . 677
Extended Directory Catalogs . . . . . . . 607 The Domino mail router . . . . . . . . . 678
Overview of directory catalog setup . . . . . 609 Clients accessing the Domino server . . . . . 680
Planning directory catalogs . . . . . . . . 610 Sample mail routing configurations . . . . . 680
Directory catalogs and client authentication . . 610 Creating a Configuration Settings document . . 688
Directory catalogs and Notes mail encryption 613 Routing internal mail . . . . . . . . . . 689

viii Lotus Domino Administrator 7 Help

 Configuring Domino to send and receive mail Integration with DOLS and Sametime . . . . 867
over SMTP . . . . . . . . . . . . . 702 Registering Domino Web Access users . . . . 868
Providing a log-on URL for Domino Web Access
Chapter 30. Customizing the Domino users . . . . . . . . . . . . . . . 868
Mail System . . . . . . . . . . . . 721 Secure mail for Domino Web Access . . . . . 869
Using realm documents in Domino Web Access 870
Customizing mail . . . . . . . . . . . . 721
Renaming a Domino Web Access user . . . . 870
Requirements for a working mail system . . . 721
Monitoring Domino Web Access activity . . . 870
Controlling messaging . . . . . . . . . 721
Customizing the look of Domino Web Access 871
Improving mail performance . . . . . . . 722
Using Domino Web Access agents . . . . . 872
Controlling message delivery . . . . . . . 725
Configuring Domino Web Access for users . . 872
Setting server mail rules . . . . . . . . . 733
Domino Access for Microsoft Outlook . . . . . 884
Customizing message transfer . . . . . . . 737
Setting up users for installation . . . . . . 885
Customizing Notes routing . . . . . . . . 751
Upgrading Domino Access for Microsoft
Customizing SMTP Routing . . . . . . . 755
Outlook from 6.5.x to 7.0 . . . . . . . . 886
Setting up and using message disclaimers . . . 789
Installing Domino Access for Microsoft Outlook 886
Mail journaling . . . . . . . . . . . . 792
Working with Domino Access for Microsoft
Setting inbound and outbound MIME and
Outlook . . . . . . . . . . . . . . 890
character set options . . . . . . . . . . 798

Chapter 31. Setting Up Shared Mail 817 Chapter 35. Monitoring Mail . . . . . 891
Tools for mail monitoring . . . . . . . . . 891
Shared mail overview . . . . . . . . . . 817
Tracking mail messages . . . . . . . . . 891
Using multiple active shared mail databases . . 818
How mail tracking works . . . . . . . . 891
How using shared mail affects a user’s mail file
Generating mail usage reports . . . . . . . 892
quota . . . . . . . . . . . . . . . 818
Mail routing event generators . . . . . . . 892
How Domino maintains the security of a shared
Setting up mail monitoring . . . . . . . . 892
mail database . . . . . . . . . . . . 819
Setting up the Reports database . . . . . . 892
How shared mail works . . . . . . . . . 819
Controlling the Mail Tracking Collector . . . . 893
Setting up shared mail databases . . . . . . 819
Configuring the server for message tracking . . 895
Managing a shared mail database . . . . . 822
Tracking a mail message . . . . . . . . . 896
Disabling shared mail . . . . . . . . . 831
Generating a mail usage report . . . . . . 898
Viewing mail usage reports . . . . . . . . 900
Chapter 32. Setting Up the POP3
Service . . . . . . . . . . . . . . 833 Chapter 36. Setting Up the Domino
The POP3 service . . . . . . . . . . . . 833
Web Server . . . . . . . . . . . . 903
Supporting outbound mail service for POP3
The Domino Web server . . . . . . . . . . 903
clients . . . . . . . . . . . . . . . 833
Web server features . . . . . . . . . . 904
Authenticating with the server . . . . . . 833
Making Web site content changes. . . . . . 904
Accessing a mail file from the Notes client and
Setting up a Domino server as a Web server . . 905
a POP3 client . . . . . . . . . . . . 834
Hosting Web sites . . . . . . . . . . . 914
Setting up the POP3 service . . . . . . . 834
Custom Web server messages . . . . . . . 934
Setting up POP3 users . . . . . . . . . 836
Improving Web server performance . . . . . 937

Chapter 33. Setting Up the IMAP

Chapter 37. Setting Up Domino to
Service . . . . . . . . . . . . . . 841
Work with Other Web Servers . . . . 941
The IMAP service . . . . . . . . . . . . 841
Setting up Domino to work with other Web servers 941
Supporting outbound mail service for IMAP
Setting up Domino to work with IBM HTTP
clients . . . . . . . . . . . . . . . 841
Servers . . . . . . . . . . . . . . 941
Authenticating with the server . . . . . . 841
Setting up Domino to work with Microsoft IIS
How Domino modifies mail files to support
servers . . . . . . . . . . . . . . 942
IMAP . . . . . . . . . . . . . . . 842
Setting up the IMAP service . . . . . . . 843
Starting and stopping the IMAP task . . . . 843 Chapter 38. Setting Up the Web
Customizing the IMAP service . . . . . . 843 Navigator . . . . . . . . . . . . . 949
Setting up IMAP users . . . . . . . . . 855 The Web Navigator . . . . . . . . . . . 949
Setting up a Web Navigator server . . . . . 949
Chapter 34. Setting Up Domino Web Customizing the Web Navigator . . . . . . 952
Access . . . . . . . . . . . . . . 867 The Web Navigator database . . . . . . . 954
Customizing the Web Navigator database . . . 955
Domino Web Access . . . . . . . . . . . 867
Security . . . . . . . . . . . . . . 867

Contents ix
Chapter 39. Planning Security . . . . 963 Roles in the ACL . . . . . . . . . . . 1038
Overview of Domino security . . . . . . . . 963 Managing database ACLs . . . . . . . . 1040
Know the business . . . . . . . . . . 963 Using the Administration Process to update
Identify assets and threats (risk analysis) . . . 963 ACLs . . . . . . . . . . . . . . . 1040
Develop strategies to protect your computing Setting up the Administration Process for
environment . . . . . . . . . . . . . 964 database ACLs . . . . . . . . . . . 1041
Develop incident handling procedures . . . . 964 Managing database ACLs with the Web
Plan and deliver employee training . . . . . 965 Administrator . . . . . . . . . . . . 1041
Keep processes current . . . . . . . . . 965 Editing entries in multiple ACLs . . . . . 1041
The Domino security model . . . . . . . 965 Viewing all database ACLs on a server . . . 1042
The Domino security team . . . . . . . . 967 Using the ACL log . . . . . . . . . . 1043
Security planning checklists . . . . . . . 969 Enforcing a consistent access control list . . . 1043
Security policies . . . . . . . . . . . 973 Updating Readers and Authors fields . . . . 1044
Setting up an Internet certificate authority . . . 973 Setting up database access for Internet users 1044
Preventing users from accessing forms and
Chapter 40. Controlling Access to views in a Web application . . . . . . . 1044
Maximum Internet name-and-password access 1045
Domino Servers . . . . . . . . . . 977 Requiring an SSL connection to a database 1046
Server access for Notes users, Internet users, and
Domino servers . . . . . . . . . . . . 977
Types of server access controls . . . . . . 977
Chapter 43. Protecting User
Server access list . . . . . . . . . . . 977 Workstations with Execution Control
Deny access list . . . . . . . . . . . 977 Lists . . . . . . . . . . . . . . . 1047
Notes ID lock out . . . . . . . . . . . 977 The execution control list . . . . . . . . . 1047
Anonymous access . . . . . . . . . . 978 The workstation ECL . . . . . . . . . 1047
Network port access . . . . . . . . . . 978 How the workstation ECL works . . . . . 1047
Setting up Notes user, Domino server, and Determining effective access . . . . . . . 1048
Internet user access to a Domino server . . . 978 ECL security access options . . . . . . . 1048
Customizing access to a Domino server . . . 979 The administration ECL . . . . . . . . 1050
Validation and authentication for Notes and Deploying and updating workstation ECLs 1055
Domino . . . . . . . . . . . . . . 993
Chapter 44. Setting Up
Chapter 41. Protecting and Managing Name-and-Password and
Notes IDs . . . . . . . . . . . . . 995 Anonymous Access to Domino
Domino server and Notes user IDs . . . . . . 995 Servers . . . . . . . . . . . . . 1057
Certificates . . . . . . . . . . . . . 995 Name-and-password authentication for
Password-protection for Notes and Domino IDs 997 Internet/intranet clients . . . . . . . . . 1057
The password quality scale . . . . . . . . 999 Name-and-password authentication over
Verifying user passwords during authentication 1000 non-SSL secured connections . . . . . . . 1058
Setting up password verification . . . . . 1002 Name-and-password authentication over SSL 1058
Using 128-bit ID file encryption . . . . . . 1003 Customizing name-and-password
Assigning multiple passwords to server and authentication . . . . . . . . . . . . 1058
certifier IDs . . . . . . . . . . . . 1003 Setting up basic name-and-password
ID recovery . . . . . . . . . . . . 1004 authentication . . . . . . . . . . . . 1058
Public key security . . . . . . . . . . 1010 Session-based name-and-password
User and server key rollover . . . . . . . 1014 authentication for Web clients . . . . . . 1060
Using cross-certificates to access servers and Controlling the level of authentication for
send secure S/MIME messages . . . . . . 1016 Internet clients . . . . . . . . . . . 1065
Adding cross-certificates to the Domino Managing Internet passwords . . . . . . 1068
Directory or Personal Address Book . . . . 1017 Multi-server session-based name-and-password
authentication for Web users (single sign-on) . 1069
Chapter 42. Controlling User Access Anonymous Internet/intranet access . . . . 1077
to Domino Databases . . . . . . . 1025 Validation and authentication for
The database access control list . . . . . . . 1025 Internet/intranet clients . . . . . . . . 1079
Default ACL entries . . . . . . . . . . 1025
Acceptable entries in the ACL . . . . . . 1026 Chapter 45. Encryption and
Configuring a database ACL . . . . . . . 1032 Electronic Signatures . . . . . . . 1081
Access levels in the ACL . . . . . . . . 1033 Encryption . . . . . . . . . . . . . . 1081
Access level privileges in the ACL . . . . . 1035 Public and private keys . . . . . . . . 1081
User types in the ACL . . . . . . . . . 1038 Encryption strength . . . . . . . . . . 1082

x Lotus Domino Administrator 7 Help

 Interoperability issues . . . . . . . . . 1082 Securing messages with S/MIME . . . . . 1123
Mail encryption . . . . . . . . . . . 1083 Setting up Notes and Internet clients for SSL
Electronic signatures . . . . . . . . . 1085 authentication . . . . . . . . . . . . 1124
Internet certificates for SSL and S/MIME . . . 1125
Chapter 46. Setting Up a Domino Setting up Notes clients for S/MIME . . . . 1130
Server-Based Certification Authority . 1089 Setting up Notes and Internet clients for SSL
client authentication . . . . . . . . . . 1133
Domino server-based certification authority . . . 1089
Setting up SSL for Notes or Domino using
Issued Certificate List (ICL) . . . . . . . 1089
SMTP . . . . . . . . . . . . . . 1135
Certificate Revocation List (CRL) . . . . . 1090
Using SSL when setting up directory assistance
Setting up a server-based Domino certification
for LDAP directories . . . . . . . . . 1136
authority . . . . . . . . . . . . . 1090
Administering a Domino CA . . . . . . . 1091
Migrating a certifier to the CA process . . . 1092 Chapter 49. Rolling Out Databases 1137
Adding a certifier to the CA process . . . . 1093 Database design, management, and administration 1137
Viewing certifiers running under the CA Creating a database . . . . . . . . . . 1137
process . . . . . . . . . . . . . . 1093 Rolling out a database . . . . . . . . . 1138
Creating a certifier for a server-based CA . . . 1094 Copying a new database to a server . . . . 1140
To create a Notes certifier . . . . . . . . 1094 Creating a Mail-In Database document for a
To create an Internet certifier . . . . . . . 1094 new database . . . . . . . . . . . . 1141
Key usage extensions and extended key usage 1096 Signing a database or template . . . . . . 1142
Creating the Certificate Requests database . . . 1098
Setting up SSL on a server-based CA server . . . 1099 Chapter 50. Organizing Databases on
To set up SSL on a server-based CA server 1100 a Server . . . . . . . . . . . . . 1145
Signing server certificates using the Certificate Organizing databases on a server . . . . . . 1145
Requests database . . . . . . . . . . . 1101 Directory links . . . . . . . . . . . 1145
To sign a server certificate request . . . . . 1101 Database links . . . . . . . . . . . . 1145
Modifying a server-based CA . . . . . . . 1102 Creating directory folders . . . . . . . . 1145
To modify a certifier through the ICL . . . . 1102 Creating directory and database links . . . . 1146
To modify a certifier through the Certifier Restricting access to a server’s data directory 1147
document . . . . . . . . . . . . . 1103
Viewing certificate requests . . . . . . . . 1103
Chapter 51. Setting Up and Managing
Revoking a certificate . . . . . . . . . . 1103
To revoke a certificate . . . . . . . . . 1103 Full-text Indexes . . . . . . . . . 1149
Backing up and recovering a certifier . . . . . 1104 Full-text indexes for single databases . . . . . 1149
To back up a certifier . . . . . . . . . 1104 Database indexes and replication . . . . . 1149
To recover a certifier. . . . . . . . . . 1104 Database indexes and the Domain Index . . . 1149
Disabling a certifier . . . . . . . . . . . 1104 Security and full-text indexes for single
Processing client certificate requests from IBM databases . . . . . . . . . . . . . 1149
Workplace users . . . . . . . . . . . . 1105 Restricted field names in full-text indexing 1150
Creating and updating full-text indexes for
single databases . . . . . . . . . . . 1150
Chapter 47. Setting Up SSL on a
Changing update frequency for a database’s
Domino Server . . . . . . . . . . 1107 full-text index . . . . . . . . . . . . 1152
SSL security . . . . . . . . . . . . . 1107 Manually updating full-text indexes for single
Internet protocols supported by Domino and databases . . . . . . . . . . . . . 1152
SSL . . . . . . . . . . . . . . . 1107 Deleting full-text indexes for single databases 1153
Setting up SSL on a Domino server . . . . . 1107
Setting up database access for SSL clients . . . 1118
Chapter 52. Setting Up Database
Managing server certificates and certificate
requests . . . . . . . . . . . . . . 1118 Libraries and Catalogs . . . . . . . 1155
Creating a self-certified certificate to test SSL Database libraries . . . . . . . . . . . 1155
certification . . . . . . . . . . . . . 1120 Server libraries . . . . . . . . . . . 1155
Modifying SSL cipher restrictions . . . . . 1120 Local libraries . . . . . . . . . . . . 1155
Authenticating Web SSL clients in secondary Creating a database library and assigning
Domino and LDAP directories . . . . . . 1121 librarians . . . . . . . . . . . . . 1155
SSL session resumption . . . . . . . . . 1122 Publishing databases in a library . . . . . 1156
Database catalogs . . . . . . . . . . . 1157
Uses for a server’s database catalog . . . . 1157
Chapter 48. Setting Up Clients for
Administering a server’s database catalog . . 1157
S/MIME and SSL . . . . . . . . . 1123 Setting up a server’s database catalog . . . . 1157
SSL and S/MIME for clients . . . . . . . . 1123
Authenticating clients and servers using SSL 1123

Contents xi
Chapter 53. Monitoring the Domino
Server . . . . . . . . . . . . . . 1159
Monitoring the Domino system . . . . . . . 1159
Monitoring Configuration database . . . . . 1159
Monitoring server shutdown . . . . . . . 1160
Monitoring processes running in the Domino
server environment . . . . . . . . . . 1160
Monitoring events on the Domino system . . 1161
Event generators . . . . . . . . . . . 1161
Event handlers . . . . . . . . . . . 1169
Viewing an event report . . . . . . . . 1175
Viewing event messages, causes, and solutions 1175
Customizing the appearance of the Domino
server console and Domino Administrator
console . . . . . . . . . . . . . . 1175
Statistics and the Domino system . . . . . 1177
Platform statistics . . . . . . . . . . 1179
Using the Domino Administrator to monitor
statistics . . . . . . . . . . . . . . 1182
Using mail-in statistics . . . . . . . . . 1185
Charting statistics . . . . . . . . . . 1185
Chapter 54. Using the Domino SNMP
agent . . . . . . . . . . . . . . 1189
The Domino SNMP Agent . . . . . . . . . 1189
The Domino SNMP Agent’s main functions 1189
Out-of-band server status through the MIB 1189
Control of a Domino server through SNMP 1189
Real-time alerts on server status . . . . . 1190
Forwarding of Domino events as SNMP traps 1190
Domino statistics through the MIB . . . . 1192
SNMP security . . . . . . . . . . . 1192
Domino SNMP Agent architecture . . . . . . 1192
About the Domino MIB . . . . . . . . . 1193
System requirements . . . . . . . . . . 1193
Microsoft Windows requirements . . . . . 1194
IBM AIX requirements . . . . . . . . . 1194
Linux requirements . . . . . . . . . . 1194
Solaris requirements . . . . . . . . . . 1194
z/OS requirements . . . . . . . . . . 1194
Configuring the Domino SNMP Agent . . . . 1194
Special considerations for partitioned servers 1194
Configuring the Domino SNMP Agent for
Microsoft Windows . . . . . . . . . . 1196
Configuring the Domino SNMP Agent for AIX 1196
Configuring the Domino SNMP Agent for
Linux . . . . . . . . . . . . . . . 1197
Configuring the Domino SNMP Agent for
Solaris . . . . . . . . . . . . . . 1198
Configuring the Domino SNMP Agent for
z/OS . . . . . . . . . . . . . . . 1199
Completing the configuration of the Domino
SNMP Agent . . . . . . . . . . . . 1201
Manually starting and stopping the Domino
SNMP Agent . . . . . . . . . . . . 1203
Using NET-SNMP with the Domino SNMP
Agent . . . . . . . . . . . . . . 1203
Using the Domino MIB with your SNMP
management station . . . . . . . . . . . 1205
Configuring traps for HP OpenView . . . . 1205
xii Lotus Domino Administrator 7 Help
Configuring traps for Domino events . . . . 1205
Configuring traps for NetView for AIX . . . 1206
Troubleshooting the Domino SNMP Agent . . . 1207
Check Server Tasks . . . . . . . . . . 1207
Check MIB Values using the SNMP
Management Station . . . . . . . . . 1207
Chapter 55. Using Server Health
Monitoring . . . . . . . . . . . . 1209
Server Health Monitor . . . . . . . . . . 1209
Table of Server Health Monitor statistics . . . 1210
Table of Server Health Monitor ratings . . . 1211
Using the Server Health Monitor . . . . . 1212
Server Health reports . . . . . . . . . 1214
Working with Server Health Monitor statistics 1215
Viewing server health with the Server Health
Monitor . . . . . . . . . . . . . . 1216
Chapter 56. Monitoring Domino
Domains . . . . . . . . . . . . . 1219
Domino Domain Monitoring (DDM) . . . . . 1219
Domino domain monitoring . . . . . . . 1219
DDM probes . . . . . . . . . . . . 1220
Maintaining DDM Probes . . . . . . . . 1242
DDM server collection hierarchy . . . . . 1243
Managing the DDM server collection hierarchy 1245
Domino Domain Monitor database (DDM.NSF) 1247
Viewing events in the Domino Domain
Monitor database . . . . . . . . . . . 1248
Maintaining the Domino Domain Monitor
database. . . . . . . . . . . . . . 1249
Using IBM Lotus instant messaging in the
Domino domain monitor database . . . . . 1252
Filtering events in DDM . . . . . . . . 1253
Chapter 57. Transaction Logging and
Recovery . . . . . . . . . . . . . 1255
Transaction logging . . . . . . . . . . . 1255
Understanding the database instance ID
(DBIID) . . . . . . . . . . . . . . 1256
How transaction logging works . . . . . . 1256
Planning for transaction logging . . . . . . 1257
Setting up a Domino server for transaction
logging . . . . . . . . . . . . . . 1257
Changing transaction logging settings . . . . 1259
Disabling transaction logging for a specific
database. . . . . . . . . . . . . . 1259
View logging . . . . . . . . . . . . 1260
Using transaction logging for recovery . . . 1260
Fault recovery . . . . . . . . . . . . . 1261
Operating systems and fault recovery . . . . 1261
Enabling fault recovery . . . . . . . . . 1261
Specifying a cleanup script for fault recovery 1261
Setting up a Fault Reports database . . . . . 1262
Creating a Fault Reports database . . . . . 1262
Collecting diagnostic information after a server or
client crash . . . . . . . . . . . . . . 1263
Writing status bar history to a log file . . . . 1264
Setting up automatic diagnostic data collection
on clients . . . . . . . . . . . . . 1264
 Setting up automatic diagnostic data collection Recertifying a server ID . . . . . . . . . 1326
on the server . . . . . . . . . . . . 1264 Uninstalling a Domino partitioned server . . . 1327
Enabling the Fault Analyzer task on the server 1265 To remove all Domino partitions on a
Using the IBM_TECHNICAL_SUPPORT directory 1266 computer . . . . . . . . . . . . . 1327
To remove one Domino partition . . . . . 1327
Chapter 58. Using Log Files . . . . 1269 Upgrading a server name to hierarchical . . . . 1327
The Domino server log (LOG.NSF) . . . . . . 1269
Controlling the size of the log file (LOG.NSF) 1269 Chapter 62. Using Activity Trends 1329
Viewing the log file (LOG.NSF) . . . . . . 1270 Activity Trends . . . . . . . . . . . . 1329
Searching the log file (LOG.NSF) . . . . . 1271 Setting up Activity Trends . . . . . . . . 1330
The Domino Web server log (DOMLOG.NSF) 1273 Understanding how Activity Trends collects
Setting up the Domino Web server log data . . . . . . . . . . . . . . . 1331
(DOMLOG.NSF) . . . . . . . . . . . 1273 Activity Trends server and statistics profiles 1332
Viewing the Domino Web server log Resource balancing in Activity Trends . . . . 1335
(DOMLOG.NSF) . . . . . . . . . . . 1274 Primary and secondary goals for resource
Logging Domino Web server requests . . . . 1274 balancing . . . . . . . . . . . . . 1337
Domino Web server logging to text files . . . 1274 Understanding resource-balancing behavior 1340
Analyzing resource-balancing distributions 1342
Chapter 59. Setting Up Activity Creating a proposal for balanced resources 1342
Logging . . . . . . . . . . . . . 1279 Evaluating server activity for resource
balancing . . . . . . . . . . . . . 1343
Activity Logging . . . . . . . . . . . . 1279
Understanding current and projected profile
The information in the log file . . . . . . 1279
charts . . . . . . . . . . . . . . 1344
Configuring activity logging . . . . . . . 1286
Using resource balancing in Activity Trends to
Viewing activity logging data . . . . . . 1287
decommission a server . . . . . . . . . 1346
Submitting a resource-balancing plan to the
Chapter 60. Maintaining Databases 1289 Domino Change Manager . . . . . . . . 1348
Database maintenance . . . . . . . . . . 1289 Domino Change Manager . . . . . . . . 1349
The Files tab in the Domino Administrator 1289 Using the Tell ChangeMan command at the
Monitoring replication of a database . . . . 1292 Domino console . . . . . . . . . . . 1350
Monitoring database activity . . . . . . . 1295 ACLs for the Domino Change Control database 1351
Replicating unread marks . . . . . . . . 1297 Default ACL settings for the Domino Change
Updating database indexes and views . . . . 1298 Control database . . . . . . . . . . . 1351
Synchronizing databases with master templates 1306 Setting ACLs for mail database moves during
Fixing corrupted databases . . . . . . . 1307 resource balancing . . . . . . . . . . 1352
Moving databases . . . . . . . . . . 1312 Resource-balancing plans . . . . . . . . 1352
Converting non-mail databases . . . . . . 1314 Database move sequences . . . . . . . . 1353
Deleting databases . . . . . . . . . . 1314 Setting up plan documents for resource
Database analysis . . . . . . . . . . 1315 balancing . . . . . . . . . . . . . 1357
Running a database analysis . . . . . . . 1317 Working with Domino Change Manager
constraints . . . . . . . . . . . . . 1358
Chapter 61. Maintaining Domino
Servers . . . . . . . . . . . . . 1319 Chapter 63. Improving Server
Changing the server administrator . . . . . . 1319 Performance . . . . . . . . . . . 1361
Setting and managing passwords for the server Improving Domino server performance . . . . 1361
console . . . . . . . . . . . . . . . 1320 Tools for measuring server performance . . . 1361
Setting a new server console password . . . 1320 Improving basic server performance and
Changing an existing server console password 1320 capacity . . . . . . . . . . . . . . 1362
Removing a server console password . . . . 1320 Improving partitioned server performance and
Decommissioning a Domain Search server . . . 1320 capacity . . . . . . . . . . . . . . 1364
To decommission a Domain Search server . . 1320 Improving Agent Manager performance . . . 1364
Decommissioning a server. . . . . . . . . 1321 Improving server performance using the
Before decommissioning a server . . . . . 1321 configuration collector . . . . . . . . . 1366
To run an analysis report on Decommission Improving database and Domino Directory
Server . . . . . . . . . . . . . . 1321 performance . . . . . . . . . . . . 1366
Viewing the report in the Results database 1322 Tips for tuning mail performance . . . . . 1367
Report comparisons . . . . . . . . . . 1324 Improving Windows 2000 server performance 1369
Deleting a server name . . . . . . . . . . 1325 Improving UNIX server performance . . . . 1369
Finding a server name in the domain with the Sources for improving server performance 1370
Domino Administrator or the Web Administrator . 1325
To view the log of locations . . . . . . . 1326

Contents xiii
Chapter 64. Improving Database Show Configuration . . . . . . . . . . 1524
Performance . . . . . . . . . . . 1371 Show Directory . . . . . . . . . . . 1525
Setting advanced database properties . . . . . 1371 Show Diskspace . . . . . . . . . . . 1526
Database properties that optimize database Show Heartbeat . . . . . . . . . . . 1526
performance . . . . . . . . . . . . 1371 Show Memory . . . . . . . . . . . 1526
Soft deletions . . . . . . . . . . . . 1376 Show Monitors . . . . . . . . . . . 1527
The database cache . . . . . . . . . . 1376 Show Opendatabases . . . . . . . . . 1527
Tools for monitoring database size . . . . . 1379 Show Performance . . . . . . . . . . 1527
Monitoring database size . . . . . . . . 1379 Show Port . . . . . . . . . . . . . 1527
Compacting databases . . . . . . . . . 1379 Show Schedule . . . . . . . . . . . 1528
Determining the file format of a database . . 1381 Show SCOS . . . . . . . . . . . . 1528
Compact options . . . . . . . . . . . 1382 Show Server . . . . . . . . . . . . 1529
Database size quotas . . . . . . . . . 1386 Show Stat . . . . . . . . . . . . . 1530
Deleting inactive documents . . . . . . . 1387 Show Stat Platform . . . . . . . . . . 1530
Allowing more fields in a database . . . . . 1389 Show Tasks. . . . . . . . . . . . . 1531
Show Transactions . . . . . . . . . . 1531
Show Users . . . . . . . . . . . . 1532
Chapter 65. Using Server.Load . . . 1391 Show Xdir . . . . . . . . . . . . . 1533
Server.Load . . . . . . . . . . . . . 1391 Start Consolelog . . . . . . . . . . . 1534
Server.Load agents . . . . . . . . . . 1391 Start Port . . . . . . . . . . . . . 1535
Server.Load metrics and messaging statistics 1392 Stop Consolelog . . . . . . . . . . . 1535
Setting up clients and servers for Server.Load 1395 Stop Port . . . . . . . . . . . . . 1535
Built-in and custom Server.Load scripts . . . 1396 Sucache refresh . . . . . . . . . . . 1535
Running the built-in Server.Load workloads 1401 Sucache show . . . . . . . . . . . . 1536
Tell . . . . . . . . . . . . . . . 1536
Chapter 66. Troubleshooting . . . . 1431 Administration Process Tell Commands . . . 1537
Troubleshooting . . . . . . . . . . . . 1431 Agent Manager Tell commands . . . . . . 1538
Troubleshooting tools . . . . . . . . . 1431 Certificate Authority process tell commands 1539
Troubleshooting the Domino system . . . . 1433 Change Manager tell commands . . . . . 1540
Overview of server maintenance . . . . . 1508 Cluster Replicator Tell commands . . . . . 1540
DIIOP Tell commands . . . . . . . . . 1541
Appendix A Server Directory Cataloger Tell commands . . . . 1542
Commands . . . . . . . . . . . . 1511 LDAP Tell commands . . . . . . . . . 1542
Domino server commands . . . . . . . . . 1511 Router Tell commands . . . . . . . . . 1542
Broadcast . . . . . . . . . . . . . 1512 Schedule Manager Tell commands . . . . . 1543
Dbcache Disable . . . . . . . . . . . 1513 SMTP Server Tell commands . . . . . . . 1544
Dbcache Flush. . . . . . . . . . . . 1513 Statistic Collector Tell Commands . . . . . 1544
Dbcache Show . . . . . . . . . . . 1514 Web Navigator Tell commands . . . . . . 1544
Drop . . . . . . . . . . . . . . . 1514 Web Server Tell commands . . . . . . . 1544
Exit . . . . . . . . . . . . . . . 1514 Trace . . . . . . . . . . . . . . . 1545
Help . . . . . . . . . . . . . . . 1514 Domino and DB2 server commands . . . . . 1546
Load . . . . . . . . . . . . . . . 1515 DB2 Access . . . . . . . . . . . . . 1546
Platform . . . . . . . . . . . . . . 1515 DB2 Catalog . . . . . . . . . . . . 1547
Pull . . . . . . . . . . . . . . . 1516 DB2 Group . . . . . . . . . . . . . 1547
Push . . . . . . . . . . . . . . . 1517 DB2 Group Info . . . . . . . . . . . 1548
Quit . . . . . . . . . . . . . . . 1518 DB2 Info . . . . . . . . . . . . . 1549
Replicate . . . . . . . . . . . . . 1518 DB2 Purge . . . . . . . . . . . . . 1550
Restart Port . . . . . . . . . . . . 1519 DB2 Reconnect . . . . . . . . . . . 1551
Restart Server . . . . . . . . . . . . 1520 Using a console to send commands to a server 1551
Restart Task . . . . . . . . . . . . 1520 Capturing server command output in a file 1551
Route . . . . . . . . . . . . . . 1520 Entering commands at the console at the server 1551
Save . . . . . . . . . . . . . . . 1521 Sending Controller and shell commands from a
Set Configuration . . . . . . . . . . 1521 remote console . . . . . . . . . . . . 1552
Set Rules . . . . . . . . . . . . . 1521 Sending commands from the Domino
Set SCOS . . . . . . . . . . . . . 1522 Administrator console . . . . . . . . . . 1553
Set Secure . . . . . . . . . . . . . 1522 Adding commands to the Commands menu 1555
Set Statistics . . . . . . . . . . . . 1523 Adding a group of servers to the Send menu 1555
Show Agents . . . . . . . . . . . . 1523 Sending commands from a Web Administrator
Show AI. . . . . . . . . . . . . . 1523 console . . . . . . . . . . . . . . . 1555
Show Allports . . . . . . . . . . . . 1523 Using the Domino Character Console to access
Show Cluster . . . . . . . . . . . . 1524 the server console . . . . . . . . . . . 1556

xiv Lotus Domino Administrator 7 Help

 To start the cconsole program . . . . . . 1556 DB2DBCodepage . . . . . . . . . . . 1577
Remote cconsole . . . . . . . . . . . 1556 DB2_DBS_Per_Schema . . . . . . . . . 1577
Additional console commands . . . . . . 1556 DB2Directory . . . . . . . . . . . . 1577
Command line switches . . . . . . . . 1556 DB2Init . . . . . . . . . . . . . . 1578
DB2Instance . . . . . . . . . . . . 1578
Appendix B Server Tasks 1559 DB2QueryViewRowLimit . . . . . . . . 1578
Domino server tasks . . . . . . . . . . 1559 DB2UDFPath . . . . . . . . . . . . 1579
Running server tasks . . . . . . . . . 1561 DB2UDFServer . . . . . . . . . . . 1579
DB_Creation_Default_Type . . . . . . . 1579
DB2_DBS_PER_SCHEMA . . . . . . . . 1579
Appendix C NOTES.INI
DDE_Timeout . . . . . . . . . . . . 1580
Settings . . . . . . . . . . . . . 1563 DDM_SecProbe_PersonDoc_Limit . . . . . 1580
Editing the NOTES.INI file . . . . . . . . 1563 Debug_Outfile. . . . . . . . . . . . 1580
To edit the NOTES.INI file using a Debug_Roaming . . . . . . . . . . . 1581
Configuration Settings document . . . . . 1563 Debug_Smart_Upgrade . . . . . . . . . 1581
Assigning Notes.INI settings through user policies 1563 Debug_SSL_Cert . . . . . . . . . . . 1581
NOTES.INI Settings . . . . . . . . . . . 1563 DEBUG_SSO_TRACE_LEVEL . . . . . . 1581
Admin . . . . . . . . . . . . . . 1564 Debug_ThreadID . . . . . . . . . . . 1582
AgentThreadDebug . . . . . . . . . . 1564 Debug_Fault_Analyzer . . . . . . . . . 1582
Allow_Access . . . . . . . . . . . . 1564 Default_Index_Lifetime_Days . . . . . . 1582
Allow_Access_portname. . . . . . . . . 1564 Deny_Access . . . . . . . . . . . . 1583
Allow_Anonymous_Access_From_DB2 . . . 1565 Deny_Access_portname . . . . . . . . . 1583
Allow_Passthru_Access. . . . . . . . . 1565 Desktop . . . . . . . . . . . . . . 1583
Allow_Passthru_Callers . . . . . . . . 1566 DIIOPConfigUpdateInterval . . . . . . . 1584
Allow_Passthru_Clients . . . . . . . . 1566 DIIOPCookieCheckAddress . . . . . . . 1584
Allow_Passthru_Targets . . . . . . . . 1566 DIIOPCookieTimeout . . . . . . . . . 1584
AMgr_DisableMailLookup . . . . . . . 1566 DIIOP_Debug_Invoke . . . . . . . . . 1585
AMgr_DocUpdateAgentMinInterval . . . . 1567 DIIOP_DUP_KEYRING . . . . . . . . 1585
AMgr_DocUpdateEventDelay . . . . . . 1567 DIIOPDNSLookup . . . . . . . . . . 1586
AMgr_NewMailAgentMinInterval . . . . . 1567 DIIOPIgnorePortLimits . . . . . . . . . 1586
AMgr_NewMailEventDelay . . . . . . . 1568 DIIOPIORHost . . . . . . . . . . . 1586
AMgr_SchedulingInterval . . . . . . . . 1568 DIIOPLogLevel . . . . . . . . . . . 1586
AMgr_UntriggeredMailInterval . . . . . . 1568 Dircat_Include_Readerslist_Notes . . . . . 1587
AMgr_WeekendDays . . . . . . . . . 1568 Directory . . . . . . . . . . . . . 1587
AppleTalkNameServer . . . . . . . . . 1569 Disable_Cluster_Replicator . . . . . . . 1587
AutoLogoffMinutes . . . . . . . . . . 1569 Disable_SaveNSDConfig . . . . . . . . 1588
BatchRegFile . . . . . . . . . . . . 1569 Disable_SaveServerConfig . . . . . . . . 1588
BillingAddinOutput . . . . . . . . . . 1569 Disable_View_Rebuild_Opt . . . . . . . 1588
BillingAddinRuntime . . . . . . . . . 1570 DisabledPorts . . . . . . . . . . . . 1589
BillingAddinWakeup . . . . . . . . . 1570 DisableLDAPOnAdmin . . . . . . . . 1589
BillingClass . . . . . . . . . . . . 1570 Display_MessageID . . . . . . . . . . 1589
BillingSuppressTime . . . . . . . . . . 1571 Display_MessageSeverity . . . . . . . . 1590
CDP_Command . . . . . . . . . . . 1571 Domain . . . . . . . . . . . . . . 1590
CertificateExpChecked . . . . . . . . . 1571 DominoCompleteDocType . . . . . . . . 1590
CertifierIDFile . . . . . . . . . . . . 1572 DominoDisableLastModifiedWithETAGS . . . 1590
ClockType . . . . . . . . . . . . . 1572 DominoDisablePassthruHTML . . . . . . 1591
Clrepl_Obeys_Quotas . . . . . . . . . 1572 DominoNoBanner . . . . . . . . . . 1591
Cluster_Replicators . . . . . . . . . . 1572 DominoNoDirLinks . . . . . . . . . . 1592
COMnumber . . . . . . . . . . . . 1573 DominoR5IntlURLDecoding . . . . . . . 1592
Compact_Retry_Rename_Wait . . . . . . 1573 DominoValidateFramesetSRC . . . . . . . 1592
Console_Log_Enabled . . . . . . . . . 1574 DominoXURLProcess . . . . . . . . . 1593
Console_Loglevel. . . . . . . . . . . 1574 Dont_Cache_Monitor_Formulas . . . . . . 1593
Console_Log_Max_Kbytes . . . . . . . . 1574 Dont_Use_Remembered_Addresses. . . . . 1593
Country_Language . . . . . . . . . . 1575 DST . . . . . . . . . . . . . . . 1594
Create_File_Access . . . . . . . . . . 1575 DSTlaw . . . . . . . . . . . . . . 1594
Create_Replica_Access . . . . . . . . . 1575 DST_Begin_Date . . . . . . . . . . . 1595
CSEnblRstTm . . . . . . . . . . . . 1576 DST_End_Date . . . . . . . . . . . 1595
CTF . . . . . . . . . . . . . . . 1576 EditExpnumber . . . . . . . . . . . 1596
DateOrder . . . . . . . . . . . . . 1576 EditImpnumber . . . . . . . . . . . 1596
DateSeparator . . . . . . . . . . . . 1576 EmptyTrash . . . . . . . . . . . . 1596
DB2Database . . . . . . . . . . . . 1577 Enable_ACL_Files . . . . . . . . . . 1597

Contents xv
 EnableBiDiNotes . . . . . . . . . . . 1597 iNotes_WA_PrintUserStyleSheet . . . . . . 1616
Enforce_Personal_Agents . . . . . . . . 1597 iNotes_WA_QueryAgents . . . . . . . . 1617
ExtMgr_AddIns . . . . . . . . . . . 1598 iNotes_WA_SametimeNameFormat . . . . . 1617
Fault_Analyzer_Match_Percentage . . . . . 1598 iNotes_WA_SametimeProtocol . . . . . . 1618
FaultRecoveryFromINI . . . . . . . . . 1599 iNotes_wa_SecMailPreferNotes . . . . . . 1618
FileDlgDirectory . . . . . . . . . . . 1599 iNotes_WA_SkipEndIESession . . . . . . 1619
Fixup_Tasks . . . . . . . . . . . . 1599 iNotes_WA_UseInternetAddrForXsp . . . . 1619
FormulaTimeout . . . . . . . . . . . 1599 InstallType . . . . . . . . . . . . . 1620
FT_Domain_Directory_Name . . . . . . . 1600 JavaEnableJIT . . . . . . . . . . . . 1620
FT_Domain_IdXthdsS . . . . . . . . . 1600 JavaJITName . . . . . . . . . . . . 1620
FT_Index_Attachments . . . . . . . . . 1600 JavaMaxHeapSize . . . . . . . . . . 1620
FT_Intl_Setting . . . . . . . . . . . 1600 JavaMinHeapSize . . . . . . . . . . 1621
FT_Max_Search_Results . . . . . . . . 1601 JavaNoAsyncGC . . . . . . . . . . . 1621
FT_No_Compwintitle . . . . . . . . . 1601 JavaNoClassGC . . . . . . . . . . . 1621
FTG_No_Summary . . . . . . . . . . 1601 JavaStackSize . . . . . . . . . . . . 1621
FT_Summ_Default_Language . . . . . . 1602 JavaUserClasses . . . . . . . . . . . 1622
FTUpdate_Idle_Time . . . . . . . . . 1602 JavaVerbose . . . . . . . . . . . . 1622
FTUpdate_Idle_Time_MS . . . . . . . . 1602 JavaVerboseGC . . . . . . . . . . . 1622
GuessMIMEBodyLang . . . . . . . . . 1603 KeyFileName . . . . . . . . . . . . 1623
Health_Report_Purge_After_N_Days . . . . 1603 KitType . . . . . . . . . . . . . . 1623
HTTPEnableConnectorHeaders . . . . . . 1603 LANnumber . . . . . . . . . . . . 1623
HTTPLogUnauthorized. . . . . . . . . 1604 LDAPBatchAdds . . . . . . . . . . . 1624
HTTP_PWD_Change_Cache_Hours . . . . 1604 LDAPConfigUpdateInterval . . . . . . . 1624
ICMNotesPort . . . . . . . . . . . . 1604 LDAPGroupMembership . . . . . . . . 1624
ID_Recovery_Suppress_Recovery_Msg . . . 1604 LDAPIdleSessionExtendedTimeout . . . . . 1625
IM_Enable_SSO . . . . . . . . . . . 1605 LDAPIdleSessionExtendedTimeoutClients . . 1626
IMAILExactSize . . . . . . . . . . . 1605 LDAPIdleSessionTimeout . . . . . . . . 1626
IMAP_Config_Update_Interval . . . . . . 1605 LDAPNotesPort . . . . . . . . . . . 1626
IMAP_Convert_Nodisable_Folder_Refs . . . 1606 LDAPPre55Outlook . . . . . . . . . . 1626
IMAPDisableFTIImmedUpdate . . . . . . 1606 LDAPName_Update_Suppress_Time . . . . 1627
IMAPDisableMsgCache . . . . . . . . 1607 Location . . . . . . . . . . . . . . 1627
IMAPGreeting . . . . . . . . . . . . 1607 Log . . . . . . . . . . . . . . . 1627
IMAPNotesPort . . . . . . . . . . . 1607 Log_AgentManager . . . . . . . . . . 1628
IMAPRedirectSSLGreeting . . . . . . . . 1607 Log_Authentication . . . . . . . . . . 1628
IMAP_Session_Timeout . . . . . . . . 1608 Log_Connections . . . . . . . . . . . 1629
IMAPShowIdleStatus . . . . . . . . . 1608 Log_Console . . . . . . . . . . . . 1630
IMAPSSLGreeting . . . . . . . . . . 1608 Log_DirCat . . . . . . . . . . . . 1630
IM_No_Setup . . . . . . . . . . . . 1608 LogFile_Dir . . . . . . . . . . . . 1630
IM_USE_CANONICAL_NAME . . . . . . 1608 Log_Replication . . . . . . . . . . . 1631
Incoming Mail Sound . . . . . . . . . 1609 Log_Sessions . . . . . . . . . . . . 1631
INET_Authenticate_with_Secondary . . . . 1609 LogStatusBar . . . . . . . . . . . . 1631
iNotes_WA_AuthTokenName. . . . . . . 1609 Log_Tasks . . . . . . . . . . . . . 1632
iNotes_WA_AutoUseWebmail . . . . . . 1610 Log_Update . . . . . . . . . . . . 1632
iNotes_WA_DefaultFormatPlainText . . . . 1610 Log_View_Events . . . . . . . . . . 1632
iNotes_WA_DisableActCntSecurity . . . . . 1610 MailBoxDisableTDNLogging . . . . . . . 1633
iNotes_WA_DisableBothFormats . . . . . . 1611 MailCharSet . . . . . . . . . . . . 1633
iNotes_WA_DisableRecodeMIMECharset . . . 1611 MailCompactDisabled . . . . . . . . . 1634
inotes_WA_DisableReuseChildWindows . . . 1611 MailCompactHour . . . . . . . . . . 1634
iNotes_wa_GZIP_Content_Types_Excluded 1611 MailConvertMIMEonTransfer. . . . . . . 1635
iNotes_wa_GZIP_Content_Types_Included 1612 Mail_Disable_Implicit_Sender_Key . . . . 1635
iNotes_wa_GZIP_Disable . . . . . . . . 1612 MailLogToEventsOnly . . . . . . . . . 1635
iNotes_WA_LogoutRedirect . . . . . . . 1612 Mail_Log_To_MiscEvents . . . . . . . . 1635
iNotes_WA_LogoutScrubType . . . . . . 1613 MailServer . . . . . . . . . . . . . 1636
iNotes_WA_MaxRowsPerLine . . . . . . 1614 MailSetup . . . . . . . . . . . . . 1636
iNotes_WA_NameLookupMaxNumMatch . . 1614 Mail_Skip_NoKey_Dialog . . . . . . . . 1637
iNotes_WA_NamePickerSearchAccentInsensitive 1615 MailSystem . . . . . . . . . . . . . 1637
iNotes_WA_NoWebmail . . . . . . . . 1615 MailTimeout . . . . . . . . . . . . 1637
iNotes_WA_OpenElementNoStore . . . . . 1615 MailTimeoutMinutes . . . . . . . . . 1637
iNotes_WA_PortalLogout . . . . . . . . 1616 MailUpgradeFolder . . . . . . . . . . 1638
iNotes_WA_PortalOffline . . . . . . . . 1616 Map_Retry_Delay . . . . . . . . . . 1638
iNotes_WA_PortalSkipEndIESession . . . . 1616 Max_Config_Files . . . . . . . . . . 1638

xvi Lotus Domino Administrator 7 Help

Max_NSDInfo_Files . . . . . . . . . . 1639 Schedule_No_Validate . . . . . . . . . 1657
Memory_Quota . . . . . . . . . . . 1639 Schema_Daemon_Breaktime . . . . . . . 1658
MinNewMailPoll . . . . . . . . . . . 1639 Schema_Daemon_Idletime . . . . . . . . 1658
Move_Mail_File_Expiration_Days . . . . . 1639 Schema_Daemon_Reloadtime. . . . . . . 1658
MSAACompatibility . . . . . . . . . . 1640 Schema_Daemon_Resynctime . . . . . . 1659
MSAAFieldNameHelp . . . . . . . . . 1640 Schema_Daemon_Resynctime . . . . . . 1659
MTCDailyTasksHour . . . . . . . . . 1640 ScriptCountryID . . . . . . . . . . . 1659
MTMaxResponses . . . . . . . . . . 1641 ScriptLanguageID . . . . . . . . . . 1659
Names . . . . . . . . . . . . . . 1641 Secure_Disable_FullAdmin . . . . . . . 1660
NB_Collect_Response_Times . . . . . . . 1642 SecureMail . . . . . . . . . . . . . 1660
NB_SSL_Option . . . . . . . . . . . 1642 Server_Availability_Threshold . . . . . . 1660
NetWareSocket . . . . . . . . . . . 1643 Server_Cluster_Default_Port . . . . . . . 1661
NetWareSpxSettings . . . . . . . . . . 1643 Server_Console_Password . . . . . . . . 1661
NewMailInterval . . . . . . . . . . . 1643 ServerKeyFileName . . . . . . . . . . 1661
NewUserServer . . . . . . . . . . . 1643 Server_Max_Concurrent_Trans . . . . . . 1661
NoDesignMenu . . . . . . . . . . . 1643 Server_MaxSessions . . . . . . . . . . 1662
NoExternalApps . . . . . . . . . . . 1644 Server_MaxUsers . . . . . . . . . . . 1662
No_Force_Activity_Logging . . . . . . . 1644 ServerName . . . . . . . . . . . . 1662
NoMailMenu . . . . . . . . . . . . 1645 ServerNoReplRequests . . . . . . . . . 1663
NoMsgCache . . . . . . . . . . . . 1645 ServerPullReplication . . . . . . . . . 1663
NotesStreamPlatformDefault . . . . . . . 1645 ServerPushReplication . . . . . . . . . 1663
NSF_Buffer_Pool_Size . . . . . . . . . 1645 Server_Restart_Delay . . . . . . . . . 1664
NSF_DbCache_Disable . . . . . . . . . 1646 Server_Restricted . . . . . . . . . . . 1664
NSF_DbCache_Maxentries. . . . . . . . 1646 Server_Session_Timeout . . . . . . . . 1664
NSF_Quota_Method . . . . . . . . . . 1646 Server_Show_Performance . . . . . . . 1665
Num_Compact_Rename_Retries . . . . . . 1647 ServerTasks . . . . . . . . . . . . 1665
NWNDSPassword . . . . . . . . . . 1647 ServerTasksAthour . . . . . . . . . . 1665
NWNDSUserID . . . . . . . . . . . 1647 Server_TransInfo_Range . . . . . . . . 1666
OptimizeImagePasteSize . . . . . . . . 1648 Setup . . . . . . . . . . . . . . . 1666
Passthru_Hangup_Delay . . . . . . . . 1648 SetupDB . . . . . . . . . . . . . 1666
Passthru_LogLevel . . . . . . . . . . 1648 Setup_First_Server_Public_Key_Width . . . . 1667
PhoneLog . . . . . . . . . . . . . 1649 SetupServerAddress . . . . . . . . . . 1667
PKCS11_Library . . . . . . . . . . . 1649 SetupServerName . . . . . . . . . . 1667
Platform_Statistics_Disabled . . . . . . . 1649 Shutdown_Monitor_Disabled . . . . . . . 1667
POP3ConfigUpdateInterval . . . . . . . 1650 SMIME_Strong_Algorithm . . . . . . . 1668
POP3_Disable_Cache . . . . . . . . . 1650 SMIME_Weak_Algorithm . . . . . . . . 1668
POP3DNSLookup . . . . . . . . . . 1650 SMTPAllHostsExternal . . . . . . . . . 1669
POP3Domain . . . . . . . . . . . . 1650 SMTP_Config_Update_Interval . . . . . . 1669
POP3_Enable_Cache_Stats . . . . . . . . 1651 SMTPDebug . . . . . . . . . . . . 1670
POP3MarkRead . . . . . . . . . . . 1651 SMTPDebugIO . . . . . . . . . . . 1670
POP3_Message_Stat_Cache_NumPerUser. . . 1651 SMTPExpandDNSBLStats . . . . . . . . 1670
POP3NotesPort . . . . . . . . . . . 1651 SMTPExpandDNSWLStats . . . . . . . 1671
portname_MaxSessions . . . . . . . . . 1652 SMTPGreeting . . . . . . . . . . . . 1671
Ports . . . . . . . . . . . . . . . 1652 SMTPNotesPort . . . . . . . . . . . 1671
Process_Monitor_Disabled . . . . . . . . 1652 SMTPNoVersionInRcvdHdr . . . . . . . 1672
ProgramMode . . . . . . . . . . . . 1653 SMTPMaxForRecipients . . . . . . . . 1672
Repl_Error_Tolerance . . . . . . . . . 1653 SMTPMTA_Space_Repl_Char. . . . . . . 1672
ReplicationTimeLimit . . . . . . . . . 1653 SMTPRelayHostsandDomains . . . . . . 1672
Replicators . . . . . . . . . . . . . 1653 SMTPSaveImportErrors . . . . . . . . 1673
Repl_Obeys_Quotas . . . . . . . . . . 1654 SMTPStrict821AddressSyntax . . . . . . . 1673
Report_DB . . . . . . . . . . . . . 1654 SMTPStrict821LineSyntax . . . . . . . . 1674
ReportUseMail . . . . . . . . . . . 1654 SMTPTimeoutMultiplier . . . . . . . . 1674
RouterAllowConcurrentXferToAll . . . . . 1654 SMTPVerifyAuthenticatedSender . . . . . 1674
RouterDisableMailToGroups . . . . . . . 1655 SSLCipherSpec . . . . . . . . . . . 1675
RouterDSNForNullReversePath . . . . . . 1655 SSL_Resumable_Sessions . . . . . . . . 1675
RouterEnableMailByDest . . . . . . . . 1655 SSL_Trace_KeyFileRead . . . . . . . . 1676
RTR_Logging . . . . . . . . . . . . 1656 SwapPath . . . . . . . . . . . . . 1676
Sched_Dialing_Enabled . . . . . . . . . 1656 TCP_DefaultZone . . . . . . . . . . 1676
Sched_Purge_Interval . . . . . . . . . 1656 TCP_EnableIPV6 . . . . . . . . . . . 1677
Schedule_Check_Entries_When_Validating 1657 TCP/IPportname_PortMappingNN . . . . . 1677
Schedule_No_CalcStats . . . . . . . . . 1657 TCP/IPportname_TCPIPAddress . . . . . . 1677

Contents xvii
 Temp_Index_Max_Doc . . . . . . . . . 1678 Time-based execution requests . . . . . . 1786
TimeSeparator . . . . . . . . . . . . 1678
TimeZone . . . . . . . . . . . . . 1678 Appendix G Accessibility
Topology_WorkInterval . . . . . . . . . 1679 and Keyboard Shortcuts in Domino
TransLog_MaxSize . . . . . . . . . . 1679
TransLog_Path . . . . . . . . . . . 1679
Administrator . . . . . . . . . . . 1789
TransLog_Performance . . . . . . . . . 1679 Accessibility and keyboard shortcuts . . . . . 1789
TransLog_Status . . . . . . . . . . . 1680 Enabling and using extended accelerator keys 1789
TransLog_Style . . . . . . . . . . . 1680 Keyboard shortcuts . . . . . . . . . . 1790
TransLog_UseAll . . . . . . . . . . . 1681 Keyboard shortcuts for the Domino
Update_Disable_Fulltext . . . . . . . . 1681 Administrator user interface . . . . . . . 1790
Update_Disable_Views . . . . . . . . . 1681 Keyboard shortcuts for databases . . . . . 1791
Update_Fulltext_Thread . . . . . . . . 1681 Keyboard shortcuts for dialog boxes . . . . 1791
Update_Idle_Time . . . . . . . . . . 1682 Keyboard shortcuts for properties boxes . . . 1791
Update_Idle_Time_MS . . . . . . . . . 1682 Keyboard shortcuts for documents . . . . . 1792
Update_No_BRP_Files . . . . . . . . . 1682 Keyboard shortcuts to select and move text in
Update_No_Fulltext . . . . . . . . . . 1682 a document . . . . . . . . . . . . 1793
Updaters . . . . . . . . . . . . . 1683 Keyboard shortcuts to move the cursor in a
Update_Suppression_Limit . . . . . . . 1683 document . . . . . . . . . . . . . 1793
Update_Suppression_Time . . . . . . . 1683 Keyboard shortcuts to change text and
UpgradeApps . . . . . . . . . . . . 1683 paragraph properties in a document . . . . 1794
UseFontMapper . . . . . . . . . . . 1684 Keyboard shortcuts when working in views 1794
$Use_ST_IM . . . . . . . . . . . . 1684
ViewExpnumber . . . . . . . . . . . 1684 Appendix H Server.Load
ViewImpnumber . . . . . . . . . . . 1685 Command Language . . . . . . . . 1797
View_Rebuild_Dir . . . . . . . . . . 1685 Server.Load script conventions . . . . . . . 1797
WCT_IM_Use_Lookup . . . . . . . . . 1685 Server.Load commands . . . . . . . . . . 1797
WebAuth_Verbose_Trace . . . . . . . . 1686 @Else command . . . . . . . . . . . 1797
WebSess_Verbose_Trace . . . . . . . . 1686 @EndIf command . . . . . . . . . . 1797
Window_Title . . . . . . . . . . . . 1687 @If command . . . . . . . . . . . . 1798
WinInfoboxPos . . . . . . . . . . . 1687 Add command . . . . . . . . . . . 1798
WinSysFontnumber . . . . . . . . . . 1687 BeginCrit command . . . . . . . . . . 1799
XPC_Console . . . . . . . . . . . . 1687 BeginLoop command . . . . . . . . . 1799
BeginLoop2 command . . . . . . . . . 1799
Appendix D System and Break command . . . . . . . . . . . 1799
Application Templates . . . . . . . 1689 Cal command . . . . . . . . . . . . 1799
System and application templates . . . . . . 1689 ChangeTo command . . . . . . . . . 1800
CheckForNewMail command . . . . . . . 1801
Close command . . . . . . . . . . . 1802
Appendix E Customizing Console command . . . . . . . . . . 1802
the Domino Directory . . . . . . . 1695 DBClose command . . . . . . . . . . 1802
The Domino Directory template . . . . . . . 1695 DbDelete command . . . . . . . . . . 1802
Rules for customizing the Domino Directory 1695 Delete command . . . . . . . . . . . 1802
Customizing the Domino Directory template 1697 Drop command . . . . . . . . . . . 1803
Creating a copy of the Domino Directory EndCrit command . . . . . . . . . . 1803
template . . . . . . . . . . . . . . 1697 Entries command. . . . . . . . . . . 1803
Customizing a visible view in the Domino ErrorDelay command . . . . . . . . . 1803
Directory . . . . . . . . . . . . . 1698 FindByKey command . . . . . . . . . 1804
Using the Domino Directory to extend the FindByName command . . . . . . . . 1804
LDAP schema . . . . . . . . . . . . 1698 GetAll command . . . . . . . . . . . 1804
Applying template customizations to the Help command . . . . . . . . . . . 1804
Domino Directory database . . . . . . . 1708 If command . . . . . . . . . . . . 1804
Upgrading to a new Domino Directory ImailCheckForNewMail command . . . . . 1805
template . . . . . . . . . . . . . . 1709 ImailCloseMailbox command . . . . . . . 1805
ImailFetchEntry command . . . . . . . 1805
Appendix F ImailFetchOld command . . . . . . . . 1805
Administration Process Requests . . 1711 ImailGetLastEntries command . . . . . . 1805
Administration process requests . . . . . . . 1711 ImailGetNewMail command . . . . . . . 1805
Administration Process Requests -- One ImailHelp command . . . . . . . . . 1805
Domain . . . . . . . . . . . . . . 1711 ImailListMailboxes command . . . . . . 1805
Cross Domain Administration Requests . . . 1771 ImailLogin command . . . . . . . . . 1806

xviii Lotus Domino Administrator 7 Help

 ImailLogout command . . . . . . . . . 1806 Using a Domino 5 certificate authority . . . . 1831
ImailOpenMailbox command . . . . . . . 1806 Setting up a Domino 5 certificate authority 1831
ImailPostMessage command . . . . . . . 1806 Creating the Domino Certificate Authority
ImailSetSeen command . . . . . . . . . 1806 application . . . . . . . . . . . . . 1831
Index command . . . . . . . . . . . 1807 Creating a CA key ring file and certificate 1832
LDAPLookup command . . . . . . . . 1807 Configuring the Domino Certificate Authority
Lookup command . . . . . . . . . . 1807 application profile . . . . . . . . . . 1833
NABRetrievePOP3Mail command . . . . . 1808 Setting up SSL on the CA server . . . . . 1833
NABUpdate command . . . . . . . . . 1808 Displaying the CA key ring file . . . . . . 1834
Navigate command . . . . . . . . . . 1808 Exporting the CA key ring file . . . . . . 1834
NewMail command . . . . . . . . . . 1809 Signing server certificates . . . . . . . . 1835
NewReplicateDB command . . . . . . . 1809 Viewing requests for certificates . . . . . . 1835
NoteAdd command . . . . . . . . . . 1809
Open command . . . . . . . . . . . 1809 Appendix K Upgrading
Pause command . . . . . . . . . . . 1810 Notes Clients . . . . . . . . . . . 1837
Populate command . . . . . . . . . . 1810
Upgrading Notes clients . . . . . . . . . 1837
Quit command . . . . . . . . . . . 1811
Before you upgrade the Notes client . . . . 1838
Read command . . . . . . . . . . . 1811
Notes Client features and their Domino server
Replicate command . . . . . . . . . . 1811
and template dependencies . . . . . . . . 1838
RetrievePOP3Mail command . . . . . . . 1811
Using IBM Lotus Notes Smart Upgrade . . . . 1843
Rewind command . . . . . . . . . . 1812
Prerequisites . . . . . . . . . . . . 1843
Rewind2 command . . . . . . . . . . 1812
To use Lotus Notes Smart Upgrade, follow this
RSVPInvitation command . . . . . . . . 1812
procedure: . . . . . . . . . . . . . 1843
SendMessage command and SendMessage
How Smart Upgrade performs an upgrade 1844
profile command . . . . . . . . . . . 1812
Smart Upgrade server failover to another
SendSMTPMessage command . . . . . . 1813
clustered server . . . . . . . . . . . 1845
SessionsClose command . . . . . . . . 1813
Smart Upgrade Tracking Reports database 1845
SessionsOpen command . . . . . . . . 1813
Creating a Lotus Notes Smart Upgrade
SetContextStatus command . . . . . . . 1813
database. . . . . . . . . . . . . . 1846
SetCalProfile command . . . . . . . . . 1813
Creating a database link to the Smart Upgrade
SetReplID command . . . . . . . . . 1814
Database . . . . . . . . . . . . . 1846
Stamp command . . . . . . . . . . . 1814
Controlling the number of concurrent Smart
Unread command . . . . . . . . . . 1814
Upgrade downloads . . . . . . . . . . 1847
Update command . . . . . . . . . . 1814
Adding update kits to the Lotus Notes Smart
WebGet command . . . . . . . . . . 1814
Upgrade database . . . . . . . . . . 1847
Running a silent upgrade using optional
Appendix I Server.Load arguments . . . . . . . . . . . . . 1851
Scripts . . . . . . . . . . . . . . 1819 Creating a Lotus Notes Smart Upgrade
Server.Load scripts . . . . . . . . . . . 1819 desktop policy settings document . . . . . 1852
Sample Server.Load scripts . . . . . . . 1819 Creating a master policy document for Lotus
Idle Workload script . . . . . . . . . . 1821 Notes Smart Upgrade . . . . . . . . . 1852
R5 IMAP Workload script . . . . . . . . 1821 Assigning the Lotus Notes Smart Upgrade
R5 Simple Mail Routing script . . . . . . 1824 master policy to users and groups . . . . . 1853
R5 Shared Database script . . . . . . . . 1826 Notes users and Lotus Notes Smart Upgrade 1854
SMTP and POP3 Workload script . . . . . 1828 Maintaining Lotus Notes Smart Upgrade . . . 1854
Web Idle Workload script . . . . . . . . 1828
Web Mail Workload script . . . . . . . . 1829 Index . . . . . . . . . . . . . . 1855

Appendix J Setting Up a
Domino 5 Certificate Authority . . . 1831

Contents xix
xx Lotus Domino Administrator 7 Help
Chapter 1. Deploying Domino
This chapter outlines the steps required to deploy IBM® Lotus® Domino(TM) 7 successfully and
introduces important concepts that you need to know before you install Domino servers.

Guidepost for deploying Domino

Whether you’re setting up IBM Lotus Domino 7 and IBM Lotus Notes® 7 for the first time or adding to
an established Domino environment, planning is vital. Along with determining your company’s needs,
you need to plan how to integrate Domino into your existing network. After planning is complete, you
can begin to install and set up Domino servers and the Domino Administrator and build the Domino
environment. The following list describes, in order, the process to use to deploy Domino.
1. Determine your company’s server needs. Decide where to locate each server physically, taking into
consideration local and wide-area networks and the function of each server.
2. Develop a hierarchical name scheme that includes organization and organizational unit names.
3. Decide whether you need more than one Domino domain.
4. Understand how server name format affects network name-to-address resolution for servers. Ensure
that the DNS records for your company are the correct type for the server names.
5. Determine which server services to enable.
6. Determine which certificate authority -- Domino server-based certification authority, Domino 5
certificate authority, third-party -- to use.
7. Install and set up the first Domino server.
8. Install and set up the Domino Administrator on the administrator’s machine.
9. Complete network-related server setup.
10. If the Domino server is offering Internet services, set up Internet site documents. There are some
instances where Internet Site documents are required.
11. Specify Administration Preferences.
12. Create additional certifier IDs to support the hierarchical name scheme.
13. Set up recovery information for the certifier IDs.
14. Add the administrator’s ID to the recovery information for the certifier IDs and then distribute the
certifier IDs, as necessary, to other administrators.
15. Register additional servers.
16. If you did not choose to do so during first server setup, Create a group in the Domino Directory for
all administrators, and give this group Manager access to all databases on the first server.
17. Install and set up additional servers.
18. Complete network-related server setup for each additional server.
19. Build the Domino environment.

Functions of Domino servers

Before you install and set up the first Domino server, consider the function and physical location of the
servers that your company needs and determine how to connect the servers to each other. The current
configuration of local and wide-area networks affects many of these decisions.

Consider your company’s need for:

v Servers that provide Notes and/or browser users with access to applications
v Hub servers that handle communication between servers that are geographically distant
v Web servers that provide browser users with access to Web applications

1
v Servers that manage messaging services
v Directory servers that provide users and servers with information about how to communicate with
other users and servers
v Passthru servers that provide users and servers with access to a single server that provides access to
other servers
v Domain Search servers that provide users with the ability to perform searches across all servers in a
Domino domain
v Clustered servers that provide users with constant access to data and provide load-balancing and
failover
v Partitioned servers that run multiple instances of the Domino server on a single computer
v Firewall servers that provide Notes users with access to internal Domino services and protect internal
servers from outside users
v xSP servers that provide users with Internet access to a specific set of Domino applications

Your decisions help determine which types of Domino servers your require. When you install each server,
you must select one of the following installation options:
v Domino Utility Server -- Installs a Domino server that provides application services only, with support
for Domino clusters. The Domino Utility Server is a new installation type for Lotus Domino 7 that
removes client access license requirements. Note that it does NOT include support for messaging
services. See full licensing text for details.
v Domino Messaging Server -- Installs a Domino server that provides messaging services. Note that it
does NOT include support for application services or Domino clusters.
v Domino Enterprise Server -- Installs a Domino server that provides both messaging and application
services, with support for Domino clusters.

Note: All three types of installations support Domino partitioned servers. Only the Domino Enterprise
Server supports a service provider (xSP) environment.

Hierarchical naming for servers and users

Hierarchical naming is the cornerstone of Domino security; therefore planning it is a critical task.
Hierarchical names provide unique identifiers for servers and users in a company. When you register
new servers and users, the hierarchical names drive their certification, or their level of access to the
system, and control whether users and servers in different organizations and organizational units can
communicate with each another.

Before you install Domino servers, create a diagram of your company and use the diagram to plan a
meaningful name scheme. Then create certifier IDs to implement the name scheme and ensure a secure
system.

A hierarchical name scheme uses a tree structure that reflects the actual structure of a company. At the
top of the tree is the organization name, which is usually the company name. Below the organization
name are organizational units, which you create to suit the structure of the company; you can organize
the structure geographically, departmentally, or both.

For example, the Acme company created this diagram for their servers and users:

2 Lotus Domino Administrator 7 Help

Looking at Acme’s diagram, you can see where they located their servers in the tree. Acme decided to
split the company geographically at the first level and create certifier IDs for the East and West
organizational units. At the next level down, Acme made its division according to department.

For more information on certifier IDs, see the topic ″Certifier IDs and certificates″ in this chapter.

Components of a hierarchical name

A hierarchical name reflects a user’s or server’s place in the hierarchy and controls whether users and
servers in different organizations and organizational units can communicate with each another. A
hierarchical name may include these components:
v Common name (CN) -- Corresponds to a user’s name or a server’s name. All names must include a
common name component.
v Organizational unit (OU) -- Identifies the location of the user or server in the organization. Domino
allows for a maximum of four organizational units in a hierarchical name. Organizational units are
optional.
v Organization (O) -- Identifies the organization to which a user or server belongs. Every name must
include an organization component.
v Country (C) --Identifies the country in which the organization exists. The country is optional.

An example of a hierarchical name that uses all of the components is:

Julia Herlihy/Sales/East/Acme/US

Typically a name is entered and displayed in this abbreviated format, but it is stored internally in
canonical format, which contains the name and its associated components, as shown below:

CN=Julia Herlihy/OU=Sales/OU=East/O=Acme/C=US.

Note: You can use hierarchical naming with wildcards as a way to isolate a group of servers that need to
connect to a given Domino server in order to route mail.

For more information, see the chapter ″Setting Up Mail Routing.″

Domino domains
A Domino domain is a group of Domino servers that share the same Domino Directory. As the control
and administration center for Domino servers in a domain, the Domino Directory contains, among other
documents, a Server document for each server and a Person document for each Notes user.

Planning for Domino domains

There are four basic scenarios for setting up Domino domains. The first scenario, which many small- and
medium-size companies use, involves creating only one Domino domain and registering all servers and
users in one Domino Directory. This scenario is the most common and the easiest to manage.

Chapter 1. Deploying Domino 3

The second scenario is common when a large company has multiple independent business units. In this
case, one organization spread across multiple domains may be the best scenario. Then all servers and
users are members of the same organization, and each business unit administers its own Domino
Directory.

For more information on administering multiple Domino directories, see the chapter ″Planning Directory
Services.″

A third scenario is common when multiple companies work closely together yet want to retain individual
corporate identities. Then one domain and multiple organizations may work best.

Finally, the fourth scenario involves maintaining multiple domains and multiple organizations. This
scenario often occurs when one company acquires another.

Sometimes the decision to create multiple Domino domains is not based on organizational structure at all.
For example, you may want to create multiple Domino domains if you have slow or unreliable network
connections that prohibit frequent replication of a single, large directory. Keep in mind that working with
multiple domains requires additional administrative work and requires you to set up a system for
managing them.

Domains can be used as a broad security measure. For example, you can grant or deny a user access to
servers and databases, based on the domain in which the user is registered. Using an extended ACL is an
alternative to creating multiple domains, because you can use the extended ACL to specify different
levels of access to a single Domino Directory, based on organization name hierarchy.

For more information on extended ACLs, see the chapter ″Setting Up Extended ACLs.″

Partitioned servers
Using Domino server partitioning, you can run multiple instances of the Domino server on a single
computer. By doing so, you reduce hardware expenses and minimize the number of computers to
administer because, instead of purchasing multiple small computers to run Domino servers that might
not take advantage of the resources available to them, you can purchase a single, more powerful
computer and run multiple instances of the Domino server on that single machine.

On a Domino partitioned server, all partitions share the same Domino program directory, and thus share
one set of Domino executable files. However, each partition has its own Domino data directory and
NOTES.INI file; thus each has its own copy of the Domino Directory and other administrative databases.

If one partition shuts down, the others continue to run. If a partition encounters a fatal error, Domino’s
fault recovery feature restarts only that partition, not the entire computer.

For information on setting up fault recovery, see the chapter ″Transaction Logging and Recovery.″

Partitioned servers can provide the scalability you need while also providing security. As your system
grows, you can migrate users from a partition to a separate server. A partitioned server can also be a
member of a cluster if you require high availability of databases. Security for a partitioned server is the
same as for a single server.

When you set up a partitioned server, you must run the same version of Domino on each partition.
However, if the server runs on UNIX®, there is an alternative means to run multiple instances of Domino
on the server: on UNIX, you can run different versions of Domino on a single computer, each version
with its own program directory. You can even run multiple instances of each version by installing it as a
Domino partitioned server.

4 Lotus Domino Administrator 7 Help

For more information on installing Domino on UNIX, see the chapter ″Installing and Setting Up Domino
Servers.″

Deciding whether to use partitioned servers

Whether or not to use partitioned servers depends, in part, on how you set up Domino domains. A
partitioned server is most useful when the partitions are in different Domino domains. For example,
using a partitioned server, you can dedicate different Domino domains to different customers or set up
multiple Web sites. A partitioned server with partitions all in the same Domino domain often uses more
computer resources and disk space than a single server that runs multiple services.

When making the decision to use partitioned servers, remember that it is easier to administer a single
server than it is to administer multiple partitions. However, if your goal is to isolate certain server
functions on the network -- for example, to isolate the messaging hub from the replication hub or isolate
work groups for resource and activity logging -- you might be willing to take on the additional
administrative work. In addition, running a partitioned server on a multiprocessor computer may
improve performance, even when the partitions are in the same domain, because the computer
simultaneously runs certain processes.

To give Notes users access to a Domino server where they can create and run Domino applications, use a
partitioned server. However, to provide customers with Internet access to a specific set of Domino
applications, set up an xSP server environment.

For more information about using Domino in an xSP environment, see the chapter ″Planning the Service
Provider Environment.″

Deciding how many partitions to have

How many partitions you can install without noticeably diminishing performance depends on the power
of the computer and the operating system the computer uses. For optimal performance, partition
multiprocessor computers that have at least one, and preferably two, processors for each partition that
you install on the computer.

Certifier IDs and certificates

Certifier IDs and certificates form the basis of Domino security. To place servers and users correctly
within your organization’s hierarchical name scheme, you create a certifier ID for each branch on the
name tree. You use the certifiers during server and user registration to ″stamp″ each server ID and user
ID with a certificate that defines where each belongs in the organization. Servers and users who belong to
the same name tree can communicate with each other; servers and users who belong to different name
trees need a cross-certificate to communicate with each other.

Note: You can register servers and users without stamping each server ID and user ID if you have
migrated the certifier to a Domino server-based certification authority (CA).

For more information about server-based CAs, see the chapter ″Setting Up a Domino Server-based
Certification Authority.″

Each time you create a certifier ID, Domino creates a certifier ID file and a Certifier document. The ID file
contains the ID that you use to register servers and users. The Certifier document serves as a record of
the certifier ID and stores, among other things, its hierarchical name, the name of the certifier ID that
issued it, and the names of certificates associated with it.

Note: During server setup, you can use an existing certifier ID instead of creating a new one. The
certifier ID that you specify cannot have multiple passwords assigned to it. Attempting to user a certifier
ID with multiple passwords generates an error message and causes server setup to halt.

There are two types of certifier IDs: organization and organizational unit.

Chapter 1. Deploying Domino 5

Organization certifier ID
The organization certifier appears at the top of the name tree and is usually the name of the company --
for example, Acme. During first server setup, the Server Setup program creates the organization certifier
and stores the organization certifier ID file in the Domino data directory, giving it the name CERT.ID.
During first server setup, this organization certifier ID automatically certifies the first Domino server ID
and the administrator’s user ID.

If your company is large and decentralized, you might want to use the Domino Administrator after
server setup to create a second organization certifier ID to allow for further name differentiation -- for
example, to differentiate between company subsidiaries.

For more information on working with multiple organizations, see the topic ″Domino domains″ earlier in
this chapter.

Organizational unit certifier IDs

The organizational unit certifiers are at all the branches of the tree and usually represent geographical or
departmental names -- for example, East/Acme or Sales/East/Acme. If you choose to, you can create a
first-level organizational unit certifier ID during server setup, with the result that the server ID and
administrator’s user ID are stamped with the organizational unit certifier rather than with the
organization certifier. If you choose not to create this organizational unit certifier during server setup, you
can always use the Domino Administrator to do it later -- just remember to recertify the server ID and
administrator’s user ID.

For information on recertifying user IDs, see the chapter ″Setting Up and Managing Notes Users.″ For
information on recertifying server IDs, see the chapter ″Maintaining Domino Servers.″

You can create up to four levels of organizational unit certifiers. To create first-level organizational unit
certifier IDs, you use the organization certifier ID. To create second-level organizational unit certifier IDs,
you use the first-level organizational unit certifier IDs, and so on.

Using organizational unit certifier IDs, you can decentralize certification by distributing individual
certifier IDs to administrators who manage users and servers in specific branches of the company. For
example, the Acme company has two administrators. One administers servers and users in West/Acme
and has access to only the West/Acme certifier ID, and the other administers servers and users in
East/Acme and has access to only the East/Acme certifier ID.

Certifier security
By default, the Server Setup program stores the certifier ID file in the directory you specify as the
Domino data directory. When you use the Domino Administrator to create an additional organization
certifier ID or organizational unit certifier ID, you specify where you want the ID stored. To ensure
security, store certifiers in a secure location -- such as a disk locked in a secure area.

User ID recovery
To provide ID and password recovery for Notes users, you need to set up recovery information for each
certifier ID. Before you can recover user ID files, you need access to the certifier ID file to specify the
recovery information, and the user ID files themselves must be made recoverable. There are three ways to
do this:
v At user registration, create the ID file with a certifier ID that contains recovery information.
v Export recovery information from the certifier ID file and have the user accept it.
v (Only for servers using the server-based certification authority) Add recovery information to the
certifier. Then, when existing users authenticate to their home server, their IDs are automatically
updated.
For more information, see the chapter ″Protecting and Managing Notes IDs.″

6 Lotus Domino Administrator 7 Help

Example of how certifier IDs mirror the hierarchical name scheme
To implement their hierarchical name scheme, the Acme company created a certifier ID at each branch of
the hierarchical name tree:

To register each server and user, Acme does the following:

v Creates /Acme as the organization certifier ID during first server setup.
v Uses the /Acme certifier ID to create the /East/Acme and /West/Acme certifier IDs.
v Uses the /East/Acme certifier ID to register servers and users in the East coast offices and uses the
/West/Acme certifier ID to register servers and users in the West coast offices.
v Uses the /East/Acme certifier ID to create the /Sales/East/Acme, /Marketing/East/Acme, and
/Development/East/Acme certifier IDs.
v Uses the /West/Acme certifier ID to create the /HR/West/Acme, /Accounting/West/Acme, and
IS/West/Acme certifier IDs.
v Uses the /Sales/East/Acme, /Sales/Marketing/Acme, and Development/East/Acme certifier IDs to
register users and servers in the East coast division.
v Uses the /HR/West/Acme, /Accounting/West/Acme, and IS/West/Acme certifier IDs to register
users and servers in the West coast division.
For more information on hierarchical name schemes, see the topic ″Hierarchical naming for users and
servers″ earlier in this chapter.

Domino server services

Before you start the Server Setup program, decide which services and tasks to set up on the server. If you
don’t select the services during the setup program, you can later enable them by editing the ServerTasks
setting in the NOTES.INI file or by starting the server task from the server console.

Internet services
The Domino Server Setup program presents these selections for Internet services:
v Web Browsers (HTTP Web services)
v Internet Mail Clients (SMTP, POP3, and IMAP mail services)

Chapter 1. Deploying Domino 7

v Directory services (LDAP)

Advanced Domino services

These Domino services, which are necessary for the proper operation of the Domino infrastructure, are
enabled by default when you set up a Domino server:
v Database Replicator
v Mail Router
v Agent Manager
v Administration Process
v Calendar Connector
v Schedule Manager
v DOLS (Domino Off-Line Services)

These are optional advanced Domino server services that you can enable:
v DIIOP CORBA Services
v DECS (Domino Enterprise Connection Services)
v Billing
v HTTP Server
v IMAP Server
v ISpy
v LDAP Server
v POP3 Server
v Remote Debug Server
v SMTP Server
v Stats
v Statistic Collector
v Web Retriever

Note: It is best to use activity logging instead of the billing service.

For more information on activity logging, see the chapter ″Planning the Service Provider Environment.″

Table of Domino naming requirements

Consider these guidelines when naming parts of the Domino system.

Name Characters Tips

Domino domain 31 maximum v This is usually the same as the organization name.
v Use a single word, made up of only alpha (A-Z) or
numeric (0-9) characters.
Notes named 31 maximum v By default, the Server Setup program assigns names in
network the format port name network -- for example, TCP/IP
network.
v Edit Notes named network names to use an identifier
such as the location of the Notes named network and the
network protocol -- for example, TCPIP-Boston.
Organization 3-64 maximum* v This name is typically the same as the Domino domain
name.
v The organization name is the name of the certifier ID and
is appended to all user and server names.

8 Lotus Domino Administrator 7 Help

Name Characters Tips
Organizational unit 32 maximum* v There can be up to four levels of organizational units.
Server 79 maximum v Choose a name you want to keep. If you change a server
name, you must recertify the server ID.
v Choose a name that meets your network’s requirements
for unique naming. On TCP/IP, use only the characters 0
through 9, A through Z, and - (dash). On NetBIOS, the
first 15 characters must be unique. On SPX, the first 47
characters must be unique.
v Keep in mind that Domino performs replication and mail
routing on servers named with numbers before it does
those tasks on servers named with alphabetic characters.
User 79 maximum* v Use a first and last name. A middle name is allowed, but
usually not needed.
Alternate user No minimum v Can have only one alternate name
Group 62 maximum v Use any of these characters: A - Z, 0 - 9, & - . _ ’ /
(ampersand, dash, period, space, underscore, apostrophe,
forward slash). The only characters that are expressly
prohibited are @ and //.
Note: You can create groups with hierarchical distinguished
names (DN). However, you must surround the forward
slash (/) in a component value of a DN by surrounding it
with double quotes. For example, 24″/″7 Support.
Note: Do not create group names containing a / (slash)
unless you are working in a hosted environment. Using the
/ in group names in a non-hosted environment causes
confusion with hierarchical naming schemes. Hierarchical
names are required in a hosted environment.
v For mail routing, you can nest up to five levels of
groups. For all other purposes, you can nest up to six
levels of groups.
Port No maximum v Do not include spaces
Country code 0 or 2 v Optional

* This name may include alpha characters (A - Z), numbers (0 - 9), and the ampersand (&), dash (-),
period (.), space ( ) , and underscore (_).

For more information on network name requirements and the effect that server name format has on
network name-to-address resolution, see the chapter ″Setting Up the Domino Network.″

Building the Domino environment

After installing the first Domino server and any additional servers, you configure the servers and build
the environment.

This overview lists the features that you may want to include in your Domino environment.
1. Create Connection documents for server communication.
2. If you have mobile users, set up modems, dialup support, and RAS.
3. Set up mail routing
4. Establish a replication schedule.
5. Configure incoming and outgoing Internet mail (SMTP).

Chapter 1. Deploying Domino 9

 6. Customize the Administration Process for your organization.
7. Plan and create policies before you register users and groups.
8. Register users and groups.
9. Determine backup and maintenance plans and consider transaction logging.
10. Consider remote server administration from the Domino console or Web Administrator console. Also
consider the use of an extended administration server.
11. Set up a mobile directory catalog on Notes clients to give Notes users local access to a
corporate-wide directory.
12. Consider implementing clustering on servers.
For information about clustering, see the book Administering Domino Clusters.

10 Lotus Domino Administrator 7 Help

Chapter 2. Setting Up the Domino Network
This chapter describes planning concepts and presents protocol-specific procedures required to run
Domino on a network. The chapter describes using network protocols from a Domino perspective and
does not provide general network information.

Lotus Domino and networks

A variety of client systems can use wireless technology or modems to communicate with Domino servers
over local area networks (LANs), wide area networks (WANs), and metropolitan area networks (MANs).
To govern how computers share information over a network, they use one or more protocols, which are
sets of rules. For example, Notes workstations and Domino servers use the Notes remote procedure call
(NRPC) protocol running over the LAN’s network protocol to communicate with other Domino servers.
Other client systems, such as Web browsers, Internet mail clients, wireless application protocol (WAP)
devices, and personal information management (PIM) devices, can also communicate with Domino
servers.

Isolated LANs can be connected by WANs. A WAN is either a continuous connection -- such as a
frame-relay, leased telephone line, or digital subscriber line (DSL) -- or a dialup connection over a modem
or Integrated Services Digital Network (ISDN) line. Dialup connections are either to an individual server
or to a LAN (through a provider network or your company’s own communications server).

Buildings or sites that are geographically close to each other can use a MAN, which is a continuous,
high-speed connection that can connect corporate LANs or connect a LAN to the WAN. Like a WAN, a
MAN is usually shared by multiple organizations.

Wireless technology that works with Domino ranges from localized transmission systems (802.11a or
802.11b) to national or international satellite transmission systems that are geostationary, mid-orbit, or
tracked orbit.

If you are planning a network for geographically dispersed locations, consider how to achieve a
cost-effective infrastructure. Placing servers in one location requires that users in other locations access
the Domino server across WAN connections, which can be slow and expensive. Placing servers in every
location and replicating databases to make the same information available on several LANs requires
attention to administration at each location. One effective way to set up a network is to use a hub server
at each location to handle communication with hub servers in other locations. Then, only the hub servers,
not every server in the network, use WAN connections.

The functionality of Notes workstations and Domino servers depends on the effectiveness and capacity of
networks. To plan a Domino network with sufficient capacity, you must consider not only the traffic to
and from Domino servers but also any other traffic on the network.

NRPC communication
Domino servers offer many different services. The foundation for communication between Notes
workstations and Domino servers or between two Domino servers is the Notes remote procedure call
(NRPC) service.

Network protocols for NRPC communication

To communicate, two computers must run the same network protocol and software driver. For dialup
connections, Lotus Domino uses its own X.PC protocol natively; Notes and Domino also support PPP
using either Microsoft Dialup Networking (DUN) or Remote Access Service (RAS) for network dialup. In

11
addition, you can use any IETF-compliant PPP communications server to dial into the network on which
the Domino server resides or though which the server can be accessed.

For more information on dialup connections, see the chapter ″Setting Up Server-to-Server Connections.″

On LANs, Lotus Domino is compatible with the TCP/IP and NetBIOS over the lower transport IP For
NetBIOS connections to work, both Notes workstations and Domino servers must use the same lower
transport.

For detailed information on which protocols are compatible with Lotus Domino for each supported
operating system, see the Release Notes.

Notes network ports

During the Server Setup program, Domino provides a list of Notes network ports based on the current
operating system configuration. If these ports are not the ones you want to enable for use with the
Domino server, you can edit the list during setup.

Because each network protocol consumes memory and processing resources, you might want to exclude
one or more ports and later remove the associated protocol software from the system.

In TCP/IP and NetBIOS, you can install multiple network interface cards (NICs) and enable additional
Notes network ports for each protocol, using the NOTES.INI file to bind each port to a separate IP
address or NetBIOS LANA number.

For more information, see the topic ″Adding a network port on a server″ later in this chapter.

Notes named networks

Consider Notes named networks in your planning. A Notes named network (NNN) is a group of servers
that can connect to each other directly through a common LAN protocol and network pathway -- for
example, servers running on TCP/IP in one location. Servers on the same NNN route mail to each
another automatically, whereas you need a Connection document to route mail between servers on
different NNNs.

When you set up Server documents, be sure to assign each server to the correct NNN. Lotus Domino
expects a continuous connection between servers that are in the same NNN, and serious delays in routing
can occur if a server must dial up a remote LAN because the remote server is inadvertently placed within
the NNN. Also bear in mind that the Notes Network field for each port can contain only one NNN
name, and no two NNN names can be the same.

NNNs affect Notes users when they use the Open Database dialog box. When a user selects Other to
display a list of servers, the servers displayed are those on the NNN of the user’s home server for the
port on which the Notes workstation communicates with the home server. Also, when users click on a
database link or document link, if a server in their home server’s NNN has a replica of that database,
they can connect to the replica.

Note: If a server is assigned to two NNNs in the same protocol, as in the case where the server has two
Notes network ports for TCP/IP, a Notes workstation or Domino server connecting to that server uses
the NNN for the port listed first in the Server document.

Resolving server names to network addresses in NRPC

Communications between Lotus Notes and Lotus Domino run over the NRPC protocol on top of each
supported LAN protocol. When a Notes workstation or Domino server attempts to connect to a Domino
server over a LAN, it uses a combination of the built-in Notes Name Service and the network protocol’s
name-resolver service to convert the name of the Domino server to a physical address on the network.

12 Lotus Domino Administrator 7 Help

The Notes Name Service resolves Domino common names to their respective protocol-specific names.
Because the Notes Name Service resolves common names by making calls to the Domino Directory, the
service becomes available to the Notes workstation only after the workstation has successfully connected
to its home (messaging) server for the first time. (The protocol name-resolver service normally makes the
first connection possible.) When the Notes workstation makes a subsequent attempt to connect to a
Domino server, the Notes Name Service supplies it with the Domino server’s protocol-specific name --
that is, the name that the server is known by in the protocol’s name service -- which is stored in the
protocol’s Net Address field in the Server document. The protocol’s name-resolver service then resolves
the protocol-specific name to its protocol-specific address, and the workstation is able to connect to the
server.

Note: When resolving names of Domino servers that offer Internet services, Lotus Notes uses the
protocol’s name-resolver service directly.

How name resolution works in NRPC

A Notes workstation or Domino server follows these steps to resolve the name of the Domino server to
which it is trying to connect over NRPC.

Note: If the Net Address field in the Server document contains a physical address -- a practice that is not
recommended in a production environment-- the Notes Name Service performs the resolve directly, thus
placing the burden of maintaining physical address changes on the Domino administrator.
1. If the workstation/server has a Connection document for the destination server that contains the
protocol-specific name, the workstation/server passes the protocol-specific name to the protocol’s
name-resolver service. If the Connection document contains a physical address, the Notes Name
Service performs the resolve directly. Normal-priority Connection documents are checked first, and
then low-priority Connection documents.

Note: Unlike in Server documents, adding physical addresses in Connection documents is not
discouraged, since only the local workstation/server uses the Connection document.
2. To determine if the destination server’s protocol-specific name is cached, the workstation checks the
Location document and the server checks its own Server document. If the name is cached, the
workstation/server uses the last-used Notes network port to determine the protocol and passes this
value to the protocol’s name-resolver service.
3. If the protocol-specific name is not cached, one of the following occurs, based on the list order of
enabled Notes network ports:
v For a Notes workstation connected to the home (messaging) server, Notes gives the common name
of the destination Domino server to the home server, which looks in the Domino Directory for the
Server document of the destination server. The home server locates the contents of the Net Address
field for the Notes named network that the Notes workstation has in common with the destination
server and passes this name to the protocol’s name-resolver service. If the workstation and the
destination server are in the same Domino domain but not in the same Notes named network, the
home server locates the names of each protocol that the workstation has in common with the
destination server and passes each to the appropriate protocol until a resolve is made. If the Notes
workstation can’t access its home server, it connects to its secondary Notes name server, which
carries out the same actions as the home server.
v For a Domino server, Domino checks the Server document for the destination server, locates the
contents of the Net Address field for the Notes named network that the Domino server has in
common with the destination server, and passes this name to the protocol’s name-resolver service.
If the destination server is in the same Domino domain as the Domino server, but not in the same
Notes named network, the Domino server locates the protocol name of each protocol that it has in
common with the destination server and passes each to the appropriate protocol until a resolve is
made.
4. If Steps 1 through 3 do not produce the server’s network address, the workstation/server offers the
Domino common name of the destination server to the name-resolver service of each protocol, based
on the order of the enabled network ports in the Server document.
Chapter 2. Setting Up the Domino Network 13
Network security
Physical network security is beyond the scope of this book, but you must set it up before you set up
connection security. Physical network security prevents unauthorized users from breaking through the
network and using one of the operating system’s native services -- for example, file sharing -- to access
the server. Physical network security also comes into play when any data is exposed, as the potential
exists for malicious or unauthorized users to eavesdrop both on the network where the Domino system
resides and on the system you are using to set up the server.

Network access is typically controlled using network hardware -- such as filtering routers, firewalls, and
proxy servers. Be sure to enable rules and connection pathways for the services that you and others will
access.

Newer firewall systems offer virtual-private-network (VPN) services, which encapsulate the TCP/IP
packet into another IP wrapper where the inner TCP/IP packet and its data are encrypted. This is a
popular way to create virtual tunnels through the Internet between remote sites. If you want to have the
Domino server access both a private VPN and the Internet for SMTP mail, make sure your solution is
able to handle full TCP data packets and that it allows dual connections. If not, the Domino server
system may require a second NIC to work around limitations of the VPN solution.

For more information, see the chapter ″Controlling Access to Domino Servers.″

NRPC and Internet connection security

To control connection access, you typically use a network hardware configuration, such as a firewall,
reverse proxy, or Domino passthru server, to which you can authorize connections and define access to
network resources.

In addition, you can encrypt all connections by service type. Encrypting connections protects data from
access by malicious or unauthorized users. To prevent data from being compromised, encrypt all Domino
and Notes services that connect to public networks or to networks over which you have no direct control.
Encrypting the connection channel prevents unauthorized users from using a network protocol analyzer
to read data.

To encrypt NRPC network traffic, use the Notes port encryption feature. For traffic over Internet
protocols, use SSL. For both NRPC and Internet protocols, you can enforce encryption at the server for all
inbound and outbound connections. In the case of the Notes client, you can also enforce encryption on all
outbound connections, even if the server to which you are connecting allows unencrypted connections.

Because encryption adds additional load to the server, you may want to limit the services for which the
server uses encryption. Other ways to minimize the load that encryption puts on the system include:
v Using an additional Domino server acting as a passthru server for NRPC connections
v Using a reverse proxy to manage authentication and encryption outside of Domino servers when using
SSL
v Removing unnecessary or unused protocols or services on the server system as well as Domino server
services
For more information, see the chapters ″Installing and Setting Up Domino Servers″ and ″Setting Up
SSL on a Domino Server.″

Using a Domino passthru server as a proxy

A proxy is a system that understands the type of information transmitted -- for example, NRPC or
HTTP-format information -- and controls the information flow between trusted and untrusted clients and
servers. A proxy communicates on behalf of the requester and also communicates information back to the

14 Lotus Domino Administrator 7 Help

requester. A proxy can provide detailed logging information about the client requesting the information
and the information that was transmitted. It can also cache information so requesters can quickly retrieve
information again.

A proxy stops direct access from an untrusted network to services on a trusted network. If an application
proxy is in use, then application-specific heuristics can be applied to look at the connections from the
untrusted networks and determine if what is being requested is legal or safe.

An application proxy resides in the actual server application and acts as an intermediary that
communicates on behalf of the requester. An application proxy works the same as a packet filter, except
the application proxy delivers the packet to the destination. An application proxy can be used with any
protocol, but it is designed to work with one application. For example, an SMTP proxy understands only
SMTP.

A circuit-level proxy is similar to an application proxy, except that it does not need to understand the
type of information being transmitted. For example, a SOCKS server can act as a circuit-level proxy. You
can use a circuit-level proxy to communicate using Internet protocols with TCP/IP -- that is, IMAP,
LDAP, POP3, SMTP, IIOP, and HTTP, as well as Internet protocols secured with SSL.

HTTP is a special case. In Domino, when the HTTP Connect method is used by an HTTP proxy,
applications using other protocols can also use the HTTP proxy, but they use it as a circuit-level proxy,
not as an application proxy. SSL uses the HTTP Connect method to get through an application proxy
because the data is encrypted and the application proxy cannot read the data. HTTPS (HTTP and SSL)
use both the HTTP proxy and the Connect method, which implies that the HTTP proxy is a circuit-level
proxy for HTTPS. The same method is used to get NRPC, IMAP, and other protocols through the HTTP
proxy.

You can set up a Domino passthru server as an application proxy for NRPC. A passthru server provides
all levels of Notes and Domino security while allowing clients who use dissimilar protocols to
communicate through a single Domino server. The application proxy does not allow Internet protocols --
for example, HTTP, IMAP, and LDAP -- to use a Domino passthru server to communicate, however. For
Internet protocols, you can use an HTTP proxy with the HTTP Connect method to act as a circuit-level
proxy.

A Notes client or Domino server can also be a proxy client and interoperate with either passthru (NRPC
protocol only) or as a SOCKS or HTTP tunnel client (for NRPC, POP3, LDAP, IMAP, and SMTP
protocols). You set this up in the Proxy setting in the client Location document.

To set up a Domino passthru server as an application proxy

When you set up an application proxy, make sure the following Domain Name System (DNS) services are
correctly configured:
v The databases db.DOMAIN and db.ADDR, which DNS uses to map host names to IP addresses, must
contain the correct host names and addresses.
v Hosts files must contain the fully qualified domain name of the servers.

If you are using the Network Information Service (NIS), you must use the fully qualified domain name
and make sure NIS can coexist with DNS.

For information on configuring these settings, see the documentation for your network operating system.

You must first connect the server to the untrusted network -- for example, the Internet -- and then set up
Notes workstations and Domino servers to use the passthru server as a proxy when accessing services
outside the trusted network.

To set up a workstation or server to use the passthru server, you must specify the passthru server in the
Location document for a workstation and in the Server document for a server.
Chapter 2. Setting Up the Domino Network 15
For more information on connecting a server to the Internet and passthru servers, see the chapter ″Setting
Up Server-to-Server Connections.″

TCP/IP security considerations

In a TCP/IP network, configure all Domino servers to reject Telnet and FTP connections. Furthermore, do
not allow file system access to the Domino server or the operating system on which it runs, unless you
are sure you can properly maintain user access lists and passwords and you can guarantee a secure
environment.

If you use the Network File System (NFS) without maintaining the password file, users can breach
security by accessing files through NFS instead of through the Domino server. If this ″back door″ access
method is needed, isolate the network pathway on a LAN NIC and segment, and make sure that the
ability to access files through NFS is exclusive to this isolated secure network.

Mapped directory links and Domino data security

To ensure data security, do not create a mapped directory link to a file server or shared Network
Attached Storage (NAS) server for a Domino server. These links can cause both database corruption and
security problems.

Database corruption
If the network connection fails while the Domino server is writing to a database on the file server or
shared NAS server, the database can become corrupted. In addition, the interdependence of the file
sharing protocols -- Server Message Block (SMB), Common Internet File System (CIFS), and Network File
System (NFS) -- and the remote file system can affect the Domino server’s performance. Domino
sometimes needs to open large numbers of remote files, and low latency for read/write operations to
these files is desirable.

To avoid these problems on Domino servers, consider doing one or more of the following:
v Create an isolated network and use cut-through (non-buffering) layer-2 switches to interconnect the
Domino server to the NAS system.
v Limit access to the NAS system to the Domino server.
v Reduce the number of hops and the distance between hops in the connection pathways between the
Domino server and the storage system.
v Use a block protocol instead of a file protocol.
v Use a private storage area network (SAN) instead of a shared NAS system.
v Avoid creating any file-access contention between Domino and other applications.

To avoid problems with Notes workstations, consider doing the following:

v Locate Notes workstations so that they are not accessing a remote file server or NAS system over a
WAN.
v To minimize the risk of database corruption because of server failure when a Notes client’s Domino
data directory is on a file server or NAS server, evaluate the reliability of the entire network pathway
as well as the remote system’s ability to maintain uninterrupted sessions to the Notes client over the
file sharing protocols it is using (SMB, CIFS, NFS, NetWare Core Protocol, or AppleShare).
v If a Notes client’s Domino data directory is on a file server or NAS server, remember that only one
user (user session) can have the user data directory files open a time. Lotus Notes does not support
concurrent access to the same ″local″ database by two clients.

Security problems
When ″Encrypt network data″ is enabled, all Domino server and Notes workstation traffic is encrypted.
However, the file I/O between the Domino server and the file server or shared NAS server is not
encrypted, leaving it vulnerable to access by unauthorized users.

16 Lotus Domino Administrator 7 Help

Planning the TCP/IP network
The default TCP/IP configuration for a Domino server is one IP address that is globally bound, meaning
that the server listens for connections at the IP addresses of all NICs on the computer. Global binding
works as long as the computer does not have more than one IP address offering a service over the same
assigned TCP port.

For operating system requirements, see the Release Notes.

The default configuration

Use these topics to plan how to integrate Lotus Domino with the TCP/IP network when the Domino
server has one IP address and is not partitioned:
v NRPC name-to-address resolution over TCP/IP
v Ensuring DNS resolves in TCP protocols

Advanced configurations
Use these topics to plan how to integrate Lotus Domino with the TCP/IP network when the Domino
server has more than one IP address or is partitioned:
v Advanced Domino TCP/IP configurations
v Partitioned servers and IP addresses
v Ensuring DNS resolves in advanced TCP/IP configurations

Changing a server’s IP address

Use this topic to change a server’s IP address:
v Changing a server’s IP address

Moving to IPv6
This topic provides the information you need if your company is migrating to the IPv6 standard:
v IPv6 and Lotus Domino

NRPC name-to-address resolution over TCP/IP

In the TCP/IP protocol, the method most commonly used to resolve server names to network addresses
is the Domain Name System (DNS), an Internet directory service developed both to allow local
administrators to create and manage the records that resolve server names to IP addresses and to make
those records available globally. While the POP3, IMAP, LDAP, and HTTP services use DNS directly, the
NRPC service uses a combination of the Notes Name Service and DNS to resolve server names to
network addresses.

For background information on how the Notes Name Service works with name-resolver services such
DNS, see the topic ″Resolving server names to network addresses in NRPC″ earlier in this chapter.

Within DNS, ″domain″ refers to a name space at a given level of the hierarchy. For example, the .com or
.org in a Web URL represents a top-level domain. In a domain such as acme.com, a DNS server -- that is,
a server running DNS software -- in the Acme company stores the records for all Acme servers, and an
administrator at Acme maintains those records.

When you set up a Notes workstation on the TCP/IP network, you normally rely on DNS to resolve the
name of the workstation’s Domino home server the first time the workstation tries to connect to it. As
long as the Notes workstation and Domino home server are in the same DNS domain level, DNS can
accomplish the resolve.

Chapter 2. Setting Up the Domino Network 17

When to edit the Net Address field in the Server document
The default format for a server’s TCP/IP network address in Lotus Domino is its fully qualified domain
name (FQDN) -- for example, app01.acme.com -- based on the DNS record and the IP address references
in the system’s TCP/IP stack. When a Notes workstation or Domino server requests this name, the
TCP/IP resolver passes it to DNS, and DNS resolves the name directly to the IP address of the
destination server, regardless of the DNS domain level of the requesting system.

If you do not want to enter the FQDN in the Net Address field, you can change it to the simple IP host
name -- for example, app01 -- either during server setup or later by editing the Server document. For
example, you might use the simple IP host name if you are setting up multiple TCP ports for NRPC, a
configuration in which using the FQDN for each network address can cause connection failures if the
Notes Name Service returns the FQDN for the wrong TCP port. In this case, using the simple IP host
name ensures that DNS does a lookup in all domain levels within the scope of the domains defined in
the requesting system’s TCP/IP stack settings.

CAUTION:
In a production environment, do not use IP addresses in Net Address fields. Doing so can result in
serious administrative complications if IP addresses change or if Network Address Translation (NAT)
connections are used, as the values returned by the Notes Name Service will not be correct.

Secondary name servers

To ensure that the Notes Name Service is always available over TCP/IP, when you set up a Notes user,
you can designate a Domino secondary name server that stands in for the home server in these
situations:
v The user’s home server is down.
v The user’s home server is not running TCP/IP.
v The user’s home server cannot be resolved over TCP/IP.

Note: In companies using multiple DNS domains, a Domino secondary name server ensures that a Notes
workstation can connect with its home server even when the home server is in a different DNS domain.
You can use policies to automate the setup of secondary name servers.

For more information, see the topic ″Ensuring DNS resolves in NRPC -- Best practices″ later in this
chapter. For information on policies, see the chapter ″Using Policies.″

Special case: The passthru server

By connecting to a passthru server, Notes users can access servers that do not share a network protocol
with their systems. If both the Notes workstation and destination server are in a different Domino
domain from the passthru server, it may not be possible for the passthru server to resolve the name of
the destination server. In this case, do one of the following:
v On the Notes workstation, create a Connection document that includes the IP address of the
destination server.
v On the passthru server, create a Connection document to the destination server.
For more information on passthru servers, see the chapter ″Setting Up Server-to-Server Connections.″

Internal alternatives to DNS

If you don’t use DNS at your site or if a Domino server is not registered with DNS (as is sometimes the
case if the server offers Internet services), use one of these methods to enable each Notes workstation and
Domino server to perform name resolution locally. Keep in mind that the upkeep required for both of
these approaches is considerable.
v Place a hosts file, which is a table that pairs each system name with its IP address, on every system
that needs private access. Set up each system so that it accesses the hosts file before accessing DNS.
v Create a Connection document that contains the destination server’s IP address on every Notes
workstation and Domino server that needs to access that server.

18 Lotus Domino Administrator 7 Help

 Tip: Use policies to automate the setup of Connection documents for Notes users. Even if you use
DNS, you should set up Connection documents for Notes users in locations from which they have
difficulty accessing the DNS server.
For more information on policies, see the chapter ″Using Policies.″

Alternative IP name services

Microsoft networking services offers four additional methods of IP address resolution. These methods are
not as reliable as traditional DNS and hosts files and can cause name and address confusion. For best
results, do not use these methods when also using the Notes network port for TCP/IP.
v Direct NetBIOS broadcast -- The system sends out a name broadcast message so that all of the systems
on the local network segment can register the name and IP address in their name cache. If you must
use NetBIOS over IP and use Domino with both the NetBIOS and TCP/IP port drivers, avoid
name-resolution problems by giving the Domino server and the system different names.

Master Browser cache (for NT domains or SAMBA servers) -- Collects broadcasted names and IP
addresses and publishes them across the NT domain to other Master Browser systems for Windows ®
systems to access in their name lookups.
v Windows Internet Name Service (WINS) -- Uses NetBIOS broadcasts. Unlike DNS, which is static in
nature, WINS is dynamic. Note that the TCP/IP stacks of Macintosh and UNIX client systems may not
be able to access the WINS server.
v LAN Manager Hosts (LMHosts) -- A static hosts file method.

CAUTION:
On a Windows system, the combination of the system’s native NetBIOS over IP name-resolver service
and DNS can cause name resolution failure for the Domino server name.

For information on avoiding this problem, see the topic ″Server name-to-address resolution over
NetBIOS″ later in this chapter.

Ensuring DNS resolves in TCP protocols

When you register a new Domino server, you specify a common name for it. Within a Domino
hierarchical name, the common name is the portion before the leftmost slash. For example, in the name
App01/East/Acme, the common name is App01. The common name, not the hierarchical name, is the
name that the Domino server is known by in DNS.

Note: When you choose a common name for a Domino server that uses DNS, use only the characters 0
through 9, A through Z, and the dash (-). Do not use spaces or underscores.

Note: The DNS names held in Lotus Notes and Lotus Domino are not case sensitive; Notes workstations
and Domino servers always pass DNS names to DNS in lowercase.

You can avoid problems and extra work if you consider the DNS configuration, as well as the effect of
other protocol name-resolver services, when you choose the format for the common name of the Domino
server.

To avoid name-resolution problems that affect all TCP services on Windows systems, see the topic
″Ensuring DNS resolves on Windows systems -- All TCP protocols.″

For procedures to help you avoid DNS problems in NRPC, see these topics:
v Ensuring DNS resolves in NRPC -- Best Practices
v Ensuring DNS resolves in NRPC -- Alternative practices
v Ensuring DNS resolves in NRPC -- A practice to use with caution

Chapter 2. Setting Up the Domino Network 19

Note that these procedures apply only to servers handling communications between Lotus Notes and
Lotus Domino (NRPC services). If you administer servers that provide Internet services such as HTTP,
SMTP, POP3, or LDAP, you can skip these topics, as these services use DNS directly.

For naming requirements when using Domino Off-Line Services (DOLs) or Domino Web Access, see the
chapter ″Installing and Setting Up Domino Servers.″

Ensuring DNS resolves on Windows systems -- All TCP protocols

If a Domino server is a Windows system, often two name services exist on the system -- NetBIOS over IP
and DNS. If you assign the same name to both the Domino server and the system, client applications that
use either the Notes Name Service or DNS can encounter name-space ghosting between the two names.
In other words, because the NetBIOS record for a system’s host name has already been found, the name
resolving process ends and the DNS record for the Domino server on that system is never found.

Note: For a Domino server on Windows 2000, problems occur only if you enable name services for
NetBIOS over IP in order to join an NT domain using Server Message Blocks (SMB).

To prevent this problem:

1. Add a preface such as W2K- to the system name, using the Network Identification tab on the System
Properties dialog box.
2. Create an A record (or, for IPv6, AAAA record) in DNS for the system name. The IP address is the
same as the one for the Domino server.
3. Create a CNAME record in DNS for the Domino server’s name, linking it to the system name.

For example, for the Domino server BosMail02/Acme, the common name is BosMail02. You name the
system NT-BosMail02. You create an A record in DNS for NT-BosMail02.acme.com and a CNAME record
for BosMail02.acme.com, linking it with NT-BosMail02.acme.com.

Ensuring DNS resolves in NRPC -- Best practices

The following procedures provide the best name-resolution practices for a Domino server using the
default NRPC configuration on a TCP/IP network (one Notes network port for TCP/IP). These
procedures address the following DNS configurations:
v One DNS domain
v Multiple DNS domain levels
If your TCP/IP configuration has multiple Notes network ports for TCP/IP, see the topic ″Ensuring
DNS resolves in advanced TCP/IP configurations″ later in this chapter.

When you have one DNS domain: If your company uses only one DNS domain, doing the following
eliminates the need for CNAME records in DNS:
1. Assign the same name as both the Domino server common name and the simple IP host name
registered with DNS.
2. Make sure the Net Address field on the Server document contains the server’s FQDN.
3. Create an A record (or, for IPv6, AAAA record) in DNS.

For example, you set up the Domino server App01/Engr/Acme. Thus, you register the server with DNS
as app01, the server’s common name. The Net Address field in the Server document contains
app01.acme.com (the server’s FQDN), and the A record is: app01.acme.com IN A 192.168.10.17.

When you have multiple DNS domain levels: If your company uses multiple DNS domain levels -- for
example, when each country in which a multinational company has offices is a subdomain in DNS --
doing the following eliminates the need for multiple CNAME records in DNS and ensures that DNS
lookups always work, regardless of the DNS domain level of the user’s system:
1. Assign the same name as both the Domino server common name and the simple IP host name.
2. Make sure the Net Address field on the Server document contains the server’s FQDN.
20 Lotus Domino Administrator 7 Help
3. Create an A record (or, for IPv6, AAAA record) in DNS.
4. If users’ systems are in a different DNS domain than that of their home server or in a DNS
subdomain of their home server’s domain, set up a secondary name server. Place this secondary name
server on the same physical network as the users’ systems or on a network that the users can access.

Note: Register the secondary name server in the root of the company’s DNS domain.
5. Set up all Notes users or a subset of users affected by Step 4, or set up an individual Notes user.
For more information on setting up groups of users, see the chapter ″Using Policies.″ For more
information on setting up an individual Notes user, see the topic ″Setting up a secondary name
server″ later in this chapter.

For example, you register the Domino server ParisMail01/Sales/Acme with DNS as
parismail01.france.acme.com. Parismail01 is the home server for some users in the DNS subdomain
spain.acme.com. You set up a secondary name server, Nameserver/Acme, register it with DNS as
nameserver.acme.com, and ensure that the Location documents of users who need a secondary name
server point to this server.

When a user in spain.acme.com attempts a first connection with the home server
(parismail01.france.acme.com), the connection fails because the DNS subdomain for spain.acme.com has
no records for the subdomain france.acme.com. Notes then connects successfully with the secondary
name server (nameserver.acme.com), since the DNS subdomain for spain.acme.com does include the
records for acme.com. When the secondary name server supplies the Notes workstation with the FQDN
from the Net Address field in the Server document for ParisMail01, DNS resolves the FQDN to an IP
address, and the user can access mail.

As long as all Server documents in the Domino domain have the TCP/IP network address in FQDN
format, this approach allows any Notes workstation or Domino server to locate any Domino server,
regardless of its DNS domain level.

Ensuring DNS resolves in NRPC -- Alternative practices

The following procedures provide alternative name-resolution practices for a Domino server using the
default NRPC configuration on a TCP/IP network (one Notes network port for TCP/IP).

Domino server names that differ from their DNS names: When your name scheme for Domino servers
is different than that for DNS, use one of the following methods to translate the Domino server’s name to
the host name:
v Create a local Connection document on each Notes client and Domino server that needs to connect to
the Domino server, and enter the FQDN for the system that hosts the Domino server in the Net
Address field. For example, for the Domino server named App01/Sales/Acme on the system registered
with DNS as redflier, enter redflier.acme.com in the Net Address fields of the Connection documents.
v Use an alias (CNAME) record in DNS to link the Domino server common name to the simple IP host
name. For example, for the Domino server App01/Sales/Acme on the system registered with DNS as
redflier, use a CNAME record to link the name App01 to the name redflier. When a Notes workstation
first accesses this server, it obtains the host name from the Net Address field of the Server document
and caches it, thereby making future connections faster.

IP addresses in Connection documents: In situations in which you don’t want to use any name-resolver
service -- such as bringing up a new server system that you don’t want known yet, or having a server on
the Internet that you want accessible but for which you can’t use DNS -- create Connection documents
that directly tell Notes workstations or Domino servers how to access this Domino server by using the
server’s IP address in the documents’ Net Address fields.

Network Address Translation (NAT): NAT is a method of translating an IP address between two
address spaces: a public space and a private space.

Chapter 2. Setting Up the Domino Network 21

Public addresses are assigned to companies by the Internet Corporation of Assigned Names and
Numbers (ICANN) or leased from the company’s ISP/NSP. Public addresses are accessible through the
Internet (routable) unless firewalls and isolated networks make them inaccessible.

Private addresses are IP address spaces that have been reserved for internal use. These addresses are not
accessible over the Internet (non-routable) because network routers within the Internet will not allow
access to them.

The following address spaces have been reserved for internal use. It is best to use these IP addresses and
not make up your own.
v Class A: 10.0.0.0 to 10.255.255.255
v Class B: 127.16.0.0 to 172.31.255.255
v Class C: 192.168.0.0 to 192.168.255.255

For example, users inside a company access the Domino server based on its assigned IP address, which is
a private address (192.168.1.1). Internet users must access the Domino server through a NAT router,
which converts the private address to one of its static public addresses (130.20.2.2). Therefore, a Notes
client accessing the server from the Internet uses the public address.

Ensuring DNS resolves in NRPC -- A practice to use with caution

The following practice, if followed precisely, should ensure good DNS resolves in NRPC for companies
with multiple DNS domain levels, but might result in extra work if the infrastructure changes. Using this
practice has the following disadvantages:
v You can never assign more than one IP address in DNS to the Domino server.
v If the FQDN changes, the Domino server name will not match the FQDN, thus invalidating the DNS
resolve. You will then need to create a new server and migrate users to it.
v If you use network address translation (NAT), the server’s FQDN must be identical in both instances of
DNS (internal and external shadow DNS).
v You cannot use other network protocols, as many of them use flat network name services, and those
that use hierarchical name systems will not function unless the name hierarchy is exactly the same.
v Diagnosing connectivity issues can be much harder.

When you have multiple DNS domain levels: If your company uses multiple DNS domain levels -- for
example, when each country in which a multinational company has offices is a subdomain in DNS -- do
the following:
1. Use the server’s FQDN as the Domino server common name.
2. Create an A record (or, for IPv6, AAAA record) in DNS.

For example, if you register a server with DNS as app01.germany.acme.com, you can also assign the
Domino server’s common name as app01.germany.acme.com. In this case, the server’s Domino
hierarchical name might be app01.germany.acme.com/Sales/Acme.

Changing a server’s IP address

Before changing a server’s IP address, consider the following potential problems:
v Problem 1: If the server’s previous IP address is stored in any Server Connection documents or Server
documents, when that server’s IP address is changed in DNS and on the server itself, these old Server
Connection documents or Server documents will cause connection failures.
Solution: Use the DNS fully-qualified domain name, not the IP address, as the network address stored
in the Server Connection documents and Server documents. You can then change the server’s IP
address in DNS without having to change the Server Connection documents or Server documents.
Changing the network address from the IP address to the DNS name can be done at any time.

22 Lotus Domino Administrator 7 Help

 To modify the Server Connection document, open the Server Connection document. On the Basics tab,
if Local Area Network is chosen in the Connection Type field, click the Advanced tab and check the
entry in the Destination server address field. If the field contains the server’s IP address, delete the IP
address and enter the fully-qualified domain name. Remember, both the server-based Domino
Directory and the client-based Address Book can have this problem.
To modify the Server document, click the Ports tab for the Net Address for TCP ports. If the field
contains the IP address, change the entry to the proper fully-qualified domain name.
v Problem 2: The algorithm that all Notes clients and Domino servers use to connect to a Domino server
can cache the IP address that was used to successfully connect to a server. If this cache entry exists,
when the server’s IP address is changed, the old cached address may be used causing the connection to
fail.
It is important to understand why this caching is performed. Notes supports a wide range of
networking technologies implemented as Notes ports. If Notes attempts to connect to a server that is
down, and tries every possible technology (Notes port) using every possible Name to Address
resolution tool until each one fails, the connection attempt takes a long time. To prevent the long delay
that would occur in reporting the error when the server goes down, Notes has implemented two server
connection algorithms. One algorithm is fast, using cached addresses, and the other is slower, using the
complete algorithm which bypasses the cache when it fails.
The following solutions can resolve this problem. Solutions are listed in the order in which they should
be used.
Solution 1: The fast connection algorithm is only used if the client or server had successfully connected
to the same server earlier in the day. If a successful connection has not yet occurred today, the slower
algorithm is used and the cache is bypassed. To avoid this problem, change a server’s IP address late in
the evening, but before midnight. This is the easiest solution because it is transparent to the user and
involves no help desk calls or any action on the user’s part.
Solution 2: The cache is rewritten following successful connection to the server. The cached address is
the address entered by the user, not the resolved IP address. Therefore, if users have the habit of
connecting to servera/acme by entering servera.acme.com, the cached address will be
servera.acme.com, not 1.2.3.4 and the problem will not occur.
Solution 3: The cache is rewritten following any successful connection to the server. If a user tries to
connect to the server by its Notes name, for example, servera/acme, the stale cache entry is used. If the
user tries to connect using the server’s fully-qualified domain name, for example, servera.acme.com,
then the cache will not be used, the new address will be fetched from DNS and the correct new
address entered in the cache. To make this successful connection using the fully-qualified domain name
of the server, use the File - Database - Open menu command or the File - Preferences - User
Preferences - Ports - Trace service menu selections.
Solution 4: The cache is stored in the following Notes fields in the Location documents for the client
and in the Server document for the server:
– $Saved Addresses
– $SavedDate
– $SavedPorts
– $SavedServers
– $SavedTriedDate
If these fields are deleted from the Location or Server document, for example, using a formula agent,
the old IP addresses in the cache cannot be used. This method can be confusing because the Notes
items are rewritten when the client or server exists from an in-memory copy. Therefore, to use this
method to clear the cache for the client, create the agent in the Local Address Book, and then switch to
the Island Location document and exit the client. Restart the client, and then run the agent to clear the
cache for all other locations. Switch to your normal location.
Sample agent formula language code to clear the cache:
– FIELD $SavedAddresses:=@DeleteField;
– FIELD $SavedDate:=@DeleteField;

Chapter 2. Setting Up the Domino Network 23

 – FIELD $SavedPorts:=@DeleteField;
– FIELD $SavedTriedDate:=@DeleteField;
– FIELD $SavedServers:=@DeleteField;
– SELECT @All
Solution 5: Disable the use of the cached addresses by using the following NOTES.INI setting:
DONT_USE_REMEMBERED_ADDRESSES=1
If the client uses multiple or slow port technologies, we discourage the use of this technique because it
can cause a long delay in reporting that a server is down.

IPv6 and Lotus Domino

Because support for IPv6 by hardware and operating system suppliers and the Internet is still in the early
stages, moving to the IPv6 standard will be a gradual process for most organizations. In Lotus Domino,
you can enable IPv6 support for SMTP, POP3, IMAP, LDAP, and HTTP services on AIX®, Solaris®, and
Linux systems.

Domino supports both IPv6 and IPv4. Thus, if an IPv6-enabled Domino server encounters an IP address
in IPv4 format, the Domino server can still make the connection to that address. When attempting to
connect to a server, Domino tries to resolve all IP addresses for a server until one works. This allows a
server to have both an IPv4 address and an IPv6 address. Domino caches the last successful address for a
server and uses only the cached address to quickly search for a server. If you do not want to use only the
cached address, enter the NOTES.INI setting DONT_USE_REMEMBERED_ADDRESSES=1.

In DNS, records that store IPv6 addresses are called AAAA records. After you enable IPv6 on a Domino
server and add the server’s AAAA record to DNS, another IPv6-enabled Domino server can connect to it
only over IPv6. Servers that don’t support IPv6 can run Domino with IPv6 support disabled, which is the
default. These servers can successfully connect to IPv6-enabled Domino servers only if the DNS for the
IPv6 servers contain A records.

Using IPv6 in a Domino network

For best results when using IPv6 with Domino servers, set up network devices in the network pathway
to connect directly with native IPv6, rather than tunnel through the IPv4 network.

Enabling IPv6 on Notes and Domino 7

To enable IPv6 on Notes and Domino 7, add the setting TCP_ENABLEIPV6=1 to the NOTES.INI file on
both the Notes client and the Domino server.

How Lotus Domino decides whether to connect over IPv6 or IPv4

A Domino server evaluates the address format and then, based on that information, makes an IPv4 or an
IPv6 connection.

Address format Server response

IPv4 Makes an IPv4 connection.
IPv4 address mapped to IPv6 Attempts to make an IPv6 connection and waits for the TCP/IP software
to make either an IPv6 or IPv4 connection, depending on the remote
system’s TCP/IP stack.
IPv6 Makes an IPv6 connection.
Server name Uses DNS to resolve the name:
v If only an A record is found, connects over IPv4.
v If only an AAAA record is found, connects over IPv6 or waits for the
TCP/IP software to make the connection.
v If both an A record and AAAA record are found, uses the AAAA
record.

24 Lotus Domino Administrator 7 Help

Using IPv6 address formats with Domino and Notes
You can use an IPv6 address as a string anywhere that an IPv4 address as a string can be used; however,
IPv4 addresses with port numbers are supported by the Notes client and the Web server in the following
format:
1.2.3.4:1352

IPv6 addresses contain a varying number of colons; therefore, the syntax shown above can not be used
with IPv6 addresses. To be consistent with a proposed format for Web servers, if the port number is
included with an IPv6 address, the address must be enclosed in square brackets.

The following address formats can be used wherever address strings are supported, for example, in
Server documents, in the Open Database dialog box, or in the Port Trace dialog box.
9.95.77.78
9.95.77.78:1352
[9.95.77.78]
[9.95.77.78]:1352
fe80::290:27ff:fe43:16ac
[fe80::290:27ff:fe43:16ac]
[fe80::290:27ff:fe43:16ac]:1352

Installing the IPv6 stack

Install the IPv6 stack before IPv6 will work for any software. To install the IPv6 stack, follow the
instructions provided for by your platform’s vendor. The instructions in this section contain general
guidelines for many platforms, but you need to follow the instructions provided by the manufacturer of
your platform.

Prior to installing the IPv6 stack, check to see if IPv6 is configured on your system by using the following
commands according to platform:

Platform Commands
Microsoft Windows platforms ipconfig /all
All other platforms ifconfig -a

After installing IPv6, use that same command to verify that IPv6 is available.

Microsoft Windows 2003 server platform: To enable IPv6 on the Microsoft Windows 2003 server
platform, use
netsh interface ipv6 install

Link local address automatically assigned

Microsoft Windows XP client: To enable IPv6 on the Microsoft Windows XP client, use
netsh interface ipv6 install

Link local address automatically assigned

AIX platform: To enable IPv6 on the AIX platform, enter

ifconfig le0 inet6 plumb up

Link local address automatically assigned

Solaris platform: To enable IPv6 on the Solaris platform, enter

ifconfig le0 inet6 plumb up

Chapter 2. Setting Up the Domino Network 25

Link local address automatically assigned

United Linux platform: IPv6 is enabled by default on the United Linux platform.

Zones: In the IPv6 standard, when link local address and site local address are used, an additional
parameter is required to specify the interface on which the address is valid. In the API, this additional
parameter is called the scope_id; in user documentation, the parameter is called the zone. In Notes and
Domino 7, use the format address string followed by the percent sign (%) followed by the zone.

On Microsoft Windows, the zone is an integer index into the interface list with the first interface being
zone one.

Note the following information regarding zones:

v Zones are mandatory on Windows for link local addresses.
v Zones are mandatory on Linux for link local addresses.
v Zones are not required on AIX and Solaris.
v A zone is NOT a characteristic of the target system, but rather a characteristic of the source system;
therefore, never attempt to put a zone into DNS, in a hosts file, or in a global data store such as the
Domino Directory.
v If a computer has only a single network interface, you can use the NOTES.INI variable
TCP_DEFAULTZONE to provide a default zone for all link local addresses.

Receiving incoming connections on IPv6 sockets or IPv4 sockets

UNIX platforms receive both IPv4 and IPv6 incoming connections on the same socket. Microsoft
Windows is not capable of receiving both incoming IPv4 and IPv6 connections on the same socket. If IPv6
is disabled, Microsoft Windows only receives IPv4 connections. If IPv6 is enabled and the port is not
bound to an address, only IPv6 connections are received. To receive both IPv4 and IPv6 connections,
define two ports -- one bound to an IPv4 address and one bound to an IPv6 address. This is easily done
for NRPC, but until now, Internet servers only provided support for a single Notes port.

Domino 7 supports two Notes ports for Internet servers. The user interface specifies two Notes port
names in the NOTES.INI variable SMTPNotesPort. For example,
SMTPNotesPort=TCPIP,TCPIP6

There is one restriction. If either of the ports is shut down (stop port tcpip) the Internet servers
momentarily shut down both ports and restart listening on the one remaining port. Also, outbound
connections for any address will succeed on any TCP port. For outbound connections, Domino creates the
proper socket to handle the attempted target address.

Making outbound connections with a TCP port bound to an IP address: When a client or a server
making outbound connections has a TCP port bound to a specific IP address, using the NOTES.INI
setting SMTPNotesPorts= <TCPIPAddress>, the bound port can only make outbound connections of the
type of the bound IP Address. For example, if a server binds the Notes Port TCPIP to an IPV4 address
and the Notes Port TCPIP6 to an IPV6 address, then port TCPIP can only make outbound connections to
IPV4 addresses and port TCPIP6 can only make outbound connections to IPV6 addresses.

In a configuration that includes IPV4 and IPV6 Notes ports bound to IP addresses, the ports listed in the
Connection documents must include all TCP ports over which the connection can possibly be made. For
example, if you create a Server Connection document from serverA to serverB, and serverB’s DNS name
can resolve to both an IPV4 address and an IPV6 address, and you want the connection to work over
IPV4 or IPV6, you must include both ports in the Connection document.

When an IPv4 or an IPv6 socket is created and used: Use the following set of rules to determine
whether to use an IPv4 or IPv6 socket:
v When connecting or listening, if IPv6 is not enabled, always create an IPv4 socket.

26 Lotus Domino Administrator 7 Help

v If connecting or listening with a bound address, use a socket that matches the address type.
v If listening and no address is bound, and if IPv6 is enabled, use an IPv6 socket.
v If listening and no address is bound, and if IPv6 is disabled, use an IPv4 socket.

Note: The address 0 indicates that a listener is willing to listen to any address. Applying the above set of
rules, note the following:
v To create an IPv6 socket that listens to any IPv6 address, do not bind to an address.
v To create an IPv4 socket that listens to any IPv4 address, bind it to address ::ffff:0.0.0.0

On UNIX servers, an IPv6 socket bound to any address accepts all incoming connections, but on
Windows the same socket only listens to incoming IPv6 connections.

On Linux, if one port binds to the ″any″ address and IPv6 is enabled, a second port cannot bind to a
specific IPv4 or IPv6 address. If this is attempted, an ″Address is already in use″ error is returned.

Examples of using NOTES.INI variables with IPv6

This section contains examples of how to set NOTES.INI variables to support various platforms and
configurations when using IPv6. In these examples, support for NRPC and SMTP is configured. The other
Internet servers are configured similarly to SMTP.

Example 1-- No IPv6 support (Applies to all platforms): No change required. IPv6 is off by default.

Example 2 -- UNIX platform supporting all valid IPv4 and IPv6 addresses: TCP_EnableIPv6=1

Example 2 assumes that no ports are bound to any addresses. By default, on UNIX, the single unbound
listening socket is IPv6. The IPv6 socket can receive connections from any IPv4 or IPv6 address.

Example 3 -- Microsoft Windows platform supporting all valid IPv4 and IPv6 addresses:
TCP_EnableIPv6=1

TCPIP=TCP, 0, 15, 0

TCPIP6=TCP, 0, 15, 0

PORTS=TCPIP,TCPIP6

TCPIP_TCPIPADDRESS=0,[::ffff:0.0.0.0]:1352

SMTPNotesPort=TCPIP,TCPIP6

Example 3 assumes that no ports are bound to any addresses. On Microsoft Windows, by default, the
TCPIP6 port is an IPv6 socket because IPv6 is enabled. The TCPIP port is an IPv4 socket, because its
bound address has the IPv4 format. Both listen to all addresses because the bound address is 0. The
SMTPNotesPort variable is required to force the SMTP listener to listen on two sockets -- one for IPv4
and one for IPv6.

Example 4 -- UNIX (but not Linux 2.4) partitioned servers. Each server listens to its assigned IPv4 and
IPv6 addresses only: Each Server:

TCP_EnableIPv6=1

TCPIP=TCP, 0, 15, 0

TCPIP6=TCP, 0, 15, 0

Chapter 2. Setting Up the Domino Network 27

PORTS=TCPIP,TCPIP6

TCPIP_TCPIPADDRESS=0,9.33.162.84:1352

TCPIP6_TCPIPADDRESS=0,[fe80::209:6bff:fecd:5b93]:1352

SMTPNotesPort=TCPIP,TCPIP6

Example 5 -- Microsoft Windows (and Linux 2.4) partitioned servers. Each server listens to its assigned
IPv4 and IPv6 addresses only: Each Server:

TCP_EnableIPv6=1

TCPIP=TCP, 0, 15, 0

TCPIP6=TCP, 0, 15, 0

PORTS=TCPIP,TCPIP6

TCPIP_TCPIPADDRESS=0,9.33.162.84:1352

TCPIP6_TCPIPADDRESS=0,[fe80::209:6bff:fecd:5b93%4]:1352

SMTPNotesPort=TCPIP,TCPIP6

The difference here is that Microsoft Windows and Linux 2.4 require the use of the zone in the address
even for addresses bound to listeners if the address is a link local address. The same effect can also be
achieved as shown in Example 5A.

Examle 5A -- Microsoft Windows and Linux 2.4 partitioned servers. Each server listens to its assigned
IPv4 and IPv6 addresses only: For each server:

TCP_EnableIPv6=1

TCP_DefaultZone=4

TCPIP=TCP, 0, 15, 0

TCPIP6=TCP, 0, 15, 0

PORTS=TCPIP,TCPIP6

TCPIP_TCPIPADDRESS=0,9.33.162.84:1352

TCPIP6_TCPIPADDRESS=0,[fe80::209:6bff:fecd:5b93]:1352

SMTPNotesPort=TCPIP,TCPIP6

Example 6 -- Any client wants to make outbound IPv4 connections: No change required

Example 6A -- A UNIX client (not Linux 2.4) wants to make an outbound IPv6 connection:
TCP_EnableIPv6=1

Connect to an IPv6 address, or to a DNS or hosts file resident name that resolves to an IPv6 address.

28 Lotus Domino Administrator 7 Help

Example 7 -- Microsoft Windows/Linux 2.4 client wants to make outbound connection via IPv6:
TCP_EnableIPv6=1

Connect to an IPv6 address, or to a DNS or hosts file resident name that resolves to an IPv6 address. If
the address is a link local address, it must include the zone, such as fe80::209:6bff:fecd:5b93%4, or the
local NOTES.INI file must contain a default zone, or the zone must be included in the local bound
address. Such addresses must NEVER be stored in DNS, in Server documents, or Connection documents.
If an IPv6-capable computer running Windows XP enables IPv6 and it is DHCP, it will automatically
have its QUAD A record stored in DNS and it is stored without a zone, because the zone is a local
construct. Therefore, the ONLY way to use such a DNS entry is to have a default zone in NOTES.INI.

Example 7A -- Microsoft Windows / Linux 2.4 client wants to make outbound connection via IPv6:
TCP_EnableIPv6=1

TCP_DefaultZone=4

Connect to an IPv6 address, or to a DNS or hosts file resident name that resolves to an IPv6 address. If
the address is a link local address, it need not include the zone, such as fe80::209:6bff:fecd:5b93 because
the zone is defaulted by the NOTES.INI variable.

Example 7B -- Microsoft Windows / Linux 2.4 client wants to make outbound connection via IPv6:
TCP_EnableIPV6=1

TCPIP=TCP, 0, 15, 0

PORTS=TCPIP

TCPIP_TCPIPADDRESS=0,[fe80::209:6bff:fecd:5b93%4]:1352

Connect to an IPv6 address, or to a DNS or hosts file resident name that resolves to an IPv6 address. If
the address is a link local address, it need not include the zone, such as fe80::209:6bff:fecd:5b93 because it
is defaulted by the bound address’s zone.

Enabling Internet protocols on both TCP/IP and TCP/IPV6 ports: Add the following settings to the file,
NOTES.INI:
v ldapnotesport=tcpip,tcpipv6
v imapnotesport=tcpip,tcpipv6
v smtpnotesport=tcpip,tcpipv6
v pop3notesport=tcpip,tcpipv6

Connecting a Notes client to a Domino server via IPv6

1. Install the Domino 7 server and Notes 7 client.
2. Enable IPv6 on both the client and the server by adding the NOTES.INI setting, TCP_ENABLEIP6=1,
to the NOTES.INI files on the Notes client and Domino server:
3. Configure a zone on both the Notes client and the Domino server.
4. On the Domino server, configure the port for IPv4 and the port for IPv6.
5. Launch the Notes client.
6. Connect from the Notes client using IPv6 address-NRPC. Optionally, you can enter the zone if you
want to.
7. A low priority Connection document is added to the local Domino Directory (NAMES.NSF). This
Connection document and IPv6 are used during future connection attempts initiated with File --
Database -- Open.

Chapter 2. Setting Up the Domino Network 29

Connecting from a Notes client using IPv6 address-NRPC: Use this procedure to connect from the
Notes client to a server using an IPv6 address.
1. Choose File -- Database -- Open.
2. In the Server field, enter the IPv6 address. Optionally, you can enter a server name that resolves to an
IPv6 address instead of entering the IPv6 address in the Server field.
A low-priority Connection document is added to your local Domino Directory (NAMES.NSF).

Advanced Domino TCP/IP configurations

A single Domino server can have multiple IP addresses if you use multiple NICs, each offering an
address, or if one NIC offers multiple addresses. Having multiple IP addresses allows the server to listen
for connections at more than one instance of the TCP port assigned to NRPC (1352) or at TCP ports that
are assigned to other services such as LDAP or HTTP. Both individual Domino servers and partitioned
Domino servers can have multiple NICs, each with its own IP address.

Multiple IP addresses and NICs on a Domino server

Set up a Domino server with multiple IP addresses, each with its own NIC, if you want to:
v Split the client load for better performance
v Split client-to-server access from server-to-server communication
v Set up mail routing, replication, or cluster replication on an alternate path (private network)
v Partition a Domino server so that more than one partition offers the same Internet service (SMTP,
POP3, IMAP, LDAP, or HTTP).
v Allow access to the Domino server via a TCP/IP firewall system over a different network segment, a
configuration known as a demilitarized zone (DMZ)
v Use a Domino passthru server as an application proxy
v Provide network/server failover, used in mission-critical resource access
v Set up alternate window and/or maximum transmission unit (MTU) settings for satellite uplink and
downlink connections isolated from local access connections

For a configuration with multiple IP addresses, you must bind each listening port to the appropriate IP
address to ensure that each TCP service receives the network connections intended for it.

For more information, see the topics ″Binding an NRPC port to an IP address″ and ″Binding an Internet
service to an IP address″ later in this chapter.

Note: A configuration with multiple NICs does not increase the number of Domino sessions you can
have on a server. In TCP/IP, machine capacity depends on processors and memory.

Multiple IP addresses with one NIC

Reasons to use one NIC to serve multiple IP addresses include:
v Isolating local versus WAN Notes named networks so local users can see only local Domino servers
v Preventing independent remote access dialup connections (ISDN dialup router) from being arbitrarily
accessed
v When setting up redundant WAN path connections for server to server access
v When the use of a different TCP/IP port map is needed for firewall connections
v When offering HTTP services to a different group than NRPC connections
v As a service provider when offering Domino server access for either Notes or Web clients to different
groups/companies

For a configuration with multiple addresses and one NIC, you must configure the TCP/IP stack and bind
each listening port to an IP address.

30 Lotus Domino Administrator 7 Help

Partitioned servers and IP addresses
When you set up a Domino partitioned server, it is usually best to assign a separate IP address to each
partition and use a separate NIC for each. Using a separate NIC for each address can make the
computer’s I/O much faster.

Lotus Domino is designed to listen for TCP/IP connections on all NICs in a computer system. If more
than one partition is hosting the same service (NRPC, SMTP, POP3, IMAP, LDAP, or HTTP), fine-tune
which partitions listen for which connections by associating each service’s TCP port with a specific IP
address.

For more information on associating services with IP addresses, see the topics ″Binding an NRPC port to
an IP address″ and ″Binding an Internet service to an IP address″ later in this chapter.

As an alternative to using a separate NIC for each IP address, you can use a single NIC and still assign a
separate IP address to each partition.

For more information, see the topic ″Assigning separate IP addresses to partitions on a system with a
single NIC″ later in this chapter.

If you are unable to assign a separate IP address to each partition, you can use port mapping.

For more information on port mapping, see the topic ″Configuring a partitioned server for one IP address
and port mapping″ later in this chapter.

Note: As an alternative to port mapping, you can use port address translation (PAT), in which a firewall
redirects the TCP port connection to a different TCP port. Both port mapping and PAT require advanced
skills to implement correctly.

Ensuring DNS resolves in advanced TCP/IP configurations

When you have Domino servers with multiple Notes network ports for TCP/IP, follow these procedures
to ensure server name-to-address resolution by DNS. This topic covers the following configurations:
v Users in different DNS subdomains accessing one Domino server
v User-to-server access and server-to-server access via different DNS subdomains

For information on servers accessing a private LAN in a Domino cluster, see the book Administering
Domino Clusters.

Users in different DNS subdomains accessing one Domino server: If users are on two isolated
networks and the Domino server has a NIC for each network, use DNS to direct the users to the NIC the
server shares with them.
1. Assign an IP address to each NIC by creating A records (or, for IPv6, AAAA records) in DNS. Use the
ping command and the IP address to test the responsiveness of the NIC.

Note: If the Domino server is running Windows and there is a route between the two networks,
prevent the NetBIOS broadcasts from exiting from both adapters by using the Windows Control Panel
to disable one instance of the WINS client. Use the Bindings tab of the Network dialog box, select All
Adapters, and select the name of the NIC for which you want to disable WINS.
2. Create two CNAME records in DNS for the Domino server, linking the server’s common name to each
NIC name in the A records. (Using CNAME records for the Domino server provides diagnostic
fidelity to test the network pathway independently of the server’s name resolve.)
3. Add a second Notes network port for TCP/IP in Domino.
For more information, see the topic ″Adding a network port on a server″ later in this chapter.
4. Bind each TCP/IP port to the IP address of the appropriate NIC. On the server console, verify that
both TCP/IP ports are active and linked to the correct IP address.

Chapter 2. Setting Up the Domino Network 31

 For more information on binding ports to IP addresses, see the topic ″Binding an NRPC port to an IP
address″ later in this chapter.
5. In the Server document’s Net Address field for each TCP/IP port, use the server’s common name
only, not its FQDN.
6. On each Notes workstation, set the user’s DNS name lookup scope to the correct DNS subdomain.

Example: At the Acme company, some users connect to the Domino server Chicago/Sales/Acme over
an Ethernet network, others over a Token Ring network. Register the Domino server with DNS as
chicago.east.acme.com for the users on the Ethernet network and as chicago.west.acme.com for users on
the Token Ring network.
1. Create start of authority (SOA) table entries in DNS for the subdomain east.acme.com, as follows:

chi-ethernet A 10.20.20.2
chicago CNAME chi-ethernet

2. Create SOA table entries in DNS for the subdomain west.acme.com, as follows:

chi-tokenring A 10.10.10.1
chicago CNAME chi-tokenring

3. Change the name of the original Notes network port for TCP/IP to TCPIP1, and name the second
port TCPIP2.
4. Use the NOTES.INI file to bind TCPIP1 to the IP address for the Ethernet network and to bind
TCPIP2 to the IP address for the Token Ring network.
5. In the Server document’s Net Address field for each TCP/IP port, enter chicago.
6. On the Ethernet users’ workstations, set the DNS name lookup scope to east.acme.com, and on the
Token Ring users’ workstations, set it to west.acme.com.

User-to-server access and server-to-server access via different DNS subdomains: If users need to access
a Domino server over the LAN and other Domino servers need to access the same server over the WAN,
add a second NIC to the server. Then use DNS to direct the users to the NIC for the LAN and to direct
other servers to the NIC for the WAN.
1. Assign an IP address to each NIC by creating an A record (or, for IPv6, AAAA record) in DNS. Use
the ping command and the IP address to test the responsiveness of the NIC.

Note: If the Domino server is running Windows and there is a route between the two networks,
prevent the NetBIOS broadcasts from exiting from both adapters by using the Windows Control Panel
to disable one instance of the WINS client. Use the Bindings tab of the Network dialog box, select All
Adapters, and select the name of the NIC for which you want to disable WINS.
2. Create two CNAME records in DNS for the Domino server, linking the server’s common name to each
NIC name in the A records. (Using CNAME records for the Domino server provides diagnostic
fidelity to test the network pathway independently of the server’s name resolve.)
3. Add a second Notes network port for TCP/IP in Domino.
For more information, see the topic ″Adding a network port on a server″ later in this chapter.
4. Bind each TCP/IP port to the IP address of the appropriate NIC. On the server console, verify that
both TCP/IP ports are active and linked to the correct IP address.
For more information on binding ports to IP addresses, see the topic ″Binding an NRPC port to an IP
address″ later in this chapter.
5. To direct the Domino server’s first outbound connection to the server-to-server network, edit the
PORT setting in the NOTES.INI file to read as follows:
PORT=serverportname, userportname

32 Lotus Domino Administrator 7 Help

 Where serverportname is the name of the Notes network port for TCP/IP that other Domino servers
will use to connect to this server, and userportname is the name of the Notes network port for TCP/IP
that users will use to connect to this server.
6. In the Server document’s Net Address field for the first TCP/IP port (the port that users will use),
enter the FQDN, using the server’s common name and the users’ DNS subdomain.

Note: Listing the port that users will use first is important, as the Notes Name Service cannot
distinguish which NIC a user is accessing and makes the connection based on the content of the Net
Address field for the first TCP/IP port listed in the Server document.
7. In the Server document’s Net Address field for the second TCP/IP port (the port that servers will
use), enter the FQDN, using the server’s common name and the servers’ DNS subdomain.
An initiating server uses its local Domino Directory to detect the Notes named network it has in
common with this server.
8. Set each user’s DNS name lookup scope to the correct DNS subdomain.
9. In each server’s TCP/IP stack, set the DNS name lookup scope to the correct DNS subdomain.

Example: At the Acme company, users connect to the Domino server BostonApp04/Sales/Acme over
the LAN, and other Domino servers access it privately over the WAN. You register the server with DNS
as bostonapp04.boston.acme.com for the LAN users and as bostonapp04.domino.acme.com for the
server-to-server network over the WAN.
1. Create the following SOA table entries in DNS for the subdomain boston.acme.com, as follows:

usr-bostonapp04 A 103.210.20.2
bostonapp04 CNAME usr-bostonapp04

2. Create the following SOA table entries in DNS for the subdomain domino.acme.com, as follows:

srv-bostonapp04 A 103.210.41.1
bostonapp04 CNAME srv-bostonapp04

3. Change the name of the original Notes network port for TCP/IP to TCPIP1, and name the second
port TCPIP2.
4. Use the NOTES.INI file to bind TCPIP1 to the IP address for the user network, to bind TCPIP2 to the
IP address for the server-to-server network, and to add the setting PORT=TCPIP2, TCPIP1.
5. In the Server document’s Net Address field for port TCPIP1, enter bostonapp04.boston.acme.com. For
port TCPIP2, enter bostonapp04.domino.acme.com.
6. On each user’s workstation, set the DNS name lookup scope to boston.acme.com. In the TCP/IP
stacks of the servers that need to connect to this server, set the name lookup scope to
domino.acme.com.

Planning the NetBIOS network

The Domino network is compatible with NetBIOS, a set of IBM session-layer LAN services that has
evolved into a standard interface that applications use to access transport-layer network protocols.
Domino supports the NetBIOS interface on Windows systems over the following transport protocols:
TCP/IP (on systems running TCP/IP) and NetBEUI (supplied with all Microsoft network products).

Note: Although you can add some NetBIOS services to Linux and UNIX systems, NRPC communication
does not use them.

For detailed system requirements for using NetBIOS with Lotus Domino, see the Release Notes.

Chapter 2. Setting Up the Domino Network 33

Deciding whether to use NetBIOS services
Including NetBIOS in the Domino network has both benefits and risks. The benefits are as follows:
v NetBIOS has low overhead relative to other protocol suites. NetBIOS over NetBEUI has the least
overhead; and NetBIOS over TCP/IP has the most.
v Because it is not directly routable, NetBIOS over NetBEUI can provide a secure means to access your
server for administration within a flat network. To access the server over a routed IP network, you can
create a data-link switching (DLSw) tunnel to limit the administration access with NetBIOS over
NetBEUI.
v Because NetBIOS name-to-address resolution services offer dynamic registration by name broadcasts,
you can use NetBIOS to build a mobile Domino network for temporary or emergency use.

The risks of using NetBIOS involve the security of the file system on Domino servers. Depending on the
access permissions of the operating system and on the transport protocol being used, NetBIOS name and
file services might allow users to see or access the server’s file system. When a server provides NRPC
services, mitigate this risk by disabling the NetBIOS name and file services (SMB/CIFS) on the system so
that the system’s name cannot be seen over the network. Other Notes/Domino systems can still find the
Domino server because Lotus Domino has its own NetBIOS name service to propagate and register the
Domino server’s NetBIOS name, but access is secure because it is controlled by the authentication and
certification features in NRPC.

If the system on which you run Domino requires NetBIOS name or authentication services, mitigate the
security risk by isolating the NetBIOS services. Install an additional NIC on the system for NetBIOS over
a private administration network, and disable NetBIOS on the NIC that the Domino server uses.

How to tell if NetBIOS is active on a system

The following are indications that NetBIOS is active:
v On Windows systems, you can see or access another Windows system’s file system through the
Network Neighborhood (indicates Server Message Block/NetBIOS).
v You can register with an NT domain (indicates Server Message Block/NetBIOS).
v On Windows 2000 or XP systems, ″NetBIOS over IP″ is selected in the system’s TCP/IP protocol
settings.

Note: On Linux and UNIX systems, the SAMBA server service (Windows file server) can offer Server
Message Block/NetBIOS or Common Internet File System/IP access, or both.

Server name-to-address resolution over NetBIOS

When a Notes workstation or Domino server running NetBIOS tries to connect to a Domino server, the
initiating system offers the destination server’s common name to the NetBIOS name service, which then
broadcasts that name and its associated network address over the NetBIOS network.

For background information on how the Notes Name Service works with name-resolver services such as
the NetBIOS name service, see the topic ″Resolving server names to network addresses in NRPC″ earlier
in this chapter.

When you use the Notes Name Service with the NetBIOS name service, only a Notes or Domino system
using the same NetBIOS transport protocol as the destination Domino server can see the destination
server’s NetBIOS name. If the Notes or Domino system has more than one NIC for which the NetBIOS
transport protocol is enabled, only the NetBIOS port with the same LANA binding as that of the
destination server can see the destination server’s name.

Which physical address is registered for a Domino server depends on the transport protocol:
v For NetBIOS over NetBEUI, the NIC’s 32-bit MAC address is used.

34 Lotus Domino Administrator 7 Help

v For NetBIOS over TCP/IP, the system’s IP address is used.

Ways to ensure successful NetBIOS resolves

Because NetBIOS broadcasting has a limited range, you may need to create a Connection document that
includes the physical address of the destination server. This process works as long as the network
pathway can carry the given lower transport protocol.

For NetBIOS over TCP/IP, you can also do one of the following:
v Use a WINS server with a static entry.
v In the initiating system’s TCP/IP stack settings, enable NetBIOS name lookup by DNS. This works
even if you are not using any NRPC services; however, the destination server must be registered with
DNS.

Note: NetBIOS name space is flat, even with TCP/IP. If the client is not within the same DNS domain
level, access by name may not be possible.

Naming Domino servers on NetBIOS

NetBIOS names are limited to 15 characters. If the common name of the Domino server is longer than 15
characters, NetBIOS truncates the name.

CAUTION:
The resolution of a Domino server name can be adversely affected if the server name is the same as
the NetBIOS name for a Windows system.

To prevent this problem without making it difficult to manage system files remotely, do the following:
v On Windows 2000, add a preface such as W2K- to the system name, using the Network Identification
tab on the System Properties dialog box.

For more information on the NetBIOS name service, see Microsoft’s resource kit documentation for the
Windows 2000 operating systems.

Setting up Domino servers on the network

Before installing a Domino server, make sure you have done the following:
v Installed one or more NICs on the system.
v Installed protocol software if necessary.
v Installed all network drivers in the correct directories.
v Installed any network software required for the protocols. For more information, see the vendor’s
documentation.

After you install the server, you use the Domino Server Setup program to accept network defaults or
customize network settings.

For more information, see the chapter ″Installing and Setting Up Domino Servers.″

After you run the setup program, you may need to complete one or more of these tasks to finish setting
up Lotus Domino on the network:
v Change the default names assigned to Notes named networks to make them consistent with actual
network topography.
v Fine-tune network port setup by adding, enabling, renaming, reordering, disabling, or deleting ports or
by enabling network encryption or compression on a port.
v Complete tasks specific to the TCP/IP, or NetBIOS, protocol.
For information on connecting Notes workstations to the network, see Lotus Notes 7 Help.

Chapter 2. Setting Up the Domino Network 35

Setting up Notes named networks
The Domino Server Setup program automatically places all servers that are in a Domino domain and that
run the same network protocol in the same Notes named network (NNN). In the Server document, the
setup program assigns each NNN a default name in the format portname network.

After you complete the Server Setup program, rename the NNN for each network port in the Server
document. It is useful if the name reflects both the location of the network and its protocol. For example,
if your company has a TCP/IP network and has LANs in Boston and San Francisco, change the name of
the NNN in Boston to ″TCPIP Boston network,″ and change the name of the NNN in San Francisco to
″TCPIP SF network.″

CAUTION:
Domino assumes that all servers in a NNN have a continuous LAN or WAN connection. If this is not
the case, serious delays in mail routing between servers can occur. Be careful not to include servers
with only dialup connections in an NNN.

To change the name of a Notes named network

1. From the Domino Administrator, select the server you just set up.
2. Click the Configuration tab.
3. Expand the Server section in the view pane.
4. Click Current Server Document.
5. Click Edit Server, and then click the Ports - Notes Network Ports tab.
6. In the Notes Network field for each port, enter a new name for the server’s Notes named network.
The name can include space characters.
7. Click Save and Close.

Fine-tuning network port setup on a server

After you install and set up a Domino server, review the list of network ports that were enabled by the
Server Setup program. Unless you customize network settings during setup, Domino enables ports based
on the current operating system configuration. To conserve system resources, disable the ports for
protocols that you don’t need.

For information on configuring a communication port for a dialup modem, see the chapter ″Setting Up
Server-to-Server Connections.″

Use Domino Administrator to make these changes to a server’s network port setup:
v Disable a network port
v Enable a network port
v Add a network port
v Rename a network port
v Reorder network ports
v Delete a network port
v Encrypt network data on a port
v Compress network data on a port

Note: On a Notes workstation, you use the User Preferences dialog box to change port setup.

For more information on changing port preferences on a workstation, see Lotus Notes 7 Help.

Disabling a network port on a server

Even after you disable a port, it still appears in the list of available ports so that you can later enable it.

36 Lotus Domino Administrator 7 Help

1. From the Domino Administrator or Web Administrator, click the server on which you want to disable
a port.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the port you want to disable, and then deselect ″Port enabled.″
5. Click OK.
6. Click the Server - Status tab.
7. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.
8. In the Server document, on the Ports - Notes Network Ports tab, specify Disabled next to the name of
the port you are disabling.
9. Save the Server document.

Enabling a network port on a server

If the server port you want to enable will be the Notes workstation’s only means of connecting with the
server, do not use this procedure. Instead, use the Ports setting in the server’s NOTES.INI file.

For more information, see the appendix ″NOTES.INI File.″

For information on creating a Connection document on a Notes workstation, see Lotus Notes 7 Help.

To enable a network port:

1. From the Domino Administrator or Web Administrator, click the server on which you want to enable
a port.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the port you want to enable, and then select ″Port enabled.″
5. Click TCP/IP Options, LANx Options, or COMx Options, and specify information as appropriate.
For more information on TCP/IP and LANx options, see the topics ″Changing the TCP/IP
connection time-out interval,″ ″Defining a NetBIOS LANA number for a Notes network port,″ and
″Defining a server’s NetWare name service in Lotus Domino″ later in this chapter.
For more information on COMx options, see the chapter ″Setting Up Server-to-Server Connections.″
6. Click OK.
7. Click the Server - Status tab.
8. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.
9. In the Server document, click the Ports - Notes Network Ports tab, and edit these fields as
necessary:

Chapter 2. Setting Up the Domino Network 37

Field Action
Port Enter the port name. Lotus Domino assigns a default port name to each network protocol
detected on the system.
Notes Network Enter the name of the Notes named network for the group of Domino servers that are in this
location and run on a particular protocol -- for example, Boston TCPIP. Space characters are
allowed in a Notes network name.
Net Address Enter the protocol-specific name of the server -- for example, sales.acme.com. The name you
use depends on the convention of the network protocol. This field is used to determine the
address that other servers use to access this server.
Disabled/Enabled Choose Enabled so that other servers will know the port is enabled.

10. Save the Server document.

11. Make sure that this server is set up to replicate its Domino Directory to other servers, or enter the
preceding changes into the Server document on a server that is set up to do the replication, or other
servers will not know that they can connect to this server over the newly enabled port.

Adding a network port on a server

If the server port you want to add will be the Notes workstation’s only means of connecting with the
server, do not use this procedure. Instead, use the Ports setting in the server’s NOTES.INI file.

For more information, see the appendix ″NOTES.INI File.″

For information on creating a Connection document on a Notes workstation, see Lotus Notes 7 Help.

To add a network port:

1. From the Domino Administrator or Web Administrator, click the server on which you want to add a
port.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Click New.
5. Specify the port name and driver, and click OK.
6. Click TCP/IP Options, LANx Options, or COMx Options, and specify information as appropriate.
For more information on TCP/IP and LANx options, see the topics ″Changing the TCP/IP
connection time-out interval,″ ″Defining a NetBIOS LANA number for a Notes network port,″ and
″Defining a server’s NetWare name service in Lotus Domino″ later in this chapter.
For more information on COMx options, see the chapter ″Setting Up Server-to-Server Connections.″
7. Click OK.
8. Click the Server - Status tab.
9. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.
10. In the Server document, click the Ports - Notes Network Ports tab, and edit these fields as necessary:

Field Action
Port Enter the port name. Lotus Domino assigns a default port name to each network protocol
detected on the system.

38 Lotus Domino Administrator 7 Help

Field Action
Notes Network Enter the name of the Notes named network for the group of Domino servers that are in this
location and run on a particular protocol -- for example, Boston TCPIP. Space characters are
allowed in a Notes network name.
Net Address Enter the protocol-specific name of the server -- for example, sales.acme.com. The name you
use depends on the convention of the network protocol. This field is used to determine the
address that other servers use to access this server.
Disabled/Enabled Choose Enabled so that other servers will know the port is enabled.

11. Save the Server document.

12. Make sure that this server is set up to replicate its Domino Directory to other servers, or enter the
preceding changes to the Server document on a server that is set up to do the replication, or other
servers will not know that they can connect to this server over the newly enabled port.
13. If you are adding an additional TCP/IP port on a computer with multiple NICs, see these topics:
v Binding an NRPC port to an IP address
v Binding an Internet service to an IP address.
14. If you are adding an additional NetBIOS port on a computer with multiple NICs, see the topic
Creating additional network ports for NetBIOS.

Deleting a network port on a server

If you delete a port, it no longer appears in the list of available ports in the Setup Ports dialog box.
1. From the Domino Administrator or Web Administrator, click the server on which you want to delete
a port.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the port you want to delete.
5. Click Delete.
6. Click OK.
7. Click the Server - Status tab.
8. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.
9. In the Server document, on the Ports - Notes Network Ports tab, delete the contents of all the fields
next to the name of the port you are deleting.
10. Save the Server document.

Renaming a network port on a server

You might want to rename a port to reflect its function. For example, suppose you add a second TCP/IP
port named SRV-TCP so that clustered servers can communicate over a private network. Then you might
want to might want to rename the original TCP/IP port through which users will communicate with the
server USR-TCP.
1. From the Domino Administrator or Web Administrator, click the server on which you want to
rename a port.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.

Chapter 2. Setting Up the Domino Network 39

 v From the Web Administrator’s Port tool, choose Setup.
4. Select the port you want to rename.
5. Click Rename, and then enter the new name. Do not use spaces in the port name.
6. Click OK.
7. Click the Server - Status tab.
8. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.
9. In the server document, on the Ports - Notes Network Ports tab, change the name of the port to the
new name and save the document.
10. If this server is the source server for any Connection documents in the Domino Directory, click
Server - Connections.
11. Select a Connection document and click Edit Connection.
12. On the Basics tab, enter the new port name in the ″Use the port(s)″ field.
13. Save and close the Connection document.
14. Repeat steps 10 to 13 for each Connection document for which this server is the source.

Reordering network ports on a server

Changing the order in which ports are listed in the Setup Ports dialog box also changes the Ports setting
in the NOTES.INI file. List the ports in the order in which you want them to be used -- for example, list
nearest or fastest connections first. Then when a server uses a Notes named network or a Connection
document to locate another server, the port with a close or fast connection will be used as the preferred
path.

If the Domino server has multiple TCP/IP ports, see the topic ″Reordering multiple server ports for
TCP/IP″ later in this chapter.

To reorder network ports:

1. From the Domino Administrator or Web Administrator, click the server on which you want to
reorder ports.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the port that you want to relocate in the list.
5. Click the up and down arrows, as necessary to relocate the port.
6. Click OK.
7. Click the Server - Status tab.
8. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.
9. In the Server document, on the Ports - Notes Network Ports tab, change the port order to the new
order by cutting and pasting all the necessary fields.
10. Save the Server document.

Note: When you create a Connection document on a server, the Connection document takes the port
order from the order in the Setup Ports dialog box. Then, whenever the server connects with the

40 Lotus Domino Administrator 7 Help

destination server, the server obtains the port order directly from the Connection document. If you
change the port order after you create Connection documents, you must save each Connection document
again. To have different Connection documents reflect different port orders, change the port order, save a
Connection document, change the port order again, save another Connection document, and so on.

Encrypting NRPC communication on a server port

You can encrypt network data on a server’s Notes network ports to prevent the network eavesdropping
that’s possible with a network protocol analyzer. Network encryption occurs at the application layer of a
given protocol and is independent of other forms of encryption. Network data is encrypted only while it
is in transit. After the data is received and stored, network encryption is no longer in effect.

Network data encryption occurs if you enable network data encryption on either side of a network
connection. For example, if you enable encryption on a server’s Notes network port for TCP/IP, you
don’t need to enable encryption on the TCP/IP ports of workstations or servers that connect to the
server.

If you want the server to have one TCP/IP port for Notes traffic over the Internet and another TCP/IP
port for internal traffic over NRPC, you can encrypt the port for Internet traffic and leave the port for
internal traffic unencrypted.

Be aware that multiple high-speed encrypted connections to a server can affect server performance
adversely. Encrypting network data has little effect on client performance. For protocols other than NRPC,
you use SSL for encryption.

For more information, see the chapter ″Setting Up SSL on a Domino Server.″

To encrypt NRPC communication:

1. From the Domino Administrator or Web Administrator, choose the server for which you want to
encrypt network data.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the port you want to encrypt.
5. Select ″Encrypt network data.″
6. Click OK.
7. Click the Server - Status tab.
8. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.

Compressing network data on a server port

To reduce the amount of data transmitted between a Notes workstation and Domino server or between
two Domino servers, enable network compression for each enabled network port. Whether you should
enable compression on a network port depends on the type of network connection and the type of data
being transmitted.

For compression to work, enable it on both sides of a network connection. To enable compression for a
network port on a server, use the Server tab in the Domino Administrator. To enable compression on
network ports on Notes workstations, from the Domino Administrator, use a setup or desktop policy
settings document or from a workstation, use the User Preferences dialog box.

Chapter 2. Setting Up the Domino Network 41

For information on policy settings, see the chapter ″Using Policies.″

WAN connections: Enabling network compression on X.PC ports can significantly reduce the time it
takes to send and receive data over a remote connection between a Notes workstation and a Domino
server or between two Domino servers.

You benefit from using network compression only if the data being transmitted is not already
compressed. In the case of a network dialup service such as Microsoft’s Remote Access Service (RAS)
which includes built-in compression, enabling compression on Notes network ports does not provide any
additional benefit. The same is true of tasks involving data that was compressed using the Lempel-Ziv
algorithm (LZ1 compression) -- such as replicating a mail file with a large number of compressed
attachments.

LAN connections: While compression decreases bandwidth use on a LAN, you must weigh this gain
against increased memory and processor use, since network compression works by buffering data before
compressing it. The cost of compression might be worth it only for a heavily loaded network.

To compress data on a server port:

1. From the Domino Administrator or Web Administrator, click the server for which you want to turn on
network compression.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the port for which you want to turn on compression.

Note: Make sure ″Port enabled″ is selected for that port.

5. Select ″Compress network data.″
6. Click OK.
7. Click the Server - Status tab.
8. Do one of these so that the change takes effect:
v From the Domino Administrator’s Tools pane, choose Restart Port. (If you can’t see the Tools pane,
make sure you are in the Server Tasks view.)
v From the Web Administrator’s Ports tool, choose Restart.

Server setup tasks specific to TCP/IP

After you run the Domino Server Setup program, complete these procedures:
1. Set up a secondary name server for Notes clients.
2. Change the server’s connection-time-out interval.
3. For servers that provide services to Internet clients, enable Domino support for IPv6.
4. For configurations involving multiple NICs on a server or partitioned server:
v Reorder multiple Notes network ports for TCP/IP.
v Bind an NRPC port to an IP address.
v Bind an Internet service to an IP address.
5. For a partitioned server with a single NIC for the entire computer, assign an IP address to each server
partition
6. Change a default TCP or SSL port number.
7. Confirm that TCP/IP is configured properly.

42 Lotus Domino Administrator 7 Help

Setting up a secondary name server
To ensure that the Notes Name Service is always available to Notes workstations, assign a secondary
name server in users’ Location documents. You can specify a different secondary name server for each
LAN location defined. The secondary name server is used when:
v The user’s home server is down.
v The user’s home server is not running TCP/IP.
v The name of the user’s home server cannot be resolved over TCP/IP.
For examples of situations in which the name of a home server cannot be resolved, see the topic
″Ensuring DNS resolves in advanced TCP/IP configurations″ earlier in this chapter.

Note: You can use setup or desktop policy settings to assign secondary name servers to groups of users.

For more information, see the chapter ″Using Policies.″

To set up a secondary name server:

1. On the Notes workstation, choose File - Mobile - Locations, and open the location for which you want
to designate a secondary name server.
2. Click ″Edit Location.″
3. Click the Advanced - Secondary Servers tab. (The Advanced tab appears only if you have a location
defined as ″Local Area Network″ or ″Both Dialup and Local Area Network.″)
4. In the ″Secondary TCP/IP Notes server name″ field, enter one of the following:
v The common name of the Domino server -- for example, Notesserver1
v The hierarchical name of the Domino server -- for example, Notesserver1/Acme
5. In the ″Secondary TCP/IP host name or address″ field, enter one of the following:
v IP address -- for example, 197.114.33.22
v The fully qualified domain name -- for example, notesserver1.acme.com
v The simple host name -- for example, notesserver1
If you specify only the host name in this field, the workstation must use the Domain Name System
(DNS) or local hosts file to locate the secondary name server. When you specify the IP address in
this field, Lotus Domino resolves the host’s IP address without having to perform a DNS or hosts
file lookup.
6. Click ″Save and Close.″

Changing the TCP/IP connection-time-out interval

You might want to increase the number of seconds that Lotus Domino waits before terminating a
connection attempt. For example, increasing the time-out interval is often necessary on a server that dials
up other Domino servers. The default time-out interval is 5 seconds.
1. From the Domino Administrator or Web Administrator, click the server for which you want to change
the time-out interval.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the TCP/IP port.
5. Click ″TCPIP Options,″ and enter a number.

Note: Unless the connection is over a dial-on-demand ISDN modem, remote bridge, or router, it is
best to enter a number no greater than 10, as the Notes client or Domino server won’t retry the
connection until the timer has expired.
6. Click OK.

Chapter 2. Setting Up the Domino Network 43

Enabling support for IPv6 on a Domino server
You can enable support for IPv6 on a Domino server that runs the IMAP, POP3, SMTP, LDAP, or HTTP
service.

To enable IPv6, add this NOTES.INI setting to the server’s NOTES.INI file:
TCP_EnableIPV6=1

Reordering multiple server ports for TCP/IP

If a Domino server has multiple Notes network ports for TCP/IP, the order in which these ports are
listed in the NOTES.INI file and the Server document affects how other servers and workstations connect
to this server. The Ports setting in the NOTES.INI file determines which port a workstation or server tries
first. In the absence of other settings that bind an NRPC, POP3, IMAP, SMTP, or LDAP service to an IP
address, all of these services will try to use the port listed first in the NOTES.INI file.

Server-to-server communication: If you add a second Notes network port for TCP/IP in order to isolate
server-to-server communication -- for example, a private network for cluster replication -- list this port
first in the NOTES.INI file so that server-to-server traffic will tend to occur over this connection, thus
decreasing the data flow on the port for the user network. To change the port order in the NOTES.INI
file, use the Port Setup dialog box.

For more information, see the topic ″Reordering network ports on a server″ earlier in this chapter.

Note: If you are setting up a private cluster network and do not list the server port first, you must add
the setting Server_Cluster_Default_Port to the NOTES.INI file. The disadvantage of adding this setting is
that if the server encounters a problem connecting over this port, it will not try another port, and
replication will not occur.

For more information on the Server_Cluster_Default_Port setting, see the appendix ″NOTES.INI File.″

Workstation-to-server communication: If a Domino server has a port for workstations to connect on --

for example, over a LAN -- and another port for servers to connect on -- for example, over a WAN -- list
the workstation port first in the Server document so that users see only servers on the LAN when they
choose File - Database - Open.

To reorder the ports in the Server document, click the Ports - Notes Network Ports tab, and edit the fields
in the table.

Binding an NRPC port to an IP address

By default, all TCP/IP-based services on a Domino server listen for network connections on all NICs and
on all configured IP addresses on the server. If you have enabled more than one Notes network port for
TCP/IP (TCP port for NRPC) on either a single Domino server or a Domino partitioned server, you must
associate the NRPC ports and IP addresses by binding each port to an address.

For background information on Domino server setups with multiple IP addresses, see the topic
″Advanced Domino TCP/IP configurations″ earlier in this chapter.

To bind an NRPC port to an IP address: When setting the NOTES.INI variables for port mapping, do
not include a zone in a port mapped address. The zone is only valid locally.
1. For each IP address, make sure you have added a Notes port for TCP/IP. Also make sure that each
port has a unique name.
For information on adding a Notes port, see the topic ″Adding a network port on a server″ earlier in
this chapter.
2. In the NOTES.INI file, confirm that these lines appear for each port that you added:
Ports=TCPIPportname
TCPIPportname=TCP, 0, 15, 0

44 Lotus Domino Administrator 7 Help

 Where TCPIPportname is the port name you defined.
3. For each port that you want to bind to an IP address, add this line to the NOTES.INI file:
TCPIPportname_TCPIPAddress=0,IPaddress
Where IPaddress is the IP address of the specific NIC.
For example:
TCPIP_TCPIPAddress=0,130.123.45.1

Note: For IPv6, enclose the address in square brackets, as it contains colons. For example:
TCPIP_TCPIPAddress=0,[fe80::290:27ff:fe43:16ac]
4. (Optional) To help you later remember the function of each port, add the default TCP port number for
NRPC to the end of the line you entered in Step 3, as follows:
:1352

CAUTION:
Do not change the assigned TCP port number unless you have a way to redirect the inbound
connection with Domino port mapping or a firewall that has port address translation (PAT).
In a situation where you must change the default NRPC port number, see the topic ″Changing a TCP
or SSL port number″ later in this chapter.

Binding an Internet service to an IP address

If the Domino server has multiple Notes network ports for TCP/IP (NRPC ports) and the server is also
hosting the SMTP, POP3, IMAP, LDAP, or Internet Cluster Manager (ICM) service, you must specify the
NRPC port that you want the service to use in the NOTES.INI file. If you do not specify an NRPC port
for an Internet service, by default the service will use the port listed first in the Ports setting in the
NOTES.INI file. You can specify the same NRPC port for multiple Internet services.

For the Domino Web server (HTTP service), you use the Server document to bind HTTP to a host name
IP address.

To bind the SMTP, POP3, IMAP, LDAP, or ICM service:

1. Bind each NRPC port to an IP address.
2. In the NOTES.INI file, specify the appropriate NRPC port for each Internet service as follows:

Note: If you don’t know the port name to enter for an NRPC port, open the Server document, click
the Ports - Notes Network Ports tab, and look at the ports associated with the TCP protocol.

Service Action
POP3 Enter POP3NotesPort=port namewhere port name is the name of the NRPC port that you want
to link the service to.
IMAP Enter IMAPNotesPort=port namewhere port name is the name of the NRPC port that you want
to link the service to.
SMTP Enter SMTPNotesPort=port namewhere port name is the name of the NRPC port that you want
to link the service to.
LDAP Enter LDAPNotesPort=port namewhere port name is the name of the NRPC port that you want
to link the service to.
ICM Enter ICMNotesPort=port namewhere port name is the name of the NRPC port that you want
to link the service to.

Example: The following example shows the lines (in bold) to add to the Ports section of the NOTES.INI
file to bind two NRPC ports to their IP addresses and to specify the second NRPC port for the SMTP
service.
Ports=TCPIP, TCP1P2

Chapter 2. Setting Up the Domino Network 45

TCPIP=TCP, 0, 15, 0
TCPIP_TCPIPAddress=0,10.33.52.1
TCPIP2=TCP, 0, 15, 0
TCPIP2_TCPIPAddress=0, 209.98.76.10
SMPTNotesPort=TCPIP2

Note: Domino adds the lines that are not bold when you use either the Domino Server Setup program or
the Domino Administrator’s Setup Ports dialog box to enable a port.

To bind the HTTP service:

1. On the Internet Protocols - HTTP tab of the Server document, enter one or more IP addresses or
FQDNs for the server in the ″Host name(s)″ field.
2. Select Enabled in the ″Bind to host name″ field.

Note: If the server is a partitioned server and has Web sites configured with separate IP addresses, or has
virtual servers (Domino 5) configured for one or more partitions, enter the partition’s IP address, and
each Web site or virtual server’s IP address in the ″Host name(s)″ field, separated by semicolons.
Alternatively, you can use FQDNs in this field. Do not list additional Web sites and virtual hosts that
have IP addresses that are already listed in this field.

Example 1 -- Server partition with Web sites: The partition’s host name is app01 and there are two Web
sites configured for it: sales.acme.com and accounting.acme.com. The Web site sales.acme.com uses the
same IP address as the partition, and the Web site accounting.acme.com has its own IP address. Enter the
following in the ″Host name(s)″ field:
9.88.43.113;9.88.46.110

where 9.88.43.113 is the IP address for both the partition and the Web site sales.acme.com and 9.88.46.110
is the IP address for the Web site accounting.acme.com.

Example 2 -- Server partition with virtual servers: The partition’s host name is app01 and there are two
virtual servers (9.88.46.114 and 9.88.46.115) and one virtual host configured for it. Enter the following in
the ″Host name(s)″ field:
9.88.43.113;9.88.46.114;9.88.46.115

where 9.88.43.113 is the IP address for both the partition and the virtual host sales.acme.com, 9.88.46.114
is the IP address for virtual server 1 (accounting.acme.com), and 9.88.46.115 is the IP address for virtual
server 2 (northeastsales.acme.com).

For information on Web sites and Internet Site documents, see the chapter ″Installing and Setting Up
Domino Servers.″

Assigning separate IP addresses to partitions on a system with a single NIC

If you use a single NIC with multiple IP addresses, you must complete additional configuration
instructions, which are based on your operating system, for each server partition.

Note: Using separate IP addresses with a single NIC can have a negative impact on the computer’s I/O
performance.

For background information on partitioned servers and the TCP/IP network, see the topic ″Partitioned
servers and IP addresses″ earlier in this chapter.

IBM AIX or Linux: You must be logged on as root.

To enable an IP address in IBM AIX:

46 Lotus Domino Administrator 7 Help

1. Add one entry in the local host names file /etc/hosts for each server partition. The entry for the
partition that uses the computer host name should already exist.
2. To enable an IP address, enter this command under the heading ″Part 2 -Traditional Configuration″ in
the startup file (etc/rc.net). Do not enter this command for the partition that uses the computer host
name.
/usr/sbin/ifconfig interface alias server_name
where interface is the name of the network interface, and server_name is the name of the partitioned
server -- for example:
/usr/sbin/ifconfig en0 alias server2
3. Restart the system if necessary, and test the configuration. From another computer, use the ping
command with the server names. To show the network status, use the netstat command.

To disable an IP address in IBM AIX or Linux: Do not remove the IP address of a server partition that
uses the computer host name as its server name.
1. Enter this command at the console:
/usr/sbin/ifconfig interface delete server_name
where interface is the name of the network interface, and server_name is the name of the partitioned
server.
2. Remove the partition’s name entry from the local host names /etc/hosts file.
3. Remove the corresponding ifconfig command from the system startup /etc/rc.net file.

Sun Solaris: This procedure is for Sun Solaris 2.6. You must have superuser privileges to configure the
NIC.

To enable an IP address in Sun Solaris:

1. Add one entry in the local host names /etc/hosts file for each server partition. The entry for the
partition that uses the computer host name should already exist.
2. For each partition, create a file named:
/etc/hostname.device:n
where device is the device name of the NIC, and n is a number that increments for each file name. The
/etc/hostname.hme0 file should already exist and contain the computer host name.
For example, if /etc/hostname.hme0 contains the name Server1, create:
/etc/hostname.hme0:1
which contains the name Server2. and
/etc/hostname.hme0:2
which contains the name Server3.
3. Create the alias for each IP address that goes to the NIC which is hme0. At the console, enter:
/sbin/ifconfig hme0 plumb
/sbin/ifconfig hme0:
n IP_address
where n is the number you created in Step 2 for each file name, and IP_address is the address assigned
to the corresponding server in Step 1. For example:
/sbin/ifconfig hme0 plumb
/sbin/ifconfig hme0:1 111.123.11.96
/sbin/ifconfig hme0:2 111.123.11.22
4. To verify the IP addresses that you configured, enter:
/sbin/ifconfig -a
5. To enable each IP address that you configured in Step 3, enter:
/sbin/ifconfig hme0:n up
where n is the number assigned to the file that contains the server name. For example:

Chapter 2. Setting Up the Domino Network 47

 /sbin/ifconfig hme0:1 up
/sbin/ifconfig hme0:2 up
To disable an IP address, enter:
/sbin/ifconfig hme0:n down
6. To configure the NIC to support multiple IP addresses at system startup, add this ifconfig command
to the startup file (probably /etc/rc2.d/S30sysident):
/sbin/ifconfig hme0 plumb
/sbin/ifconfig hme0:n IP_address
/sbin/ifconfig hme0:n up
where n corresponds to the number you created in Step 2 for each file name, and IP_address is the
address assigned to the corresponding server in Step 1.
7. Test the configuration. From another computer, use the ping command with the server names. To
show the network status, use the netstat command.

To disable an IP address in Sun Solaris: Do not remove the IP address of the server partition that uses
the computer host name as its server name.
1. To disable the IP address, type:
/sbin/ifconfig hme0:n down
where n is the number assigned to the file that contains the server name. For example:
/sbin/ifconfig hme0:1 down
2. Remove the corresponding /etc/hostname.hme0:n file. For example, to remove Server2, remove the
/etc/hostname.hme0:1 file, which contains the name Server2.
3. Remove the partition’s server name entry from the local host names /etc/hosts file.

Windows: To configure a single NIC for multiple IP addresses on Windows systems, do the following:
v For Windows 2000, use the Network and Dial-up Connections icon on the Control Panel , and then the
Local Area Connection icon. Click the Properties button. For more information, see the Windows 2000
documentation.

Configuring a partitioned server for one IP address and port mapping

To configure server partitions to share the same IP address and the same NIC, you use port mapping.
With port mapping, you assign a unique TCP port number to each server partition and designate one
partition to perform port mapping. The port-mapping partition listens on port 1352 and redirects Notes
and Domino connection requests to the other partitions.

If the port-mapping partition fails, existing sessions on the other partitions remain connected. In most
cases, Notes clients will not be able to open new sessions on any of the partitions. However, because each
Notes client maintains information in memory about recent connections, including those redirected by the
port-mapping partition, a client may be able to connect to a partition even when the port-mapping
partition is not running. A client or remote server that has a Connection document containing both the IP
address and the assigned port can always access the port-mapping partition.

Because the port-mapping partition requires extra system resources, consider dedicating the partition to
this task only. To do this, remove all other server tasks, such as mail routing and replication, from the
partition’s NOTES.INI file.

Port mapping works for NRPC communication only. However, you can use the Server document in the
Domino Directory to configure IMAP, LDAP, and POP3 services and Domino Web servers to use unique
ports for communication. When you do, you must make the port number available to users when they
try to connect to the servers.

48 Lotus Domino Administrator 7 Help

Note: Because Internet protocols carry a large amount of data, you may encounter I/O bottlenecks if you
use a single NIC with too many server partitions. Consider adding additional NICs and isolating the data
by protocol.

To configure for one IP address and port mapping: When you set up port mapping, the port-mapping
partition automatically routes NRPC communication requests to the other server partitions.

Note: When setting the NOTES.INI variables for port mapping, do not include a zone in a port mapped
address. The zone is only valid locally.
1. Decide which server partition will perform port mapping.
2. Choose a unique TCP/IP port number for each server partition on the computer. The port-mapping
partition uses the assigned port, 1352. It is best to use port numbers 13520, 13521, 13522, 13523, or
13524 for the additional server partitions.
3. In the NOTES.INI file of the port-mapping partition, include one line for the port-mapping partition
and one line for each of the other partitions. For the port-mapping partition, enter:
TCPIP_TcpIpAddress=0,IPAddress:1352
where TCPIP is the port name, and IPAddress is the IP address of the port-mapping partition.
For each of the other partitions, enter:
TCPIP_PortMappingNN=CN=server_name/O=org,IPaddress:TCP/IP port number
where TCPIP is the port name, NN is a number between 00 and 04 assigned in ascending sequence,
server_name is the server name of the partition, org is the organization name, IPAddress is the shared IP
address, and TCP/IP port number is the unique port number you chose for the partition.

Note: You must assign the numbers for NN in ascending order beginning with 00 and ending with a
maximum of 04. If there is a break in the sequence, Domino ignores the subsequent entries.
4. In the NOTES.INI file of each of the other partitions, include this line:
TCPIP_TcpIpAddress=0, IPAddress:IPport_number
where TCPIP is the port name, IPAddress is the shared IP address, and IPport_number is the unique
port number you chose for the partitioned server.
5. In the Net Address field on the Ports - Notes Network Ports tab in the Server document for each
partition, enter the fully qualified domain name -- for example, sales.acme.com -- or enter the
common server name -- for example, Sales.
6. Create an IP address entry for the port-mapping partition in the DNS, NIS, or the local hosts file.
7. Include each partition name as a separate CNAME entry in the DNS, NIS, or the local hosts file.
8. If you also plan to set up the partitions for IMAP, LDAP, and POP3 services and Web server
communication, assign to each protocol a unique port number in the ″TCP/IP port number″ field on
the appropriate subtabs (Web, Directory, and Mail) on the Ports - Internet Ports tab of the Server
document.

Note: You must make these port numbers available to users when they try to connect to these
servers. For example, if you assign port 12080 to the Web server acme.com, users must include
acme.com:12080 in the URL in order to connect to the server, unless they have a means to redirect the
connection to this port assignment.

Example: This example shows the lines you add to the NOTES.INI files of the server partitions to set up
port mapping for six partitions.

Partition 1 (the port-mapping partition):

TCPIP_TcpIpAddress=0,192.94.222.169:1352
TCPIP_PortMapping00=CN=Server2/O=Org2,192.94.222.169:13520
TCPIP_PortMapping01=CN=Server3/O=Org3,192.94.222.169:13521
TCPIP_PortMapping02=CN=Server4/O=Org4,192.94.222.169:13522

Chapter 2. Setting Up the Domino Network 49

TCPIP_PortMapping03=CN=Server5/O=Org5,192.94.222.169:13523
TCPIP_PortMapping04=CN=Server6/O=Org6,192.94.222.169:13524

Partition 2:
TCPIP_TcpIpAddress=0,192.94.222.169:13520

Partition 3:
TCPIP_TcpIpAddress=0,192.94.222.169:13521

Partition 4:
TCPIP_TcpIpAddress=0,192.94.222.169:13522

Partition 5:
TCPIP_TcpIpAddress=0,192.94.222.169:13523

Partition 6:
TCPIP_TcpIpAddress=0,192.94.222.169:13524

Changing a TCP or SSL port number

The following sections describe the TCP ports that Domino services use and provide guidelines should
you ever need to change these ports.

Default port for NRPC: By default, all NRPC connections use TCP port 1352. Because the Internet
Assigned Number Authority (IANA) assigned Lotus Domino this port number, non-Domino applications
do not usually compete for this port.

Do not change the default NRPC port unless:

v You can use a NAT or PAT firewall system to redirect a remote system’s connection attempt.
v You are using Domino port mapping.
v You create a Connection document that contains the reassigned port number.

To change the default NRPC port number, use the NOTES.INI setting TCPIPportname_TCPIPAddress and
enter a value available on the system that runs the Domino server. TCP ports with numbers less than
5000 are reserved for application vendors. You may use any number from 1024 through 5000, as long as
you don’t install a new application that requires that number.

Note: When setting the NOTES.INI variables for port mapping, do not include a zone in a port mapped
address. The zone is only valid locally.

Default ports for Internet services: You may occasionally need to change the number of the TCP or SSL
port assigned to an Internet service. Lotus Domino uses these default ports for Internet services:

Service Default TCP port Default SSL port

POP3 110 995
IMAP 143 993
LDAP 389 636
SMTP inbound 25 465
SMTP outbound 25 465
HTTP 80 443
IIOP 63148 63149
Server Controller N/A 2050

50 Lotus Domino Administrator 7 Help

Confirming that TCP/IP is configured properly
Before you can use TCP/IP for communication, use the following tests to confirm that the configuration
is properly set up:
1. Use the ping command with the remote system’s TCP/IP address -- for example, ping 192.9.200.1. If
this is unsuccessful, the TCP/IP software isn’t properly installed and configured. TCP/IP must be
working before you can use it. Contact the TCP/IP software vendor or operating system vendor if
you need assistance.
2. Use the ping command with the FQDN of the remote server -- for example, ping
mail05.boston.acme.com. If this is unsuccessful, the host-name-to-IP-address translation isn’t working.
If you can’t ping by host name, the server or workstation will not be able to communicate with the
server running on the remote system.
3. If you use a local hosts file, make sure that it contains the server name and IP address of every
Domino server with which you want to communicate.
4. If you use DNS, make sure that you have properly configured the TCP/IP software on this system to
query the correct DNS server. Make sure that your DNS records include the server name and IP
address of every Domino server with which you want to communicate.

Note: Make sure that your IP host names do not contain illegal characters such as spaces,
underscores, or ampersands.
5. If you use the Network Information Service (NIS), make sure that you have properly configured the
UNIX system for NIS. Make sure that the NIS hosts map contains the server name and IP address of
every Domino server with which you want to communicate.
6. Depending on your name-resolution practices, do one of the following:
v If your Domino server names are the same as the DNS host names, make sure you have followed
the instructions in the topics Ensuring DNS resolves on Windows systems -- All TCP protocols,
Ensuring DNS resolves in NRPC -- Best practices, and Ensuring DNS resolves in advanced TCP/IP
configurations.
v If your Domino server names are different from the DNS host names, use the ping command to
verify that all of the DNS names which represent the Domino server are responding from the
correct network areas, as well as the Domino server name, if needed.
v If you are using IP addresses in Connection documents, use the ping command to verify the IP
address itself.
v If you are using network address translation (NAT), verify that access is possible from both the
internal network and external Internet using the appropriate IP addresses. If you are using
name-resolver services, make sure that the external DNS offers out the public address and the
internal DNS offers out the private address.
For more information on the last three practices in Step 6, see the topic ″Ensuring DNS resolves in
NRPC -- Alternative practices″ earlier in this chapter.

Server setup tasks specific to NetBIOS

After you run the Domino Server Setup program, complete these procedures:
1. Use the Domino Administrator to define a NetBIOS LANA number for the NetBIOS port.
2. If you want the server to connect to different segments of a NetBIOS network, create one or more
additional Notes network ports for NetBIOS.

Defining a NetBIOS LANA number for a Notes network port

To run NetBIOS on a server, after you complete the Server Setup program, you must determine the
NetBIOS LANA number to which the Notes network port will be bound. The NetBIOS LANA number is
a logical number that represents a NetBIOS transport protocol stack on a NIC. You must know which
transport protocol Notes workstations and other Domino servers are using for NetBIOS within your
workgroup or company.

Chapter 2. Setting Up the Domino Network 51

If the computer running the Domino server has more than one NIC running the same protocol stack, you
must define a different NetBIOS LANA number for each Notes network port for NetBIOS.

NetBIOS systems using the same transport protocol should be in the same Notes named network. If you
create Connection documents on the server, the LAN port you select must also be for the same transport
protocol.

To define a LANA number in Lotus Domino:

1. From the Domino Administrator or Web Administrator, click the server for which you want to define
a LANA number.
2. Click the Configuration tab.
3. Do one of these:
v From the Domino Administrator’s Tools pane, choose Server - Setup Ports.
v From the Web Administrator’s Port tool, choose Setup.
4. Select the Portname port, where Portname is the name of the NetBIOS port for which you are defining
a LANA number.
5. Click ″Portname Options,″ and choose Manual.
6. Enter the correct LANA number.
7. Click OK.

To find the LANA number for a NetBIOS protocol on a Windows XP or 2000 system: A Windows XP
or 2000 system does not have a direct means to see the LANA associations. For Windows XP or 2000
systems you can either review the system’s registry bindings or use a Microsoft tool called LANACFG to
see and change the LANA number assignments.

The following is an example of the tool’s output from a Windows 2000 server.
lanacfg [options]
showlanapaths - Show bind paths and component descriptions for each exported lana
setlananumber - Change the lana number of a bind path
rewritelanainfo - Verify and write out lana info to the registry
showlanadiag - Show lana diagnostic info

From the DOS prompt, enter

C:\>lanacfg showlanapaths

You see the following:

Lana: 4
-->NetBEUI Protocol-->3Com EtherLink III ISA (3C509/3C509b) in Legacy mode
Lana: 7
-->NetBEUI Protocol-->WAN Miniport (NetBEUI, Dial Out)
Lana: 3
-->NWLink NetBIOS
Lana: 0
-->WINS Client(TCP/IP) Protocol-->Internet Protocol (TCP/IP)-->3Com EtherLink III ISA (3C509/3C509b) in Legacy mode

Creating additional network ports for NetBIOS

After you run the Domino Server Setup program, you can create network segments for multiple NetBIOS
interfaces on the same computer by adding a Notes network port for NetBIOS for each additional NIC.

In addition to adding each port for NetBIOS, do the following:

52 Lotus Domino Administrator 7 Help

v Associate each Notes network port for NetBIOS with a specific NetBIOS interface by defining a LANA
identifier for each port.
v Make sure that all Domino servers that will access each other have an interface that uses a common
transport protocol. It is best if they are also in the same Notes named network.
v Make sure that the network segments to which the server system’s NICs are attached do not have a
pathway in common. The NetBIOS name service (NetBIOS over IP) can fail if it detects the same
system name or Domino name echoing back between the pathways. If you are using both the NetBIOS
name service and DNS or a hosts file for name resolution, make sure that the server name in DNS or
the hosts file is different from the system name.

Chapter 2. Setting Up the Domino Network 53

54 Lotus Domino Administrator 7 Help
Chapter 3. Installing and Setting Up Domino Servers
This chapter describes how to plan a hierarchical name tree and how to install, set up, and register
Domino servers.

Server installation
The first step in deploying a Domino server is installation, or copying the program files to the system’s
hard drive.

To install Domino, see the following procedures:

Installing Domino on Windows systems

Installing Domino on UNIX and on Linux on zSeries systems

For information on installing servers for hosted environments, see the chapter ″Setting Up the Service
Provider Environment.″

Installing Domino on Windows systems

You can install Domino on a Windows system by following this procedure, or you can perform a silent
install of a local server.

For information about installing the xSP server, see the topic Installing the first server or additional
servers for hosted environments.

For information about silent server installation, see ″Using silent server installation to install Domino on
Windows systems″ in this chapter.
1. Before you install the Domino server program files on a Windows system, do the following:
v Make sure that the required hardware and software components are in place and working.
v Read the Release Notes for operating system and network protocol requirements and for any
last-minute changes or additions to the documentation.
v Temporarily disable any screen savers and turn off any virus-detection software.
v Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.
v Make sure that all other applications are closed. Otherwise, you may corrupt any shared files, and
the Install program may not run properly.
v If you are upgrading to Domino from a previous release, see the book Upgrade Guide.
2. Run the install program (SETUP.EXE), which is on the installation CD.
3. Read the Welcome screen, and click Next. Then read the License Agreement and click I accept the
terms in the license agreement, and then click Next.
4. Choose the program directory, and choose whether you are installing partitioned servers. Click Next.
5. Specify the data directory in which to copy the software. If you are installing a partitioned server, If
you are installing partitioned servers, specify a data directory for each partition.

Note: For partitions, use the Add button to add each of the data directories to the list. If they are not
added to the list they will not be installed.
6. Select the server type you acquired:

55
 v Domino Utility Server -- Installs a Domino server that provides application services only, with
support for Domino clusters. The Domino Utility Server removes client access license
requirements. Note that it does NOT include support for messaging services. See full licensing text
for details.
v Domino Messaging Server -- Installs a Domino server that provides messaging services. Note that
it does NOT include support for application services or Domino clusters.
v Domino Enterprise Server -- Installs a Domino server that provides both messaging and
application services, with support for Domino clusters.
v Customize - Allows you to select the features you want to install.

Note: All installation types support Domino partitioned servers. Only the Domino Enterprise
Server supports a service provider (xSP) environment.
7. If you are installing partitioned servers, specify a data directory for each partition.
8. Review the summary information, and then select Next to begin installing files.
9. Click Finish to complete the install program.
10. Choose Start - Programs - Lotus Applications - Lotus Domino Server, or use the icons on your
Desktop to start the Server Setup program.

Entering system commands correctly

Some of the procedures that follow include instructions for entering commands at the system command
prompt. The instructions tell you to enter the command from the ″Domino program directory″ or ″Notes
program directory,″ depending on whether you are performing the procedure on a Domino server or a
Notes workstation. Before entering commands, make sure you understand the following definitions of
these terms as they apply to your operating system.

Windows operating systems

On a Domino server, the Domino program directory is c:\lotus\domino, unless you installed the
program files to a different location. On a Notes workstation, the Notes program directory is
c:\lotus\notes, unless you installed the program files to a different location.

UNIX operating systems

For Domino on a UNIX® server, the actual location of the server program files is different from the
directory you use for entering commands. Always use the following path for entering commands:
lotus/bin/server

The ″server’″ portion of the path is a script that initializes a UNIX shell so that Domino programs can run
on UNIX.

While by default the actual location of the lotus directory is /opt/ibm/lotus, you can change it to any
location, for example, /local/lotus or /usr/lotus.

Using silent server installation to install Domino on Windows systems

Use Domino’s silent server installation to install servers without any intervention during the installation
process. The silent server installation suppresses the wizard and the launcher user interface. There is no
need to monitor the installation or to provide additional input through the typical installation dialog
boxes.

Before running Domino’s silent server install on a Windows system, do the following:
v Make sure that the required hardware and software components are in place and working.
v Read the Lotus Domino Release Notes for operating system and network protocol requirements. Check
the Release Notes for last-minute changes or additions that may impact the silent server install.
v Temporarily disable screen savers and turn off virus-detection software.

56 Lotus Domino Administrator 7 Help

v Before running any Domino setup command, complete any pending reboot actions you may have from
installing other applications.
v Make sure that all other applications are closed; otherwise, you may corrupt shared files, and the
Install program may not run properly.
v If you are upgrading from a previous Domino release, see the book Upgrade Guide.

Customized silent server install on Win32 systems

There are two steps to running a customized silent server install.
1. Create or record the response file, which contains the installation configuration information.
2. To create the response file, you can use the template file, sample_response.txt, located on the CD with
the other installation files. Modify the template file and save it to a new response file name.
3. Run the silent install referencing the response file.

Creating the response file for silent server installation

A typical (non-silent) install uses dialog boxes to receive input from you during installation. The silent
(automated) server install does not prompt you for input. Instead, response files are used to provide the
detail information for the install process. There are two methods of generating response files, the template
and record methods.

A response file created using the template method contains the literal values that are used during the
install process. It is generated prior to the execution of the installation and contains all of the default
installation options and paths. You can manually customize this file by editing options. The benefit of
using a template file is that you do not need to install a server in order to create the file.

A response file created using the record method is generated after the server install completes, at the time
the wizard exits and stores the values of the applicable wizard properties in the file. The recorded
response file is useful for saving a record of a specific wizard execution session which can later be reused
in a silent or modified installation. When you install a server, your customizations are saved to the
resulting response file, eliminating the need to edit the response file. This is the ″safer″ method because
you do not create issues caused by typos or incorrect entries and values.

Creating a response file based on a template

Use this procedure to create a response file that is based on the template, sample_response.txt. Response
files contain installation configuration information. The template file, sample_response.txt, is located on
the CD with the other installation files.

Note: It takes several minutes for the response file to be created. When the SETUP.EXE file and the
JAVA.EXE file have finished running, the new response file is ready for use. To determine whether
SETUP.EXE and JAVA.EXE have finished running, check the Task Manager.
1. To create the response file, do one of these:
v Open the template file, modify the file as necessary, and then save the file to a new name.
v Save the file to a new file name, modify the file, and then save the file again.
2. Run the silent install referencing the response file.

To use a response file

To use a response file, specify the -options parameter and the exact path to the response file on the
command line. Enter the command in the format shown in the example:
setup.exe -silent -options c:\temp\file.txt

For additional examples, see the table.

Installation activity Example

Silent install with default selections and options setup.exe - silent

Chapter 3. Installing and Setting Up Domino Servers 57

Installation activity Example
Creating a Response File: setup -options-template c:\temp\file.txt
Recording a response file setup -options-record c:\temp\file.txt
Silent install using response files setup.exe -silent -options c:\temp\file.txt

Running the Silent Server Install on Win32 Systems

To create a response file for automating the Lotus Domino installation, you must pass command line
parameters to SETUP.EXE. The command line parameters are listed and explained in the table in Step 2.

When the response file has been created, perform the silent install of the Domino server.
1. Launch the server install with any of the command line parameters shown in the table below.

Parameter Description and example

-silent Runs the basic silent server install.

For example, setup.exe -silent

-options-record filename Records in a response file, all of the installer selections you use.

For example, setup -option-record C:\temp\file.txt

Using Domino’s express install

Note: Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.

Express install is similar to a regular server install except that you have the additional option of
launching the server from the last window displayed during express install. During the express install,
you are presented with various dialog boxes and informational messages, as you would be during the
standard Domino server install; however, during express install, many of the options presented on the
dialog boxes are selected for you, resulting in a faster install process.

To run Domino’s Express Install, from the Installer command line, enter the following command:
setup -express

Note: Run Domino express server install from the full installation kit. It is not available for installation
from a Web kit.

Using silent server install on UNIX systems

These instructions apply only to UNIX systems. Before running a silent server install, read all of the
installation information in this chapter.

Running a silent server install on UNIX

1. Make a local copy of the file SCRIPT.DAT. The SCRIPT.DAT file is located in the install directory.
2. Edit the new copy of SCRIPT.DAT. The step-by-step instructions for editing the file are in the
SCRIPT.DAT file.
3. Run the install program by entering this command:
./install -script /tmp/script.dat

Note: The command shown above uses the directory name ″tmp″ but you may name this directory
according to your own naming conventions.

58 Lotus Domino Administrator 7 Help

Concurrent I/O and Direct I/O not supported on Domino servers on AIX
Concurrent I/O (CIO) and Direct I/O (DIO) are not supported with Lotus Domino servers. CIO is a file
system feature introduced in AIX 5.2.0.10, also known as maintenance level 01, in the Enhanced
Journaling File system (JFS2). This feature improves performance for many environments, particularly for
relational databases.

Because the CIO feature is not supported for use with Domino servers, do not enable this option on file
systems that Domino accesses. If this option is enabled, Domino data may be corrupted which can causes
server crashes or performance issues.

Certain core file system items, such as file buffer cache, per-file lock or inode lock, and sync daemon, are
managed differently by the operating system with the CIO option enabled. Domino is not coded to
address these changes in behavior.

The CIO option is typically enabled as a flag when a file system is mounted. Use these steps to disable
the mount option:
1. Run this command for each file system mounted with CIO:
chfs -a options=rw /FS_NAME
Where /FS_NAME is the name of the mount point.
2. Unmount and remount each file system, or reboot, which has the same effect when done after
running the chfs commands.
3. To verify that the change was applied, run ’mount’ and verify that you do not see ″cio″ in the mount
options column, as shown in the examples.

Example of output with CIO disabled

/dev/test05lv /test05 jfs2 Oct 04 23:13 rw,log=INLINE

Example of output with CIO enabled:

/dev/test03lv /test03 jfs2 Sep 19 19:25 rw,cio,log=INLINE

For more information on the CIO feature, see the AIX whitepaper ″Improving Database Performance With
AIX Concurrent I/O″ at http://www-1.ibm.com/servers/aix/whitepapers/db_perf_aix.pdf

The Domino Server Setup program

The Domino Server Setup program guides you through the choices you make to configure a Domino
server. Setting up the first Domino server in a domain establishes a framework that consists of the
Domino Directory, ID files, and documents. When you set up additional servers, you build upon this
framework.

Note: Domino first server setup creates IDs with a default public key width of 1024 bits. If a different
key width is required, run SETUP.EXE to install the Domino files but before starting the server, open the
server’s NOTES.INI file, and then set SETUP_FIRST_SERVER_PUBLIC_KEY_WIDTH to the desired key
width. For example, for Domino R5-compatible keys, install the files for the Domino server by running
SETUP.EXE, but before starting the server, open the NOTES.INI file and then set
SETUP_FIRST_SERVER_PUBLIC_KEY_WIDTH=630. The public key width can be set to either 630 or 1024
when using the NOTES.INI variable.

Setting up the first Domino server does the following:

v Creates a Domino domain.
v Creates the certification log file, names it CERTLOG.NSF, and saves it in the Domino data directory.

Chapter 3. Installing and Setting Up Domino Servers 59

v Uses the PUBNAMES.NTF template to create the Domino Directory for the domain, names the
directory NAMES.NSF, and places it in the Domino data directory.
v Creates an organization certifier ID, names it CERT.ID, and saves it in the Domino data directory.
v Optionally creates an organizational unit certifier ID, names it OUCERT.ID, and stores it in the Domino
Directory.
v Creates a Certifier document, which describes the organization certifier ID, in the Domino Directory.
v Creates a server ID, names it SERVER.ID, and saves it in the Domino data directory.
v Uses the organization certifier ID to certify the server ID.
v Creates a Server document in the Domino Directory and includes in it information that you specified
during the setup program.
v Creates a Person document in the Domino Directory for the Domino Administrator that you specified
during the setup program.
v Creates a user ID and password for the Domino Administrator and attaches it as a file named USER.ID
to the administrator’s Person document in the Domino Directory.
v Uses the organization certifier ID to certify the administrator’s user ID.
v Gives the administrator and the server Manager access in the ACL of the Domino Directory.
v Adds the server name to the LocalDomainServers group in the Domino Directory.
v Creates the log file, names it LOG.NSF, and saves it in the Domino data directory.
v Enables the appropriate network and serial ports.
v Creates a mail directory in the Domino data directory and creates a mail file in that directory for the
Domino Administrator.
v Creates the Reports file, names it REPORTS.NSF, and saves it in the Domino data directory.
v Updates network settings in the Server document of the Domino Directory.
v Configures SMTP, if selected during the setup program.
v If ″DOLS Domino Off Line Services″ was selected during the setup program, creates the Off-Line
Services file, names it DOLADMIN.NSF, and saves it in the Domino data directory,.
v Updates the Access Control List in all databases and templates in the Domino data directory tree to
remove Anonymous access and/or add LocalDomainAdmin access, depending on the selections made
during the setup program.
v Configures xSP Service Provider information, if selected during the install program.

Setting up an additional Domino server does the following:

v Copies the Domino Directory, if a file location was specified during the setup program, names it
NAMES.NSF, and saves it in the Domino data directory.
v Dials the existing Domino server if the connection is made through a modem (possible only on
Windows systems).
v Copies the server’s ID from the location specified during the setup program, either from a file, a copy
of the directory, or the existing Domino server’s directory; names it SERVER.ID; and saves it in the
Domino data directory.
v Retrieves the Domain name and Administrator name from the Server document in the Domino
Directory.
v Creates the log file, names it LOG.NSF, and saves it in the Domino data directory.
v Copies or replicates the Administration Requests file, names it ADMIN4.NSF, and saves it in the
Domino data directory.
v Copies or replicates the Monitoring Configuration file, names it EVENTS4.NSF, and saves it in the
Domino data directory.
v Replicates the Domino Directory, if it doesn’t already exist, names it NAMES.NSF, and saves it in the
Domino data directory.
v Creates a Connection document to the existing Domino server in the Domino Directory.

60 Lotus Domino Administrator 7 Help

v Creates the Reports file, names it REPORTS.NSF, and saves it in the Domino data directory.
v Updates network settings in the Server document of the Domino Directory.
v Configures SMTP, if selected during the setup program.
v If ″DOLS Domino Off-Line Services″ was selected during the setup program, creates the Off-Line
Services file, names it DOLADMIN.NSF, and saves it in the Domino data directory.
v Updates the Access Control List in all databases and templates in the Domino data directory tree to
remove Anonymous access and/or add LocalDomainAdmin access, depending on the selections made
during the setup program.
v Configures xSP Service Provider information, if selected during the install program.
v Replicates changes made to the Server document with the existing server, if any.
v Removes the SERVER.ID attachment from the Domino Directory, if applicable.

Using Domino Off-Line Services (DOLS) and Domino Web Access

To provide Domino Web Access users with the ability to work off line, you must enable DOLS when you
set up the server. DOLS enables users to work off line, disconnected from the network, and provides
many replication features that Notes users expect when working in the Notes client.

Users require a Notes ID so that DOLS can synchronize the offline mail file with the server. The default
DOLS configuration will prompt the user for a Notes ID the first time they go offline with Domino Web
Access.

If you rename a user, the user must reinstall the DOLS offline subscription in order for the offline mail
file to synchronize with the server. After a name change, the user must wait for the old Notes ID and
password to stop working, accept the name change using a Notes client, then log on to Domino Web
Access with the new Notes ID and password.

Setting up DOLS on a server

Domino Off-Line Services (DOLS) must be configured on the Domino server for users to be able to take
applications off-line and use only a browser to work with them. You can enable any application for
DOLS. The following templates are enabled for DOLS by default:
v Domino Web Access (DWA7.NTF, iNOTES6.NTF and iNOTES5.NTF)
v Extended Mail (MAIL7EX.NTF)
v Discussion - Notes and Web (R7) database (DISCSW7.NTF)

To configure DOLS during Domino Server Setup

1. Under ″Setup Internet services for,″ select ″Web Browsers (HTTP services),″ and then click Customize.
2. In the ″Domino tasks″ list, select ″DOLS Domino Off-Line Services.″
3. At the end of setup, when you have the option to create an access control list entry, add the group
LocalDomainAdmins to all databases and templates.
4. Accept the default option ″Prohibit Anonymous access to all databases and templates.″ If you deselect
this option, you must open the ACL for each DOLS application and assign No Access to Anonymous.
5. Make sure the following names are identical:
v The TCP/IP DNS host name -- In Windows, choose Start - Programs - Windows Explorer. Then
choose Network Neighborhood properties - TCP/IP properties. On the DNS Configuration tab, look
at the Host field.
v The server name -- Open the Server document and look at the Server name field.
v The Internet host name -- Open the Server document and look at the ″Fully qualified Internet host
name″ field.

Note: DOLS runs on Domino servers configured to work through a Microsoft IIS server.

Chapter 3. Installing and Setting Up Domino Servers 61

To configure DOLS manually
If you do not configure DOLS during Domino Server Setup, you can configure DOLS manually by
editing the Server document.
1. Open the Server document.
2. Click Internet Protocols - HTTP.
3. In the ″DSAPI filter file names″ field, enter the DSAPI filter file name that corresponds to the
operating system that the server is running, and then restart the server:
v Win32 - ndolextn
v Linux - libdolextn
v AIX® - libdolextn
v Solaris/Sparc - libdolextn
v S390® - libdolextn
v iSeries® - libdolextn

Note: On the iSeries platform, the Server document is updated when a new server is configured or
an existing server is modified using the CFGDOMSVR or CHGDOMSVR CL command with
DOLS(*YES) specified.
For more information on configuring an iSeries server with DOLS, see the Lotus Domino 7 for iSeries
Release Notes.
4. Create a DOLADMIN.NSF database from the template DOLADMIN.NTF.
5. After the database is created, restart the Domino administrator and click the Configuration tab. The
name of the DOLADMIN.NSF is an option in the Navigation pane.

To set up DOLS on clustered servers

Before using DOLS on a clustered Domino 7 server, make sure that:
v The Domino server is either a Domino Utility Server or Domino Enterprise Server.
v All servers in the cluster run the same release of Domino with DOLS
v Clustered server management is running to handle both failover of replication and HTTP
v Internet Cluster Manager is running
v Subscription directories must have the same name on every clustered server. For example, if a
subscription is under \data\Webmail user\7CD5957CB669AE2285256BDF00567AD8\, this name cannot
be different on a different server in the cluster.

To configure DOLS on a server that uses Web Site documents

If you create a Web Site Document (a type of Internet Site document) on the Domino server, you must
add the appropriate DOLS DSAPI filter filename to the DSAPI field in the Web Site document for DOLS
to be enabled. If there are several Web Site documents, you must add the DSAPI filter filename to each
one. To add the DOLS DSAPI filter filename to a Web Site document:
1. Open the Web Site document.
2. Click the Configuration tab.
3. In the ″DSAPI filter″ field, enter the DSAPI filter file name that corresponds to the operating system
that the server is running, and then restart the server:
v Win32 - ndolextn
v Linux - libdolextn
v AIX - libdolextn
v Solaris/Sparc - libdolextn
v S390 - libdolextn
v iSeries - libdolextn

62 Lotus Domino Administrator 7 Help

For more information on Internet Site documents, see the topic ″Configuring Internet sites with Web Site
and Internet Site documents.″

Setting up Domino Web Access on a server

Domino Web Access provides Notes users with browser-based access to Notes mail and Notes calendar
and scheduling features. Using Domino Web Access, a user can send and receive mail, view the calendar,
invite people to meetings, create to do lists, keep a notebook, and work off line.

To set up Domino Web Access, choose ″Web Browsers (HTTP Web services)″ during Server Setup. If you
want to give users the ability to work off line, also choose Domino Off-Line Services (DOLS). DOLS is
not required to run Domino Web Access.

Note: When providing a Domino domain name, do not use a period. For example, use AcmeProduction
as a domain name instead of Acme.Production.

In the Domino Administrator, make sure that the Fully Qualified Domain name (FQDN) (such as
acme.lotus.com) is specified on the Basics tab of the Server document.

Setting up Domino Web Access with Sametime

Domino Web Access (DWA) integrates an instant messaging (IM) capability so that users can chat with
their co-workers online and maintain an instant messaging list that shows the online status of other users.
The instant messaging awareness feature also displays online status next to the names of people in mail
messages, views and folders.

There are two versions of Sametime available for Domino 7.0, however these instruction apply to both
version. References to the Sametime server also apply to installing the limited use version. The two
versions are:
v IBM Lotus Instant Messaging Limited Use -- the default instant messaging capability that is included in
Domino 7.0.
v IBM Lotus Sametime® -- the full instant messaging product that includes Web conferencing capabilities.
It is available only if your organization purchased it.

For complete information on installing IBM Lotus Sametime, see the IBM Lotus Sametime 7.0 Installation
Guide for your operating system, and the IBM Lotus Sametime 7.0 Administrator’s Guide. To view or
download the Sametime documentation, go to http://www.lotus.com/LDD/doc.

Configuration Notes:
v For Mozilla, you must have at least Sametime 3.1 to run instant messaging integration. Previous
versions of Lotus Sametime are not supported in Domino Web Access on Mozilla.
v When you install Domino 7.0, the stlinks files that are installed in the stlinks directory (for example,
C:\st\domino\Data\domino\html\sametime\stlinks), are overwritten. If you have modified stlinks
files (for example, if the Sametime server is configured for tunneling) these files will be replaced. When
you are upgrade to 7.0, these files are backed up in a file called stlinks.sav. For additional information,
see the topic Customizing STLinks files for tunneling or reverse proxy servers.
v To access the Sametime server using a protocol that is different from the current Web page’s protocol,
use the NOTES.INI configuration setting iNotes_WA_SametimeProtocol.
v Sametime integration with Domino Web Access is not supported with JRE 1.4.1.

Part 1 - Set up Domino Web Access on a Domino server:

1. Set up Domino Web Access on a server by making the appropriate selections during server setup.
2. Register users with the Domino Web Access (DWA7.NTF) mail template.

Chapter 3. Installing and Setting Up Domino Servers 63

Part 2 - Set up the Sametime server: If possible, the Sametime server should be in the same Domino
domain as the Domino Web Access server. Follow the instructions in the IBM Lotus Sametime 7.0
Installation Guide to install and configure instant messaging on a dedicated Domino server in the same
Domino domain as the Domino Web Access server.

If the Sametime server is in a different domain than your Domino Web Access server, follow the
instructions in Setting up Sametime and Domino Web Access in different domains.

Make sure the Sametime server is functioning properly before proceeding. If you have multiple Sametime
servers in a single community, also make sure that Domino single sign-on (SSO) is functioning properly
between the servers. For complete information on working with multiple Sametime servers, see the IBM
Lotus Sametime 7.0 Administrator’s Guide, available on http:\\www.lotus.com/ldd/doc.

Part 3 - Create Connection documents: You need Connection documents for the Domino Web Access
and the Sametime server if the Sametime server is not in the same domain as the Domino Web Access
server. Also, if the Sametime server is in the same domain as the Domino Web Access server, but is not
clustered with the registration server, you need a Connection document in order to replicate the Domino
Directory.

Create Connection documents using the standard procedure, and include the information below:

On the Domino Web Access server:

v Enter the Sametime server’s name in the ″Destination server″ field. For example: Sametime/Acme.
v Enter the Domino Web Access server’s name in the ″Source domain″ field.
v Enter the Sametime server’s name in the ″Destination domain″ field.

On the Sametime server:

v Enter the Domino Web Access server’s name in the ″Destination server″ field.
v Enter the Sametime server’s name in the ″Source domain″ field.
v Enter the Domino Web Access server’s name in the ″Destination domain″ field.

Part 4 - Specify the Sametime server for Domino Web Access users: There are two ways to specify a
Sametime server for Domino Web Access users. You can edit the Configuration Settings document for the
Domino Web Access server, or you can edit the person document for each user who uses instant
messaging.

Method 1

To enable instant messaging and set the Sametime server for all Domino Web Access users at one time,
use the Instant Messaging settings in the Configuration Settings document, Domino Web Access tab. After
you have done this, individual users can enable or disable instant messaging on their local Domino Web
Access clients by setting a User Preference.

Method 2

If you choose not to enable instant messaging for all users, then you must edit the person document for
each user who will use instant messaging:
1. From the Domino Administrator, click the People & Groups tab.
2. Select the Domino Web Access Domino directory, then click People.
3. Double-click a name to open the user’s Person document.
4. Click Edit.
5. Enter the name of the Sametime server in the ″Sametime server″ field. For example,
Sametime/Sales/Acme/UK.

64 Lotus Domino Administrator 7 Help

6. Click ″Save & Close.″
7. Repeat Steps 3 though 6 for each person.

Part 5 - Set up Domino Web SSO authentication between the DWA server and IM server: Domino
single sign-on (SSO) authentication allows Web users to log in once to a Domino or WebSphere server,
and then access any other Domino or WebSphere server in the same DNS domain that is enabled for
single sign-on (SSO) without having to log in again. In a multiple server environment, it is possible that
one or more servers in your Domino domain are already configured for Domino SSO, and the Domino
Directory already contains a Domino Web SSO configuration document. When you install Sametime, it
creates a Web SSO configuration document called LtpaToken unless one already exists in the Domino
directory. If an LtpaToken configuration document already exists, Sametime does not attempt to alter it.

For more information about Domino Web SSO authentication, see the topic Multi-server session-based
name-and-password authentication for Web users (single sign-on).

Configure the Domino Web Access server for Web SSO

Complete the steps in this section if your DWA server is not configured for Web SSO, and you want to
use the Web SSO document that Sametime created to configure it.
1. Ensure that the Domino Directory has replicated throughout the Domino domain since you installed
Sametime.
2. Update the Web SSO Configuration document that was created when you installed Sametime
(LtpaToken):
a. Open the Domino Directory and select the Configurations - Web - Web Configurations view.
b. From within this view, expand the list of Web SSO Configurations.
c. Open the ″Web SSO Configuration for LtpaToken″ document in edit mode. (If you are unable to
edit the document, record the settings in the document, and then delete it and create a new one.)
d. Update these fields if necessary:
Domino Server Names -- make sure this field contains the name of all of the DWA servers and
Sametime servers that should participate in Single Sign-on.
DNS Domain -- make sure this is the fully-qualified domain name of the DWA and Sametime
server.
e. Click Save & Close.
3. Enable single sign-on and basic authentication in the Server document for the DWA server as
described in Enabling single sign-on and basic authentication. When you update the Web SSO
Configuration field, select LtpaToken from the list.
4. Ensure that the updates replicate to all of the servers in the domain.

Update Domino Web Access server Web SSO configuration

Complete the steps in this section if your DWA server is already configured for Domino Web SSO. You
must add the Sametime server to your configuration:
1. Update your existing Domino Web SSO Configuration document.
a. Open the Domino Directory and select the Configurations - Web - Web Configurations view.
b. From within this view, expand the list of Web SSO Configurations.
c. Open the Domino Web SSO document that you are using for your DWA server in edit mode.
d. Update these fields if necessary:
Domino Server Names -- make sure this field contains the name of all of the DWA servers and
Sametime servers that should participate in Single Sign-on.
DNS Domain -- make sure this is the fully-qualified domain name of the Sametime server.
e. Click save & Close.

Chapter 3. Installing and Setting Up Domino Servers 65

2. Update the Server document for the Sametime server.
a. Open the server document.
b. Click Internet Protocols - Domino Web Engine, and select the Web SSO Configuration field.
c. From the drop-down list, select the Web SSO Configuration that you are using for the DWA server.
d. Click Save & Close.
3. Ensure that the updates replicate to all of the servers in the domain.

Although Domino SSO is the preferred authentication method, you can continue to use secrets and
tokens authentication databases, if you are already using them. For example, if any of the servers in your
domain is configured for something other than multiple server SSO, (single server SSO for example) you
must use secrets and tokens authentication. For information on setting up Secrets and Tokens
authentication, see the topic Setting up Secrets and Tokens authentication for instant messaging in
Domino Web Access.

Part 6 - (for mixed environments only) Copy the SametimeApplet folder on the Domino Web Access
server to the Sametime server: For a mixed environment, in which the users’ mail files are based on the
INOTES5.NTF mail template, and they are using Domino Web Access Chat, you must copy the
SametimeApplet folder from the Domino Web Access server to the same location on the Sametime server.
On the Domino Web Access server, the applets are located in the <data directory>\domino\html
directory.

Note: Chat is the Domino Web Access feature that provided awareness and allowed people to chat with
co-workers in Domino Web Access prior to 6.5.2. To use Chat, you must also lower the value of the
instant messaging security setting in the SAMETIME.INI file to allow a connection from an older client.
For iNotes5 and iNotes6 mail templates, use VP_SECURITY_LEVEL=20. For more information on
specifying the minimum security level, see the IBM Lotus Sametime 7.0 Installation Guide (available on
http://www.lotus.com/LDD/doc), which details this setting.

Part 7 - Verify that instant messaging works with Domino Web Access:
1. Make sure that replication is complete, the Person documents exist on the Sametime server, and that
the updated Web SSO document exists on all of the servers that will participate in single sign-on..
2. If you have not already done so, follow the instructions in the IBM Lotus Sametime 7.0 Installation
Guide to verify that instant messaging is working properly before you test whether it is working with
Domino Web Access clients.
3. Launch Domino Web Access in a browser. In any view or document in which online awareness
appears, click the Active status icon of the person you want to chat with to test the instant messaging
connection.

Note: If the instant messaging status does not appear next to the Welcome username text in Domino Web
Access, check the user’s Person document in the Domino directory. If you configured the Sametime server
by populating this document, make sure the ″Sametime server″ field is correct (Basics tab, under
Real-Time Collaboration).

Setting up Secrets and Tokens authentication for instant messaging in Domino

Web Access
If you want to use Secrets and Tokens authentication databases for your instant messaging security
instead of Domino Single Sign-On (SSO) Authentication, you must Create a one-time replica of the
Tokens database on the Domino Web Access server. When you do this, remember that file names are case
sensitive on UNIX, so the Secrets database name must be entered exactly as STAuthS.nsf.

To replicate STAuthS.nsf from the Sametime server to the Domino server directory:
1. Using a Notes client, choose File - Database - Open.
2. Enter the name of the Sametime server (for example, Sametime/Acme).

66 Lotus Domino Administrator 7 Help

3. Enter the Secrets database filename: STAuthS.nsf
4. Click Open.
5. Choose File - Replication - New Replica.
6. Enter the name of the Domino Web Access server (for example, iNotes/Acme)
7. Ensure that the database is replicated to the data directory: ...\domino\data\stauths.nsf.
8. Click OK to create the replica.

Note: After you have replicated stauths.nsf from your Sametime server to your Domino server, open the
Replication Settings dialog box for the database, click Other, and check the ″Temporarily disable
replication for this replica″ box. This will prevent another version of the database from a Windows
system from overwriting your name change (using uppercase and lowercase letters) for the UNIX server.

Customizing STLinks files for tunneling or reverse proxy servers

If your Sametime server is configured for tunneling or if you are using reverse proxy servers in your
environment, you may need to customize some files on both your DWA server and your Sametime
server.

Using a custom port for tunneling: If the Sametime server is configured for tunneling on port other
than 8082, you must modify the stlinks.js file on both the Sametime server and the DWA server.
1. Locate the following directory on your Sametime server. This directory contains both the stlinks.js file
and the hostinfo.js file.
<sametime_data_directory>\domino\html\sametime\stlinks
2. Copy the following two lines from the Hostinfo.js file to the beginning of the stlinks.js file (by default,
there are only 2 lines in the Hostinfo.js file):
var HTTP_TUNNELING_PORT=xx;
var TUNNELING_ADDRESS="";
The values you see for these variables in the hostinfo.js file should match your Sametime server
tunneling configuration. For releases after 2.5, Sametime normally creates and automatically updates
the content of these files on the Sametime server.
3. Save the updated stlinks.js file on the Sametime server.

Note: When you upgrade your Sametime server to a later release, the stlinks.js file is replaced with
the default version and you must perform steps 1-3 again to update the file. It is also possible that
installing a Sametime fix pack may make it necessary to restore the updates.
4. Copy the updated stlinks.js file from the Sametime server to the DWA server, replacing the existing
stlinks.js file in <domino_data_directory>\domino\html\sametime\stlinks.

Note: If the DWA server is running on i5/OS, make sure that the owner of the stlinks.js file is set to
QNOTES.

Using reverse proxy servers: If your network environment uses reverse proxy servers to protect the
identities of servers behind a firewall, you may need to modify the stlinks.js file on both the DWA server
and the Sametime server.

You must modify the stlinks.js file if you want DWA users to be able to connect to the Sametime
community inside the intranet even if they are outside the firewall. Stlinks.js is located in the following
directory on each server: <domino_data_directory>\domino\html\sametime\stlinks

Two variables that provide reverse proxy support are included in stlinks.js:
ll_RProxyName - the reverse proxy name
ll_AffinityId - the Sametime server affinity ID

Chapter 3. Installing and Setting Up Domino Servers 67

To enable reverse proxy support, the server administrator must replace the defaults with appropriate
values and uncomment the lines. For example:
var ll_RProxyName="https://proxy.ibm.com";
var ll_AffinityId="st1";

Make sure you update the stlinks.js file on both the DWA server and the Sametime server.

For more information about reverse proxy support, see the IBM Lotus Sametime 7.0 Installation Guide
(available on http://www.lotus.com/LDD/doc).

Once you have customized the contents of the stlinks.js files, there are some issues related to future
server upgrades that you need to be aware of:
v When you upgrade Domino to a new release, the customized STLinks files may be replaced, and
DWA-Sametime integration to stop working. This can occur when you upgrade Domino on either the
DWA server or the Sametime server.
In recent Domino releases, the original contents of the STlinks directory are backed up to the following
directory before the files are replaced:
Windows: <domino_data_directory>\domino\html\sametime\stlinks.save
AIX and Solaris: <domino_data_directory>/domino/html/sametime/stlinks.save
i5/OS: <domino_data_directory>/domino/html/sametime/stlinks/stlinks.sav
After you upgrade Domino on either the DWA server or the Sametime server, restore any stlinks.js
customizations from the file in the backup directory to the file in the stlinks directory.
v When you update the level of Sametime by installing a newer release of Sametime or applying a fix
pack, it is possible that you will also need to copy the newer version of the stlinks directory to your
DWA server. Make sure you check the documentation that accompanies the Sametime update to
determine if this is necessary. If this occurs, you will need to reapply your stlinks.js customizations on
each of the servers.

Setting up Sametime and Domino Web Access in different domains

If you prefer to use Web single sign on (SSO) authentication, see the topic Setting up the Web SSO
Configuration document for more than one Domino Domain.

To set up a cross-domain configuration when the Sametime server and the Domino Web Access server are
located in different domains:
1. Cross certify both domains with each other.
2. Configure Directory Assistance on the Sametime server.
3. If you have set up single sign on (SSO), go to Step 4. If you do not have SSO set up, replicate
STAuthS.nsf to the Domino Web Access Server (file name is case sensitive on UNIX servers).
4. Create a server document for the Sametime server in the Domino Directory of the Domino Web
Access server, completing the fields below. Another way to do this is to edit Configuration Settings
document, Domino Web Access tab, and enter the Sametime server name in the in the field ″Set an
instant messaging server hostname for all DWA users.″ If you use this setting, you do not need to
complete Step 5.
v Server name
v Domain name
v Fully qualified Internet host name
v Is this a Sametime server?
5. Enter the Sametime server name in the Sametime Server field of each Domino Web Access user’s
Person document.

Note: If the Sametime server is configured using a port other than the default port, then the ″Fully
Qualified Hostname″ field must contain hostname:port.

68 Lotus Domino Administrator 7 Help

For complete information on working with multiple Sametime servers, see the IBM Lotus Sametime 7.0
Administrator’s Guide, available on http://www.lotus.com/LDD/doc.

Troubleshooting Sametime in Domino Web Access

If instant messaging icons do not display in Domino Web Access mail and the Contact List, check the
following:
v The Sametime server is up running. To make sure stlinks is running normally, you can check the
Sametime server directory \trace\stlinks.txt log file.
v All the ST**** services are up running. Check the control panel - services; all ST**** services should be
running when the Sametime server has fully started. If there are ST**** services not running, start
STCommunity server first. If this service cannot be started, check the network connections and the
Sametime server log file.
v Make sure the \stlinks directory and the files are on both the Sametime server and application server
directories.
v When you update the level of Sametime by installing a newer release of Sametime or applying a fix
pack, it is possible that you will also need to update the stlinks files on your DWA server. Make sure
you check the documentation that accompanies the Sametime update.
v If you had previously customized the STLinks files and have recently upgraded either your Sametime
server or your Domino Web Access server to a new version of Domino, the customized files may have
been replaced. See the topic Customizing STLinks files for tunneling or Reverse Proxy servers.
v Make sure the user has enabled Instant Messaging in Preferences.
v Make sure the user’s Person document has been set up with the Sametime server names.
v Use the http:// protocol only for the Sametime server.

To identify the current Sametime server version:

1. Type the following URL: http://<Sametime server hostname>/stcenter.nsf if the Sametime server is
running on a Windows platform. To avoid case sensitive issues on other platforms, search for the file
under <Sametime server directory>/stcenter.nsf and use the file name case as it shown there.
2. At the bottom of the page, click Administer the Server.
3. Login to Instant Messaging, and then click Help - About Sametime.

Browser Address: The instant messaging integration features rely on the ability of the browser to
directly communicate with the Sametime server. This means that the fully-qualified Internet hostname of
the Sametime server must be resolvable from the browser (for example, the fully qualified Internet
hostname for a Domino server named IM/Acme might be im.acme.com).

Therefore, either DNS must be able to resolve this address or it must be resolved to the proper IP address
by some other mechanism (such as editing of the local operating system’s hosts file).

Using the Domino Server Setup program

The following procedures describe the ways you can use the Server Setup program.
v Use the Server Setup program on the server you are setting up
v Use the Server Setup program from a client system or from another server
v Create a setup profile by recording your choices during the Server Setup program
v Use a setup profile to set up multiple servers with the same requirements
v Use a setup profile without viewing the setup screens (″silent″ setup)
v Using automatic server setup on Linux on zSeries and on UNIX

Chapter 3. Installing and Setting Up Domino Servers 69

Indic language support in the Domino Server Setup program
You can change both the font and the alphabet that displays when you enter text in a field on a Server
Setup program screen. Normally, the alphabet that displays is that of the default language.

The Domino Server Setup program supports the following alphabets:

Bengali

Devanagari

Gujarati

Gurmukhi

Kannada

Malayalam

Oriya

Tamil

Telugu

To change the font

Note: Changing the font is required for the Devanagari alphabet, as the default font does not work with
it.
1. Start the setup program by starting the Domino server.
2. On the Welcome screen, click Font.
3. Select a font that will work with the alphabet you plan to use.
4. To select an alphabet different from that of the default language, see the following procedure.

To change the alphabet

Changing the alphabet is supported for the Windows, AIX, and Linux operating systems only.
1. Start the setup program by starting the Domino server.
2. Right-mouse click on the title bar of the screen in which you want to enter text that uses an alphabet
different than that of the default language.
3. Select ″Select Input Method.″
4. Select the alphabet that you want to use.
5. Enter text in one or more fields on the screen.

Note: Clicking Next to go to the next screen restores the alphabet to that of the default language. Repeat
the preceding procedure for each screen on which you want to use a different alphabet.

Using automatic server setup on Linux on zSeries and on UNIX

Automatic server setup is a UNIX and Linux on zSeries feature for single local Domino servers. When
automatic server setup is used for new server installations, server setup runs automatically after the
server installation is complete. For server upgrades, the server is restarted automatically after the
installation is complete.

Automatic server setup does not apply to partitioned servers or to remote servers.

70 Lotus Domino Administrator 7 Help

By default, server setup is set to manual so that the server setup does not automatically run for new
server installs, and server restart does not automatically run for server upgrades.

You can enable this feature from the script file containing all of the user configuration parameters for
UNIX script installation. In the UNIX kit directory, the sample script file is SCRIPT.DAT.

Note: Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.

Enabling automatic server setup from the script file

To enable the automatic server setup feature from the script file, complete the following steps.
1. Open your script file.
2. Locate the variable, start_server_setup =

Note: The default is start_server_setup = 0, which is the manual setting. When the manual setting (0)
is active, you must manually initiate the server setup or server restart.
3. Enter one of these values according to when you want automatic setup to run:
v 0 -- To disable automatic server setup and enable manual setup. You have to manually start the
server after a new server installation or restart the server after an upgrade when you use this
setting.
v 1 -- To automatically launch server setup after installation or to automatically restart the server after
a server upgrade.

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.
When the Install program starts, it asks for the password of the ID that owns the Notes data directory.
v 2 -- To automatically launch server setup in listen mode after installing a new server. You can then
connect to the server using the Remote Server Setup tool. To automatically restart the server after
installing a server upgrade.

Note: When the Install program starts on a Linux on zSeries system, the program asks for the
password of the ID that owns the Notes data directory.

Enabling automatic server setup from the user interface

To enable the automatic server setup feature from the UNIX or Linux on zSeries user interface, complete
the following steps.
1. Locate the option ″Select server setup method.″

Note: The default is Manual Server Setup. When the manual setting (0) is active, you must manually
initiate the server setup or server restart.
2. Press the Spacebar until you see the setting you want to use. You can use one of the following
settings:
v Local Server Setup -- To automatically launch server setup after installation or to automatically
restart the server after a server upgrade.

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.
When the Install program starts, it asks for the password of the ID that owns the Notes data directory.
v Remote Server Setup -- To automatically launch server setup in listen mode after installing a new
server. You can then connect to the server using the Remote Server Setup tool. To automatically
restart the server after a server upgrade.

Chapter 3. Installing and Setting Up Domino Servers 71

 Note: When the Install program starts on a Linux on zSeries system, the program asks for the
password of the ID that owns the Notes data directory.
v Manual Server Setup -- To disable automatic server setup and enable manual setup. You have to
manually start the server after a new server installation or restart the server after an upgrade when
you use this setting.
3. Press Tab to accept the setting.

Using the Domino Server Setup program locally

After installing the Domino server program files on a server, you can run the Domino Server Setup
program locally by starting the server. The Server Setup program asks a series of questions and guides
you through the setup process. Online Help is available during the process.

Note: During server setup, you can use an existing certifier ID instead of creating a new one. The
certifier ID that you specify cannot have multiple passwords assigned to it. Attempting to use a certifier
ID with multiple passwords generates an error message and causes server setup to halt.

If you are using Linux on zSeries, you cannot use the Domino Server Setup program locally. You must
use the Domino Server Setup program remotely, as described in the next section.

Note: Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.

Using the Domino Server Setup program remotely

After you install the program files for a Domino server on a system, you can use either a Windows client
system or another Domino server to run the Server Setup program remotely. Running the Server Setup
program from a Windows client is easier if the client has Domino Administrator installed -- to run the
program from a client without Domino Administrator, you need the Java runtime environment plus some
files from the program directory of an installed Domino server.

Note: During server setup, you can use an existing certifier ID instead of creating a new one. The
certifier ID that you specify cannot have multiple passwords assigned to it. Attempting to user a certifier
ID with multiple passwords generates an error message and causes server setup to halt.

For more information, see the topic ″Entering system commands correctly″ earlier in this chapter.

To run the Server Setup program from a Windows client with Domino
Administrator
Note: Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.
1. Make sure that you:
v Selected ″Remote Server Setup″ when you installed Domino Administrator on the client system (on
the Windows desktop, choose Start - Programs - Lotus Applications and see if Remote Server Setup
appears in the list)
v Know the host name or network address of the remote system
2. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
3. At the command prompt on the server system, from the Domino program directory, do one of the
following:
v On a Windows server, enter
nserver -listen
v On a UNIX server, enter
server -listen

72 Lotus Domino Administrator 7 Help

4. On the client system, choose Start - Programs - Lotus Applications - Remote Server Setup.
5. In the Connect to Remote Domino Server dialog box, click Ping to ensure that you can connect to the
remote server.
6. Enter the host name or network address of the remote server.
7. Click OK to start the Domino Server Setup program.

To run the Server Setup program from a Windows client without Domino
Administrator, or from a UNIX workstation
Note: Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.
1. Make sure that you know the host name or network address of the remote system.
2. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
3. At the command prompt on the server, from the Domino program directory, do one of the following:
v On a UNIX server, enter
/lotus/bin/server -listen
v On a Windows server, enter
nserver -listen
4. On the client system, install the Java runtime environment.
5. Create a temporary directory on the client system. For example, enter the following at the command
prompt:
v On a Windows client:
mkdir c:\temp
v On a UNIX workstation:
mkdir /temp
6. Do one of the following:
v From a Windows client, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP.CMD from the server to the directory you created on the client system. These files
are in C:\Domino program directory on the server.
v From a UNIX workstation, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP from the server to the directory you created on the workstation. These files are in
/Domino program directory/lotus/notes/latest/ibmpow/ on an AIX server, /Domino program
directory/lotus/notes/latest/zlinux/ on a Linux on zSeries server, /Domino program
directory/lotus/notes/latest/linux/ on a Linux server, and /Domino program
directory/lotus/notes/latest/sunspa/ on a Solaris server.

Note: Linux on zSeries and z/OS ship tar files on the cd which contain all the files needed for
remote server setup.
v On Linux on zSeries -- ZLINUX_CLIENT.TAR
v On z/OS -- ZOS_CLIENT.TAR
7. At the command prompt on the client system, from the directory you created, do one of the
following:
v On a Windows client, enter remotesetup.cmd
v On a UNIX workstation, enter remotesetup
8. In the Connect to Remote Domino Server dialog box, click Ping to ensure that you can connect to the
remote server.
9. Enter the host name or network address of the remote server.
10. Click OK to start the Domino Server Setup program.

Chapter 3. Installing and Setting Up Domino Servers 73

To run the Server Setup program from another server system
1. Install the Domino server program files on both server systems, but do not run the Domino Server
Setup program.
2. Make sure that you know the host name or network address of the remote system.
3. At the command prompt on the local server system, from the Domino program directory, do one of
the following:
v On a Windows server, enter
nserver -listen
v On a UNIX server, enter
server -listen
4. Do one of the following:
v On a Windows server, enter
nserver -remote
v On a UNIX server, enter
server -remote

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.

Tip: Entering nserver -help or server -help displays all parameters available for working with
remote server setups.
5. In the Connect to Remote Domino Server dialog box, click Ping to ensure that you can connect to the
remote server.
6. Enter the host name or network address of the remote server.
7. Click OK to start the Domino Server Setup program.

Creating a server setup profile

A server setup profile is a file that you use to quickly configure servers. To create a server setup profile,
you run the Server Setup program in record mode, either at the server you are setting up or from a
Windows client. Creating a server setup profile from a Windows client is easier if the client has Domino
Administrator installed -- to create a profile from a client without Domino Administrator, you need the
Java runtime environment plus some files from the program directory of an installed Domino server.

For more information, see the topic ″Entering system commands correctly″ earlier in this chapter.

To create a setup profile at a server

1. Install the Domino server program files on the server system, but do not run the Domino Server
Setup program.
2. At the command prompt on the server, from the Domino program directory, do one of the following:
v On a Windows server, enter
nserver -record
v On a UNIX server, enter
server -record

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.

Tip: Entering nserver -help or server -help displays the parameters available for working with
server setup profiles.
3. Enter a name and description for the profile.

74 Lotus Domino Administrator 7 Help

4. Continue through the setup program.
Domino saves your selections in a file with the name you specified in Step 3. By default this file is
created in the Domino program directory.

To create a setup profile from a Windows client with Domino Administrator

1. Make sure that you selected ″Remote Server Setup″ when you installed Domino Administrator on the
client system.
2. Install the Domino server program files on the server system, but do not run the Domino Server
Setup program.
3. At the command prompt on the client system, from the Notes program directory, enter
serversetup -record
4. Enter a name and description for the profile.
5. Continue through the setup program.
Domino saves your selections in a file with the name you specified in Step 4 and stores the file in the
Notes program directory on the client system.

To create a setup profile from a Windows client without Domino Administrator or

from a UNIX workstation
1. Install the Domino server program files on the server system, but do not run the Domino Server
Setup program.
2. On the client system, install the Java runtime environment.
3. Create a temporary directory on the client system. For example, enter the following at the command
prompt:
v On a Windows client:
mkdir c:\temp
v On a UNIX workstation:
mkdir /temp
4. Do one of the following:
v From a Windows client, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP.CMD from the server to the directory you created on the client system. These files
are in C:\Domino program directory on the server.
v From a UNIX workstation, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP from the server to the directory you created on the workstation. These files are in
/Domino program directory/lotus/notes/latest/ibmpow/ on an AIX server, /Domino program
directory/lotus/notes/latest/zlinux/ on a Linux on zSeries server, /Domino program
directory/lotus/notes/latest/linux/ on a Linux server, and /Domino program
directory/lotus/notes/latest/sunspa/ on a Solaris server.

Note: Linux on zSeries and z/OS ship tar files on the CD that contains the files needed for remote
server setup.
v On Linux on zSeries -- ZLINUX_CLIENT.TAR
v On z/OS -- ZOS_CLIENT.TAR
5. At the command prompt on the client system, from the directory you created, enter:
remotesetup -record

Note: For Linux on zSeries and z/OS, Set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.
6. Enter a name and description for the profile.
7. Continue through the setup program.
Domino saves your selections in a file with the name you specified in Step 6 and stores the file in the
client-system directory that you created in Step 3.
Chapter 3. Installing and Setting Up Domino Servers 75
Using a server setup profile
You can use a server setup profile at the server you are setting up or from a client system. Using a server
setup profile from a Windows client is easier if the client has Domino Administrator installed -- to use a
profile from a Windows or UNIX client without Domino Administrator, you need the Java runtime
environment plus some files from the program directory of an installed Domino server.

When you use a setup profile, you choose whether or not to view the setup screens as you run the
profile. Running a profile without viewing the screens is sometimes referred to as a ″silent″ setup.

For more information, see the topic ″Entering system commands correctly″ earlier in this chapter.

To use a setup profile at the server

1. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
2. At the command prompt on the server, from the Domino program directory, do one of the following:
v On a Windows server, enter
nserver -playback
v On a UNIX server, enter
server -playback

Tip: Entering nserver -help or server -help displays the parameters available for working with
server setup profiles.
3. Choose the profile to use. If you don’t see the profile you want in the list, click Browse to locate the
directory that contains the profile.
4. To change the existing profile, select ″Modify selected profile.″ Click OK to start the server setup.

To use a setup profile from a Windows client with Domino Administrator

1. Make sure that you selected ″Remote Server Setup″ when you installed Domino Administrator on
the client system.
2. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
3. At the command prompt on the server system, from the Domino program directory, do one of the
following:
v On a Windows server, enter
nserver -listen
v On a UNIX server, enter
server -listen
4. At the command prompt on the Windows client, from the Notes program directory, enter:
serversetup -playback
5. In the Connect to Remote Domino Server dialog box, click Ping to ensure that you can connect to the
server.
6. Enter the host name or network address of the server.
7. Click OK.
8. Choose the profile to use. If you don’t see the profile you want in the list, click Browse to locate the
directory that contains the profile.
9. To change the existing profile instead of running it to set up a new server, select ″Modify selected
profile.″
10. Click OK to start the server setup.

76 Lotus Domino Administrator 7 Help

To use a setup profile from a Windows client without Domino Administrator or
from a UNIX workstation
1. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
2. At the command prompt on the server system, from the Domino program directory, do one of the
following:
v On a Windows server, enter
nserver -listen
v On a UNIX server, enter
server -listen
3. On the client system, install the Java runtime environment.
4. Create a temporary directory on the client system. For example, enter the following at the command
prompt:
v On a Windows client:
mkdir c:\temp
v On a UNIX workstation:
mkdir /temp
5. Do one of the following:
v From a Windows client, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP.CMD from the server to the directory you created on the client system. These files
are in C:\Domino program directory on the server.
v From a UNIX workstation, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP from the server to the directory you created on the workstation. These files are in
/Domino program directory/lotus/notes/latest/ibmpow/ on an AIX server, /Domino program
directory/lotus/notes/latest/zlinux/ on a Linux on zSeries server, /Domino program
directory/lotus/notes/latest/linux/ on a Linux server, and /Domino program
directory/lotus/notes/latest/sunspa/ on a Solaris server.

Note: Linux on zSeries and z/OS ship tar files on the CD that contains the files needed for remote
server setup.
v On Linux on zSeries -- ZLINUX_CLIENT.TAR
v On z/OS -- ZOS_CLIENT.TAR
6. At the command prompt on the client system, from the directory you created, enter:
remotesetup -playback

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.
7. In the Connect to Remote Domino Server dialog box, click Ping to ensure that you can connect to the
server.
8. Enter the host name or network address of the server.
9. Click OK.
10. Choose the profile to use. If you don’t see the profile you want in the list, click Browse to locate the
directory that contains the profile. To change the existing profile, select ″Modify selected profile.″
11. Click OK to start the server setup.

Using silent server setup

A ″silent″ setup is one in which you do not view the setup screens as you run the server setup profile.
You can do a silent setup at the server you are setting up or from a client system. Doing a silent setup
from a Windows client is easier if the client has Domino Administrator installed -- to do a silent setup

Chapter 3. Installing and Setting Up Domino Servers 77

from a Windows or UNIX client without Domino Administrator, you need the Java runtime environment
plus some files from the program directory of an installed Domino server.

Tip: When doing a silent setup, display a progress bar (Windows) or have percent-complete written to
the command line (UNIX) by adding the -pb parameter to the end of the command.

For more information, see the topic ″Entering system commands correctly″ earlier in this chapter.

To do a silent setup at the server

Note: Before running any Domino setup command, be sure to complete any pending reboot actions you
may have from installing other applications.
1. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
2. At the command prompt on the server, from the Domino program directory, do one of the following:
v On a Windows server, enter
nserver -silent c:\myprofile.pds
v On a UNIX server, enter
server -silent /myprofile.pds
where myprofile is the name you gave to the profile file.

Note: If the profile file is not in the root directory, use the profile’s full path in the command.

Tip: Entering nserver -help or server -help displays the parameters available for working with
server setup profiles.
3. If the profile uses existing server, certifier, or administrator IDs that require passwords, do the
following:
a. Create a text file that contains the passwords for the existing IDs. The keywords in this are:
Server=
AddServer=
Certifier=
OUCertifier=
Administrator=
b. Add a parameter in the command line for the name of the password file. For example, on
Windows enter:
nserver -silent c:\myprofile.pds c:\passwd.txt
4. If this is a partitioned server setup, add the = parameter to the command line to specify the
NOTES.INI file in this partition’s Domino data directory. For example, on Windows enter:
nserver -silent c:\myprofile.pds =c:\lotus\domino\data2\notes.ini
5. Check the ERRORLOG.TXT file in the Domino data directory to confirm that the setup is complete, or
to view any error messages that were generated during setup.

To do a silent setup from a Windows client with Domino Administrator

1. Make sure that you selected ″Remote Server Setup″ when you installed Domino Administrator on the
client system.
2. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
3. At the command prompt on the server system, from the Domino program directory, do one of the
following:
v On a Windows server, enter
nserver -listen

78 Lotus Domino Administrator 7 Help

 v On a UNIX server, enter
server -listen
4. At the command prompt on the client system, from the Notes program directory, enter:
serversetup -silent c:\myprofile.pds -remote serveraddress
Where myprofile is the name you gave the setup profile and serveraddress is the host name or network
address of the server you are setting up.

Note: If the profile file is not in the root directory, use the profile’s full path in the command.
5. If the profile uses existing server, certifier, or administrator IDs that require passwords, do the
following:
a. Create a text file that contains the passwords for the existing IDs. The keywords in this are:
Server=
AddServer=
Certifier=
OUCertifier=
Administrator=
b. Add a parameter in the command line for the name of the password file. For example, on
Windows enter:
serversetup -silent c:\myprofile.pds c:\passwd.txt -remote serveraddress
6. If this is a partitioned server setup, add the = parameter to the command line to specify the
NOTES.INI file in this partition’s Domino data directory. For example, on Windows enter:
serversetup -silent c:\myprofile.pds -remote serveraddress =c:\lotus\domino\data2\notes.ini
7. Check the ERRORLOG.TXT file in the Notes data directory to confirm that the setup is complete, or
to view any error messages that were generated during setup.

To do a silent setup from a Windows client without Domino Administrator or from

a UNIX workstation
1. Install the Domino server program files on a server system, but do not run the Domino Server Setup
program.
2. At the command prompt on the server system, from the Domino program directory, do one of the
following:
v On a Windows server, enter
nserver -listen
v On a UNIX server, enter
server -listen

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.
3. On the client system, install the Java runtime environment.
4. Create a temporary directory on the client system. For example, enter the following at the command
prompt:
v On a Windows client:
mkdir c:\temp
v On a UNIX workstation:
mkdir /temp
5. Do one of the following:
v From a Windows client, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP.CMD from the server to the directory you created on the client system. These files
are in C:\Domino program directory on the server.

Chapter 3. Installing and Setting Up Domino Servers 79

 v From a UNIX workstation, copy the remote setup files CFGDOMSERVER.JAR, JHALL.JAR, and
REMOTESETUP from the server to the directory you created on the workstation. These files are in
/Domino program directory/lotus/notes/latest/ibmpow/ on an AIX server, /Domino program
directory/lotus/notes/latest/zlinux/ on a Linux on zSeries server, /Domino program
directory/lotus/notes/latest/linux/ on a Linux server, and /Domino program
directory/lotus/notes/latest/sunspa/ on a Solaris server.

Note: Linux on zSeries and z/OS ship tar files on the CD that contains the files needed for remote
server setup.
v On Linux on zSeries -- ZLINUX_CLIENT.TAR
v On z/OS -- ZOS_CLIENT.TAR
6. At the command prompt on the client system, from the Notes program directory, enter:
remotesetup -silent c:\myprofile.pds -remote serveraddress

Note: For Linux on zSeries and z/OS, set the DISPLAY environment variable so that the setup
program is directed to a workstation supporting X-Window.
Where myprofile is the name you gave the setup profile and serveraddress is the host name or network
address of the server you are setting up.

Note: If the profile file is not in the root directory, use the profile’s full path in the command.
7. If the profile uses existing server, certifier, or administrator IDs that require passwords, do the
following:
a. Create a text file that contains the passwords for the existing IDs. The keywords in this are:
Server=
AddServer=
Certifier=
OUCertifier=
Administrator=
b. Add a parameter in the command line for the name of the password file. For example, on
Windows enter:
remotesetup -silent c:\myprofile.pds c:\passwd.txt -remote serveraddress
8. If this is a partitioned server setup, add the = parameter to the command line to specify the
NOTES.INI file in this partition’s Domino data directory. For example, on Windows enter:
remotesetup -silent c:\myprofile.pds -remote serveraddress =c:\lotus\domino\data2\notes.ini
9. Check the ERRORLOG.TXT file to confirm that the setup is complete, or to view any error messages
that were generated during setup.

The Certification Log

When you set up the first Domino server in a domain, the Server Setup program creates the Certification
Log. If you delete the log, you can recreate it, but be aware that the new log will not contain the
information it previously stored.

The Certification log records information related to recertification and name changes. When you add
servers and users to Domino, the Certification Log maintains a record of how you registered them. For
each registered server and user, the Certification Log stores a document containing the following
information:
v Name and license type
v Date of certification and expiration
v Name, license type, and ID number of the certifier ID used to create or recertify the ID

80 Lotus Domino Administrator 7 Help

Create a replica of the Certification Log on every server that is a registration server and on every server
that stores a Domino Directory that is used for user management -- for example, renaming and
recertifying users. If the server whose Domino Directory replica you are using does not have a
Certification Log, user-management actions will fail.

Server registration
Before you install and set up additional servers, you must register them. In effect, registering a server
adds the server to the system. The server registration process creates a Server document for the server in
the Domino Directory and creates a server ID. After registering and installing a server, you use the Server
Setup program to obtain a copy of the Domino Directory for the new server and to set up the server to
run particular services and tasks -- for example, the HTTP service, the Mail Router, and so on.

The server registration user interface automatically removes leading spaces and trailing spaces from
passwords. Passwords cannot begin or end with a space. This also applies to certifier registration and
user registration.

Note: When setting up an additional server, obtaining the Domino Directory from the registration server
via dialup over a modem is possible for Windows systems only. For other operating systems, the
additional server must be on the network in order to communicate with the registration server.

Before you register servers, plan and understand your company’s hierarchical name scheme. The name
scheme defines which certifier ID to use when you register each new server. In addition, make sure that
you have access to each certifier ID, know its password, and have created ID recovery information for it.

If you have decided to use the Domino server-based certification authority (CA), you can register servers
without access to the certifier ID file and its password.

For more information on the hierarchical name scheme, see the chapter ″Deploying Domino.″ For
information on ID recovery, see the chapter ″Protecting and Managing Notes IDs.″ For more information
on using the Domino server-based CA, see the chapter ″Setting Up a Domino Server-based Certification
Authority.″

The registration server, which is the server that initially stores changes to documents in the Domino
Directory until the Domino Directory replicates with other servers, must be up and running on the
network. To register servers from your workstation, you must have access to the registration server and
have at least Author access with the Server Creator and Group Modifier roles in the ACL of the Domino
Directory.

When you register a server, Domino does the following:

v Creates a server ID for the new server and certifies it with the certifier ID
v Creates a Server document for the new server in the Domino Directory
v Encrypts and attaches the server ID to the Server document and saves the ID on a disk or in a file on
the server
v Adds the server name to the LocalDomainServers group in the Domino Directory
v Creates an entry for the new server in the Certification Log (CERTLOG.NSF)

If you have a Domino server-based CA for issuing Internet certificates, you can choose to configure the
new server to support SSL connections by providing a server key ring password and the server’s host
name. Then, Domino does the following:
v The registration process creates a certificate request in the Administration Requests database
(ADMIN4.NSF) to be processed by the server’s Internet CA
v The registration process creates a ″create SSL key ring″ request in ADMIN4.NSF

Chapter 3. Installing and Setting Up Domino Servers 81

v Once you set up and start the new server and the ″create SSL keying″ request has replicated to it, the
″create SSL key ring″ request creates the server key ring file and an ″enable SSL ports″ request for the
administration server of the Domino Directory
v The ″enable SSL ports″ request enables all the SSL ports on the new server and creates a ″monitor SSL
status″ request for the new server
v The ″monitor SSL status″ request restarts all of the Internet tasks currently running on the new server
so that the tasks will accept SSL connections

Note: You must use the Domino Administrator if you want to use this server registration process to
configure a new server for SSL.

For more information on these requests, see the appendix ″Administration Process Requests.″

Registering a server
Note: If you have not specified a registration server in Administration Preferences, this server is by
default:
v The server specified in the NewUserServer setting in the NOTES.INI file
v The Administration server
1. If you are supplying the certifier ID, make sure that you have access to it and that you know its
password.
2. If you are using the Domino Administrator and would like the new server to support SSL, make
sure that you have an Internet CA configured.
3. From the Domino Administrator or Web Administrator, click the Configuration tab.
4. From the Tools pane, click Registration - Server.
5. If you are using the Domino Administrator, do the following:
a. If you are using the CA process, click Server and select a server that includes the Domino
Directory that contains the Certificate Authority records, and the copy of the Administration
Requests database (ADMIN4.NSF) that will be updated with the request for the new certificate.
Then click ″Use the CA Process,″ select a CA-configured certifier from the list, and click OK.
b. If you are supplying the certifier ID, select the registration server. Then click ″Certifier ID″ and
locate the certifier ID file. Click OK, enter the password for the certifier ID, and click OK.
c. In the Register Servers dialog box, click Continue if you want to apply the current settings to all
servers registered in this registration session; otherwise, complete these fields:

Field Action
Registration Server Click Registration to specify the registration server.
Certifier If the certifier ID displayed is NOT the one you want to use for all servers registered in
this session, or if you want to use the Domino server-based CA instead of a certifier ID,
click Certifier and you return to Step 4.
Public key specification The public key specification that you use impacts when key rollover is triggered. Key
rollover is the process used to update the set of Notes public and private keys that is
stored in user and server ID files.

Choose one:
v Compatible with all releases (630 bits)
v Compatible with Release 6 and later (1024 bits)
Note: For information about the significance of the public key specification and key
rollover, see the topic User and server key rollover.
License type Choose either North American (default) or International. In practice, there is no
difference between a North American and an International ID type.

82 Lotus Domino Administrator 7 Help

Field Action
Expiration date (Optional) To change the expiration date of the Server Certificate, enter the date in
mm-dd-yyyy format in the Certificate Expiration Date box. The default date is 100 years
from the current date, minus allowances for leap years.
Certificate Authority If you want the server to support SSL, select an Internet CA from the list.

d. Click Continue.
6. If you are using the Web Administrator, do the following:
a. Select a registration server that includes the Domino Directory that contains the Certificate
Authority records, and the copy of the Administration Requests database (ADMIN4.NSF) that
will be updated with the request for the new certificate.
b. Select a CA-configured certifier from the list, and click OK.
7. In the Register New Server(s) dialog box, complete these fields for each server that you want to
register:

Field Action
Server name Enter the name of the new server.
Server title Enter the server title, which appears on the Configuration tab in the All Server
Documents view and in the Server Title field of the Server document.
Domino domain name The default domain name is usually the same as the name of the organization certifier
ID.
Server administrator Enter the name of the person who administers the server.
name
ID file password Required if you are going to store the server ID in the Domino Directory.

Optional if you store the server ID in a file.

The password is case-sensitive and characters you use will depend on the level you set
in the Password quality scale.
Password Options Click Password Options. Specify a password quality scale by choosing the level of
complexity for the password. By default, the level is 0, where 16 is the highest. Click
OK.
Location for storing server v Select ″In Domino Directory″ to store the server ID in the Domino Directory.
ID
v Select ″In File″ to store the server ID file in a file. Then click ″Set ID File,″ select the
name and path for the file, and click Save.
Note: You don’t see this field from the Web Administrator, as the server ID is stored in
the Domino Directory.

8. (Domino Administrator only) If you chose an Internet CA in the Register Servers dialog box and you
want the server to support SSL connections, click Advanced, select ″Enable SSL ports,″ and complete
the following fields:
v Server key ring password -- Enter a password for the server key ring
v Server host name -- Enter the fully qualified domain name of the server, for example,
app01.acme.com
9. Do one:
v Click the green check box to add the server to the registration queue.
v Click the red X to clear the fields.
10. The server registration queue displays the servers ready to be registered. To display the settings for a
server, select the server name in the queue.
11. Click one:

Chapter 3. Installing and Setting Up Domino Servers 83

 vNew Server -- To clear fields in the Register New Server(s) dialog box
vRegister All -- To register all servers in the registration queue
vRegister -- To register the highlighted server in the registration queue
vRemove -- To remove the highlighted server from the registration queue
vDone -- To close the Register Server(s) dialog box. Any servers remaining in the registration queue
will not be registered.
12. After you register a server, install it and then run the Server Setup program to configure it.

Optional tasks to perform after server setup

After running the Server Setup program, you may want to perform one or more of the following tasks,
depending on the needs of your company:
v Create an additional organization certifier ID.
v Create an organizational unit certifier ID.
v Use Internet Site documents to configure Internet protocol server tasks:
– Enable the Internet Sites view
– Create an Internet Site document
– Set up security for Internet Site documents

Creating an additional organization certifier ID

When you set up the first server in a domain, you create an organization certifier. If your hierarchical
name scheme calls for having multiple organizations but only one Domino Directory, you must create an
additional organization certifier ID.

For more information on organization certifier IDs, see the chapter ″Deploying Domino.″
1. From the Domino Administrator, click the Configuration tab.
2. From the Tools pane, choose Registration - Organization.
3. (Optional) To change the registration server, which is the server that initially stores the Certifier
document until the Domino Directory replicates, click Registration Server, select the correct server, and
then click OK. If you have not specified a registration server in Administration Preferences, the
registration server is by default:
v The local server, if there is one and it contains a Domino Directory
v The server specified in the NewUserServer setting in the NOTES.INI file
v The Administration server
4. (Optional) Click Set ID file to change the location where Domino stores the certifier ID. Be sure to
keep the certifier ID file in a secure place so that it is readily accessible to register new servers and
users, but safe from misuse. By default, the certifier ID is stored in C:\.
5. Complete these fields:

Field Action
Organization name Enter the name of the organization. Enter a name different from the one used on the
organization certifier ID created when you set up the first Domino server.
Country code (Optional) Adding an organizational country or region code for the country or region
where the organization’s corporate headquarters are located minimizes the chance that
another organization has the same organization name as yours. Enter the country or
region code only if you have registered your organization name with a national or
international standards body. For multinational companies, you can enter a country or
region in which the company has offices, as long as the organization name is registered
there.

84 Lotus Domino Administrator 7 Help

Field
Certifier password
Password quality scale
Security type
Mail certification requests
to (Administrator)
Location
Comment
Action
Enter a case-sensitive password for the certifier. The characters you use for this
password depend on the level set in the ″Password quality scale″ field.
Choose the level of complexity for the password. By default, the level is 8, where 16 is
the highest.
Choose either North American (default) or International. In practice, there is no
difference between a North American and an International ID type.
Enter the name of the administrator who handles recertification requests. The name
specified here appears in the Certifier document in the Domino Directory. If you are
creating a certifier ID for an off-site administrator, enter that administrator’s name in
this field.
(Optional) Enter text that appears in the Location field of the Certifier document.
(Optional ) Enter text that appears in the Comment field of the Certifier document.

6. Click Register.

Creating an organizational unit certifier ID

You can create up to four levels of organizational unit (OU) certifiers. To create first-level OU certifier
IDs, you use the organization certifier ID. To create second-level OU certifier IDs, you use the first-level
OU certifier IDs, and so on.

For background information on OU certifier IDs, see the chapter ″Deploying Domino.″

For background information on OU certifier IDs, see the topic ″Certifier IDs and certificates.″

Note: The registration server is the server that initially stores the Certifier document until the Domino
Directory replicates. If you have not specified a registration server in Administration Preferences, the
registration server is by default:
v The local server if there is one and it contains a Domino Directory
v The server specified in NewUserServer setting of NOTES.INI
v The Administration server

To create an organizational unit certifier ID

1. From the Domino Administrator, click the Configuration tab.
2. From the Tools pane, select Registration - Organizational Unit.
3. (Optional) To change the registration server, click Registration Server, select the correct server, and
then click OK.
4. Do one:
v Select ″Supply certifier ID and password.″ Click Certifier ID, select the certifier ID, click Open, and
click OK. Enter the ID password, and click OK.
v Select ″Use the CA Process″ and then choose a CA certifier from the list.
5. Click OK. If you are supplying the certifier ID, enter its password and click OK.
6. (Optional) To change the registration server, click Registration Server, select the correct server, and
then click OK.
7. (Optional) To change which certifier ID to use to register the new certifier ID:
a. Click Certifier ID.
b. Select the certifier ID, click Open, and click OK.
c. Enter the ID password and click OK.

Chapter 3. Installing and Setting Up Domino Servers 85

 8. (Optional) Click ″Set ID File″ if you want to change the location where Domino stores the certifier
ID. Be sure to keep the certifier ID file in a secure place so that it is readily accessible to register new
servers and users, but safe from misuse. By default the ID is stored in C:\.
9. Complete these fields:

Field
Organizational Unit
Certifier password
Password quality scale
Security type
Mail certification requests
to (Administrator)
Location
Comment
Action
Enter a name for the new organizational unit.
Enter a case-sensitive password for the certifier. The characters you use for this
password depend on the level set in the ″Password quality scale″ field.
Choose the level of complexity for the password. By default, the level is 8, where 16 is
the highest.
Choose either North American (default) or International. In practice, there is no
difference between a North American and an International ID type.
Enter the name of the administrator who handles recertification requests. The name
specified here appears in the Certifier document in the Domino Directory. If you are
creating a certifier ID for an off-site administrator, enter that administrator’s name in
this field.
(Optional) Enter text that appears in the Location field of the Certifier document.
(Optional) Enter text that appears in the Comment field of the Certifier document.

10. Click Register.

Internet Site documents

Internet Site documents are used to configure the Internet protocols supported by Domino servers. A
separate Internet Site document is created for each protocol -- Web (HTTP), IMAP, POP3, SMTP Inbound,
LDAP, and IIOP -- which is then used to provide protocol configuration information for a single server,
or for multiple servers in a Domino organization. Specifically, you can create:
v Web Site documents. You create a Web site document for each Web site hosted on the Domino server.
v LDAP Site documents. You create an LDAP site document for LDAP protocol access to an
organization in a directory.
v IMAP, POP3, and SMTP Site documents. You create an individual Internet Site document for each
mail protocol for which you enter an IP address.
v IIOP Site documents. You create an IIOP Site document to enable the Domino IIOP (DIIOP) task on
the server. This task allows Domino and the browser client to use the Domino Object Request Broker
(ORB) server program.

Internet Site documents make it easier for administrators to configure and manage Internet protocols in
their organizations. For example, prior to Domino 6, if you wanted to set up a Web site in your
organization, it was necessary to configure each Domino server in the domain with Mapping documents,
Web realms, and File Protection documents. If you had virtual servers and virtual hosts, you had to do
the same thing for them. In Domino 6, you can configure a Web Site document so that all servers and
hosts use it to get configuration information for a Web site, including mapping information, file
protection information, and Web realm authentication information.

You must use Internet Site documents if you:

v Want to use Web-based Distributed Authoring and Versioning (WebDAV) on a Domino Web server.
v Have enabled SSL on your server and want to use Certificate Revocation Lists to check the validity of
Internet certificates used to authenticate with the server.
v Are using a service provider configuration on your server (see ″For service providers only″ below).

86 Lotus Domino Administrator 7 Help

The Domino server is configured to use Internet Site documents if the option ″Load Internet
configurations from Server\Internet Sites documents″ is enabled on the Basics tab on Server document. If
the option is not enabled, the server defaults to Server document settings to obtain configuration
information for Internet protocols.

Internet Site documents are designed to be used as follows:

v For any incoming connection, Internet Site documents, Certifier documents and Global Domain
documents are used to determine which organization (certifier) is associated with the target IP address.
In the xSP configuration, this is important because the Site document determines the hosted
organization. In a non-xSP Domino configuration, all incoming IP addresses usually map to the top
level certifier.
v For a specific organization and a specific protocol and a specific server, the Internet Site document is
used to determine which authentication controls are to be applied.

When you enter a Host name or IP address in an Internet Site document, you do not gain control over
which authentication controls are applied according to the IP address the user connects to. Instead, the
first Internet Site document located for the server and the organization is used. As a result, except for
Web Site documents, you should have only one Internet Site document for each organization, protocol,
and server combination.

For example, do not do the following:

Server A has two IP addresses and you create the following two Internet Site documents for POP3:
v One Internet Site document for one IP address with no SSL allowed
v One Internet Site document for another IP address, with SSL allowed.

The IP address is used to determine the organization and both Internet Site documents apply to the same
organization. The first Internet Site document that matches the server and the organization is used, in this
case, the Internet Site document that does not allow SSL.

Modifications to Internet Site documents (including the creation of new Site documents) are dynamic. The
server or protocol does not need to be restarted after you create a new Site document, or after you
modify or delete an existing one. Changes generally take effect minutes after the change is made. The
ability to dynamically create, modify, or delete Internet Site documents is especially valuable in service
provider environments, so that existing hosted organizations are not interrupted when a new hosted
organization is configured.

Internet Site documents are created in the Internet Sites view, which is used to help manage Internet
protocol configuration information by listing the configured Internet Site documents for each organization
in the domain.

CAUTION:
If you use an Internet site document to configure one Internet protocol on a server, you must also use
Internet site documents for all Internet protocols on that server. For example, you cannot set up an
LDAP Internet Site document and, on the same server, use the Server document to configure HTTP.

While most protocol settings are configured in Internet Site documents, there are some settings that need
to be configured in the Server document to support Internet protocol configurations. These include
settings for:
v Enabling and configuring the TCP/IP port.
v Enabling and configuring the SSL port (including redirecting TCP to SSL).
v Accessing the server -- such as who can access the server and how.

For more information on server access settings, see the chapter ″Controlling Access to Domino Servers.″

Chapter 3. Installing and Setting Up Domino Servers 87

Setting up Internet Site documents on a Domino server
Do the following to set up basic Internet Site functionality on a Domino server.
1. Create Internet Sites document for the Internet protocols you want to use.
2. Set up security for each Internet Site document.
3. Enable Internet Site documents on the server.

For service providers only

Internet Site documents are required for hosted organizations. These documents control each hosted
organization’s use of Internet protocols. A hosted organization can only use an Internet protocol if the
hosted organization has an Internet site document for that protocol. A shared IP address may be used for
all hosted organizations, or unique IP addresses may be set up for each hosted organization. Internet Site
documents link IP addresses to the individual hosted organizations for each Internet protocol.

When registering hosted organizations, you have the option to create Internet Site documents during
hosted organization registration, or you can choose to create them later.

Service providers need to consider the following when using Internet Site documents:
v Each hosted organization has one Web Site document that can be created during hosted organization
registration. You must create this initial Web Site document to activate the HTTP protocol. If you have
multiple Web sites, you need one individual Web Site document for each additional Web site for each
organization. If the hosted organization supports DOLS, the Web Site document must contain the name
of the DSAPI filter file name. For more information, see the topic To configure DOLS on a server that
uses Web Site documents in this chapter.
v You must create one mail protocol Site document (IMAP, POP3, or SMTP) for each protocol used by
each organization.
v In a hosted environment, Domino IIOP (DIIOP) can use the information in the IIOP Internet site
document to define the scope of the Domino Directory used to validate users. With DIIOP, you can use
any Java® code running on any server on the network.
v If your configuration has one IP address that is shared by multiple hosted organizations, HTTP, IMAP,
LDAP, POP3, and SMTP are the available protocols. For IMAP, LDAP, POP3, and SMTP users, the
name provided during authentication must be the user’s Internet e-mail address, so that the server
knows the organization of which each user is a member. Anonymous access to LDAP is not supported
in this configuration.
v To enable SSL for a hosted organization, you must enter the server IP address in the field ″Host names
or addresses mapped to this site″ on the Basics tab of the Internet Site document.

Creating an Internet Site document

You can create Internet Site documents for Web, IMAP, POP3, LDAP, SMTP Inbound, and IIOP Internet
protocols. You create one document at a time.

To create an Internet Site document:

1. From the Domino Administrator, click Configuration - Web - Internet Sites.
2. Click Add Internet Site, and select the type of Internet Site document to create.

88 Lotus Domino Administrator 7 Help

3. Click the Basics tab, and complete these fields:

Field Action
Descriptive name for this site (Optional) Enter a name that differentiates this site from all others that you
create. This name appears in the Internet Sites view in this format: the type
of Internet Site, the descriptive name, and the host name or address. For
example:

Web Site: MyWebSite (www.acme.com)

If you do not enter a name, the default name is the type of Internet Site
document with the host name or address appended. For example:

POP3 Site: (www.acme.com)

For hosted environments -- The default descriptive name is a combination

Organization
Use this Web site to handle requests
which cannot be mapped to any
other Web sites
Host names or addresses mapped to
this site
of the hosted organization name with the type of site document appended.
For example, a Domino IIOP site with a hosted organization name of Acme
would Acme IIOP Site.
(Required for all Internet Site documents) Enter the name of the registered
organization that hosts the Internet Site document. The name must
correspond to the organization’s certifier.
Note: For Web Sites set up in a non-service provider configuration, this
name can be any suitable word or phrase.
(Web Site documents only) Choose one:
v Yes -- This Web site processes incoming HTTP requests if Domino cannot
locate the Web sites that were entered in the ″Host names or addresses
mapped to this site″ field.
v No (default) -- This Web site does not process incoming HTTP requests for
which Domino cannot locate a Web site.
(Required for all Internet Site documents) Enter the target host names or IP
addresses that trigger a connection’s use of this Internet Site document.

If the site is set up for SSL, you must specify IP addresses.

Domino servers that host this site
For hosted environments -- When creating Domino IIOP Site documents, the
first host name IP address that is on this list will be used to advertise
DIIOP’s service creating diiop_ior.txt. Therefore, it is recommended that each
Domino server have its own Internet Site document.
(Required for all Internet Site documents) Enter the name of one or more
Domino servers that host this site. You can use any variation of
distinguished name (for example, Server1/Sales/Acme) as well as wildcards
(for example, */Acme).

The default is (*), which means that all servers in the domain can host this
site.

If you leave the field blank, the Internet Site will not be loaded on any
Domino server.

4. For all Internet Site documents, complete the settings on the Security tab.
5. Some Internet Sites require additional configuration. The table below indicates the Internet Site
documents that require additional configuration, and the locations for settings in those documents for
enabling additional configuration information unique to those protocols.

Chapter 3. Installing and Setting Up Domino Servers 89

Document Complete
Web Site v Configuration tab
v Domino Web Engine tab
IMAP Site v Public Folder tab
IIOP Site v Configuration tab

6. Save and close the document.

Setting up security for Internet Site documents

To set up security for Internet Site documents, you can enable SSL server and client authentication,
name-and-password authentication, or anonymous access for Internet and intranet clients.

In order to enable SSL for Internet Sites, you must configure the SSL port on the Server document and set
up SSL on the server by obtaining a server certificate and key ring from an Internet certificate authority.

To set up SSL authentication, you must create a server key ring file for each Internet Site document.
However, if the Internet site documents are for the same organization, but are created for different
protocols, a single server key ring file can be used. Be sure to enter the server key ring file name in the
appropriate field on the Security tab of each site document.

If you want to use Certificate Revocation Lists (CRL) for Internet certificate authentication, the server
must be using a Domino server-based certification authority for issuing Internet certificates.

To enable SSL for a hosted organization, you must use the server IP address in the field ″Host names or
addresses mapped to this site″ on the Basics tab of the Internet Site document.

Note: For Web sites, the common name on the server key ring must match the DNS name to which the
IP address in the Web Site document is mapped. The IP address must be stored in the field ″Host name
or addresses to map to this site,″ which is located on the Web Site document. If you enable Redirect TCP
to SSL in a Web Site document, both the host name and the IP address must be stored in this field.

You should be familiar with SSL authentication, name and password authentication, and anonymous
access before completing these steps.

For more information about SSL authentication, see the chapter ″Setting Up SSL on a Domino Server.″

For more information about name-and-password authentication and anonymous access, see the chapter
″Setting Up Name-and-Password Authentication and Anonymous Access on a Domino Server.″

To set up security for Internet Site documents:

Note: In Domino, it is possible to effectively prohibit access to an Internet Site by selecting ″no″ for all
authentication options in an Internet Site Document. These options include TCP authentication, SSL
authentication, and TCP anonymous access.
1. From the Domino Administrator, click Configuration - Web - Internet Sites.
2. Choose the Internet Site document to modify, and click Edit Document.
3. Click Security, and complete these fields:

Field Enter
TCP Authentication

90 Lotus Domino Administrator 7 Help

Field Enter
Anonymous (Applies to all Internet sites, except IMAP and POP3)

Choose one:
v Yes -- To allow anonymous access to this site
v No -- To prohibit anonymous access
Name & password Choose one:
v Yes -- To require a user to authenticate with the user’s name and Internet
password to access the site
v No -- To not require name and password authentication
Redirect TCP to SSL (Applies to Web Site only) Choose one:
v Yes -- To require clients and servers to use the SSL protocol to access the Web
site
v No -- To allow clients and servers to use SSL or TCP/IP to access the Web site
SSL Authentication
Anonymous (Applies to all Internet sites, except IMAP and POP3)

Choose one:
v Yes -- To allow users access over the SSL port without authenticating with a
name and password
v No -- To deny users anonymous access
Name & password Choose one:
v Yes -- To require a user to authenticate with user name and Internet password
in order to access this site using SSL
v No --To not require a name and password
Client certificate (Applies to Web Site, IMAP, POP3, and LDAP)

Choose one:
v Yes -- To require a client certificate for access to this site
v No -- To not require a client certificate
SSL Options
Key file name Enter the name of the server key ring file.
Protocol version Choose one:
v V2.0 only -- Allows only SSL 2.0 connections.
v V3.0 handshake -- Attempts an SSL 3.0 connection. If this fails and the requester
detects SSL 2.0, attempts to connect using SSL 2.0.
v V3.0 only -- Allows only SSL 3.0 connections.
v V3.0 with V2.0 handshake -- Attempts an SSL handshake, which displays
relevant error messages. Makes an SSL 3.0 connection if possible.
v Negotiated (default) -- Attempts an SSL 3.0 connection. If this fails, attempts to
use SSL 2.0. Use this setting unless you are having connection problems caused
by incompatible protocol versions.
Accept SSL site certificates Choose one:
v Yes -- To accept the certificate and use SSL , even if the server does not have a
certificate in common with the protocol server
v No (default) -- To prohibit the acceptance of SSL site certificates for access
Accept expired SSL certificates Choose one:
v Yes -- To allow clients access, even if the client certificate is expired
v No -- To prohibit client access using expired SSL certificates

Chapter 3. Installing and Setting Up Domino Servers 91

Field Enter
Check for CRLs Choose one:
v Yes -- To check the certifier’s Certificate Revocation List (CRL) for the user
certificate you are attempting to validate. If a valid CRL is found and the user
certificate is on the list, the user certificate is rejected.
v No -- To not use Certificate Revocation Lists
Trust expired CRLs Choose one:
v Yes -- To use expired but otherwise valid Certificate Revocation Lists when
attempting to validate user certificates
v No -- To reject expired Certificate Revocation Lists
Allow CRL search to fail Choose one:
v Yes -- If the attempt to locate a valid Certificate Revocation List fails, proceed as
if ″Check for CRLs″ is set to No.
v No -- If a valid Certificate Revocation List for the user certificate is not found,
reject the certificate. If ″Trust expired CRLs″ is set to Yes, an expired CRL is
valid. If ″Trust expired CRLs″ is set to No, the authentication will fail for every
user certificate for which a matching valid CRL is not located.
SSL Security
SSL ciphers Click Modify to change the SSL cipher settings for this site document. These
settings apply only to SSL v3. SSL v2 ciphers cannot be changed.
Enable SSL V2 Choose Yes to enable SSL v2 for this site document.

4. Save the document.

Enabling Internet Sites on a server

If you enable the use of Internet Sites on a Domino server, the server obtains Internet protocol
configuration information from site documents. Comparable configuration settings in the Server
document are not used.

If the use of Internet Sites is not enabled, comparable Server document settings are used to obtain
protocol configuration information.

You can only use the Internet Sites view for Domino servers. Servers running Domino 5.0x or earlier do
not have the option for enabling the Internet Sites view.

Note: Each time you start or restart HTTP, a console message indicates whether the HTTP task is using
Internet Sites or the Server document (Web Server Configurations view) to obtain Internet protocol
configuration information.

To enable Internet Sites on a server:

1. Open the Server document you want to edit, and click Edit Server.
2. Click the Basics tab.
3. In the Basics section, enable ″Loads Internet configurations from Server/Internet Sites documents.″
4. Save the document.
5. Restart the server.

Note: The HTTP task is backward-compatible with the Web Server Configurations view.

Starting and shutting down the Domino server

Start the Domino server so users can access shared databases and obtain other server services. Do not
enter keystrokes or click the mouse while the Domino server is starting or shutting down.

92 Lotus Domino Administrator 7 Help

Note: If the server program is running, do not use CTRL+S to stop scrolling the console, because no
server services take place until you press a key to continue.

To start the server

Operating system Action
Windows 2000/2003 Choose Start - Programs - Lotus Applications - Lotus Domino Server.
UNIX Enter the path for the Domino program directory. For example, if
you installed Domino in the /opt directory, enter:

/opt/ibm/lotus/bin/server

To shut down the server

Enter either exit or quit at the console. It may take ten seconds or more for the server to shut down.

Starting Domino as an application or a Windows service

If you have installed Domino as a Windows service, when you start the Domino 7 server, a dialog box
appears prompting you to specify whether to start Domino as an application or a Windows service.
1. On the Lotus Domino Server dialog box, choose one:
v Start Domino as a Windows service -- Starts the Domino server as a Windows service. Domino then
runs like any Windows service.
– If you choose this option without selecting either of the check boxes, the next time you start
Domino, this message displays ″Lotus Domino is installed as a Windows service.″ The dialog
box does not display again.
– If you choose this option and you select the ″Always start Domino as a service at system
startup,″ Domino always starts as a Windows service and this dialog box no longer appears at
start up.
The ″Don’t ask me again″ check box does not apply to the ″Start Domino as a Windows service″
due to the way that Windows services work.
v Start Domino as a regular application -- Starts the Domino server as any application would be
started. This is the traditional method for starting and running the Domino server.
– If you choose this option without selecting either of the check boxes on the dialog box, the next
time Domino starts, you are prompted with this dialog box again.
– If you choose this option and you select the ″Don’t ask me again″ check box, you are not
prompted with this dialog box again and Domino always starts as an application.
– If you choose this option and select the check box ″Always start Domino as a service at system
startup″ Domino runs as an application during the current session. The next time you start the
server, Domino runs as a Windows service.
2. Optionally, you can also choose neither of the following, one of the following, or both:
v Always start Domino as a service at system startup -- Select this check box if you want Domino to
always start as a Windows service. Once you select this option and click OK, you can not change
your selection using this dialog box.
v Don’t ask me again -- Select this check box if you do not want to be prompted again when the
Domino server starts. After you select this check box and click OK, you will not be able to reset
your selections using this dialog box.
3. Click OK.

When run as a Windows service, Domino runs as any other Windows services runs. Some of the benefits
associated with running Domino as a Windows service are listed below.
v If you select ″Automatic″ for starting services, Windows services are started when the system starts.

Chapter 3. Installing and Setting Up Domino Servers 93

v Windows services can be controlled via the Windows service manager. The Windows service manager
can be used remotely.
v Services continue to run even when you log off the system.

Using instant messaging in the Domino Directory

The Domino Directory is now enabled for instant messaging, meaning that you can conduct an online
chat directly from the Domino Directory. The instant messaging Chat feature is available only if you have
a Sametime server, and only for Windows versions of IBM Lotus Domino/Notes.

Chats are interactive, real-time text conversations.

From the People document, Group document, and from the Domino Directory itself there is a Chat
option in the menu bar. You can perform these instant messaging activities:
v Click Chat and you can choose from the following options:
v Chat with -- Open a chat with the person whose name is currently selected in the open document or
directory.
v Add to Instant Contact List -- Add the selected person’s name to an instant messaging contact list that
you choose.
v Show/Hide Contact List -- Toggles between displaying the names in the contact list and hiding the list.

94 Lotus Domino Administrator 7 Help

Chapter 4. Setting Up Server-to-Server Connections
After you configure servers, create Connection documents to enable mail transfer, replication, and remote
access between servers on different networks.

Planning server-to-server connections

Servers must connect to each other to exchange data, for example to replicate databases and exchange
mail. You can create connections between servers across a local area network (LAN) or wide area network
(WAN); using a dialup modem or remote access service; using a passthru server, which is a server that
acts as an intermediary server between a client and its destination; or over the Internet.

For a calling server to connect to a given destination server, it requires information about how and when
to contact the destination server. The information about how to contact the destination server includes the
network to use to reach the target server, and, depending on the type of network, the network addresses,
phone number, and other information needed to make the connection.

When a server needs to connect to a destination server on the same Notes Named Network, the
information needed to make the connection is readily available and the connection occurs automatically,
without any administrative intervention. However, when two servers don’t share a common network, the
calling server must be able to obtain this information by some other method. In a Domino network,
administrators create Connections documents in the Domino Directory to store information about how to
connect to a destination server.

In addition to providing the network information required to contact a destination server, Connection
documents can also specify when to contact the destination server. Depending on the type of
communications required, a calling server may attempt to establish contact with the remote server
immediately, or only at scheduled intervals. For example, a server looking up a name on, or performing
cluster replication with a given destination server requires immediate access to a remote server.

On the other hand, to perform tasks such as routing mail or replicating databases, a calling server may
require only periodic access to the destination server. When setting up a Connection document for a task
that doesn’t require immediate access, you can specify when the calling server attempts to make the
connection. Network information in a Connection document is used to create the connection to the
specified destination server, whether or not the connection is related to a task defined in the schedule
part. In other words, a calling server can use the network information in a Connection document to
contact a specified destination server when contacting that server for reasons other than mail routing or
replication.

Connections between servers -- that is, your connection topology -- should enable servers to exchange
information reliably and efficiently, maximizing the capacity of the physical network, while minimizing
connection-related costs.

When creating Connection documents for scheduled operations or to enable contact with a destination
server, keep the following factors in mind:
v The physical network to which the servers belong -- Are servers in the same, or different Notes named
networks?
v Function of the server -- What is the primary role of the server? For example, is it an application
server, Web server, or Directory server? Does the server provide passthru or dialup access to connect
remote or disparate networks?
v Tasks running on the server -- Does the server require Connection documents for both replication and
mail routing?

95
v Access requirements -- Does the server need to be reached over a modem connection or as a passthru
destination?
v Does the planned connection topology make the best use of the available network infrastructure? It the
server hardware adequate to support its role in replication or routing? For example, if a server is to be
used as a replication hub, does it have a fast processor, sufficient memory, and enough disk space?
Does the server require multiple NICs? Is there enough bandwidth between servers to support the
anticipated traffic?
v Keep the number of Connection documents and the number of ″hops″ -- that is, the number of
between the connecting and destination servers -- to a minimum.
v The Domino domain location of the servers -- Are servers in the same domain, adjacent domains,
non-adjacent domains?

The number of Connection documents that you create for a server depends on whether the server is
running the replication task and/or the mail task. When you configure a server, the Server document, by
default, enables mail routing. When you create a Connection document, replication is enabled. Depending
on how you use the server -- that is, whether you store mail files and/or application databases on it --
you must create a minimum of one or two Connection documents.

For more information on configuring replication, see the chapter "Creating Replicas and Scheduling Replication.″
Cre

For more information on mail routing, see the chapter ″Overview of the Domino Mail System.″

Servers can also use information gathered from an External Domain Network Information (EDNI)
document to make a connection. As an administrator, you configure this document to retrieve names and
addresses of servers in another domain so that users and servers do not require Connection documents to
connect to servers in that domain.

For more information on EDNI documents, see the topic ″Setting up external domain lookups″ later in
this chapter.

Remote (modem) access and server topology

Servers that are not on the same LAN or WAN can use modem connections to communicate with each
other. For example, servers in remote field offices can establish modem connections with servers in a
central office to route mail or replicate databases.

To create a topology for remote servers, first determine which databases the workstations and servers
access frequently. In particular, think about how you want to route mail and replicate databases.
Determine if users and servers in remote locations need access to certain mail and other databases. If so,
consider these methods to make the databases available:
v Create replicas of the databases on a remote server
For information about using database replicas, see the chapter ″Scheduling Replication.″
v Place modems on local servers that remote users need to access.
96 Lotus Domino Administrator 7 Help
 For information about connecting servers by modem, see the topic ″Planning for modem use″ later in
this chapter.
v Set up a passthru server for use by remote servers or users.
For information about setting up passthru servers, see the topic ″Setting up a server as a passthru
server″ later in this chapter.

Because users who connect to a remote server over a Notes Direct Dialup connection typically have only
one modem on their workstations, by default, they can connect to that one server only. Creating replicas
of frequently used databases on that server enables remote users to access multiple databases over a
single dialup connection.

Setting up a passthru server enables remote workstations or servers that connect to one Domino server to
access additional Domino servers also. Using a passthru server consolidates modem resources on a few
Domino servers and centralizes administration and troubleshooting.

How a server connects to another server

A connecting server uses the following steps to determine how to connect to a destination server. As soon
as the connecting server successfully connects to the destination, it stops searching for additional
connection methods.
1. The connecting server tries to connect using the same method it used the last time it made a
successful connection to the destination server. Note these two exceptions:
v If the server never connected to the destination server, the server searches for a path (consisting of
a network port and any passthru servers) to the destination server.
v If the server has connected previously, but the connection now fails, the server conducts a new path
search if it is the first attempt of the day.
2. The connecting server checks to see if it already has a WAN port connection to the destination server.
3. The server examines normal-priority Connection documents in the Domino Directory for information
on what path to use to connect to the destination server. A normal-priority Connection document is
one that has Normal selected in the ″Usage priority″ field. If multiple normal-priority Connection
documents exist for the same destination server, the server chooses the Connection document to use
based on the type of connection in the following order:
v Local Area Network
v Network Dialup
v Notes Direct Dialup
v Passthru server
v Hunt group of passthru servers

Note: A server that uses a passthru connection to reach the destination server must first be able to
connect to the passthru server. To provide information on how to connect to the passthru server,
you may have to create an additional Connection document.
4. The connecting server checks information stored in memory about other servers in the server’s Notes
named network. It uses this information to define a path to the destination server. The server reads
this information from Server documents in its local Domino Directory.
5. If the connecting server’s local Domino Directory does not contain information about the destination
server, it tries to connect directly to the destination server on the LAN by using the server common
name as its address.
6. The connecting server checks the low-priority Connection documents. A low-priority Connection
document is one that has Low selected in the ″Usage priority″ field.
7. If the connecting server still cannot find a path to the destination server, it issues a message that a
connection is not possible.

Chapter 4. Setting Up Server-to-Server Connections 97

Note: For workstations connecting to servers, the search logic is the same except that the workstation
tries to use the passthru server listed as default in the Location document to make the connection if Steps
1 through 5 fail. If the Location document does not define a default passthru server and the workstation
is already connected to a server over a Notes Direct Dialup connection, the workstation uses that server
as a passthru to reach the destination server.

To display information about how a server makes a connection, open the Miscellaneous Events view in
the log file (LOG.NSF). To change the amount of information Domino records about connections in the
log file, change the log level.

For more information on log files, see the chapter ″Using Log Files.″

Replication and server topology

As the number of Domino servers on your network increases, so does the amount of replication required
to distribute information across the network. Because replication uses memory and processing time, plan
how servers connect to perform replication. If you allow servers to replicate at random, so that a given
server replicates a single database with multiple servers, or perhaps replicates different databases with
different servers, servers can become so overloaded with replication requests that it interferes with their
ability to respond to client requests.

To provide for efficient replication, consider setting up some servers as dedicated replication servers.
Using dedicated servers to handle replication greatly reduces the amount of work that database servers
have to devote to replication, because the database servers have to replicate with the replication servers
only, instead of having to replicate with every server that maintains a copy of a given database. To
control replication, you create Connection documents that specify which servers to replicate with and
when.

How you connect servers for replication depends on many factors, including the layout of physical
network and the size of your organization, as well as the extent to which you want to re-use existing
Connection documents created for mail routing. There are several different configurations, or topologies,
you can use to control how replication occurs between servers:
v Hub-and-spoke
v Peer-to-peer
v Ring

Choose the replication strategy that provides the most efficient replication performance. In many cases,
you’ll use different topologies in different parts of the network.

Using a hub-and-spoke topology to manage replication

A hub-and-spoke topology is generally the most common and efficient replication topology in larger
organizations, because it minimizes network traffic. Hub-and-spoke replication establishes one central
server as the hub, which schedules and initiates all replication with all of the other servers, or spokes.
The spokes update the hub server by replication (and mail routing), and the hub in turn updates each
spoke. Hub servers replicate with each other or with master hub servers in organizations that use more
than one hub. In short, the hub server acts as the traffic manager of the system, overseeing system
resources, ensuring that replication takes place with each spoke in an orderly way, and guaranteeing that
all changes are replicated to all spoke servers.

To set up replication in a hub-and-spoke system, you create one Connection document for each
hub-and-spoke connection. To ensure that the replication task on the hub, rather than the spokes, assumes
most of the work always, in each Connection document specify the hub server as the source server, the
spoke server as the destination server, and pull-push as the replication method.

A hub-and-spoke topology can be especially useful at large, multiple-server sites or in a centralized office
that needs to connect via phone or leased lines to smaller, regional offices. If you have a large site, you

98 Lotus Domino Administrator 7 Help

can use a combination of topologies -- for example, two hub-and-spoke arrangements and one
peer-to-peer arrangement between the two hub servers.

The major drawback of hub-and-spoke topology is that it is vulnerable to single point of failure if the
hub is not working. Deploying a backup server that replicates the hub and can quickly be reconfigured
into a hub server if the primary hub goes down can alleviate this shortcoming.

Benefits of a hub-and-spoke topology

1. Install multiple protocols on hub servers to enable communication in a Domino system that uses more
than one protocol. This places hub servers in multiple Notes named networks, another source of
efficiency. Hub servers can connect multiple Notes named networks, where a single hub server and its
spoke servers often make up one Notes named network.
2. Bridge parts of a network -- for example, a LAN and a WAN.
3. Centralize administration of the Domino Directory, standardize database ACLs, and limit access to the
hub. You can designate the hub with Manager access and the spokes with Reader access so that you
make those changes on one replica on the hub to synchronize the spokes.
4. Designate hubs by role -- for example, replication hubs and mail hubs.
5. Place server programs such as message transfer agents on hubs to make them easily accessible.
6. Connect remote sites with a hub server.
7. Minimize network traffic and maximize network efficiency.
8. Centralize data backup at the hub. By backing up databases on the hub only, you conserve resources
on spoke servers.
9. Improve server load balancing. However, network traffic increases on the hub LAN segment. If you
have more than 25 servers per hub, establish tiers of hubs. If a hub goes down, replication for that
hub and its spokes is disabled until the hub is repaired or replaced.

Note: Do not use hub-and-spoke replication for databases larger than 100MB that have replicas on less
than four servers. Instead, schedule replication for these databases to occur separately from other
replications.

Using a peer-to-peer topology to manage replication

In a peer-to-peer topology, replication is less centralized than in a hub-and-spoke configuration, with
every server being connected to every other server. Because peer-to-peer replication quickly disseminates
changes to all servers, it is often the best choice for use in small organizations, or for sharing databases
locally among a few servers. However, it can be inefficient when a database resides on more than a few
servers.

In a peer-to-peer topology, the potential for replication problems decreases, because only two servers
communicate for each replication and no hub or intermediary servers are involved. However,
peer-to-peer replication requires many Connection documents, increases administration since you must
avoid overlap in replication schedules, and prevents you from standardizing ACL requirements.

Other topology strategies

Another method of managing replication is to use Cluster replication. This ensures constant access to
data, because data on one server is duplicated on one or more cluster mates. If the primary server
becomes unavailable, data can be obtained from other servers in the cluster.

For more information on using clusters, see the book Administering Domino Clusters.

Other replication topologies include:

v End-to-end - Also known as a chain topology, connects two or more servers in a chain. Information
travels in one direction along the chain and then travels back in the other direction. End-to-end
replication is less efficient than ring replication but is useful in situations where information needs to
travel in only one direction.

Chapter 4. Setting Up Server-to-Server Connections 99

v Ring - Similar to an end-to-end topology, but connects servers in a circle so that replication occurs
within a closed loop. Ring replication can be useful in a large organization for replicating information
between hub servers.
v Binary tree - Connects servers in a pyramid fashion: the top server connects to two servers below, each
of which connects to two servers below, and so on. Information travels down the pyramid and then
back up.

Using existing mail routing connections for replication

As you plan for replication, consider re-using the connections you may have already set up for Notes
mail routing. If you previously created a Connection document for mail routing, you can easily enable
the replication task on that document.

Unlike mail routing, which works in one direction and requires a pair of Connection documents to enable
two-way routing, replication between servers works in both directions, and requires only one Connection
document between each pair of servers. Because the server that initiates replication takes on the larger
share of the replication workload, if decide to add replication to one of the Connection documents
already used for mail routing between two servers, add the replication task to the document on the more
powerful server in the pair.

Examples of server topology

This topic provides examples of the following server topologies:
v Example of hub server topology
v Hub-and-spoke topology
v Hub-and-spoke with peer-to-peer topology
v Application server topology
v Mail and directory server topology
v Remote server topology

Example of hub server topology

The hub servers at Acme Corporation handle server communication between servers located on the East
and West Coasts. These servers are geographically distant and connect over the Internet using a modem
or ISDN line. Controlling communication through hub servers is beneficial because it centralizes
administration for connections that may be costly or time consuming.

By using hub servers, only two servers, not every server in the organization, need to make the remote
connection.

The firewall server is a Domino server that protects Hub-E/East/Acme and Hub-W/West/Acme from
outside users. Because the firewall server uses Domino instead of some other type of firewall software,
the hub servers can use Domino features, such as mail and replication, to send and receive information.

100 Lotus Domino Administrator 7 Help

Example of hub-and-spoke topology

In this example, the Acme Corporation has one hub server, Hub-E/East/Acme, and three spoke servers.
The spoke servers -- HR-E/East/Acme, HR-S/South/Acme, and HR-W/West/Acme -- contain an
Employee Benefits application. Employees on the East Coast access the application on HR-E/East/Acme;
employees on the West Coast access a replica of the application on HR-W/West/Acme; and employees in
the South access a replica of the application on HR-S/South/Acme. Any changes to the application
replicate through Hub-E/East/Acme to the HR servers. The HR servers send changes to the hub, which
then sends changes back to the HR servers. With the three Connection documents that Acme created, the
hub server performs the replication, reducing the load on the spokes. Making the application available to
East, West, and South users prevents them from making costly WAN connections to the application.

Example of hub-and-spoke with peer-to-peer topology

In this example, the Acme Corporation has two hub servers -- Hub-W/West/Acme and
Hub-E/East/Acme -- connected peer-to-peer. Each hub server replicates with several spoke servers. Any

Chapter 4. Setting Up Server-to-Server Connections 101

changes replicate through the hubs to the spoke servers. The spoke servers send changes to the hub, and
then the hubs replicate with each other and send changes back to the spoke servers.

Example of application server topology

Depending on where you locate applications, they can be accessible to Notes users, to browser users, or
to both Notes and browser users. To be available to browser users, an application must be on a Domino
Web server.

In this example, Web/East/Acme stores a Web application for the organization’s Web site. The
application is accessible to browser users who are outside the Acme Corporation. Webstage-E/East/Acme
and Webstage-W/West/Acme have replicas of the Web application. Users can make changes to the Web
application on Webstage-E/East/Acme and Webstage-W/West/Acme. Webstage-W/West/Acme uses a
schedule that sets up replication through the hub servers to Webstage-E/East/Acme.
Webstage-E/East/Acme does not have a replication schedule, so once changes to the Web application are
complete, users manually replicate changes from Webstage-E/East/Acme to Web/East/Acme. This
replication makes the changes available to users outside the Acme Corporation.

The Acme Corporation also has two servers that do not host Web applications -- HR-E/East/Acme and
HR-W/West/Acme. These servers contain an Employee Benefits application that only internal employees
who use a Notes workstation can access. Employees on the East Coast access the application on
HR-E/East/Acme, and employees on the West Coast access a replica of the application on
HR-W/West/Acme. Any changes to the application replicate through the hub servers to the HR servers.
Making the application available to East and West Coast users prevents them from making costly WAN
connections to the application.

In this example, three firewalls on Domino servers are used to protect the Acme network from external
intruders: one firewall exists between the hub server in Acme’s West Coast office and the public network
over which it communicates with the East Coast Office; a second firewall protects the hub server at the
East Coast office; a third firewall protects Webstage-E/East/Acme from attacks that might come from the
Internet through Web/East/Acme.

102 Lotus Domino Administrator 7 Help

Example of mail and directory server topology

The Acme Corporation uses two mail servers -- one for each geographic location. All users send mail
using a mail database located on either Mail-E/East/Acme or Mail-W/West/Acme. The mail databases
are accessible to all mail client software -- Notes workstations, IMAP, POP3, and browsers.

Routing mail messages is similar to replicating changes made in databases. In this example, the mail
servers route messages through the hub servers to the mail server in the other location. For example,
when Alan Jones/Sales/East/Acme sends a message to Susan Salani/HR/West/Acme, the message
routes from Mail-E/East/Acme to Hub-E/East/Acme, from Hub-E/East/Acme to Hub-W/West/Acme,
and then from Hub-W/West/Acme to its final destination Mail-W/West/Acme. Susan
Salani/HR/West/Acme reads the message on her mail server, Mail-W/West/Acme.

Directory servers provide users and servers with information about other users and servers -- for
example, information needed to address or send mail. Directories contain information about how to
communicate with all Notes and Internet users and Domino servers. In many cases, you can set up a
mail server as a directory server.

In this example, a condensed directory catalog is on each Notes client and a Domino Directory is on each
server -- Mail-E/East/Acme, Hub-E/East/Acme, Hub-W/West/Acme, and Mail-W/West/Acme. To
resolve names, clients check the local directory catalog first; if the name is not there, Domino checks the
Domino Directory.

Domino uses replication, which is the process by which Domino updates one directory database with
changes from a directory database on another server. For example, if a change is made on
Mail-E/East/Acme, the change is sent to the replicas on Hub-E/East/Acme, Hub-W/West/Acme, and
Mail-W/West/Acme. Users cannot access the directories on the hub servers; users access directories only
on the mail servers.

At Acme Corporation, replication occurs automatically at a scheduled time. The replication schedule
determines how long it takes for changes to appear on the directory servers.

Again, a firewall using a Domino server lets you use Domino features to send information across the
WAN -- in this case, you use the mail routing and replication features.

Chapter 4. Setting Up Server-to-Server Connections 103

Example of a remote server topology

The Acme company chose this remote server topology so that remote users and servers have access to the
entire system by connecting to one server (the passthru server). Acme uses the passthru to function only
as a bridge between the remote user or server and the rest of the system. To keep the load on the
passthru to a minimum, the server does not contain application or mail databases.

Users who work remotely dial in through the passthru server and can access any server in the system. As
most of Acme’s users who dial in remotely have only one modem on their system, using the passthru
server allows them to access multiple servers with one connection. To reduce traffic on the passthru
server, Acme recommends that its remote users replicate databases and then work on the local replicas.
Then users can work in their local replicas and dial in and replicate occasionally with the server replicas.

Acme dedicated five modems to the passthru server. The remote server also dials into one of these
modems for replication. Because this server makes its connection in the early morning hours, the
connection does not conflict with users trying to access the system.

Acme uses a hunt group configuration for its modems so that users have only one phone number to dial
when connecting. Acme’s phone infrastructure is set up so that multiple modems can have one phone
number. For this type of hunt group (all modems are on one server), Acme does not need to create a
Connection document to set up the hunt group.

The remote server is in Acme’s satellite office in Ohio. Employees who work in this office focus on
marketing and use this server to access various marketing related databases. The remote server contains
replicas of relevant databases, and it replicates once a day to update the databases. By using the remote
server, users in the Ohio office save time and resources because they don’t have to dial into Acme’s
system as often.

Creating a LAN connection

You must create a Connection document to schedule mail routing to and replication between servers on a
LAN. You might also need to create a Connection document to provide the information needed to ensure
a server uses a certain protocol when connecting to another server on the LAN.

104 Lotus Domino Administrator 7 Help

A LAN Connection document can also be used to provide the information needed for servers to make
other types of connections, such as constant connections to Internet servers.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click Add Connection.
5. Select Local Area Network in the ″Connection type″ field.
6. Complete these fields:

Field Description
Connection Type Select Local Area Network.
Source server The name of the connecting server.
Source domain The name of the connecting server’s domain. This field is required only for mail routing.
Use the port(s) The name of the network ports (or protocols) that the connecting or source server uses to
connect to the destination server.
Usage priority Choose one:
v Normal (default) - Select this option if this document defines the primary path to a
server.
v Low - Select this option to define a backup path to a server.

For more information about the effect of specifying the usage priority for a connection, see
the topic ″Forcing a server connection to use a specific protocol″ later in this chapter.
Destination server The name of the answering server.
Destination domain The name of the answering server’s domain. This field is required only for mail routing.
Optional network Provide an optional network address to facilitate attempts to locate the destination server
address over a TCP/IP connection. If the field contains no entry, Domino attempts to determine
the address of the destination server from the following sources: the server’s memory
cache, an External Domain Network Address document, or system services that search the
local hosts file or DNS to resolve the name.

Enter a fully-qualified host name or IP address -- for example, HR-E.Acme.com or

192.22.256.36. Because IP addresses are subject to change, for ease of management, it’s best
to use host names in Connection documents. When a host name is used, if the IP address
changes, the connecting server obtains the updated IP address from the DNS.

7. Click the Replication/Routing and Schedule tabs to define the tasks you want to run, and select the
times you want the server to contact its destination.
8. Click Save & Close.

Forcing a server connection to use a specific protocol

If multiple protocols are available for connecting a source server to a given destination, you can specify
which protocol to use by setting the usage priority in a Connection document describing how the source
server contacts the destination. The usage priority specified in a Connection document determines the
order in which Domino selects the Connection document when searching for how to connect a source
server to a destination. If multiple ports are enabled on the two servers, you can force Domino to use a
specific port by specifying it in the Connection document and setting the Usage priority field to Normal.

For example, suppose that both SPX and TCP/IP are enabled on Server A, the source server, and Server
B, the destination server. You create a Connection document from Server A to Server B specifying that
Server A uses the port TCP/IP to contact Server B and set the usage priority in this document to Normal.
When determining how to connect to Server B, Server A first checks the Domino Directory for a
normal-priority Connection document governing the connection. After locating the document, Server A

Chapter 4. Setting Up Server-to-Server Connections 105

learns that the TCP/IP port is specified, and proceeds to use that port to attempt a connection to Server
B. Setting the usage priority works for all types of Connection documents: LAN, Notes Direct Dialup,
Network Dialup, Passthru, and so forth.

If multiple normal-priority Connection documents exist for the same destination server, the connecting
server chooses one based on the type of connection in the following order of preference:
1. Local Area Network
2. Network Dialup
3. Notes Direct Dialup
4. Passthru server
5. Hunt group of passthru servers

You can also use the usage priority setting to configure a backup path to a destination server. When you
set the usage priority for a Connection document to Low, the connecting server only uses the information
in the document to connect to the destination server as a last resort, after it has exhausted all other
possible means of locating connection information.

For more information on how a server determines the route to a destination, see the topic ″How a server
connects to another server″ earlier in this chapter.

To set the usage priority for a connection

1. From the Domino Administrator, click the Configuration tab.
2. Click Server, and then click Connections.
3. Select the Connection document for which you want to set the usage priority, and click Edit
Connection.
4. Complete this field, and then click Save & Close:

Field Enter
Usage priority Choose one:

Normal - This Connection document defines a primary path to the destination server. The
connecting server attempts to use this Connection document to make the connection to the
destination server.

Low - This Connection document defines a backup path to the destination server. The
connecting server uses this Connection document only as a last resort when trying to
connect to the destination server.

Setting up external domain lookups

By default, a Notes user who wants to open a database on a server outside the local Domino domain, can
do so only if there is a Connection document in either their Personal Address book, or in the Domino
Directory on their home server that describes how to reach the target server. To enable Notes users to
connect more easily to servers outside of their domain, you can create an External Domain Network
Information (EDNI) document in the Domino Directory.

The EDNI document works in conjunction with a server task called GETADRS to import address
information from another Domino domain so that Notes users can connect to servers in the external
domain. In the EDNI document, you specify the external Domino domain containing the servers you
want users to connect to and the protocols for which you want connection information. In many cases,
TCP/IP is the only protocol for which you may need a document. You also specify a server in your local
domain that requests the information (Requesting Server) and a server in the external domain that
supplies the information (Information Server).

106 Lotus Domino Administrator 7 Help

To gather information, the requesting server runs the GETADRS program, which asks the specified
information server for a list of the servers in the external Domino domain. GETADRS returns the address
information it obtains to an AdminP request for processing. When the Administration server processes
the request, it places the information in the Domino Directory as a response document to the original
EDNI document.

After AdminP adds the server address information to the local Domino Directory users attempting to
open databases on servers in the external domain can use the information from this document to make
the connection without requiring a connection document.

Using EDNI documents, you can reduce the number of Connection documents in the Domino Directory,
eliminating those that are not required for replication or routing.

Before creating an EDNI document, determine if the connection information is useful for the domain. For
example, if you are using the NetBIOS protocol, which isn’t a routable protocol, a direct connection to the
external domain may not be possible even if you have the network address of the server in an EDNI
document. Also, if an external domain server has multiple TCP/IP ports, the host name or address
returned to the EDNI document may not be the address of the appropriate port to use. Because each
protocol has its own restraints, you should thoroughly research and test the external domain lookup
capability using the network system configuration at your organization before using it.

To share information across domains, the Domino domain requesting the information must be
cross-certified with the external domain.

Because the Requesting Server gathers information from Server documents in an external domain, these
documents need to be configured properly to enable successful server name lookups. For example, a
document with a fully qualified host name or IP address would enable a successful lookup, but a
document with only the server common name may not (unless that common name were a full host
name).

The data from an external domain server lookup resolves client requests for a server address only; it does
not add additional server names to a client’s request for a list of servers.

To set up an External Domain Network Information document

1. Verify that the local domain is cross-certified with the external domain.
2. From the Domino Administrator, click the Configuration tab.
3. Open the Server folder, and then click External Domain Network Information.
4. Click Add Ext Domain Net Info.
5. Complete these fields, and then click Save & Close:

Field Description
Requesting server The name of the local domain server that performs the request for external domain
information. This server runs the GETADRS task to obtain information from the
information server in the external domain.
Information server The name of the server in the external domain from which the requesting server obtains
information.
Domain to query The name of the external domain.
Protocols to query The name of one or more protocols in the external domain to query. Specify only protocols
that are used in both domains.

6. Run the GETADRS program on the Requesting server. You run GETADRS using any of these
methods:
v Run the program manually from the server console by entering:
LOAD GETADRS

Chapter 4. Setting Up Server-to-Server Connections 107

 v Create a program document to run the program as a scheduled task. Running GETADRS as a
scheduled task ensures that information in the local Domino Directory remains synchronized with
updates from the external domain.
For information about running server tasks in a program document, see the appendix, ″Server Tasks.″
v Add GETADRS to the ServerTasks or ServerTasksAt lines in the NOTES.INI file of the requesting
server; the task runs at server startup, or at the specified time, respectively.
After GETADRS obtains information from the external domain, for each protocol specified in the
EDNI, AdminP creates an External Domain Network Address document as a response document to
the original EDNI. Each response document contains the names and addresses of the servers in the
queried domain that use that protocol.
By default, AdminP processes the information returned by GETADRS to create the External Domain
Network Address documents at the interval scheduled in the Server document. You can run AdminP
manually to force it to process the request immediately.
For more information about scheduling AdminP requests, see the chapter ″Setting Up the
Administration Process.″ For information about Tell commands used with AdminP, see the appendix
″Server Commands.″

Internet connections
To enable a Domino server to connect to another server across the Internet, you must establish Internet
access with an Internet Service Provider (ISP) and register an Internet domain name with the ISP -- for
example, acme.com. After you contract Internet service, create Connection documents to instruct the local
Domino servers how to contact the target server.

Servers can connect to the ISP using a direct connection or by way of a Domino or non-Domino proxy
server. If the local network uses a proxy server to connect to the Internet, the calling Domino server does
not need to connect to the ISP directly, because the proxy server establishes this connection to the ISP.

Servers connecting to the Internet require networking software that is compatible with the Internet. If
TCP/IP is not already installed on the Domino server, install the protocol using the installation
instructions included with the operating system. If you do not have a Domino TCP/IP port enabled for
the server, add and enable the port.

For information about adding a network port to a Domino server, see the chapter ″Setting Up the
Domino Network.″

Direct (leased-line) connection

A leased-line connection is considered a direct connection to the Internet. If you have a leased-line
connection, Domino servers on the internal LAN connect to the Internet through a firewall or router over
a leased phone line.

A firewall filters traffic passing between the internal network and the Internet and is usually part of a
TCP/IP router. Most firewalls work by hiding the IP addresses of computers on your internal network
from the Internet, thus breaking the connection between the internal and external networks, so that while
there is a connection between the internal LAN and the firewall, and from the firewall to the Internet,
there’s no direct connection between the Internet and the local network.

108 Lotus Domino Administrator 7 Help

To connect a Domino server to an Internet server over a direct connection, create a LAN Connection
document to the target server.

For more on how to create a LAN Connection document, see the topic ″Creating a LAN connection″
earlier in this chapter.

Proxy connections
A proxy is a server that provides indirect access to the Internet. A proxy server usually runs in
conjunction with firewall software to pass incoming and outgoing requests between servers on either side
of a firewall. If your organization uses a proxy server for its Internet connection, a Domino server on the
internal LAN connects to the Internet through the proxy and firewall servers, which, in turn, connect to
your ISP. Because the proxy server establishes the connection with the ISP, the Domino server does not
connect to the Internet directly.

A Domino proxy server is one type of proxy server. You set up a Domino passthru server as a proxy for
the Internet the same way that you set up a passthru server for internal Domino communication. You do
not need to configure the server differently for Internet connections. The proxy server does not have to be
a Domino server.

Creating a server-to-server Internet connection through a proxy server

When two Domino servers both have direct, constant connections to the Internet, each can use the IP
address of the other to contact it as though both servers were on the same LAN. To define the
connections between the two, you create a LAN Connection document.

However, when a server is connected through a proxy server, rather than having a direct connection,
after you create a LAN Connection document to define the connection, you must complete the proxy
information in the Server document of the calling server as described in the following procedure:
1. From the Domino Administrator, click the Configurations tab and expand the Server view.
2. Select the Server document of the server to connect to the Internet through the proxy, and click Edit
Server.
3. Click the Ports - Proxies tab, and then do one of the following:
v To connect through an HTTP proxy, in the HTTP Tunnel proxy field, enter the proxy’s
fully-qualified domain name or IP address and specify the port to use for the connection. For
example, enter httpproxy.company.com:8080 or 192.168.77.34:8080.
v To connect through a SOCKS proxy, in the SOCKS proxy field, enter the proxy’s fully-qualified
domain name or IP address of the SOCKS proxy and specify the port to use for the connection. For
example, enter socks.company.com:1080 or 192.168.77.34:1080.

Note: If you enter values for both fields, Domino uses the HTTP Tunnel proxy.
4. Click Save & Close.

Note: By default, if the server is configured to use a proxy, it uses the proxy for all connections. To
prevent use of the proxy for connections to certain servers, enter the server names in the ″No Proxy for
these hosts or domains″ field on the Ports - Proxies tab on the Server document.

Chapter 4. Setting Up Server-to-Server Connections 109

Passthru servers and hunt groups
Passthru is a process that runs on a server and establishes connections between the users and servers
connected to that server and other servers. Passthru connections use an intermediary server as a
″stepping stone″ to connect the two servers. Passthru is useful in two instances:
v When two servers connect directly -- When a client (in this case, either a Notes client or a Domino
server) does not share a common protocol with a destination server, you can set up an intermediary
server that runs both protocols as a passthru server to enable the client to connect to the destination.
For example, suppose that Server A, which runs only NetBIOS, needs to connect to Server C, which
runs only TCP/IP. If Server B runs both NetBIOS and TCP/IP, Server B can act as a passthru server to
allow communication between Server A and Server C.
v When you want to provide additional security -- Domino lets you apply additional access controls to
passthru connections, enabling you to use passthru connections to act as an proxy server for filtering
NRPC traffic. You can specify the users and servers that can access a server as a passthru destination,
as well as those that can use a server to make passthru connections to another server. Internet
protocols such as HTTP, IMAP, and LDAP cannot use a Domino passthru server to communicate with
a destination server.

You can set up a passthru server so that it leads to additional passthru servers as well as directly to a
passthru destination server. Thus, you can chain together multiple passthru connections to enable a client
to pass through several servers until it connects to a given target server.

Passthru access is valuable to Notes client users as well. When you provide a Notes client with access a
to a passthru server, the client user can connect to a single server to access other network servers. For
mobile users, this enables access to multiple destination servers on the same LAN over a single phone
connection. Using a passthru server this way saves the time and expense of configuring many individual
servers to support modem connections and of requiring Notes client users to use multiple phone calls to
access multiple servers.

Passthru Logging
To enable to monitoring of passthru traffic for security reasons, after you configure a server as a passthru
server, the server log (LOG.NSF) records information about passthru sessions established through that
server. For example, the log records information about users who access this server for to make passthru
connections to other servers.

For more information about server log files, see the chapter ″Using Log Files.″

Hunt groups
If your telecommunications infrastructure supports a hunt group -- that is, a pool of modems that are
connected to different phone lines but that use a single phone number -- you can configure Domino
servers and Notes client users to connect to a hunt group on a passthru server. Whenever a call is made
to the hunt group number, the incoming call is routed to the first available modem in the group.

You can use a hunt group with one or more passthru servers. If more than one passthru server is used in
the hunt group, to allow any passthru server in the hunt group to receive a call and route it to the
destination server, the calling server or user must use a Hunt Group Connection document.

For more information about configuring Lotus Notes clients to use a passthru server, see Lotus Notes 7
Help.

Planning the use of passthru servers

Perform these steps to set up passthru servers:
1. List all the workstations and servers that need to access a passthru server. Also list the protocols that
the workstations and servers run.

110 Lotus Domino Administrator 7 Help

2. List the destination servers that the workstations and servers need to access. Also list the protocols
that the destination servers run.
3. Determine where in the topology to locate the passthru server based on which workstations and
servers need access and which servers are the destinations. The passthru server must run all of the
protocols that the workstations and servers that access it run, as well as all of the protocols of the
destination servers. In addition, the passthru server must have enough modem connections to handle
the anticipated dial-in traffic.
If you anticipate high traffic through the passthru server, create a dedicated passthru server. A
dedicated passthru server does not contain applications and mail databases. It functions solely to
provide workstations and servers with access to destination servers.
Also, determine if you want to use more than one passthru server in a hunt group. In a hunt group,
one phone number represents all passthru servers in the group, and the load is automatically spread
among the passthru servers. Be sure to set up all passthru servers in a hunt group to pass through to
the same destination servers.
4. Determine the users and servers whose access to the passthru servers and destination servers you
need to restrict. Create policy settings documents that include setup and desktop settings to prevent
access to the servers.
5. List the Notes client users that need to use a passthru server and determine a default passthru server
for each. If you have many Notes client users, create user setup policies to evenly assign them among
the default passthru servers to ensure optimal server performance.
If you plan to use hunt groups, list which Notes client users will connect to each hunt group. Record
the name and phone number of the hunt group and the names of all the destination servers that
members of the hunt group pass through to.
For more information about using policies to manage server access, see the chapter ″Using Policies.″

Example of a passthru server topology

Chapter 4. Setting Up Server-to-Server Connections 111

The Acme company has a dedicated passthru server that functions only to provide workstations and
servers with access to destination servers. This server does not contain any databases. The passthru runs
all the protocols that the destination servers run so that users and servers that connect to it have access to
the entire system.

Note that passthru can benefit users and servers on the same network as the passthru server as well as
remote users and servers. For example, some of the Notes clients in the above diagram are on the same
LAN as Webstage-E and HR-E, but because they do not share any protocols, they cannot access these
servers without using passthru.

The above topology requires the following configuration:

v Notes Direct Dialup Connection document on the remote server for connection to passthru server.
v Passthru Connection document on the remote server to specify passthru.
v Connection documents on the remote server for connection to each destination server.
v Modified Location document on local Notes clients to specify name of passthru server.
v Notes Direct Dialup Connection document on remote Notes clients for connection to passthru.
v Passthru Connection documents on remote Notes clients to specify passthru connection.
v Modified Server documents (to allow appropriate access rights) on passthru and destination servers.

Setting up a server as a passthru server

Set up a server as a passthru server to enable users and other servers to route through it to connect to a
passthru destination server.
1. From the Domino Administrator, click the Configuration tab.
2. Click Server - All Server Documents.
3. Open the Server document for the server that you want to set up as a passthru server, and click Edit
Server.
4. Click the Security tab, and in the Passthru Use section, complete these fields and then click Save &
Close:

Field Description
Access this server If this server is not a passthru destination, leave this field blank.

For information about setting up a server as a passthru destination, see the topic ″Setting
up a server as a passthru destination″ later in this chapter.
Route through Specifies the names of the users, groups, and servers allowed to connect to a destination
server through this server. When this field is blank (the default), the server does not allow
passthru connections.

Enter an asterisk (*) to provide passthru access for all users and servers, even those not
listed in the Domino Directory. Enter a hierarchical name with an asterisk as the common
name to provide access for all users and servers certified by a particular organization or
organizational unit. For example, the entry */Acme allows access to all users in the Acme
organization.

Separate multiple entries with commas or semicolons.

Entries in this field are granted passthru access, even if denied general access to the server
in the Server Access section of the Server document Security tab.

112 Lotus Domino Administrator 7 Help

Field Description
Cause calling Specifies the names of users, groups, and servers allowed to use the modem on this server
to connect to a remote destination server. By default, this field is blank and the server
prohibits all incoming connections from generating calls to other servers. Enter an asterisk
(*) to allow incoming connections from any source to initiate a call to a destination server.
Note: If you allow incoming connections from any source to initiate calls, when recording
the event in the Passthru Connections view of the Notes Log, Domino indicates only that
the connecting client was not authenticated, rather than specifying the name of the source.
Destinations allowed Specifies the names of the remote servers this server can connect to as passthru
destinations.

By default, this field is blank and the server allows routing to all servers configured as
passthru destinations. Adding entries to this field restricts passthru access from this server
to the specified destination servers only.

5. Set up servers as passthru destinations.

For information about setting up a server as a passthru destination, see the topic ″Setting up a server
as a passthru destination″ later in this chapter.
6. Create Connection documents as necessary to connect the passthru server to destination servers that
do not share the same LAN.

Setting up a server as a passthru destination

Set up a server as a passthru destination to enable users and servers to access it through a passthru
server.
1. From the Domino Administrator, click the Configuration tab.
2. Click Server - All Server Documents.
3. Open the Server document for the server that you want to set up as a passthru destination, and click
Edit Server.
4. Click the Security tab, enter values in this Passthru Use field, and then save the document:

Field Description
Access this server Specifies the names of the users, groups, and servers allowed to access the server as a
passthru destination. When this field is blank (the default), the server is not available as a
passthru destination.

Enter an asterisk (*) to provide access for all users and servers, even those not listed in the
Domino Directory. An asterisk followed by a certifier name provides access for all users and
servers certified by a particular organization or organizational unit. For example, the entry
*/Acme allows access to all users in the Acme organization.

Separate multiple entries with commas or semicolons.

Note: Access to a passthru destination is subject to restrictions set in the Server Access section of the
Server document’s Security tab. These fields define general access to the server.

You can grant a user or server general access to a server and prohibit access to the same server as a
passthru destination. However, if you deny a user or server general access to a server, those users and
servers cannot access the server as a passthru destination.

Creating a passthru connection

After you set up the passthru and destination servers, you can set up servers to connect to passthru
servers. Creating a passthru connection enables the server to forward requests from users and other
servers to connect to a specified destination server.

Chapter 4. Setting Up Server-to-Server Connections 113

Note: The passthru Connection document specifies the server to use for passthru, but does not define
how to connect to the passthru server. If a server does not have a direct connection to the passthru server
over the LAN, you must create a separate Connection document to define the path to the passthru server.

Before creating a passthru connection, verify that the current server is not configured to use a default
passthru server. When a server is configured to use a default passthru server and it receives a request to
connect to a destination server for which no other connection is defined, it attempts to route through the
named server to the requested destination. If the named server is not set up to allow passthru
connections to the requested destination server, the passthru attempt places an unnecessary load on both
servers.

To verify that a server is not configured to use a default passthru server

1. From the Domino Administrator, click the Configuration tab.
2. Click Server - Current Server document.
3. Click the Basics tab and expand the Server Location Information section.
4. Verify that the ″Passthru server″ field is empty.

To create a passthru connection

1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click Add Connection.
5. Complete these fields:

Field Description
Connection type Select Passthru server
Source server The name of the server connecting to the passthru server
Source domain The name of the connecting server’s domain
Use passthru server or hunt The name of the passthru server or hunt group that this connection uses to reach the
group destination server
Usage priority Choose one:
v Normal (default) - Select this option if this document defines the primary path to
a server.
v Low - Select this option to define a backup path to a server.

Destination server
Destination domain
For more information about the effect of specifying the usage priority for a
connection, see the topic ″Forcing a server connection to use a specific protocol″
earlier in this chapter.
The name of the destination server to connect to through the passthru server.
The name of the destination server’s domain

6. Click the Replication/Routing and Schedule tabs to define the tasks you want to run, and select the
times you want the server to call its destination.
7. Click Save & Close.

Connecting a server to a hunt group

A hunt group is a collection of telephone extensions that is assigned one phone number. Each call that
comes in to that number is assigned to the next free line in the group. If your telecommunications
infrastructure supports hunt groups, any passthru server in the hunt group can receive a call and route it
to a specified destination server.

114 Lotus Domino Administrator 7 Help

After you set up a hunt group, create a Hunt Group Connection document to enable servers to connect to
the hunt group servers.

A Hunt group connection document is required whenever a hunt group has multiple passthru servers. If
a hunt group has a single passthru server, create a Network dialup Connection document to define the
connection, rather than a hunt group Connection document.

To create a Hunt group connection document

1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click Add Connection.
5. Complete these fields and then click Save & Close:

Field Description
Connection type Hunt group
Source server The name of the server connecting to the hunt group
Source domain The name of the connecting server’s domain. Required only if the source server and
destination server are in different Domino domains.
Use the port The modem port
Always use area code Specifies when the modem on the source server includes the area code to dial a number.
Choose one:
v Yes - The server always includes the area code to dial, even when dialing numbers in
the local exchange.
v No - (default) The server includes the area code only when dialing numbers outside the
local area code.
Usage priority Choose one:
v Normal (default) - Select this option if this document defines the primary path to a
server.
v Low - Select this option to define a backup path to a server.

For more information about the effect of specifying the usage priority for a connection, see
the topic ″Forcing a server connection to use a specific protocol″ earlier in this chapter.
Hunt group Enter a unique name to identify the hunt group, for example, AcmeEastHuntGroup. If you
create passthru Connection documents that use this connection, the hunt group name you
enter in them must match the name entered here.

The name you enter name here is also used to apply commands to the hunt group servers.
For example, to replicate a database that is located on a hunt group server, enter:
rep hunt_group_name database

In this case, the calling server initiates the modem connection to the designated hunt
group and then replicates the specified database on each server where it resides.
Destination domain The name of the domain to connect to through the hunt group. Required only if the source
server and destination server are in different Domino domains. Enter a domain name to
ensure that the hunt group connects to a server in the specified domain.
Destination country The country code to use when dialing the number of the hunt group modem.
code
Destination area code The area code to use when dialing the number of the hunt group modem.
Destination phone The phone number of the hunt group modem.
number
Login script name The name of the login script file to use when connecting to the hunt group.

Chapter 4. Setting Up Server-to-Server Connections 115

Field Description
Login script arguments Arguments required during processing of the specified login script; for example, name and
password. Enter arguments from left to right in the order of use.

Planning for modem use

For a Domino server to communicate with a remote Domino server by modem, you must
v Install one or more modems on the calling and receiving servers.
v Configure the communication port.
v Create a dialup modem connection from the calling server to the receiving server. Domino uses either a
Notes Direct Dialup connection or a Network Dialup Connection to communicate with another server
over a modem. The type of connection required depends on whether each server is directly connected
to a modem.
For information about creating dialup connections, see the topics ″Creating a Notes Direct Dialup
connection″ and ″Creating a Network Dialup connection″ later in this chapter.

Installing modems
The number of modems that you can use on a server is dependent on the operating system and system
resources -- for example, the number of available communication ports. Each modem needs its own
communication port.

If you expect heavy dialup use, install additional modems or install a multiple-port communication board
to connect multiple modems to multiple communication ports on a single board.

Use these questions to help you determine the number of modems:

1. How many users and servers do you want to be able to use the server simultaneously?
The number of modems that you install on a remote server determines the number of users and
servers that can access it simultaneously. Consider the expense of purchasing more modems against
server accessibility.
2. Do users take advantage of workstation-to-server replication when accessing the server?
To reduce server demand, encourage users to keep local replicas of databases on their workstations,
work on them without a dialup modem connection, then connect to the central server to exchange
new and updated documents with the central server’s database.
3. What types of users connect to this server?
If the server supports a high number of users who connect exclusively over dialup connections -- for
example, when a server’s primary users are field personnel who are always on the road -- dialup
demand for the server is higher than on a server where users only occasionally use modem
connections.

Modems and modem command files

After you install a modem on a server, configure the communication port by specifying the modem type
and port number.

Specifying a modem type automatically associates a modem with a modem command file. A modem
command file is a text file containing commands that Domino issues to the modem. If none of the
available modem types matches your modem, you can modify a generic modem command file or contact
IBM support to obtain the appropriate modem file.

116 Lotus Domino Administrator 7 Help

Modem command files, which have the file extension MDM, tell the modem how to operate. They are
specific to Domino and the type of modem you are using. When you choose a modem type, you must
select a matching modem file. Domino comes with specific modem command files for a wide variety of
modems.

Domino installs modem files in the Domino Data\Modems subdirectory. Commands in the modem
command file are arranged as required by the X.PC protocol provided with Domino.

Domino provides a generic all-speed modem file, GEN_ALL.MDM, which you can modify. For
information on modem command files and instructions on modifying them, use a text editor to read the
file TEMPLATE.MDM. Use this file in conjunction with the documentation that came with the modem to
modify modem command files.

Modify a modem command file only under the following circumstances:

v If you need additional commands that a Domino modem command file does not provide
v If Domino does not provide a modem command file that is compatible with your modem
v If the default modem command file, AUTO.MDM, does not work
v If you cannot obtain a modem file that works with your modem from IBM support

Creating a Notes Direct Dialup connection

When both the local and remote Domino servers have their own modems, you can use a Notes Direct
Dialup (dialup modem) connection to connect them. After the local server connects to the remote server,
it can perform tasks, such as route mail and replicate databases.

When using Notes Direct Dialup connections, Domino uses the X.PC protocol driver. The X.PC protocol
driver is installed automatically when you install a Domino server. It links Domino to a computer’s
operating system and the hardware devices that handle the communication.

Notes Direct Dialup connections use Domino security and thus offer tighter security than Network
Dialup connections to a remote access server.
1. Make sure that you already installed a modem and that one exists on the destination server.
2. From the Domino Administrator, click the Configuration tab.
3. Click Server, and then click Connections.
4. Click Add Connection.
5. Select Notes Direct Dialup in the ″Connection type″ field.
6. Complete these fields:

Field Description
Source server The name of the calling server.
Source domain The name of the calling server’s domain.
Use the port(s) The name of the communications port that the calling or source server uses.
Always use area code Specifies whether the source server always uses the area code when dialing. Choose one:
v Yes - The server always includes the area code to dial, even when dialing numbers in
the area code defined in the source server’s Server document. Use this option if your
phone system requires an area code for local calls.
v No - (default) The server includes the area code only when dialing numbers outside the
local area code.

Chapter 4. Setting Up Server-to-Server Connections 117

Field Description
Usage priority Choose one:
v Normal (default) - Select this option if this document defines the primary path to a
server.
v Low - Select this option to define a backup path to a server.

For more information about the effect of specifying the usage priority for a connection, see
the topic ″Forcing a server connection to use a specific protocol″ earlier in this chapter.
Destination server The name of the remote server.
Destination domain The name of the remote server’s domain.
Destination country The country code for the remote server. Enter this number only if it’s required to complete
code the call.
Destination area code The remote server’s area/city code. Enter this number only if it’s required to complete the
call.
Destination phone The phone number of the remote server.
number
Login script file name The name of the connect script to use when connecting to the remote server. Supply this
file name only if additional information is required to authenticate with the destination
server after dialing completes.
Login script arguments Between 1 and 4 values used by the login script when authenticating with the destination
server. For example, enter a login name and password if the login scripts must provide
these elements when connecting to the destination server. The script uses the values in the
order in which they are entered. Values entered in this field are not encrypted and are
displayed in the clear.

7. Click the Replication/Routing and Schedule tabs to define the tasks you want to run, and select the
times you want the server to call its destination.
8. Click Save & Close.

Note: To ensure the best performance for connections that use data-compressing modems, don’t apply
Domino network data encryption to ports using these modems. Rather than reducing the size of the
transmitted data, the modem’s hardware compression techniques can increase it, negating the benefits of
the modem compression.

For more information about encrypting data on an NRPC port, see the chapter ″Setting Up the Domino
Network.″

Creating a Network Dialup connection

To connect a local Domino server with a remote server that does not have its own modem, create a
Network dialup connection. Domino uses Microsoft Dial-Up Networking (DUN) and the Microsoft
Remote Access Service (RAS) to make a dialup connection to a non-Domino server on the remote
network. After establishing the connection, the local server uses the remote access service to communicate
with the destination server. Domino can interact with resources on the other network as if it were
connected directly to the network, routing mail and replicating databases with servers on the remote
network.

Because RAS uses its own compression, Domino compression should not be used with RAS.

Notes clients and Domino servers who establish a Network Dialup connection to a Remote Access Server
can access the entire remote Domino network over the remote LAN. After establishing a connection, the
calling client or server can communicate with servers on the remote LAN using the network protocols
defined in RAS only, that is, TCP/IP and Netbios.

118 Lotus Domino Administrator 7 Help

To create a Network dialup connection
1. Configure the modem port on the source server.
2. Make sure that the remote access service is properly set up on the local Domino server and on the
remote network server.
On the local server, configure DUN to dial out to the RAS server.
On the non-Domino remote server, configure RAS to answer calls. For details on how to configure
RAS, refer to the documentation provided with the operating system.
3. From the Domino Administrator, click the Configuration tab.
4. Click Server, and then click Connections.
5. Click Add Connection.
6. Complete these fields:

Field Description
Connection type Network Dialup
Source server The fully-distinguished Notes name of the connecting server. For example,
Server1/Sales/ACME.
Source domain The name of the connecting server’s Domino domain. Required only if the source server
and destination server are in different Domino domains
Use LAN port(s) Specifies the port that the server uses to establish the network dialup connection using the
remote access service.
Usage priority Choose one:
v Normal (default) - Select this option if this document defines the primary path to a
server.
v Low - Select this option to define a backup path to a server.

For more information about the effect of specifying the usage priority for a connection, see
the topic ″Forcing a server connection to use a specific protocol″ earlier in this chapter.
Destination server The fully-distinguished Notes name of the Domino server you want to access.

For SMTP routing connections, enter the host name of the destination server, for example,
internet.isp.com.
Destination domain The name of the destination server’s Domino domain. Required only if the source server
and destination server are in different Domino domains.

Leave this field blank when configuring SMTP routing to an ISP server.
Optional network Provide an optional network address to facilitate attempts to locate the destination server
address over a TCP/IP connection. If the field contains no entry, Domino attempts to obtain the
destination server’s IP address from the IP protocol stack.

Enter a fully-qualified host name or IP address -- for example, HR-E.Acme.com or

192.22.256.36. Because IP addresses are subject to change, for ease of management, it’s best
to use host names in Connection documents. When a host name is used, if the IP address
changes, the connecting server obtains the updated IP address from the DNS.

7. Click the Network Dialup tab and complete the following fields:

Field Description
Choose a service type Select Microsoft Dial-up Networking

Chapter 4. Setting Up Server-to-Server Connections 119

Field Description
Configure service Lets you specify the Dial-up Networking entry that the server uses when connecting to
this destination. Click Edit Configuration, and complete this field in the Microsoft
Dial-up Networking dialog box:
v Dial-up Networking name - Name of the Microsoft Dial-up Networking phonebook
entry on the source server containing the information on how to dialup the remote
server.

Optionally, you can complete the following additional fields in the dialog box. If you
complete these fields, the settings override those configured in the specified Dial-up
Networking entry on the server. These settings are used by the remote access service,
not by Domino. Complete the fields and then click OK
v Login name - The name that the server uses to log in to the remote access server.
v Password - The password the server uses to log in to the remote access server. For
security reasons, when you enter the password, it appears as a series of asterisks.
After you save the Connection document, before storing the document Domino
encrypts the password with the public keys of the source server and the users and
servers listed in the Owners and Administrators fields of the document.
v Phone number - The phone number of the remote access server. If the server uses
pulse dialing, do not enter a phone number in this field. Also, be sure to select Pulse
in the server’s modem configuration options and in the Microsoft Dial-up Networking
dialog, provide a phone number and check the Use Telephony dialog properties box.
v Area code - Area code of the remote access server.
v Country code - Country code of the remote access server.
v Dial-back phone number - The phone number of the source server. If the remote
access server has call-back enabled, it calls this number after authentication
completes.
v Domain - The Windows logon domain of the remote access service

The remaining fields on this tab are read-only and display information only if you completed the
corresponding field in the previous step.
8. Click the Replication/Routing and Schedule tabs to define the tasks you want to run, and select the
times you want the server to call its destination.
9. Click Save & Close.

Note: To ensure the best performance for connections that use data-compressing modems, don’t apply
Domino network data encryption to ports using these modems. Rather than reducing the size of the
transmitted data, the modem’s hardware compression techniques can increase it, negating the benefits of
the modem compression.

For more information about encrypting data on an NRPC port, see the chapter ″Setting Up the Domino
Network.″

Encrypting Network Dialup Connection documents

Domino can hide and encrypt the parameter part of the Network Dialup Connection document by using
the public keys of specific user or server IDs. When completed, only users and servers with those IDs can
make connections using the document and can view the parameters in the document.

Use these steps to encrypt a Connection document created prior to Release 5 so that only the users and
servers you specify can use the document to make a connection and view the settings in the document.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Open the Network Dialup Connection document.
120 Lotus Domino Administrator 7 Help
5. Choose File - Document Properties.
6. Click the Security tab (the key icon), and deselect ″All readers and above.″
7. In the ″Public Encryption keys″ field, enter the names of users and servers who need access to the
document, and then save the document.

Coordinating dialup ISP connections between servers

When two geographically distant servers are both connected to the Internet, they can use the Internet
connection to replicate databases or route mail. When both servers have constant connections to the
Internet, scheduling these tasks is easy. But if either server’s Internet connection is intermittent, for
example, if one server uses a dialup connection to an ISP, it can be difficult to schedule tasks to coincide
with times when both servers are available.

To automate the coordination of dialup schedules, Domino lets you create an AutoDialer connection. An
AutoDialer connection provides a link between two Connection documents: one document that controls
when a source server initiates the given replication or mail routing task; and one document that controls
when the destination server dials up an ISP to establish an Internet connection. An AutoDialer task on
both servers tracks the task schedule set in the source server’s Connection document and prompts the
destination server to come online in time to receive requests from the calling server.

The source server uses the destination server’s IP address to establish the connection. Because this
requires a stable IP address, the destination server’s ISP must provide static IP addresses; that is, it must
assign the server the same IP address every time the server connects to the ISP.

AutoDialer connections honor the timeout settings specified for the modem communication port. If a
connection is idle for the amount of time specified, Domino closes the connection.

Example of using an AutoDialer connection

Two remote servers, Jupiter and Pluto, share a common Domino Directory and must replicate once a day
with each other. Jupiter, a powerful server with a direct connection to the Internet, is located at company
headquarters in New York. Pluto, a much less powerful computer, located at a branch office in San
Francisco, connects to the Internet by dialing up a local ISP number. To enable Jupiter to assume the
greater share of the workload, the administrator chooses to have it serve as the source server and initiate
the replication. Because a direct dialup connection between the servers would require a costly
long-distance call, the administrator decides to connect the servers over the Internet to perform the
replication.

To enable replication, the administrator creates an AutoDialer connection for the two server by doing the
following:
1. Creates a Pluto-to-ISP Network Dialup connection document that provides information on how to
connect the destination server, Pluto, to the ISP, using a local phone number. In the Pluto-to-ISP
connection document, the administrator then does the following:
v Enables AutoDialer and specifies that Pluto will begin to dial up the ISP three minutes before the
scheduled replication with Jupiter.
v Assigns the AutoDialer connection the name ″PlanetReplication.″
2. Creates a Jupiter-to-Pluto LAN connection document that provides information on how the source
server, Jupiter, connects to Pluto. In the Jupiter-to-Pluto LAN connection document, the administrator
then does the following:
v To enable Jupiter to locate Pluto on the Internet, specifies Pluto’s IP address in the Optional
Network Address field.
v Enables AutoDialer and assigns the AutoDialer connection in this document the same name as the
AutoDialer connection in the Pluto-to-ISP Connection document: ″PlanetReplication″ This name
provides the link between the two documents.
v Sets the schedule on the Jupiter-to-Pluto connection document to begin replication at 10:00 AM.

Chapter 4. Setting Up Server-to-Server Connections 121

3. After saving both documents, the Domino Directory must be replicated so that both servers are aware
of the change. The administrator on Pluto dials the server into the ISP and then issues the replicate
command from the server console to replicate the Domino Directory between the two servers.
4. The administrator on Pluto then adds the AutoDialer task to the ServerTasks item in the NOTES.INI
file to start the AutoDialer task on Pluto.

Domino then searches the available Connection documents to locate any that have the AutoDialer
connection name ″PlanetReplication.″ After it finds the matching documents, Domino calculates when
Pluto must dial up its ISP to answer the replication request from Jupiter, and sets this schedule in the
Pluto-to-ISP connection document. In this example, because Pluto is in the time zone GMT -08:00, it must
dial up the ISP at 6:57 AM local time to come online three minutes before Jupiter, in the time zone GMT
-05:00, initiates replication at 10:00 AM local time.

At 6:57 AM the AutoDialer on Pluto requests the dialup information from the Pluto-to-ISP connection
document and dials the ISP. Three minutes later, Jupiter sends a replication request over the Internet to
Pluto.

Using AutoDialer with Notes Direct Dialup connections

Although AutoDialer is intended primarily for use in coordinating connections over the Internet between
two servers, you can also use AutoDialer to enable a remote Domino server to dial directly into another
Domino server, or into a passthru server.

For more information, see the topic ″Coordinating Notes Direct Dialup connections between servers″ later
in this chapter.

To set up an AutoDialer connection

1. Create a Network Dialup connection document that defines how the destination server for the
scheduled task connects to its ISP.
For information on creating a Network Dialup connection, see the topic ″Creating a Network Dialup
connection″ earlier in this chapter.
2. On the Replication/Routing tab of the Connection document you created in Step 1, complete the
following fields in the AutoDialer section:

Field Description
AutoDialer Task Select Enabled
AutoDialer connection Specifies a name for this AutoDialer connection. Enter any unique name, for example,
name InternetReplication. It’s best to use a name that’s short and descriptive.

The name you enter in this field must also appear in the AutoDialer connection name field
in the Connection document that provides the schedule for this task (see Step 5).
Connect remote server Specifies how many minutes before a scheduled action that this server will dial up to
to network connect to the Internet. To ensure availability, specify a time value that enables the server
to be online several minutes before the start of the scheduled action.

3. Click Save & Close.

4. Create a LAN Connection document that defines how the source server for the scheduled task
connects to the destination server.
5. Enter the following information in the Connection document you created in Step 4 and the click Save
& Close:

Tab Field Description

Basics Optional network Enter the IP address of the destination server.
address

122 Lotus Domino Administrator 7 Help

Tab Field Description
Replication/Routing Use AutoDialer to Select Enabled.
connect remote server
to network
AutoDialer connection The AutoDialer
name connection name
specified in the
Network Dialup
connection document
you created in Step 2,
for example,
InternetReplication.
Schedule Schedule Select Enabled
Connect at times Specify the time to
replicate with or route
mail to the destination
server. Enter a specific
time only, for example,
10:00 AM, not a time
range.
Repeat interval Leave this field blank.
Domino does not
support repeat intervals
for AutoDialer
connections.
Days of week Specify the days when
the calling server
attempts to make this
connection.

6. Connect the destination server (the dialing server) to the Internet by having it dial up the ISP.
7. From the server console of the destination server, enter the command:
Replicate servername directoryfile
Where servername is the name of the source, or replication, server, and directoryfile is the filename of
the Domino Directory database. For example, enter:
Replicate Jupiter NAMES.NSF
8. Add the AutoDialer task to the ServerTasks item in the NOTES.INI file to start the AutoDialer task on
Pluto.

Coordinating Notes Direct Dialup connections between servers

To enable two servers to perform scheduled tasks when one or both of them uses a dialup connection to
access the network, you can create an AutoDialer connection to automatically coordinate the dialup
schedule with the task time. In most cases you use an AutoDialer connection to schedule tasks over
Internet dialup connections, but an AutoDialer connection can also enable a remote Domino server to dial
directly into another Domino server, or into a passthru server.

The process for creating an AutoDialer connection for use with a Notes Direct Dialup connection is
similar to the one used to create an AutoDialer connection for a Network Dialup connection. For
replication tasks, set up the more powerful server to be the source server, and the less powerful server,
generally the server with the dialup connection, to be the destination server.

If the dialing server connects into a passthru server rather than connecting directly to the replication
server, all communications between the dialing server and the replication server occur through the
passthru server. The replication server cannot locate the dialing server on the network except with the

Chapter 4. Setting Up Server-to-Server Connections 123

help of the passthru server and so requires a Passthru connection document to provide this information.
In addition, you must also configure the dialing server, as well as the replication server, as passthru
destinations.

To set up an AutoDialer connection for use with Notes Direct Dialup connections
1. Create a Notes Direct Dialup connection document that defines how the dialing, or destination, server
connects to the Domino server initiating replication (the source server).
For information on creating a Notes Direct Dialup connection, see the topic ″Creating a Notes Direct
Dialup connection″ earlier in this chapter.
If the dialing server dials into a passthru server, rather than directly into the source server, in addition
to this Notes Direct Dialup connection document, you must also create a Passthru connection
document if one doesn’t already exist. You must also set up the source server as a passthru
destination.

Note: The AutoDialer section on this Passthru connection document is not used.
For information on creating a Passthru connection document, see the topic ″Creating a passthru
connection″ earlier in this chapter.
2. On the Replication/Routing tab of the Connection document you created in Step 1, complete the
following fields in the AutoDialer section:

Field Description
AutoDialer Task Select Enabled
AutoDialer connection Specifies a name for this AutoDialer connection. Enter any unique name, for example,
name AutoDialReplication. It’s best to use a name that’s short and descriptive.

The name you enter in this field must also appear in the AutoDialer connection name field
in the Connection document that provides the schedule for this task (see Step 5).
Connect remote server Specifies how many minutes before a scheduled action that this server will dial up to
to network connect to the Internet. To ensure availability, specify a time value that enables the server
to be online several minutes before the start of the scheduled action.

3. Click Save & Close.

4. Create a Passthru connection document describing how the replication server connects to the
destination server.
5. Enter the following information in the Passthru connection document you created in Step 4:

Tab Field Description

Replication/Routing Use AutoDialer to Select Enabled.
connect remote server
to network
AutoDialer connection The AutoDialer
name connection name
specified in the Notes
Direct Dialup
Connection document
in Step 2, for example,
AutoDialReplication.
Schedule Schedule Select Enabled

124 Lotus Domino Administrator 7 Help

Tab Field Description
Connect at times Specify the time to
replicate with or route
mail to the answering
server. Enter a specific
time only, for example,
10:00 AM, not a time
range.
Repeat interval Leave this field blank.
Domino does not
support repeat intervals
for AutoDialer
connections.
Days of week Specify the days when
the calling server
attempts to make this
connection.

6. Click Save & Close.

Configuring a communication port

If you specified a communication port when you configured the server, you do not need to specify the
port again. You configure an additional communication port only when you add an additional modem or
other device to a server or when you need to adjust the settings for a port currently in use.
1. Install the modem on the server communication port and ensure that the operating system
recognizes the port.
2. From the Domino Administrator, select the Server - Status tab.
3. From the Servers pane, select the server on which to set up the port. On platforms, such as UNIX,
for which there is no Domino Administrator client, you can set up ports remotely.
4. From the Tools pane, click Server - Setup Ports.
5. Select the name of the port on which you installed the modem, for example, COM1.
If the communication port name does not exist, select New, type the name of the communication
port on which you installed the modem, select XPC for the driver, and then click OK.
6. Select Port Enabled.
7. If you want to enable Domino network data encryption, select ″Encrypt network data.″

Note: Enabling network encryption can slow performance, especially for connections that use
data-compressing modems. Never apply Domino network data encryption to ports that use
data-compressing modems. Rather than reducing the size of the transmitted data, the modem’s
hardware compression techniques can increase it, negating the benefits of the modem compression.
For more information about setting up network data encryption for a port, see the topic Encrypting
network data on a server port.
8. Select ″Compress network data″ to enable Domino network data compression. Network compression
occurs only if it is enabled on both sides of the connection. If compression is not enabled on the
server being connected to, data will not be compressed.
9. Click portname Options, where portname is the name of the port whose settings you want to change.
10. Modify default port settings, as needed and then click OK.

Note: These settings apply to digital-analog modems only, not cable or DSL modems.
The default port settings work in most situations. However, if you are performing troubleshooting,
you may wish to adjust some of the settings. The following settings are available:

Chapter 4. Setting Up Server-to-Server Connections 125

Field Description
Modem type Associates a modem with a modem command file. If none of the listed modems is an
exact match for the installed modem, select the closest match by brand and speed. If the
modem is 100% Hayes-compatible, select ″Auto Configure″ (AUTO.MDM) for Domino to
determine the modem type automatically and select the appropriate Hayes command file.
Because the Auto Configure modem file does not provide optimal performance, use it only
as a temporary measure while obtaining an appropriate modem

If there’s no match and your modem is not 100% Hayes-compatible, you may need to edit
an existing modem command file or create a new one. For information about your
modem, see your modem documentation.

For information about editing modem command files, see the topic ″Modifying a modem
command file″ later in this chapter.
Maximum port speed Specifies the maximum speed at which the communication port on the computer sends
data to the modem and receives data from the modem. Domino selects a maximum data
transmission speed based on the modem type you select. The maximum speed is limited
by the maximum speed specified in the modem’s command file and may also be limited
by the server’s operating system. Default value is 19200. Specify the highest value
supported by your modem hardware. Select a lower port speed if you are having trouble
with a noisy phone line or cannot establish the carrier.
Note: When using a null modem, the maximum port speed on both computers must
match.
Speaker volume Specifies how loudly to amplify modem tones during connection attempts. Choose the
volume that best allows you to monitor call progress: Low Medium, or High; or choose
Off to mute the modem.
Dial mode Choose one:
v Tone - For touch-tone phone lines.
v Pulse - For rotary phone lines or modems that do not support touch-tone dialing.
Log modem I/O Select this option to help troubleshoot modem connection problems by recording modem
control strings and responses in the Miscellaneous Events view of the server’s Notes Log
(LOG.NSF).

To conserve disk space, after the problem is fixed, deselect this option to prevent the extra
information from being recorded.
Log script I/O Select this option to help troubleshoot communication problems between servers that
occur after the modem establishes a connection. The server records script file responses
and replies in the Miscellaneous Events view of the server’s Notes Log (LOG.NSF).

To conserve disk space, after the problem is fixed, deselect this option to prevent the extra
information from being recorded.
Hardware flow control Specifies how data is sent between the computer and the modem. Select this option (the
default on operating systems other than UNIX) to enable data flow control. Deselect this
option only if you’re using a modem or external serial port that doesn’t support flow
control. When deselected, messages about errors and retransmissions can appear in the
Phone Calls view of the log file (LOG.NSF).
Wait for dialtone before Select this option (the default) to require the modem to detect a dialtone before dialing.
dialing Deselect this option on phone systems where dial tone detection is a problem.
Dial timeout Specifies the time, in seconds, that the source server continues attempting to connect to
the destination server before it cancels the attempt. Increase the dial time-out period when
using pulse dialing or when calling overseas. The default value is 60.
Hangup if idle Specifies the time, in minutes, that the modem on the source server waits before hanging
up if there is no data passing through the connection. The default value is 15. For ports
that workstation users dial into, specify a longer idle time so users have time to read or
compose long documents.

126 Lotus Domino Administrator 7 Help

Field Description
Port number Specifies the port number for the current port type. Domino automatically sets the port
number to the number specified in the port name -- for example, if COM7 is the port
name, the port number is 7. On UNIX systems, specify a port number N that matches the
/dev/cuaN device file that you linked to the asynchronous port.

11. To specify an acquire script for this port, click Acquire Script, select the script in the Acquire Script
dialog box, and then click OK.
For more information on acquire scripts, see the topic ″Writing and editing acquire and login scripts″
later in this chapter.
12. If necessary, you can edit acquire scripts and modem command files.
For information about editing modem command files and acquire scripts, see the topic ″Modifying
modem command files and acquire scripts″ later in this chapter.

Modifying modem command files and acquire scripts

When you modify a modem command file or acquire script, you can only modify the file on the local
server. To apply a modified modem file to a remote server, edit the file locally and copy it to the Domino
Data/Modems subdirectory on the remote server. Then restart the server so that the modifications take
effect.
1. Use the documentation that came with the modem to determine which additional commands you
must add to the modem command file.
2. From the Domino Administrator, select the Server - Status tab.
3. From the Tools pane, click Server - Setup Ports.
4. From the Communication Ports box, select the modem communications port; for example, COM1.
5. Click portname Options, where portname is the name of the communications port you selected in step
4.
6. To edit a modem file, in the Modem type field, select the modem command file that you want to
modify -- typically, Generic All-Speed Modem File and click Modem File.
To edit an acquire script, click ″Acquire Script.″
7. Edit the content of the file as necessary. Refer to the comments at the top of the file for instructions.
8. Click Save to save the file using the current name.
Or, to save the file under a new name, click Save As, enter a new name for the modified file in the
File name field, and the click Save.
9. Click Done to close the Edit dialog box, and then click OK to close each of the remaining open dialog
boxes.

Note: To ensure the best performance for connections that use data-compressing modems, don’t apply
Domino network data encryption to ports using these modems. Rather than reducing the size of the
transmitted data, the modem’s hardware compression techniques can increase it, negating the benefits of
the modem compression. For more information about setting up network data encryption for a port, see
the chapter ″Setting up the Domino Network.″.

Using acquire and login scripts

How you specify a script when making a call depends on the type of script.

Type of script Steps

Acquire script Specify the script when you set up the communication port. When the server makes a call
using the specified port, Domino uses that acquire script to obtain a modem from a modem
pool. Domino runs the commands in the acquire script before running the commands in the
modem script.

Chapter 4. Setting Up Server-to-Server Connections 127

Type of script Steps
Login script Specify a login script in the Notes Direct Dialup Connection document for connecting to a
specified server. When making a call to that server, Domino uses the specified login script.

Writing and editing acquire and login scripts

Domino uses acquire and login scripts to make certain connections. A Domino server that doesn’t have its
own modem can use an acquire script to obtain a modem from a modem pool on a communications
server. The server runs the commands in the acquire script prior to running the commands in the modem
file used to make the connection. You specify the acquire script to use when configuring the modem port.
Check the documentation that came with the communications server to see if the server includes an
acquire script.

Login scripts provide information required to access a destination server and are required by some Direct
dialup connections. The server runs the commands in the login script after running the modem command
file.

You can edit an existing acquire or login script or create new ones from scratch using any text editor.
When editing or writing scripts, use the appropriate script commands, keywords, and comments. The
keywords identify and classify the script file. The script commands execute sequentially. The keywords
you use depend on the device that the script sets up.

Any time you change a script, make sure you save the file with an SCR extension and copy it to the
Notes Data/Modems subdirectory of every workstation and the Domino Data/Modems subdirectory of
every server that uses the script.

General rules for writing script files

1. Start lines with a colon to indicate a branch label. Do not exceed the maximum branch label length of
eight characters. If you specify more than eight characters, the script uses only the first eight.
2. Start lines with a semicolon to indicate a comment line.
3. Do not exceed the maximum line length of 80 characters.
4. Embed control characters 0 - 20H in strings. For example, use ^M for CTRL+M. Use double carets for
a literal caret. For example, use ^^M for CARET+M.
5. Specify up to four optional arguments for login scripts: ^1, ^2, ^3, ^4. Then, when you make a call on
the workstation or server, you enter values for these arguments, or you enter them permanently in the
Connection document in the Domino Directory or Personal Address Book. The values you enter
replace the ^1, ^2, ^3, or ^4 in the script when you make each call.
6. Raise the data terminal ready (DTR) signal at the start of script file processing. If the modem does not
automatically raise this signal, you must use the DTR_HIGH command.

Editing script files

Script files are ASCII text files with the extension SCR that Domino stores in the Modems subdirectory of
the Domino data directory. You can open and edit login scripts and acquire scripts using any text editor.
In addition, you can also open an acquire script for editing from the Port Setup dialog box during the
process of setting up a server’s communications port.

For information about how to edit an script from the Port Setup dialog box, see the topic ″Configuring a
communication port″ earlier in this chapter.

Script keywords
Use these keywords when you write a script file.

128 Lotus Domino Administrator 7 Help

DESC
A one line description of the script file’s purpose. Dialog boxes for selecting the script display the text
associated with this keyword. Always include a DESC line in a script file to provide users with
information about the script. For example, if you open the Acquire Script dialog box while setting up a
communication port, the following text appears for the default acquire script (COMSERV.SCR):
Acquire a modem via a communications server

Similarly, mobile users who use login scripts when configuring dialup communications from a Notes
client, see the value of the DESC keyword in the login script.

TYPE
Tells whether the script is an acquire or connect script. For example:
TYPE CONNECT

ARG...ARG4
For connect scripts only, these optional keywords precede a description of each of the four script
arguments. You may write scripts using from 0 through 4 arguments. For example, you might use the
following script arguments and descriptors in a connect script file:
ARG1 1. REMOTE DTE ADDRESS:
ARG2 2. None entered:
ARG3 3. None entered:
ARG4 4. None entered:

ARG1 is a keyword and ″1. REMOTE DTE ADDRESS:″ is the description that appears in the Call Setup
dialog box. ARG2, ARG3, and ARG4 are keywords. ″X. None entered:″ lets users enter arguments when
making the call. Users can enter arguments when they choose File - Mobile - Call Server, select More
Options, and then select Call Setup; or they can enter arguments in the Notes Direct Dialup Connection
document in the Domino Directory or Personal Address Book.

Commands for acquire and connect scripts

The available script commands are described in this table.

Command Description Syntax

BREAK Sends a communications break. Time is specified in BREAK [time]
100ms intervals. Default is 500ms. Maximum is
2000ms. Timing of breaks is not exact.
DTR_HIGH Raises the DTR signal on the selected port. DTR_HIGH

If the modem or other communication device does

not automatically raise data terminal ready (DTR)
at the start of script file processing, use the
DTR_HIGH script command or configure DTR on
your modem or communication device.
DTR_LOW Lowers the DTR signal on the selected port. DTR_LOW
ERROR Tells the script file to branch to the specified label if ERROR label
an error previously occurred. If no label is specified,
the ERROR condition is cleared, but no branch
occurs.
FAIL Terminates execution of the current script. The FAIL [text string]
optional text string is logged in the log file
(LOG.NSF).
GOTO Branches unconditionally to the specified label. If GOTO label
the label does not exist, the script file terminates,
and the error is logged in the log file (LOG.NSF).

Chapter 4. Setting Up Server-to-Server Connections 129

Command Description Syntax
LOG OFF Turns off informational logging if you have Log LOG OFF
modem I/O selected (for execution of this script
only). Uses the log file (LOG.NSF).
LOG ON Turns on informational logging if you have Log LOG ON
modem I/O deselected. This command logs
execution of only this script.
PROMPTUSER Displays an interactive dialog box to prompt a user PROMPTUSER″Dialog box title″
from a script.
[″Title1″″[initializer]″″Title2″
The user needs to run a script with this command ″[initializer]″″Title3″″[initializer]″
from a Notes client.
″Title4″″[initializer]″]
REPLY Sends a string to the serial port. Carriage REPLY ″string″ [;]
return/line feed is sent at the end of the string
unless you include a semicolon (;).
WAIT Waits a given amount of time for the case-sensitive WAIT [time] [FOR ″string″]
specified string, which must be enclosed in quotes.
Any data other than a matched string is passed
along. If a time is not specified, waits a maximum
of 60 seconds.
WATCH Same as WAIT, but with multiple responses and WATCH [time] [FOR] ″string1″ statement
actions. The WATCH command terminates ″string2″ statement ENDW
(continues to the next instruction) when one of the
strings is matched or when time-out occurs.

Connecting Notes clients to servers

After you set up a server to accept inbound connections, it can accept them from both servers and clients.
The methods used to establish connections from clients to servers on remote networks are similar to those
used when connecting one server to another. To connect to a remote Domino server, clients may require
Connection documents, and depending on the type of connection, might also require a modem, COM
port information, and other data, documents, and files. You can also connect clients to non-Domino
Internet servers. The following table provides information on other types of information required to
create client-to-server connections.

Requirements for connecting Notes clients to remote servers over

various access media
Type of client and connection to
Domino network
Notes client connecting directly to
Domino network over LAN, cable
data network, or digital subscriber
line (DSL)
Required documents in the Personal Additional files and information
Address Book required
v Office Location document. For v Notes user ID
connections through a passthru v Name of a server containing a
server the Location document Domino Directory
must specify the name of the
v Name and port number of proxy
passthru server
server, if any
v Connections through a passthru
server require a Passthru
Connection document

130 Lotus Domino Administrator 7 Help

Type of client and connection to
Domino network
Notes client connecting directly to
Domino network over dialup line
Notes IMAP or POP3 mail client
connecting directly to an Internet
mail server over LAN, cable, or DSL
connection
Notes IMAP or POP3 mail client
connecting to an Internet mail server
over a dialup connection
To connect to Domino through a passthru server, users must specify the name of the passthru server in
the current Location document and set up Passthru Connection documents.
Required documents in the Personal Additional files and information
Address Book
v Home (Notes Direct Dialup)
Location document. For
connections through a passthru
server the Location document
must specify the name of the
passthru server
v Notes Direct Dialup Connection
document
v Connections through a passthru
server require a Passthru
Connection document
v Internet Location document
v Account documents
v Home (Network Dialup) Location
document
v Account document
v Network Dialup Server document
Chapter 4. Setting Up Server-to-Server Connections
required
v Notes user ID
v Name of a server containing a
Domino Directory
v Dialup phone number
v Modem and COM port information
v E-mail address
v Incoming and outgoing mail server
addresses
v Proxy server information
v Internet mail address
v ISP account and password
v Incoming and outgoing mail server
addresses
v Dialup telephone number
131
132 Lotus Domino Administrator 7 Help
Chapter 5. Setting up Domino and DB2
This chapter contains overview information about Domino and DB2, describes how to install and set up
Domino and DB2, and explains how to maintain and administer your Domino and DB2 environment.

Understanding Domino and DB2 -- Limited Availability

Domino 7 with DB2 is released with Limited Availability, as such, it is not available for general usage.

For more information about the Limited Availability program and other important information on this
topic, see the URL http://www.ibm.com/lotus/nsfdb2.

An understanding of DB2 concepts is assumed before you attempt to configure Domino and DB2.

For information about DB2, see the DB2 Information Center

http://publib.boulder.ibm.com/infocenter/db2help/index.jsp.

You can configure IBM Lotus Domino to run with DB2 databases and Notes databases. You can also
access and view data stored in Notes databases as well as data stored in DB2 databases. When working
with your data, there is no visible difference between the data stored in a Notes database and data stored
in a DB2 database.

When you run Domino with DB2, there are three distinct interactions that occur between Domino and
DB2. They are:
v Domino uses DB2 as an alternate data store for Notes data.
v Specific sets of data are pushed from an NSF to DB2 in the form of DB2 Access Views (DAVs).
v A Notes view can be built based on an SQL query in the form of Query Views.

Note: DAVs and Query Views are explained later in this topic.

When working with data, you interact only with the Domino server as a Notes user. In a Domino and
DB2 configuration, all of the data stored in DB2 is owned by Domino; therefore, you do not need a DB2
ID. The client is unaware that the storage is in DB2 and not in an NSF file. There is no need for users to
have DB2 connectivity because DB2 connectivity is handled by the Domino server.

Domino connects to DB2 using the Domino server user account assigned to it when you run the DB2
Server Enablement tool from the Domino Administrator. The DB2 Server Enablement tool enables a
Domino server to communicate with a DB2 server.

133
For more information, see the topic ″Enabling Domino access to a DB2 server.″

DB2 Access Views

A DB2 Access view (DAV) is a shared resource that lets you define a DB2 view of Notes data. DAVs
enable you to leverage the data that is stored in DB2. While the DAV actually exists in DB2, it is
accessible by both Domino and non-Domino applications. Using DAVs is an option; you can set up your
Domino and DB2 configuration to use DAVs if you choose to.

A Notes NSF can contain many notes that differ from each other, whereas DB2’s relational database is
organized in structured tables and columns that are similar to each other. To help resolve the issue of
using two very different database structures, a DAV identifies a common set of notes in an NSF. This
common set of notes can then be used by DB2.

For example, you can organize notes in DB2 based on the Notes form that is used to create the note. In
this example, the form ″Employee″ contains the text fields FirstName, LastName, Street1, Street2, State,
and Zip Code.″ Therefore, you can create a DAV in Domino Designer that instructs Domino to create a
DB2 view that provides access to a specific set of notes that contain a specific set of fields.

CAUTION:
When creating a DAV, the designer must be sure that field names are entered exactly as they appear in
the database. If a field name is invalid, no data displays.

Access to the DAV is managed by a the DB2 Access server installed on the DB2 server.

134 Lotus Domino Administrator 7 Help

The DAV makes the data available directly by SQL. Third-party applications that use Open Database
Connectivity (ODBC) can read the data.

Domino stores NSFs as a set of tables in DB2. You cannot view this data, it is private to Domino. You can
only view NSF data in DB2 by creating a DAV to expose that data.

For more information about DB2 Access Views, see the topic ″DB2 Access Views″ in the Domino Designer
7 documentation.

Query views
A Query view is another type of Notes view. Like other types of Notes views, query views are design
elements that are part of Notes applications. A query view uses an SQL query to populate its data instead
of using a view formula that selects notes from a Notes database. If you want to create a query view
based on data in a Notes database that resides in DB2, you must first have defined and populated a DAV.

Data in DB2 databases is accessed and manipulated through System Query Language (SQL) statements.
Chapter 5. Setting up Domino and DB2 135
When you create a Notes view that is based on an SQL query, keep the following tips in mind:
v If the query view references only non-Domino data, you cannot ″open″ the notes in the Notes view. It
will literally be a Notes view of DB2 data.
v If the query view references Domino data via a DAV and selects the #NOTEID from the DAV, you can
open the note.
v A Query can be composed dynamically in the Notes client application, for example, by using the
@prompt function. For example, the application can prompt the user for STATE and then query only
the people who live in the selected state.
v A Query View can join data from multiple DB2 tables and views; therefore, you can join data from two
NSFs by joining two separate DB2 Access Views.

A benefit of using DB2 to access data is that Query Views are dynamic; you can re-execute them with
different SQL statements to quickly access specific notes. Regular Notes views need to be rebuilt using
the Update and Updall tasks, but Query Views do not; therefore, they do not take up space in the NSF.
Query Views can do things that regular Notes views cannot do, for example, they can join data from
multiple NSFs and they can access non-Domino data. Non-Domino data is any data visible to DB2.

For more information about Query Views, see the topic ″Query Views″ in the Domino Designer 7
documentation.

DB2 and Domino authentication

When accessing Notes data from a DAV or Query view, users need both a Notes user name and a DB2
user account name. For access to DAVs from SQL, the user connects as a specific DB2 user name. This
DB2 user account uses the corresponding Notes user name to verify Domino access rights (ACLs) to the
Notes data. For access to a Query View from Notes, the user connects to Notes using their Notes ID, and
the Query View uses the corresponding DB2 account name to verify DB2 access privileges for the data
being accessed.

Benefits of using Domino with DB2

Domino with DB2 offers benefits to Domino customers and to DB2 customers. Domino customers benefit
from improved performance and scalability, the ability to use relational constructs, access to SQL-based
views of Notes and non-Notes data, greater transaction processing speed, and fast access to DB2. DB2
customers benefit from improved XML/collaboration support, Domino services, Notes application
development support, and integration of Domino data into DB2 applications. Domino with DB2 also
offers full enforcement of Domino security.

Some key features of Domino with DB2 are listed here:

136 Lotus Domino Administrator 7 Help

v Domino with DB2 supports Domino security. SQL queries return rows of data if the user has ″Read″
permission in the ACL for the NSF and is a valid Reader, that is, the user’s name appears in the
Reader fields for the requested data.
v Any version of the Notes client that has access to the Domino server can access the Domino databases
stored in DB2.
v You save memory in the Unified Buffer Manager (UBM) pools when NSF databases are moved into
DB2. By default, Domino uses 1/8 to 3/8 of available memory. Use this NOTES.INI variable with the
recommended value of 25:
NSF_BUFFER_POOL_SIZE_MB=25

Domino and DB2 user accounts that are needed for Domino and DB2
To install the DB2 software on Microsoft Windows or on IBM AIX or UNIX, you need an installation
account.
v An installation account is an OS user account created in Microsoft Windows or AIX/UNIX. You use
this account to install the DB2 software.

Accounts required with Microsoft Windows

Each account is fully explained later in the documentation, but here is a list of the user accounts that you
will need:
1. A DB2 administrator’s account which is an OS user account. This OS user account starts the DB2
services.
2. A DB2 user account that the Domino server uses to authenticate with the DB2 server. This DB2 user
account is created during DB2 server enablement and is called the Domino server user account.

Note: The DB2 server enablement tool enables a Domino server to communicate with a DB2 server.
3. A Notes user account with Domino server access rights.
4. A DB2 account name which is an OS user account that you will map to the Notes user account. This
mapped account is needed for accessing the DB2 Access Views and Query Views.

Accounts required with AIX/UNIX

Each account is fully explained later in the documentation, but here is a list of the user accounts that you
will need:
1. A DB2 user account name that Domino uses to authenticate with the DB2 server. This account can be
the DB2 instance owner, in which case, it is created when the DB2 instance is created during DB2
server installation and configuration. If you are not using the DB2 instance account, this DB2 account
is created during the DB2 server enablement process and is called the Domino server user account.
2. A Notes user account with Domino server access rights.
3. A DB2 account name which is an OS user account that you will map to the Notes user account. This
mapped account is needed for accessing the DB2 Access Views and Query views.

Using the Domino Web Administrator client with Domino and DB2
The Domino Web Administrator client can be used with Domino and DB2. The Domino and DB2 features
that are available from the Domino Web Administrator function exactly as they do when using those
same features from the Domino Administrator client.

These Domino and DB2 features are also available using the Domino Web Administrator client:
v DB2 Server Enablement Tool
v Edit DB2 Access server Connection document
v Test DB2 Access

Chapter 5. Setting up Domino and DB2 137

Databases created with Domino 7
The information in this topic is unique to the Domino with DB2 configuration. For information about
creating Notes databases, see the Domino Administrator printed or online documentation.

For information about creating databases in DB2, go to the DB2 Information Center at
http://publib.boulder.ibm.com/infocenter/db2help/index.jsp

Database storage
When you run the DB2 Server Enablement Tool from the Domino Administrator or the Domino Web
Administrator, you specify a number of parameters. One of these is the default database storage type of
either DB2 or NSF that is assigned to all databases that you create. By default, the database storage type
is DB2, but you can change that to NSF on the DB2 tab of the Server document. When NSF is the default
database storage type, new databases are created as files in the Domino server’s disk space. When DB2 is
the default database storage type, the databases are stored in a DB2 database managed by the DB2 server.
″Classic″ Domino databases are referred to as NSF databases, and NSFs stored in a DB2 database and
managed by a DB2 server are referred to as DB2 enabled Notes databases.

Only databases stored in DB2 can be accessed in DB2 using SQL. Databases created with an NSF are not
visible to DB2. NSFs and DB2 enabled Notes databases are visible to the Domino server.

Each DB2 enabled Notes database can be identified by the following icon in the Files panel of the
Domino Administrator:

Databases not supported as DB2 enabled Notes databases

The Domino tasks listed in the following table create databases in NSF format on DB2 enabled Domino
servers.

Note: Do not create replicas for these .NSF files on a DB2 enabled Domino server:

Command to
Task run task Description Database
Activity Trends Collector trends Runs the Activity Trends Collector which activity.nsf
performs historical and trended analysis on
Domino Activity data.
Administration Process AdminP Automates a variety of administrative tasks. admin4.nsf
Billing Billing Collects all generated billing information. billing.nsf
Cataloger Catalog Updates the database catalog. catalog.nsf
Cluster Database Directory Cldbdir Updates the cluster database directory and cldbdir.nsf
Manager manages databases with cluster-specific
attributes.
Event Monitor Event Monitors events on a server. events4.nsf
HTTP Server HTTP Enables a Domino server to act as a Web webadmin.nsf
server so browser clients can access
databases on the server.
IMAP Server IMAP Enables a Domino server to act as a mail files for IMAP
maildrop for IMAP clients. users/mail7.ntf

138 Lotus Domino Administrator 7 Help

 Command to
Task run task Description Database
LDAP Server LDAP Enables a Domino server to provide LDAP schema.nsf
directory services to LDAP clients.
MTC MTC Reads log files produced by the router and mtstore.nsf
writes summary data about message traffic
to a database for message tracking purposes.
Router Router Routes mail to other servers. mail.box
Rooms & Resource Manager RnRMgr Processes all Rooms and Resources clubusy.nsf or
activities, such as meeting invitations, busytime.nsf
reschedules or cancellations, and updates
the Busytime database accordingly.
Schedule manager Sched Processes all user calendar activities and clubusy.nsf or
updates the Busytime database accordingly. busytime.nsf
SMTP listener SMTP Listens for incoming SMTP connections, mail*.box
enabling Domino to receive mail from other
SMTP hosts.

The databases in the following table are not supported as DB2 enabled Notes databases in Domino 7 and
DB2.

Note: Do not create replicas for these .NSF files on a DB2 enabled Domino server:

Database Usage Description From template

DBDIRMAN.NSF Domino Server Keeps information about all DBDIRMAN.NTF
Notes databases on the
Server.
DDM.NSF Admin Client, Domino Domino Domain DDM.NTF
Server Monitoring provides one
location in the Domino
Administrator client that
you can use to view the
overall status of multiple
servers across one or more
domains.
DIRCAT.NSF Domino server, Notes Directory catalog is an DIRCAT5.NTF
Client optional directory database
that typically contains
information aggregated
from multiple Domino
Directories.
DOMCHANGE.NSF RunJava task The Domino Change domchange.ntf
Control database is used by
the Domino Change
Manager process to manage
and execute change control
plans. It includes an
approval cycle workflow
and tight integration with
the Administration Process.
ISPY50.NSF ISY server task This database is created mail7.ntf
automatically by the ISpy
server task for its mail
probing activities.

Chapter 5. Setting up Domino and DB2 139

Database Usage Description From template
LOG.NSF Domino Server, Notes Notes Log created at LOG.NTF
Client Domino server startup.
Records and stores
information about all types
of Domino server activities
and remote workstation
communication activities.
NAMES.NSF Domino Server, Notes Public Address Book (NAB) PUBNAMES.NTF
Client Name and Address Book
RESRC7.NSF Admin Client, Notes Client Resource Reservation RESRC7.NTF
Database
STATREP.NSF Statistic Collector Task Monitoring Results STATREP5.NTF
Database (formerly
Statistics Reporting)
contains statistics for one or
more servers in a domain
(gathered by the Statistic
Collector Task).
WEB.NSF Averaging agent The Averaging Agent
collects ratings that the
users assign to Web pages
and calculates the rating of
pages in the Web Navigator
database.

Compact database options are enabled for Domino and DB2

Several Compact options are implemented for Domino and DB2 configurations. When the -B option is
applied to a DB2 enabled Notes database, it reclaims disk space through tablespace reduction. This is
accomplished by a series of table and index reorganizations in DB2, which attempt to lower the
tablespace’s high water mark (HWM) so that the tablespace can be reduced in size. The effect of the DB2
table and index reorganizations is more significant if you run compact when Domino is not running.
Space reclamation in DB2 is entirely different than that which a Domino administrator is accustomed to.
Performing compact -B on a DB2 enabled Notes database does not guarantee that any space can be
reclaimed.

Running compact -B on a directory results in a single set of table and index reorganizations because
several DB2 enabled Notes databases can exist in a set of tables within a tablespace. The table and index
reorganizations for data in a DB2 enabled Notes database are deferred until compact is finished with
regular NSF processing.

Note: The Compact -b option does not have any impact on a DB2 enabled Notes database.

The Domino administrator should be familiar with the DB2 Database Analysis and Reporting Tool
(db2dart.) Db2dart is a DB2 utility that displays tablespace usage information, including what needs to be
done to best lower the HWM of a tablespace so that the tablespace can be reduced in size.

For more information about db2dart, go to the DB2 Information Center at

http://publib.boulder.ibm.com/infocenter/db2help/index.jsp.

140 Lotus Domino Administrator 7 Help

Domino and DB2 supported platforms and configurations
Use the information in these topics to verify which platforms and configurations are supported.
v Supported platforms and hardware and software requirements
v Supported configurations in Domino and DB2

Supported platforms and hardware and software requirements

Pre-Domino 7 releases cannot use Query Views, as well as some Designer features for DB2 Access Views.
Any version of the Notes C-API program that can access the DB2 enabled Domino server can also access
Notes databases stored in DB2.

DB2 key for access to Domino 7 with DB2

Limited Availability
Domino with DB2 is released with Limited Availability, as such, it is not available for general usage.

For more information about the Limited Availability program and other important information on this
topic, see the URL http://www.ibm.com/lotus/nsfdb2.

To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For Microsoft
Windows platforms, use NDB2KEY.DLL; for IBM AIX platforms, use libdb2key_r.a.

Add the DB2 key to the Domino Program directory. The default Domino Program directory on Microsoft
Windows is C:\Program Files\Lotus\Domino; the default Domino Program directory on IBM AIX is
/opt/lotus/ibm.

For more information about the DB2 key, see the URL http://www.ibm.com/lotus/nsfdb2.

Supported platforms
Domino 7 and DB2 are supported on these platforms:
v Microsoft Windows ®
v IBM AIX® 5.2 and 5.3

Note: Shared mail is not supported for a DB2 server. The recommended method of installation is to
create a new DB2-enabled Domino server and replicate to DB2. If an existing server is upgraded to a
DB2-enabled Domino server, the shared mail linked mail files need be unlinked prior to the upgrade.

Software requirements
v IBM Lotus Domino server 7
v IBM Lotus Domino Administrator 7.0
v DB2 UDB Enterprise Server Edition version 8.2.2 (FixPak 9).
v DB2(R) Run-Time Client is required for remote configurations
CAUTION:
Do not confuse the DB2 Run-Time Client with the DB2 Run Time Client Lite (RTCL). We do NOT
support the DB2 Run Time Client Lite.
v IBM DB2 Access for Lotus Domino 7.0
v IBM Lotus Notes Client 7.0 is required to be able to open Query Views

Memory requirements for a DB2 enabled Domino server, Microsoft Windows or

IBM AIX
Microsoft Windows platform
v Computers require a minimum 1 GB RAM, 2GHz Processor.

Chapter 5. Setting up Domino and DB2 141

v On a local configuration, that is, the Domino server and the DB2 server are installed and running on
the same Microsoft Windows computer, the computer should be dedicated to Domino and have no
more than one DB2 instance and one DB2 database for the Domino server.
v On a remote configuration, that is, the Domino server and the DB2 server are installed on and are
running on separate Microsoft Windows computers, the DB2 server must have one DB2 instance and
one DB2 database for the Domino server.

IBM AIX platform

v The DB2 Server can be configured with multiple DB2 instances but can only have one DB2 instance
and one DB2 database per Domino Server.
v A minimum of 1GB memory per DB2 instance
v The Input Output Completion Protocol (IOCP) must be installed on AIX systems on which the DB2
Access server is installed. If Domino has not been installed on the computer where the DB2 Access
server is to be installed, you must manually verify that IOCP is installed and enabled prior to installing
the DB2 Access server.

Other requirements
v Transaction logging must be enabled to run the DB2 Domino server. When you enable transaction
logging on the Server document, set the log file size to at least 192 MB.
v UTF-8 is supported for Domino 7 and DB2. New databases are created as UTF-8 databases. No other
database encoding is supported.

What’s not supported in this release of Domino and DB2?

Domino 7 and DB2 does not support the use of the following:
v IMAP4
v ODS version 41
v Domino’s extended ACLs are not supported with DB2 enabled Notes databases.
v SCOS (shared mail)
v System databases are not supported as DB2 enabled Notes databases (NAMES.NSF, LOG.NSF, etc.)

Memory and hardware requirements

v 2 GHz processor
v 1 GB RAM

Supported configurations in Domino and DB2

The following Domino and DB2 configurations are supported:
v Local Configuration -- Domino 7 and DB2 8.2.2 (for current beta) installed and running on one
computer. (See Figure 1)
v Remote Configurations -- See Remote Configuration, Figure 2 and Figure 3.
– DB2 Run-Time Client is installed on the same servers as Domino 7, and the Domino 7 server is
pointing to one instance of DB2 8.2.2 installed on another computer. The DB2 Run-Time Client must
be installed on the Domino server. (See Figure 2)
CAUTION:
Do not confuse the DB2 Run-Time Client with the DB2 Run Time Client Lite (RTCL). We do not
support the DB2 Run Time Client Lite.
– Multiple Domino servers are reinstalled on one partitioned server. DB2 is installed on another
server. (See Figure 3)

To use a DB2 server remotely, the computer on which the Domino server resides must also have one of
the following DB2 components installed:
v DB2 Run-Time Client -- Must be installed on the Domino server in all configurations where DB2 is
installed on one computer and Domino is installed on another computer.
142 Lotus Domino Administrator 7 Help
v DB2 UDB Enterprise Server Edition -- Includes all components of a DB2 server and connects to a
remote DB2 server.
v DB2 Workgroup Edition -- We do not provide this but if a customer has purchased and is using this,
we will support it.

Each Domino server manages its own database on the DB2 server.

A DB2 server can support multiple Domino servers, each connected to its own database. These can be
separate databases in the same DB2 instance or separate DB2 instances -- each supporting a single
database / Domino server (recommended).

For information about DB2, go to the DB2 Information Center at

http://publib.boulder.ibm.com/infocenter/db2help/index.jsp.

Example of a local Domino and DB2 configuration

In this configuration, the Domino server and DB2 server are installed and running on the same computer.

You can configure DB2 to support one or more Domino servers.

Example of a remote Domino and DB2 configuration that uses

separate servers
In a remote configuration, Domino runs on one or more servers and DB2 runs on one or more servers.
This example applies to DB2 on IBM AIX because the DB2 server contains multiple DB2 Instances.

You can configure DB2 to support multiple Domino servers.

In this configuration, the DB2 Run-Time Client is installed on the Domino servers.

CAUTION:
Do not confuse the DB2 Run-Time Client with the DB2 Run Time Client Lite (RTCL). We do not
support the DB2 Run Time Client Lite.

Chapter 5. Setting up Domino and DB2 143

Each Domino server must point to its own unique DB2 database.

Example of a remote Domino and DB2 configuration that uses

partitions
In this remote configuration, multiple Domino servers reside on one partitioned server that communicates
with DB2, which is installed on a separate computer.

144 Lotus Domino Administrator 7 Help

Mixed platforms are supported for Domino and DB2. For example, you can run a Domino server on
Microsoft Windows and also have a remote DB2 server running on IBM AIX.

Chapter 5. Setting up Domino and DB2 145

Installation and setup procedures
Complete the installation procedures for Microsoft Windows or IBM AIX according to the platform you
are using, whether you are installing a DB2 Access server, and whether you are setting up a local or
remote configuration. You only need to install the DB2 Access server on a DB2 server if you want to
make Domino data available in DB2. If you only host NSF databases in DB2, you do not need to install
the DB2 Access server. The DB2 Access server facilitates your use of the Domino Designer view functions
for DB2 by enabling Domino’s user security.

Microsoft Windows
If you are setting up a local configuration on Microsoft Windows, complete one of these two procedures:
v Installing and setting up Domino and DB2 on Microsoft Windows - Local configuration
v Installing and setting up Domino and DB2 and the DB2 Access server on Microsoft Windows - Local
configuration

If you are setting up a remote configuration on Microsoft Windows, complete one of these two
procedures:
v Installing and setting up Domino and DB2 on Microsoft Windows - Remote configuration
v Installing and setting up Domino and DB2 and the DB2 Access server on Microsoft Windows - Remote
configuration

Anyone installing their Domino and DB2 configuration on a Microsoft Windows platform must also
complete this procedure:
v Installing DB2 on Microsoft Windows

IBM AIX
If you are setting up a local configuration on IBM AIX, complete one of these two procedures:
v Installing and setting up Domino and DB2 on IBM AIX - Local configuration
v Installing and setting up Domino and DB2 and the DB2 Access server on IBM AIX - Local
configuration

If you are setting up a remote configuration on IBM AIX, complete one of these two procedures:
v Installing and setting up Domino and DB2 on IBM AIX - Remote configuration
v Installing and setting up Domino and DB2 and the DB2 Access server on IBM AIX - Remote
configuration

Anyone installing a Domino and DB2 configuration on an IBM AIX platform must complete these two
procedures:
v Installing DB2 on IBM AIX
v IBM AIX post-installation procedure

All platforms
Complete these procedures only if you will be using the DB2 Access server and you did not install it as
part of one of the installation procedures you have already completed.

Installing the DB2 Access server

v Creating a server ID for the DB2 Access server
v Installing the DB2 Access server on the DB2 server

146 Lotus Domino Administrator 7 Help

Domino server enablement and mapping Notes and DB2 user IDs
The final two setup steps are:
v Enabling the Domino server to communicate with the DB2 server
v Mapping the DB2 ID to a Notes ID in the Domino server’s Domino Directory

Creating the DB2 installation account

You must have a DB2 installation account and use that user account to log on to a local computer to
install the DB2 server. The DB2 Server Enablement tool uses this user account during the DB2 Domino
server setup.

The DB2 installation account can be a local or domain user account that you create at the OS level in
Windows/AIX and it must belong to the Administrators group on the computer on which you are
performing the DB2 installation.

For details about creating user or domain accounts and assigning Administrator rights, see your
Microsoft Windows or IBM AIX documentation. For example, in Microsoft Windows, create the account
from the Control Panel - Administrative Tools, and then assign the Administrator rights listed below to
the account from Control Panel - Local Security Policy.

The installation account must be granted the following rights:

v Act as part of the operating system
v Create a token object
v Increase quotas
v Replace a process level token

If the Administrators group already has the administrator rights, there is no need to specifically add the
DB2 installation account because these rights will be inherited.

Note: If you want the DB2 Setup wizard to create a new DB2 administration server user account, which
is a domain user account, the installation account that you use to perform the DB2 installation must also
be assigned the right to create domain user accounts and it must belong to the Administrators group on
the computer on which you are performing the DB2 installation.

For more information about the DB2 installation account, go to the DB2 Information Center
http://publib.boulder.ibm.com/infocenter/db2help/index.jsp.

After you create the DB2 installation account and assign the necessary rights, log in using the DB2
installation account to begin installing DB2.

Creating the DB2 administrator and administration server account

You create the DB2 administrator account during the DB2 installation process. The DB2 administrator
account is also called the DB2 Administration server (DAS) user account. DAS is a DB2 administration
service that supports the GUI tools and assists with administration tasks on local and remote DB2
servers. The DAS user account logs the DAS service on to the computer when the DAS service is started.
It can be a local user account or a domain user account. It is recommended that the DAS user account
have SYSADM authority on each DB2 system in your environment so that it can start or stop other
instances as necessary.

Note: By default, any user that is part of the Administrator group has SYSADM authority.

The DB2 administrator account starts the DB2 services, such as DB2 DAS, DB2 Remote Command server,
DB2 Governor, and other DB2 services.

Chapter 5. Setting up Domino and DB2 147

You can create the DAS account before you install DB2 or you can use the DB2 Setup wizard to create it.
The DAS account must be granted these rights:
v Act as part of the operating system
v Create a token object
v Log on as a service
v Increase quotas
v Replace a process level token

The DB2 administrator account must belong to the Administrator’s group on the machine on which you
perform the DB2 installation.

Installing and setting up Domino and DB2 on Microsoft Windows -

Local configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For Microsoft
Windows platforms, use NDB2KEY.DLL. Add the DB2 key to the default Domino Program directory,
C:\Program Files\Lotus\Domino.

For more information about the DB2 key, contact your IBM representative.

Complete this procedure to set up a new Domino and DB2 environment on Microsoft Windows. This is
not a procedure for upgrading an existing Domino and DB2 configuration.

Procedure
1. Install and set up the Domino server and the Domino Administrator. For instructions, see Chapters 1
- 3 of Administering the Domino System, or see the Domino Administrator 7 Help.
2. When you start the Domino server, you are prompted to specify whether to run Domino as an
application or a Windows service. Choose application.
3. Create an installation user account.
4. Install DB2 on Microsoft Windows.
5. Create a DB2 administrator account.
6. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be turned on in Domino.
Linear, circular or archival transaction logging may be used. DB2 enabled Notes databases do not
work if transaction logging is not enabled.
7. Enable the Domino server to communicate with the DB2 server.
8. After Domino creates the initial DB2 database, stop the Domino server.
9. Determine whether your DB2 configuration has a SYSCTRL group by entering this command from
the DB2 Command Line Processor (CLP):
GET DBM CFG
10. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
11. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START
12. Restart the Domino server and the Domino Administrator.
13. Map the DB2 user name to a Notes user name.

148 Lotus Domino Administrator 7 Help

You are now ready to create views.

Installing and setting up Domino and DB2 and the DB2 Access server
on Microsoft Windows - Local configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For Microsoft
Windows platforms, use NDB2KEY.DLL. Add the DB2 key to the default Domino Program directory
C:\Program Files\Lotus\Domino.

For more information about the DB2 key, contact your IBM representative.

Complete this procedure to set up a new Domino and DB2 environment on Microsoft Windows. This is
not a procedure for upgrading an existing Domino and DB2 configuration.

Procedure
1. Install and set up the Domino server and the Domino Administrator. For instructions, see Chapters 1
- 3 of Administering the Domino System, or see the Domino Administrator 7 Help.
2. When you start the Domino server, you are prompted to specify whether to run Domino as an
application or a Windows service. Choose application.
3. Create an installation user account.
4. Install DB2 on Microsoft Windows.
5. Create a DB2 administrator account.
6. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be turned on in Domino.
Linear, circular or archival transaction logging may be used. DB2 enabled Notes databases do not
work if transaction logging is not enabled.
7. Create a server ID for the DB2 Access server.
8. Install the DB2 Access server on the server running DB2.
9. Enable the Domino server to communicate with the DB2 server.
10. After Domino has created the initial DB2 database, stop the Domino server.
11. Determine whether your DB2 configuration already has a SYSCTRL group by entering this command
from the DB2 Command Line Processor (CLP):
GET DBM CFG
12. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
13. Update the DB2 configuration by entering these commands from the CLP:
DB2STOP
DB2START
14. Restart the Domino server and the Domino Administrator.
15. From the Domino server console, enter
DB2 ACCESS SET
16. To verify that the DB2 Access server is installed and configured properly, use the Test DB2 Access
feature from the Domino Administrator client.
17. Map the DB2 user name to a Notes user name.

You are now ready to create views.

Chapter 5. Setting up Domino and DB2 149

Installing and setting up Domino and DB2 on Microsoft Windows -
Remote configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For Microsoft
Windows platforms, use NDB2KEY.DLL. Add the DB2 key to the default Domino Program directory,
C:\Program Files\Lotus\Domino. For more information about the DB2 key, contact your IBM
representative.

Complete this procedure to set up a new Domino and DB2 environment on Microsoft Windows. This is
not a procedure for upgrading an existing Domino and DB2 configuration.

Procedure
1. Install and set up the Domino server and the Domino Administrator. For instructions, see Chapters 1
- 3 of Administering the Domino System, or see the Domino Administrator 7 Help.
2. When you start the Domino server, you are prompted to specify whether to run Domino as an
application or a Windows service. Choose application.
3. Create an installation user account.
4. Install DB2 on Microsoft Windows.
5. Create a DB2 administrator account.
6. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be turned on in Domino.
Linear, circular or archival transaction logging may be used. DB2 enabled Notes databases do not
work if transaction logging is not enabled.
7. Install the DB2 Run Time Client on the same system as the Domino server.
8. Enable the Domino server to communicate with the DB2 server.
9. After Domino creates the initial DB2 database, stop the Domino server.
10. Determine whether your DB2 configuration already has a SYSCTRL group by entering this command
from the DB2 Command Line Processor (CLP):
GET DBM CFG
11. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
12. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START
13. Restart the Domino server and the Domino Administrator.
14. Map the DB2 user names to Notes user names.

You are now ready to create views.

Installing and setting up Domino and DB2 on IBM AIX - Local

configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For IBM AIX
platforms, use libdb2key_r.a. Add the DB2 key to the default Domino Program directory, /opt/lotus/ibm.
For more information about the DB2 key, contact your IBM representative.

Complete this procedure to set up a new Domino and DB2 environment on IBM AIX. This is not a
procedure for upgrading an existing Domino and DB2 configuration.

150 Lotus Domino Administrator 7 Help

Note: When you create file systems on IBM AIX, enable the large file option. For more information, see
the subtopic ″Enabling large files″ in the topic ″AIX operating system tuning″ in the Tivoli Software
Information Center.

Note: Only 64-bit Instances are supported on AIX.

Prerequisite
v The SYSADMIN_GROUP must contain the user ″root.″
v Swap space should equal or exceed physical RAM. For example, if you have 8 GB RAM, you must
have at least 8 GB of swap space.

Procedure
1. Install and set up the Domino server. For instructions, see Chapters 1 - 3 of Administering the Domino
System, or see the Domino Administrator 7 Help.
2. Start the Domino server.
3. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be turned on in Domino.
Linear, circular or archival transaction logging may be used. DB2 enabled Notes databases do not
work if transaction logging is not enabled.
4. Stop the Domino server.
5. Install DB2 on IBM AIX.
6. From the AIX OS or from the AIX administrator tool, create these three primary groups:

Note: You are creating a group for each of the three users listed in Step 10.
v DAS user group. For example, use group name db2asgrp.
v Fenced user group for the user who owns the DB2 Access server. For example, use the group
name db2fadm1.
v Instance owner account group. For example, use the group name db2iadm1.
7. Determine whether your DB2 configuration already has a SYSCTRL_GROUP. From the DB2
Command Line Processor (CLP) enter the command:
GET DBM CFG
8. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If you do not have a
group with SYSCTRL_GROUP access, create a group named DB2DOM. You will be designating
DB2DOM as a DB2 SYSCTRL_GROUP later during this procedure.
9. Add the Domino user account to the DB2DOM group or to whatever group you have designated as
a SYSCTRL_GROUP.
10. From the AIX OS or from the AIX administrator tool, create these three user accounts and then add
the user to the corresponding group you created in Step 6.
v DB2 instance owner -- When you create this account, it is automatically created in the home
directory.
v Fenced -- DB2 Fenced User runs user-defined functions (DB2 Access) and stores procedures
outside of the address space used by the DB2 database.
v DAS account -- DAS account runs the DB2 server on your system.
11. You now have the following users and groups set up:

Required user Example user name Example primary group name

Instance owner db2inst1 db2iadm1
Fenced user db2fenc1 db2fadm1
DB2 administration server user db2as db2asgrp

Chapter 5. Setting up Domino and DB2 151

12. From the AIX OS or from the AIX administrator tool, assign secondary groups to the users you
created as follows:

User name Primary group Secondary groups

db2inst1 db2iadm1 Db2asgrp, db2dom
db2fenc1 db2fadm1 db2dom
db2as db2asgrp Db2iadm1, db2dom

13. Restart the Domino server and the Domino Administrator client.
14. On the DB2 server, log in using the instance owner user account name and password.
15. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
16. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START
17. From the Domino Administrator, run the DB2 Server Enablement Tool to enable the Domino server
to communicate with DB2.
18. Complete the AIX post-installation procedure.

Installing and setting up Domino and DB2 and the DB2 Access server
on Microsoft Windows - Remote configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For Microsoft
Windows platforms, use NDB2KEY.DLL. Add the DB2 key to the default Domino Program directory,
C:\Program Files\Lotus\Domino. For more information about the DB2 key, contact your IBM
representative.

Complete this procedure to set up a new Domino and DB2 environment on Microsoft Windows. This is
not a procedure for upgrading an existing Domino and DB2 configuration.

Procedure
1. Install and set up the Domino server and the Domino Administrator. For instructions, see Chapters 1
- 3 of Administering the Domino System, or see the Domino Administrator 7 Help.
2. When you start the Domino server, you are prompted to specify whether to run Domino as an
application or a Windows service. Choose application.
3. Create an installation user account.
4. Install the DB2 server on Microsoft Windows.
5. Create the DB2 administrator account.
6. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be turned on in Domino.
Linear, circular or archival transaction logging may be used. DB2 enabled Notes databases do not
work if transaction logging is not enabled.
7. Install the DB2 Run-Time Client on the same system as the Domino server.
8. Create a server ID for the DB2 Access server.
9. Install the DB2 Access server on the server running DB2.
10. Enable the Domino server to communicate with the DB2 server available in the Domino
Administrator.
11. After Domino has created the initial DB2 database, stop the Domino server.

152 Lotus Domino Administrator 7 Help

12. Determine whether your DB2 configurations already has a SYSCTRL group by entering this
command from the DB2 Command Line Processor (CLP):
GET DBM CFG
13. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
14. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START
15. Restart the Domino server and the Domino Administrator.
16. From the Domino server console, enter
DB2 ACCESS SET
17. To verify that the DB2 Access server is installed and configured properly, use the Test DB2 Access
feature from the Domino Administrator client.
18. Map the DB2 user name to a Notes user name.

You are now ready to create views.

Installing and setting up Domino and DB2 on IBM AIX - Remote

configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For IBM AIX
platforms, use libdb2key_r.a. Add the DB2 key to the default Domino Program directory, /opt/lotus/ibm.
For more information about the DB2 key, contact your IBM representative.

Complete this procedure to set up a new Domino and DB2 environment on IBM AIX. This is not a
procedure for upgrading an existing Domino and DB2 configuration.

When you create file systems on IBM AIX, enable the large file option. For more information, see the
subtopic ″Enabling large files″ in the topic ″AIX operating system tuning″ in the Tivoli Software
Information Center.

Note: Only 64-bit Instances are supported on AIX.

Prerequisite
v The SYSADMIN_GROUP must contain the user ″root.″
v Swap space should equal or exceed physical RAM. For example, if you have 8 GB RAM, you must
have at least 8 GB of swap space.

Procedure
1. Install and set up the Domino server. For instructions, see Chapters 1 - 3 of Administering the Domino
System, or see the Domino Administrator 7 Help.
2. Start the Domino server.
3. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be enabled in Domino. Linear,
circular or archival transaction logging may be used. DB2 enabled Notes databases do not work if
transaction logging is not enabled.
4. Stop the Domino server.
5. Install DB2 on IBM AIX.
6. From the AIX OS or from the AIX administrator tool, create these three primary groups:

Chapter 5. Setting up Domino and DB2 153

 Note: You are creating a group for each of the three users listed in Step 10.
v DAS user group. For example, use group name db2asgrp.
v Fenced user group for the user who owns the DB2 Access server. For example, use the group
name db2fadm1.
v Instance owner account group. For example, use the group name db2iadm1.
7. Determine whether your DB2 configuration already has a SYSCTRL_GROUP. From the DB2
Command Line Processor (CLP) enter the command:
GET DBM CFG
8. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If you do not already
have a group with SYSCTRL_GROUP access, create a group named DB2DOM. You will be
designating DB2DOM as a DB2 SYSCTRL_GROUP later during this procedure.
9. Add the Domino user account to the DB2DOM group or to whatever group you have designated as
a SYSCTRL_GROUP.

Note: In a remote configuration, the Domino user account can be the same ID as the Instance
owner’s user ID.
10. From the AIX OS or from the AIX administrator tool, create these three user accounts and then add
the user to the corresponding group you created in Step 6.
v DB2 instance owner -- When you create this account, it is automatically created in the home
directory.
v Fenced -- DB2 Fenced User runs user-defined functions (DB2 Access) and stores procedures
outside of the address space used by the DB2 database.
v DAS account -- DAS account runs the DB2 server on your system.
11. You now have the following users and groups set up:

Required user Example user name Example primary group name

Instance owner db2inst1 db2iadm1
Fenced user db2fenc1 db2fadm1
DB2 administration server user db2as db2asgrp

12. From the AIX OS or from the AIX administrator tool, assign secondary groups to the users you
created as follows:

User name Primary group Secondary groups

db2inst1 db2iadm1 Db2asgrp, db2dom
db2fenc1 db2fadm1 db2dom
db2as db2asgrp Db2iadm1, db2dom

13. Install the DB2 Run-Time Client on the same system as the Domino server.
14. Restart the Domino server and the Domino Administrator client.
15. On the DB2 server, log in using the instance owner user account name and password.
16. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not already have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by
entering this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
17. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START

154 Lotus Domino Administrator 7 Help

18. From the Domino Administrator, run the DB2 Server Enablement Tool to enable the Domino server
to communicate with DB2.
19. Complete the AIX post-installation procedure.

Installing and setting up Domino and DB2 and the DB2 Access server
on IBM AIX -- Remote configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For IBM AIX
platforms, use libdb2key_r.a. Add the DB2 key to the default Domino Program directory, /opt/lotus/ibm.
For more information about the DB2 key, contact your IBM representative.

Complete this procedure to set up a new Domino and DB2 environment on IBM AIX. This is not a
procedure for upgrading an existing Domino and DB2 configuration.

On IBM AIX, the Domino server’s installation process checks for the proper configuration of the Input
Output Completion Protocol (IOCP). IOCP must be installed on AIX systems on which the DB2 Access
server is installed. If Domino has not been installed on the computer where the DB2 Access server is to
be installed, you must manually verify that IOCP is installed and enabled prior to installing the DB2
Access server.

When you create file systems on IBM AIX, enable the large file option. For more information, see the
subtopic ″Enabling large files″ in the topic ″AIX operating system tuning″ in the Tivoli Software
Information Center.

Note: Only 64-bit Instances are supported on AIX.

Prerequisite
v The SYSADMIN_GROUP must contain the user ″root.″
v Swap space should equal or exceed physical RAM. For example, if you have 8 GB RAM, you must
have at least 8 GB of swap space.

Procedure
1. Install and set up the Domino server. For instructions, see Chapters 1 - 3 of Administering the Domino
System, or see the Domino Administrator 7 Help.
2. Start the Domino server.
3. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be enabled in Domino. Linear,
circular or archival transaction logging may be used. DB2 enabled Notes databases do not work if
transaction logging is not enabled.
4. Stop the Domino server.
5. Install DB2 on IBM AIX.
6. From the AIX OS or from the AIX administrator tool, create these three primary groups:

Note: You are creating a group for each of the three users listed in Step 10.
v DAS user group. For example, use group name db2asgrp.
v Fenced user group for the user who owns the DB2 Access server. For example, use the group
name db2fadm1.
v Instance owner account group. For example, use the group name db2iadm1.
7. Determine whether your DB2 configuration already has a SYSCTRL_GROUP. From the DB2
Command Line Processor (CLP) enter the command:
GET DBM CFG

Chapter 5. Setting up Domino and DB2 155

 8. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If you do not already
have a group with SYSCTRL_GROUP access, create a group named DB2DOM. You will be
designating DB2DOM as a DB2 SYSCTRL_GROUP later during this procedure.
9. Add the Domino user account to the DB2DOM group or to whatever group you have designated as
a SYSCTRL_GROUP.

Note: In a remote configuration, the Domino user account can be the same ID as the Instance
owner’s user ID.
10. From the AIX OS or from the AIX administrator tool, create these three user accounts and then add
the user to the corresponding group you created in Step 6.
v DB2 instance owner -- When you create this account, it is automatically created in the home
directory.
v Fenced -- DB2 Fenced User runs user-defined functions (DB2 Access server) and stores procedures
outside of the address space used by the DB2 database.
v DAS account -- DAS account runs the DB2 server on your system.
11. You now have the following users and groups set up:

Required user Example user name Example primary group name

Instance owner db2inst1 db2iadm1
Fenced user db2fenc1 db2fadm1
DB2 administration server user db2as db2asgrp

12. From the AIX OS or from the AIX administrator tool, assign secondary groups to the users you
created as follows:

User name Primary group Secondary groups

db2inst1 db2iadm1 Db2asgrp, db2dom
db2fenc1 db2fadm1 db2dom
db2as db2asgrp Db2iadm1, db2dom

13. Install the DB2 Run-Time Client on the same system as the Domino server.
14. Restart the Domino server and the Domino Administrator client.
15. Install IOCP on the same server on which you will install the DB2 Access server.
16. Create a server ID for the DB2 Access server
17. Install the DB2 Access server on the server running DB2.
18. On the DB2 server, log in using the Instance owner user account name and password.
19. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
20. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START
21. From the Domino Administrator, run the DB2 Server Enablement Tool to enable the Domino server
to communicate with DB2.
22. Complete the AIX post-installation procedure.

156 Lotus Domino Administrator 7 Help

Setting up DB2 on Microsoft Windows
During DB2 server setup, Domino’s administration process updates the Server document and the
NOTES.INI file with information that you provide. DB2 installation creates the DB2 database but does not
include any DB2 configuration, such as creating accounts, which is done separately. For more information
about the DB2 key, contact your IBM representative.

Before you run the DB2 Setup wizard, set up one user account at the operating system level that you will
use to install DB2. This DB2 installation user account must have Administrator rights and must adhere to
the DB2 naming rules.

For information about the DB2 installation account, see Creating the DB2 installation account.

Transaction Logging
As previously mentioned, transaction logging must be enabled on the Domino server before you install
DB2. Ensure that you have enabled transaction logging. On the Server document on which you enable
transaction logging, set the Log file size to at least 192 MB.

Setting up DB2 on Microsoft Windows

Follow these steps to set up DB2 on Microsoft Windows systems.
1. Run SETUP.EXE.
2. Click Install Product.
3. Choose DB2 UDB Enterprise Server Edition.
4. Click Next. The DB2 Setup wizard runs.
5. Make these selections:
v Select the Typical installation option unless you wish to add additional DB2 features.
v Select the default DB2 administrator name unless you are using other naming standards.
v Set up an Administration Contact List. Create a Local contact list on the system unless you are
using remote notification.
v Enter the host name of your Domino server in the Notification SMTP Server field unless you have
another SMTP server that you are using. This assumes that your Domino server is running SMTP.
v Accept the default settings to configure DB2 instances. Keep a record of the instance name, as it is
required to configure Domino to work with DB2.
v You do not need to prepare the DB2 Tools Catalog.
v You are not required to specify a contact for Health Monitor Notification, but you may choose to
enter the name and Internet e-mail address of your DB2 Administrator.

Installing and setting up Domino and DB2 and the DB2 Access server
on IBM AIX -- Local configuration
To enable Domino 7 with DB2, use the ″DB2 key″ that allows access to Domino 7 with DB2. For IBM AIX
platforms, use libdb2key_r.a. Add the DB2 key to the default Domino Program directory, /opt/lotus/ibm.
For more information about the DB2 key, contact your IBM representative.

Complete this procedure to set up a new Domino and DB2 environment on IBM AIX. This is not a
procedure for upgrading an existing Domino and DB2 configuration.

On IBM AIX, the Domino server’s installation process checks for the proper configuration of the Input
Output Completion Protocol (IOCP). IOCP must be installed on AIX systems on which the DB2 Access
server is installed. If Domino has not been installed on the computer where the DB2 Access server is to
be installed, you must manually verify that IOCP is installed and enabled prior to installing the DB2
Access server.

Chapter 5. Setting up Domino and DB2 157

When you create file systems on IBM AIX, enable the large file option. For more information, see the
subtopic ″Enabling large files″ in the topic ″AIX operating system tuning″ in the Tivoli Software
Information Center.

Note: Only 64-bit Instances are supported on AIX.

Prerequisite
v The SYSADMIN_GROUP must contain the user ″root.″
v Swap space should equal or exceed physical RAM. For example, if you have 8 GB RAM, you must
have at least 8 GB of swap space.

Procedure
1. Install and set up the Domino server. For instructions, see Chapters 1 - 3 of Administering the Domino
System, or see the Domino Administrator 7 Help.
2. Start the Domino server.
3. On the Domino server, permanently enable transaction logging.

Note: To use a DB2 enabled Notes database, transaction logging must be turned on in Domino.
Linear, circular or archival transaction logging may be used. DB2 enabled Notes databases do not
work if transaction logging is not enabled.
4. Stop the Domino server.
5. Install DB2 on IBM AIX.
6. From the AIX OS or from the AIX administrator tool, create these three primary groups:

Note: You are creating a group for each of the three users listed in Step 10.
v DAS user group. For example, use group name db2asgrp.
v Fenced user group for the user who owns the DB2 Access server. For example, use the group
name db2fadm1.
v Instance owner account group. For example, use the group name db2iadm1.
7. Determine whether your DB2 configuration already has a SYSCTRL_GROUP. From the DB2
Command Line Processor (CLP) enter the command:
GET DBM CFG
8. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If you do not already
have a group with SYSCTRL_GROUP access, create a group named DB2DOM. You will be
designating DB2DOM as a DB2 SYSCTRL_GROUP later during this procedure.
9. Add the Domino user account to the DB2DOM group or to whatever group you have designated as
a SYSCTRL_GROUP.
10. From the AIX OS or from the AIX administrator tool, create these three user accounts and then add
the user to the corresponding group you created in Step 6.
v DB2 instance owner -- When you create this account, it is automatically created in the home
directory.
v Fenced -- DB2 Fenced User runs user-defined functions (DB2 Access) and stores procedures
outside of the address space used by the DB2 database.
v DAS account -- DAS account runs the DB2 server on your system.
11. You now have the following users and groups set up:

Required user Example user name Example primary group name

Instance owner db2inst1 db2iadm1
Fenced user db2fenc1 db2fadm1
DB2 administration server user db2as db2asgrp

158 Lotus Domino Administrator 7 Help

12. From the AIX OS or from the AIX administrator tool, assign secondary groups to the users you
created as follows:

User name Primary group Secondary groups

db2inst1 db2iadm1 Db2asgrp, db2dom
db2fenc1 db2fadm1 db2dom
db2as db2asgrp Db2iadm1, db2dom

13. Log on as Domino server administrator, in the UNIX shell used to start the Domino server, set the
DB2INSTANCE parameter as shown in these examples below for ksh and csh.

ksh csh
export DB2INSTANCE=<db2instancename> setting DB2INSTANCE <db2instancename>

14. Restart the Domino server and the Domino Administrator client.
15. Create a server ID for the DB2 Access server .
16. Install the DB2 Access server on the server running DB2.
17. On the DB2 server, log in using the instance owner user account name and password.
18. If your DB2 configuration has a SYSCTRL_GROUP, you can omit this step. If your DB2 configuration
does not have a SYSCTRL_GROUP, set up DB2DOM as the SYSCTRL_GROUP in DB2 by entering
this command from the DB2 CLP:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
19. Update the DB2 configuration by entering these commands from the CLP window:
DB2STOP
DB2START
20. From the Domino Administrator, run the DB2 Server Enablement Tool to enable the Domino server
to communicate with DB2.
21. Complete the AIX post-installation procedure.

Installing DB2 on IBM AIX

Note: Only 64-bit Instances are supported on AIX.

Installing DB2 8.2.2

1. Locate the file ese.dbcs.tar.Z.
2. Uncompress ese.dbcs.tar.Z, and then tar -xvf ese.dbcs.tar.
3. Log in as root.
4. From the ese.dbcs directory, run db2setup.
5. Install these options:
v DB2 UDB Enterprise Server Edition
v DB2 Application Development Client
v DB2 Administration Client
6. Enter the name of the DAS user that you created. (You created a DAS user account when you
created users and groups when installing Domino and DB2 on IBM AIX.)
7. Create a DB2 instance on a 64-bit single partition server. Make the DB2 instance owner account the
owner of the DB2 instance.
8. Enter the DB2 Fenced user account name.
9. When you have completed entering the requested information, click Finish.
10. From the DB2 CLP, assign the proper privileges to the DB2DOM group by entering:

Chapter 5. Setting up Domino and DB2 159

 Db2 update dbm cfg using SYSCTRL_GROUP db2dom

Verify that your DB2 setup on IBM AIX is correct

1. Log in as db2inst1.
2. Enter DB2.
3. At the command line processor (CLP), type this command to create a test database:
Db2 create db test
4. Type these commands to display a list of DB2 databases:
Db2 list db directory
Db2 connect to test
Db2 connect reset

IBM AIX post-installation procedure

After you install and set up Domino and DB2 on IBM AIX, complete one of these post-installation
procedures according to whether you are using the ksh or csh command line interface.

Resetting the environment variable using the command line window ksh
1. On the Domino server, log in as the Domino user who will start the Domino server, and then type
this command to identify the DB2 instance you are using:
export DB2INSTANCE=db2instancename
2. Log in as the Domino user, and then change to the data directory. Start the Domino server by typing:
server
At server startup, this message displays indicating that a number of connections are pre-allocated. The
lowest possible number of connections is four, but the value may be greater depending on what is
necessary.
DB2 Connection pre-allocation complete, Available Count =<number>
3. Logged in as the Domino user, stop the Domino server by entering this command from the Domino
server console:
exit
4. As the instance owner, stop and restart the DB2 instance, by entering these commands:
db2stop
db2start
5. Logged in as the Domino user, start the Domino server.

Resetting the environment variable using the command line window csh
1. On the Domino server, log in as the Domino user who will start the Domino server, and then type
this command to identify the DB2 instance you are using:
setenv DB2INSTANCE=db2instancename
2. Log in as the Domino user, and then change to the data directory. Start the Domino server by typing:
server
At server startup, this message displays indicating that a number of connections are pre-allocated. The
lowest possible number of connections is four, but the value may be greater depending on what is
necessary.
DB2 Connection pre-allocation complete, Available Count =<number>
3. Logged in as the Domino user, stop the Domino server by entering this command from the Domino
server console:
exit
4. As the instance owner, stop and restart the DB2 instance, by entering these commands:
db2stop
db2start

160 Lotus Domino Administrator 7 Help

5. Logged in as the Domino user, start the Domino server.

Creating a server ID for the DB2 Access server

Note: You only need to register a server and create a new server ID if you will be using the DB2 Access
server. If you will be using DB2 Access Views (DAVs) and enabling the Domino server to communicate
with DB2, you need to perform this procedure and you also need to install and use the DB2 Access
server.

Before installing a DB2 Access server on the DB2 server, you need a server ID saved to a file. Use this
server ID when you install the DB2 Access server. When you are registering a new server, be sure to
select the DB2 Server access check box to create a server ID specifically for the DB2 Access server. When
you use the DB2 Access Server option, the server ID is automatically saved to a file. When you create the
server ID, do not assign a password to the ID. Be sure to make note of the server ID path and file name,
because you are required to enter this information when installing the DB2 Access server.
1. From the Domino Administrator, click the Configuration tab.
2. From the Tools pane, click Registration - Server.
3. From the Domino Administrator, do one of the following:
a. To use the CA process, click Server, and then select a server that has the Domino Directory that
contains the Certificate Authority records and the copy of the Administration Requests database
(ADMIN4.NSF) that will be updated with the request for the new certificate. Then click ″Use the
CA Process,″ select a CA-configured certifier from the list, and click OK.
b. To provide the certifier ID, select the registration server. Then click ″Certifier ID″ and locate the
certifier ID file. Click OK, enter the password for the certifier ID, and click OK.
4. In the Register Servers dialog box, complete these fields and then click Continue:

Field Action
Registration Server Click Registration to specify the registration server, and then click OK.
Certifier If the certifier ID displayed is NOT the one you want to use for all servers registered in
this session, or if you want to use the Domino server-based CA instead of a certifier ID,
click Certifier and return to Step 4.
Certificate Authority Not applicable for DB2 Access server.
Public key specification Choose one:
v Compatible with all releases (630 bits)
v Compatible with Release 6 and later (1024 bits)
License type Choose North American (default) or International. In practice, there is no difference
between a North American and an International ID type.
Expiration date (Optional) Enter a date in mm-dd-yyyy format in the Certificate Expiration Date box. The
default expiration date is 100 years after the current date, minus allowances for leap
years.
Certificate Authority Accept the default of None Available.

5. On the Basics tab of the Register New Server(s) dialog box, complete these fields:

Field Action
Server name Enter the name of the new server.
Server title Enter the server title. The Configuration tab in the All Server Documents view and the
Server Title field of the Server document display this title.
Domino domain name The default domain name is usually the same as the name of the organization certifier
ID.

Chapter 5. Setting up Domino and DB2 161

Field Action
Server administrator Enter the name of the person who administers the server.
name
ID file password Do not assign a password.
Password Options Password quality scale. Not applicable for DB2 Access server.
Location for storing server Deselect the default setting ″In Domino Directory.″
ID
Select ″In File,″ and then click ″Set ID File.″ Select the name and path for the file, and
click Save. Make note of the full path because you will be required to enter it later.
Note: You can also save the server ID to the default path, Notes client...
data\ids\servers directory.

6. Click Advanced, and select the check box for ″This server is a DB2 Access server only.″
7. Click the green check box to add the server to the registration queue.

Note: The server registration queue displays the names of the servers that are ready to be registered.
To display the settings for a specific server, select the server’s name.
8. Click Register All.

Installing the DB2 Access server on the DB2 server

You only need to install the DB2 Access server if you want to make Domino data available in DB2. If you
only host NSF databases in DB2, you do not need to install the DB2 Access server. The DB2 Access server
facilitates your use of the Domino Designer view functions for DB2 by enabling Domino’s user security.

Install the DB2 Access server on the DB2 server that hosts Notes data. This can be the same computer on
which Domino is installed for a local configuration, or it may be a different computer in a remote
configuration. The DB2 Access server enforces Domino database security, such as ACLs and reader lists,
for DB2-enabled data. If the DB2 Access server is not installed properly, the DB2 Designer functions will
not be available and you will not be able to access DB2 data.

Install and enable the DB2 Access server to allow DB2 to access Domino data. The DB2 Access server
requires a server ID. Copy the server ID file that you are using for the DB2 Access server to the server on
which you are installing the DB2 Access server. If you have not completed the procedure ″Creating a
server ID for the DB2 Access server,″ do so before installing the DB2 Access server on the DB2 server.

Note: The DB2 Access server cannot cross-certify Domino servers from domains other than its own
domain.

When you install the DB2 Access server, a DB2 Access Server Connection document is created when the
Domino server is started. This DB2 Access Server Connection document connects the DB2 Access server
and a Domino server that you designate using the Domino Administrator. The DB2 Access Server
Connection document contains a configuration-only Domino Directory.

We recommend that you perform the DB2 Access server installation prior to running the DB2 Server
Enablement Tool from the Domino Administrator. If you perform the DB2 Access server installation after
running the DB2 Server Enablement Tool, you must complete Steps 3a and 3b of the procedure Installing
and setting up Domino and DB2 and the DB2 Access server on Microsoft Windows - Local configuration.

After you install the DB2 Access server, Domino changes the name of the server ID file to USER.ID and
stores the file in the data directory for the DB2 Access server.

Note: If your configuration includes the DB2 Access Server, TCPIP is the only supported port setting.
Any other configured port settings are disabled.

162 Lotus Domino Administrator 7 Help

Performing the DB2 Access server install
On Microsoft Windows systems, install the DB2 Access Server to the DB2 function directory, for example,
C:\program files\ibm\sqllib\function. There is an alternative that is not recommended. The alternative is
to install the DB2 Access server to any location, and then enter the full path for that location in the Path
environment variable.

Prerequisites
1. Gather the following information before running the setup program. While the InstallShield Wizard is
running, you will be prompted to enter:
v The name of the DB2 Access Domino server ID file and the location where the server ID file is
stored. Enter the complete server ID path with filename.
v The location where the local DB2 server is installed. The subdirectory is always SQLLIB, but you
need the complete path.
v For AIX configurations, you must be logged on as the root user to perform the installation. The root
user must be a member of the group SYSADMIN_GROUP.
v For AIX configuration, you need to know the DB2 Instance name.
v For AIX configurations, you need a temporary directory of approximately 150 megabytes.
2. Before beginning the installation process, you must have already created (registered) a new server and
retained the server ID.

Procedure
1. Run the Domino DB2 Access setup file. The InstallShield Wizard for IBM DB2 Access for Lotus
Domino runs.
2. If you are using Microsoft Windows, skip this step. On AIX only, review the log file,
DB2SETSTDOUT.LOG, to determine whether the install was successful. The log file is in the directory
that contains the DB2 Access server files. For example, in AIX the log file is in this directory:
/local/domudf/db2setstdout.log.
3. When the InstallShield Wizard completes the installation, do one of these:
v If you installed the DB2 Access server prior to running the DB2 Server Enablement tool, you are
done installing the DB2 Access server. You may now proceed to run the DB2 Server Enablement
Tool. OR
v If you installed the DB2 Access server after running the DB2 Server Enablement tool, complete
Steps a and b.
a. Ensure that the DB2 tab on the Server document contains the correct information in these fields,
and then add or modify information in those fields as necessary:
v DB2 Access server name -- Fully-qualified user name of the USER.ID file that the DB2 Access
server is using. For example, DB2AccServ/DomainName
v DB2 Access path -- On AIX configuration, the directory containing libdomudf. On Microsoft
Windows configurations, this entry is not used.
b. From the Domino server console, enter
DB2 ACCESS SET
User-defined functions are created in the DB2 database and a DB2 Access Server Connection
document is created.
4. From the Domino server console, enter this command to review the DB2 install information:
db2 info

For information about the information that is returned by the DB2 INFO command, see the topic DB2
INFO.

Chapter 5. Setting up Domino and DB2 163

Enabling the Domino server to communicate with the DB2 server
procedures
After installing Domino and DB2 and installing the DB2 Access server, complete these procedures to
enable the Domino server to communicate with the DB2 server according to whether you are using the
Domino server enablement tool, or manually enabling the Domino server.
v Enabling Domino access to a DB2 server
v Using the DB2 Server Enablement Tool
v Manually creating the Domino server user and other accounts on Microsoft Windows

When you have completed the Domino server enablement procedures, proceed to Mapping the DB2 ID to
the Domino server’s Domino Directory.

This section of the documentation also includes these topics that are related to server enablement:
v NOTES.INI variables set by the DB2 Server Enablement Tool
v Configuration variables modified during DB2 server enablement

Enabling Domino access to a DB2 server

Use the DB2 Server Enablement Tool, available from the Domino Administrator client, to automatically
enable Domino to access a DB2 server. Or, you can manually enable Domino to access a DB2 server.
When you enable a Domino server for DB2, Domino stores its Notes data in DB2. When a Notes database
is enabled for DB2, Domino creates a DB2 database schema for it, as well as a set of tables in that schema
to hold the Notes database data. The schema name is based on the NSF file name.

The DB2 Server Enablement Tool is the recommended method of enabling Domino access to a DB2
server. The DB2 Server Enablement Tool does the following:
v Checks for a valid DB2 library path and does one of these:
– On Microsoft Windows -- If a valid DB2 library path is located, the Enable Server for DB2 Based
Data dialog box displays with the focus in the field, DB2 Library Path. If a valid DB2 library path is
not located, Domino posts a message stating you must install DB2 prior to enabling the Domino
server.
– On IBM AIX -- A dialog box displays in which you can enter the default DB2 install path. If you
have not installed DB2, you must do so before proceeding.
v Inserts the DB2 user name and password in the Domino server ID.
v Checks the accuracy of the DB2 information that you entered. (If any DB2 information is incorrect, the
Enable Server for DB2-Based Data dialog box displays with the focus in the field containing the
incorrect information.) If the DB2 information is accurate, Domino does the following:
– Writes the configuration information to the NOTES.INI file.
– Populates the fields on the DB2 tab of the Server document on the administration server and
replicates the Server document back to the originating server. To allow the Server document to be
updated, the administration process must by running on all of your servers and a replication
schedule must be enabled between the administration server and the server you are enabling.

The administration process posts an administration request in the local copy of the Administration
Requests database (ADMIN4.NSF). The replicator then replicates ADMIN4.NSF to the administration
server. The administration process on the administration server processes the administration request and
updates the Server document with the new information. The replicator then replicates the changes to the
Server document on the originating server.

The Domino server user name and password are stored in the Domino server’s ID file. The Domino
server user account enables Domino to access a DB2 server. Create one Domino server user account for
each Domino server.

164 Lotus Domino Administrator 7 Help

Note: If you are using Microsoft Windows and you have already created a system control group to which
you want to add the Domino server user, add the Domino server user to that group.

After creating the Domino server user account, create a Domino server user group named DB2DOM and
add the Domino server user to that group. You must then manually define DB2DOM as a system control
group in DB2. The system control group parameter assigns system control (SYSCTRL) authority to the
group name. The Domino server user account is a member of the DB2DOM group that has SYSCTRL
authority; and as such, the Domino server user account has the right to allow Domino to access the DB2
server. The Domino server user has complete authorization over the DB2 database and its contents. This
server user acts on behalf of all Notes users.

Note: If you have a Windows user account that you want to use as the Domino server user, begin this
process with Step 3 of the procedure in the topic Manually creating the Domino server user account and
the DB2DOM group.

Activating the SYSCTRL_GROUP setting

This information applies regardless of whether you use the Server Enablement Tool or you manually
create the Domino server user and DB2DOM group. If the SYSCTRL_GROUP is set up for the first time
in DB2, stop and start the DB2 server by issuing the following commands from the DB2 Command Line
Processor (CLP):
DB2STOP
DB2START

Enabling a Domino server to communicate with a DB2 server

The DB2 Server Enablement Tool enables DB2 as a data store for Domino, which enables Domino to use
DB2. After DB2 server enablement occurs, the fact that DB2 is used as a data store is transparent to Notes
client users. Only administrators are aware of this. Notes users use Domino Notes as usual; Domino uses
DB2.

During the DB2 server enablement process, the DB2 database is created. Domino uses the administration
process to create that database, and the administration process requires that the administration server is
running. After the database is created, the default schemas, domino.catalog, and other objects are created.
Several NOTES.INI variables are automatically set by the DB2 Server Enablement Tool, using information
that you provide.

CAUTION:
The DB2 database name that you enter in this procedure is automatically stored in the NOTES.INI
variable DB2DATABASE. If you later delete or modify this value, Domino’s DB2 capabilities are
effectively disabled. The name stored in DB2DATABASE is used as the basis for the names of the
database, buffer pool, tablespaces, and schema.

In this procedure, all of the steps apply to all supported platforms unless there is a notation at the
beginning of the step that indicates it is for IBM AIX only or Microsoft Windows only. If a step does not
apply to your configuration, just omit that step and proceed to the next step.

Prerequisites
1. From the Domino Administrator, point to the server you are enabling.
2. Have this information available before you begin the procedure:
v The name of the DB2 instance that you created when you installed DB2. If you are using Microsoft
Windows, the default instance name is DB2; on AIX, it is whatever you named it.
v The Domino server account name and password. This is a user name created at the OS level that
will be used by the Domino server to access the DB2 server. This user account must have at least
SYSCTRL_GROUP access in DB2 or it must be a member of the group, DB2DOM.
v The server ID that you created for the DB2 Access server.

Chapter 5. Setting up Domino and DB2 165

 v If you are using AIX, the location where you installed the DB2 Access server. This path is used in
the DB2 Access Path field of the Server document and in one of the dialog boxes for the DB2 Server
Enablement tool. Microsoft Windows does not prompt for this information; Windows uses the
default DB2 function directory.

Procedure
1. From the Domino Administrator, click Configuration.
2. Click DB2 Server -- Enable Server for DB2.

Note: If the feature Enable Server for DB2 is not active, the Domino server is already enabled for
DB2, or you are using a pre-Domino 7 version of the Lotus Domino and Notes software, or you are
using a platform other than Microsoft Windows or IBM AIX.
3. Complete the fields on the DB2 Server tab and DB2 Access tab as follows:

Field Action
DB2 and Domino are on different systems or DB2 is If any of these conditions are true, click this check box:
64-bit on AIX server v DB2 and Domino are installed on different computers.
v 64-bit DB2 instance is used on the DB2 AIX server.
v You are using the DB2 Run-Time Client on the
Domino server.
DB2 Instance Name Enter the DB2 instance name that you created when you
installed the DB2 server.
Note: This field only applies to local configurations
using a 32-bit DB2 instance.
DB2 Datastore Directory (Optional) Enter the full path and name of the directory
where the DB2 enabled Notes databases will be stored
on the DB2 server. For example,
v In Microsoft Windows, a sample path is:
c:\db2db\srvr\
v In IBM AIX, a sample path is:
/local1/db2inst1/db2dir/

Users must have appropriate access rights for the

directory that you enter.
DB2 Database Name Enter a database name, or accept DOMINO as the
default DB2 database.
Host Name Enter the name of the remote server that will store data.
This field applies only to remote configurations.
Port Number/Service Name Enter the port number or service name for the remote
instance of DB2. This field applies only to remote
configurations.

Open the DB2 Control Center to obtain this information,

and then right click the instance to which you are
connecting. Select ″Setup Communications.″ Review the
TCP/IP properties. An example of a service name is
db2c_DB2. An example of a port number is 50000. You
can use either in this field.

166 Lotus Domino Administrator 7 Help

Field Action
DB2 Node Name This field appears only for remote configurations or if a
64-bit DB2 instance is being used on the DB2 AIX server.
Enter the DB2 node name, that is, the name assigned to
the DB2 server in the DB2 Node Directory. The node
name you enter cannot be a name that is assigned to
another entity in the DB2 configuration. For example, the
node name cannot be identical to the DB2 instance name
nor the Domino server name. The DB2 server
enablement tool uses the DB2 node name to create the
DB2 node.
By default, create databases as Choose one:
v DB2 (default) -- Creates DB2 databases.
v NSF -- Creates Domino NSF databases.
Immediately update the server’s Domino Directory with Click this check box to update the Domino Directory
DB2 information immediately instead of waiting for the administration
process to initiate the update.
Automatically restart the Domino server upon successful Click this check box to restart the server after the DB2
enablement Server Enablement Tool runs and the DB2 information is
added to the Domino Directory.

Field Action
OS account name to be used by Domino to access DB2 This user name is an operating system user account name
that Domino uses to access the DB2 server. This is a
Microsoft Windows or IBM AIX account. If you are using
IBM AIX, you can only enter an existing user account
name; you cannot create one from this dialog box.

Do one:
v Enter a new name to create the new user account. This
option applies only to Microsoft Windows.
v Enter an existing user account name if you have created
one that you want to use. It must be an OS user
account name.
DB2 Password Enter the password for the new or existing user account
name that you entered in the field ″OS account name to
be used by Domino to access DB2.″ that The Domino
server uses this password to access the DB2 server.
Verify DB2 password Reenter the password.
DB2 Access server name Enter the name of the DB2 Access server that you
registered using the Domino Administrator and that you
used for the DB2 Access server install. This server name is
used for DB2 Access Views. Domino adds the DB2 Access
name to the field, Trusted Servers, in the Server Access
section of the Security tab on the Server document for the
Domino server.

Chapter 5. Setting up Domino and DB2 167

Field Action
DB2 Access path Enter the full path to the location of the DB2 Access
server. The DB2 database uses this path to access the DB2
Access server’s DLL. For example,
C:\Program Files\IBM\DB2 Acces\ndomudf.dll

If the DB2 Access server is not installed on the same

computer as the DB2 server, the path should include the
server on which DB2 Access is installed. The DB2 server
uses this path to load the DB2 Access service.

4. Click Enable.
5. One of these occurs, according to platform:
v Microsoft Windows -- A status box displays. If there are no errors, click OK. Click Store or Continue
according to whether you want to stop the server-enablement process or continue the process.
v IBM AIX -- A series of messages appears. Review the messages, and then click Stop or Continue
according to what you want to do.
6. If you installed the DB2 Access server prior to running the DB2 Server Enablement tool, enter this
command from the Domino server console:

DB2 ACCESS SET

NOTES.INI variables set by the DB2 Server Enablement Tool

The DB2 Server Enablement Tool uses the data you entered to set the NOTES.INI values shown below.
The NOTES.INI settings are added to the NOTES.INI file the first time the server restarts after the DB2
Server Enablement Tool is run and the Server document is updated. To modify these settings, you must
use the DB2 tab in the Server document.

You can open the NOTES.INI file to view the settings established when you enabled a Domino server to
communicate with a DB2 server.

For information about the updates to the Server document, see the topic Setting and modifying DB2
values in the Server document.

NOTES.INI setting Description

DB_CREATION_DEFAULT_TYPE Displays the format used to create and store Domino
data. The default value is DB2. The default type you
specify, DB2 or NSF, displays here.
DB2DIRECTORY Stores the name of one or more directories in which
tablespaces for Domino databases are stored.
DB2INSTANCE Stores the DB2 instance name or DB2 node name you
specify for the Domino environment.
DB2DATABASE Stores the name of the DB2 database that you specify.
The default DB2 database name is Domino.
DB2INIT Displays one of these value:
v Create -- Designates that the new DB2 database, tables,
table spaces, and other DB2 objects should be created
when Domino starts.
v OK -- After the DB2 objects are created, this setting is
set to OK. For example, if you successfully create a
new DB2 enabled Notes database, this variable
displays OK.

168 Lotus Domino Administrator 7 Help

NOTES.INI setting Description
DB2UDFSERVER Stores the name of the DB2 Access server that you
installed with DB2. This server name is used for DB2
Access Views.
DB2UDFPATH Stores the full path for the location of the DB2 Access
server. The DB2 database uses this path to access the
DB2 Access server DLL.
DB2DBCODEPAGE Indicates the code page to use when creating the DB2
database. This setting is ignored after the DB2 database
is created. Do not change the default, UTF-8.
DB2_DBS_PER_SCHEMA The maximum number of DB2 enabled Notes databases
that can be stored in one DB2 group.
DB2LOCALE This NOTES.INI variable is added by the DB2 server
enablement tool if you do not use the default setting.

Configuration variables modified during DB2 server enablement

When you enable a Domino server to communicate with a DB2 server, Domino modifies the following
DB2 database manager configuration parameters for optimal performance:

Configuration parameter Value

FCM_NUM_BUFFERS 4096.00
KEEPFENCED YES
NOTIFYLEVEL 0.00
MAXAGENTS 400.00
PRIV_MEM_THRESH 32767.00
INTRA_PARALLEL OFF
MAX_QUERYDEGREE 1.00
SHEAPTHRES 40960.00
FEDERATED YES

When you enable a Domino server to communicate with an existing DB2 database, Domino modifies the
following DB2 database management configuration parameters:

Configuration parameter Value

MAXFILOP 128.00
MAXAPPLS AUTOMATIC
SORTHEAP 1024.00
DBHEAP 4096 on Microsoft Windows

20000 on IBM AIX

SHEAPTHRES_SHR 8192.00
DFT_QUERYOPT 0.00
APPLHEAPSZ 512.00
STMTHEAP 8192.00
APP_CTL_HEAP_SZ 8192.00
APPGROUP_MEM_SZ 30000.00

Chapter 5. Setting up Domino and DB2 169

Configuration parameter Value
UTIL_HEAP_SZ 5000.00
LOCKLIST 2500.00
CATALOGCACHE_SZ 512.00
MINCOMMIT 1.00
NUM_IOCLEANERS 20.00
NUM_IOSERVERS 1.00
SEQDETECT NO
LOGBUFSZ 512.00
LOGFILSIZ 131077.00
LOGPRIMARY 3.00
LOGSECOND 0.00

Manually creating the Domino server user and other accounts on

Microsoft Windows
You manually create the Domino server user and the DB2DOM group, and then add the server user to
the group. The information in this section applies to local configurations running on Microsoft Windows
systems.

Manually creating the Domino server user account and the DB2DOM group
1. Using the DB2 naming conventions to create a Microsoft Windows user account.
2. Specify a password for the new user account, and then click Create to save the user name and
password. Exit that dialog box.
3. Create a new Windows group and name it DB2DOM.
4. Add the new user to the DB2DOM group. When you click Create, the DB2DOM group is added to
the group list.

Designating the DB2DOM group a system control group

Prior to initiating this procedure, read the information in Enabling Domino access to a DB2 server and
then complete the necessary procedures.

Note: If you already have a SYSCTRL group that you want to use, you can add the Domino server user
to the existing group instead of creating a new group.
1. From the Windows desktop, choose Start - Programs - IBM DB2 - Command Line Tools - Command
Line Processor.
2. From the command line processor (CLP), enter this command to define DB2DOM as a system control
group:
Update dbm cfg using SYSCTRL_GROUP DB2DOM
This message appears: ″Completed Successfully.″
3. From the CLP, enter this command to stop the DB2 server:
db2stop
4. From the CLP, enter this command to restart the DB2 server:
db2start
5. Enter this command to exit the CLP:
Quit
6. Enter this command to close the command window:
Exit

170 Lotus Domino Administrator 7 Help

Mapping the DB2 ID to a Notes ID in the Domino server’s Domino
Directory
Note: If you are upgrading to Domino 7 from a beta release, and you have used the Set DB2 ID tool to
set up DB2 account names, upgrade the Domino Directory with the new template and then run the Set
DB2 user name tool for any user that needs access to DB2 databases.

Users must have a DB2 identity to access DB2 databases from the DB2 server. This DB2 user name (an
OS user name) must be mapped to a Notes user name. After the DB2 user name is mapped to a Notes
user name, the user’s Domino privileges are enforced, that is, the ACLs assigned to the NSF apply. If the
user’s DB2 user name is not mapped to the Domino server’s Domino Directory, the user is assigned
″Anonymous″ access to the DAV. They are then only able to view information that the Domino NSF’s
ACL allows. Although the user connects directly to DB2, access to Domino data is still managed by
Domino (in addition to DB2 GRANT privilege control). DB2 user names are used to access DB2 data.

Although a DAV makes Notes data available in DB2, Domino still enforces security on this data. To
access Notes data using SQL (for example, CLP, ODBC, and Notes Query Views), a user must have both
a DB2 user identity and a Lotus Notes identity, and the DB2 user name must be mapped to the Lotus
Notes user name in the Domino Directory of the Domino server that ″owns″ the DB2 enabled Notes
database.

The DB2 to Notes user mapping must be unique. If you map more that one Notes user to a single DB2
user name, an error is generated when you try to access the DAV using either a query view or SQL.

Use ″Set DB2 user name″ from the Tools panel in the Domino Administrator to map a DB2 (OS) user
name and a Notes user name. For instructions on using Set DB2 user name, see the topic ″Mapping DB2
user names to Notes user names.

When a DB2 user attempts to access data in a DAV, the DB2 Access server verifies with the Domino
server that the DB2 user is a known Notes user and that the Notes user has access to the NSF on which
the DAV is based. For SQL access, the DB2 user is mapped to a Notes user to check Notes ACL
privileges. It is the mapping of the DB2 user name and Notes user name that verifies that the DB2 user is
a known Notes user.

When a Notes application uses an SQL Query View to access Notes and non-Notes data stored in DB2, to
make the connection to DB2 it uses the DB2 user name that is mapped to the Notes ID of the Notes user
executing the query. In this case, the Notes user is mapped to a DB2 user to verify that the user has the
necessary GRANTS in DB2 to see the data.

If a user is only cross certified to access a DB2-enabled Domino server and that user does not have a
Person document in that server’s Domino Directory, you can use the Set DB2 User Name tool in the
Domino Administrator to set the DB2 Account name for that user.

Allowing anonymous access to Notes data

In some cases, you may not want to have ″user level″ security checks done when Notes data is accessed
in SQL. You may choose to control access to DAVs by using DB2’s GRANT mechanism instead of
mapping the DB2 user name to the Notes user name. To use DB2’s GRANT mechanism, add this setting
to the NOTES.INI file on the DB2 Access server:
ALLOW_ANONYMOUS_ACCESS_FROM_DB2=1

When this NOTES.INI setting is enabled, anonymous access to Notes is used whenever a DB2 user name
is not mapped to a Notes user name.

Chapter 5. Setting up Domino and DB2 171

Enabling anonymous access removes the name mapping requirement, but Domino still controls access to
the DAV. To use anonymous access, the Domino server must allow anonymous access and the default
access level of the NSF associated with the DAV must provide sufficient rights to perform the requested
SQL operation. For example, read permission for SELECTS, author permission for INSERTs, and so forth.

Note: Anonymous access allows you to use SQL to access Notes data without mapping users; however;
DB2 Access Views provide Notes access to DB2 data and always require a valid mapping. You cannot use
anonymous access in a Query View.

Mapping DB2 user names to Notes user names

1. From the Domino Administrator, click People and Groups.
2. Click People. Select the person for whom you are mapping a DB2 account user name to a Notes user
name.
3. Click Tools - People - Set DB2 User Name.
4. Complete these fields, and then click OK.

Field Action
Use name from network account name field, if available Click this check box if there is an existing network
account name in the Person document and you want to
use that name.

The user name should be all uppercase characters.

Default format Choose a default name format. For example, LastName
FirstName.

If ″Enter Discrete Name″ is chosen here, the Discrete

Name field displays.
Separator Choose a separator to separate the name components. For
example, an underscore character separates the first name
from the last name.

If ″Enter Custom pattern″ is selected in the ″Default

format″ field, the Separator field does not display.
Format pattern This field appears only if ″Enter Custom pattern″ is
selected in the ″Default format″ field. Enter the custom
pattern you want to use. For example, you could use
FirstInitialLastName.

To view a list of the valid characters you can use to create

a custom pattern, see the topic ″Using formulas to create
custom patterns in user names.
Discrete name This field displays if ″Enter Discrete Name″ is selected in
the Default Format field.

Make resulting name uppercase
Enter the user’s discrete name, that is, a name you enter
individually -- not a name generated by specifying a
pattern.
Choose this option if you want to display the DB2 user
name in uppercase characters.

Using formulas to create custom patterns in user names

When defining a custom pattern for creating user names, you can use the characters and symbols shown
in the table below to create the custom patterns. Enter the custom patters in the Format Pattern field of
the Set DB2 User Name dialog box.

172 Lotus Domino Administrator 7 Help

Example

For example, you can create a formula for the custom pattern of LastName followed by the underscore
character followed by the OrganizationName:

L_O

Character or Symbol Represents

F First name
L Last name
M Middle name
T Title
G Generation
O Organization name
I ID
C Location
D Department
V Server
S Short name
_ Underscore
. Dot
= Equal
% Percent

DB2 groups
Domino uses a concept called groups to manage storage in DB2. Grouping allows multiple DB2 enabled
Notes databases to share a single schema, tablespace, and table set.

When you create a DB2 enabled Notes database, it is automatically assigned to the next available DB2
group. In most cases, Domino’s management of groups is sufficient and you will not need to manage
groups in any way. But there are some circumstances in which you may want or need to manage groups.
v As used by Domino, DB2 tablespaces are limited to a maximum size of 256 GB. The default is to store
ten DB2 enabled Notes databases per group; therefore, this creates a maximum DB2 enabled Notes
database size of 25.6 GB. You may want to isolate large databases in their own groups to avoid this
limit.
v In DB2, the tablespace is the smallest unit of backup and restore; therefore, you may want to store DB2
enabled Notes databases with the same backup policy in the same group.
v Grouping similar DB2 enabled Notes databases in one group enables you to better reuse the existing
DB2 indices which can impact the length of time needed to reorganize the tablespace using Compact.

By default, ten DB2 enabled Notes databases can be associated with a DB2 group, but you can use the
″Maximum number of NSFs in group″ field on the DB2 tab of the Server document to change that value.

Each DB2 group is assigned one of the following statuses:

v Open -- The DB2 group does not yet contain the maximum number of DB2 enabled Notes databases
and is not full, and the DB2 group has not been locked by an administrator. DB2 enabled Notes

Chapter 5. Setting up Domino and DB2 173

 databases can be added or moved to any group that has a status of open. When the number of
databases added to the DB2 group reaches the maximum, the DB2 group is automatically assigned a
status of Full.
v Full -- The DB2 group contains the maximum allowed number of DB2 enabled Notes databases. No
additional databases can be added or moved to this DB2 group, unless you change the maximum
number of databases allowed in the group. If you move a database from this DB2 group to another
DB2 group, the DB2 group status will change from Full to Open.
v Locked -- An administrator has manually locked the DB2 group. The DB2 group can be locked prior to
its being associated with the maximum number of DB2 enabled Notes databases that are allowed per
DB2 group, or when the DB2 group is full. When a DB2 enabled Notes database is locked, no
additional databases can be associated with it, but a database can be moved out of a locked group into
another group.

Each DB2 group status is represented by an icon, as shown in the table.

The maximum number of DB2 enabled Notes databases is set to ten by default, in the Maximum number
of NSFs in Group field on the DB2 tab of the Server document. This value is set to ten for performance
purposes. If you change the entry to a value greater than ten, the next time a database is created, the DB2
groups will backfill until the new maximum number of DB2 enabled Notes databases per group is
reached. For example, the next DB2 enabled Notes database will be associated with GRP1 unless it is
explicitly locked. You cannot reset the maximum number of databases allowed in a DB2 group that is
locked.

DB2 group classes

Each group created in DB2 has a class property associated with it. This property can be used by users or
applications to label groups. For example, a backup vendor might label groups Nightly, Weekly, or
Manual. Domino itself makes no use of the Group Class label other than to allow sorting in the Domino
Administrator. The default DB2 class is named DEFAULT, but you can add additional classes and rename
existing classes. You can also change the name of a class associated with one or more DB2 groups, and
thereby create new classes.

The DB2 Group administration tools are enabled for DB2-enabled Domino servers only.

You can also view and sort DB2 enabled Notes databases and DB2 group information.

Note: The Group Administration user interface is not available from the Domino Web Administrator
client.

Managing DB2 groups and classes

You manage individual DB2 groups and classes from the Domino Administrator client or the Domino
server console. DB2 Group administration is performed on a per-server basis.

You can perform these procedures to manage a DB2 group or class:

v Lock a DB2 group
v Unlock a DB2 group
v Move a database to another DB2 group
v Associate a DB2 group with a DB2 class

174 Lotus Domino Administrator 7 Help

v Rename a DB2 class
v Create a new DB2 class

Locking a DB2 group

When you manually lock a DB2 group, you prevent additional databases from being added to it. If you
manually lock a DB2 group, and then remove a DB2 enabled Notes database from the group, the group
remains locked, even if the group does not contain the maximum number of DB2 enabled Notes
databases.
1. From the Domino Administrator, click the Files tab.
2. In the left panel, click DB2 Groups.
3. Select the DB2 group that you want locked.
4. Choose Tools - DB2 Groups - Lock Group.

Unlocking a DB2 group

You can unlock a DB2 group to allow additional databases to be added to a DB2 group. When you
unlock a DB2 group that is not full, the DB2 group status changes to Open. If you unlock a DB2 group
that is full, the DB2 group status changes to Full, and no additional databases can be added to that DB2
group.
1. From the Domino Administrator, click the Files tab.
2. In the left panel, click DB2 Groups.
3. Select the DB2 group you want unlocked.
4. Choose Tools - DB2 Groups - Unlock Group.

Renaming a DB2 class

You must have Administrator rights to rename a DB2 class.
1. From the Domino Administrator, click the Files tab.
2. In the left panel, click DB2 Groups.
3. Select the class that you want to rename.
4. Choose Tools - DB2 Groups - Rename Class.
5. Specify the new class name, and then click OK.

DB2 class names are not case-sensitive.

Associating a DB2 group with a class

You can associate a DB2 group with a new or existing DB2 class.
1. From the Domino Administrator, click the Files tab.
2. In the left panel, click DB2 Groups.
3. Select the DB2 group that you want to associate with a class.
4. Choose Tools - DB2 Groups - Set Class.
5. Do one of these:
v To associate a DB2 group with an existing class, type the class name, and then click Move.
v To associate a DB2 group with a new class, enter the new class name, and then click OK.

Moving a DB2 enabled Notes database to another DB2 group

You can move a DB2 enabled Notes database to a new or existing DB2 group. DB2 enabled Notes
databases can be moved to an unlocked DB2 group or to DB2 group that is not full. The log file,
LOG.NSF, stores a record of moved databases.

Chapter 5. Setting up Domino and DB2 175

You can also move a DB2 enabled Notes database from one DB2 group to another, by dragging the DB2
enabled Notes database to the new group.

You must have Administrator rights to move a DB2 enabled Notes database to another DB2 group.
1. From the Domino Administrator, click the Files tab.
2. In the left panel, choose DB2 Group Name.
3. Select the database that you want to move.
4. Choose Tools - DB2 Groups - Move to Group.
5. Do one of these:
v To move a database to an existing DB2 group, type the DB2 group name, and then click Move.
v To move a database to a new DB2 group, click the check box ″Move databasename to new group,″
and then click Move. The new group name displays in the left panel.

Note: If you attempt to move a database and all DB2 groups are full or locked, the check box ″Move
databasename″ is selected by default and the Group Name field is not active. Click Move and a new DB2
group is created for you. The selected database is then moved to the new DB2 group. The new DB2
group is automatically added to the class named DEFAULT.
6. Press F9 to display the results of the move.

Upgrading Domino 7 and DB2

Use these procedures to upgrade from a beta release of Domino 7 and DB2.

Complete the prerequisites, and then complete one of the procedures according to whether or not you
have created a DB2 database and whether it contains one or more DB2 enabled Notes databases.

Prerequisites if you are running Domino 7, beta 1, 2, or 3

If you are using Domino 7, beta release 1, 2 or 3, complete these steps:
1. Back up all DB2 enabled Notes databases to NSF storage before recreating the DB2 database.
2. When the back up of the data is complete, open the Server document - DB2 tab. Note the information
in the fields on the DB2 tab, and then close the Server document.
3. Stop the Domino server, and then verify that all server tasks have stopped.

Procedure - Upgrading when you have created DB2 enabled Notes

databases
Use this procedure if you created a DB2 database and it contains DB2 enabled Notes databases.

If you or any users are using Domino 7 beta release 1, 2 or 3 and you do not have UTF-8 encoding,
complete all of the steps in this procedure. If you are using a post beta 3 version of Domino and DB2, or
if you are sure that you are using UTF-8 encoding, omit Step 3.
1. Stop the Domino server if it is running.
2. Upgrade to Domino 7 and DB2.
3. To create a new DB2 database with the same name as the DB2 database used in the beta release,
ensure that the NOTES.INI entry, DB2INIT=, is set to DB2INIT=CREATE in the server’s NOTES.INI
file.
4. Start the Domino server. Your upgrade process is complete.

176 Lotus Domino Administrator 7 Help

Procedure - Upgrading when you have not created any DB2 enabled
Notes databases
Use this procedure if you did not create a DB2 database with DB2 enabled Notes databases.

Complete the following procedure:

v Upgrading from a beta release to Domino 7 and DB2

Upgrading from a beta release to Domino 7 and DB2

To enable the new DB2 features inside of Domino 7, use the ″DB2 key″ that allows access to Domino 7
with DB2. For Microsoft Windows platforms, use NDB2KEY.DLL; for IBM AIX platforms, use
libdb2key_r.a. Add the DB2 key to the default Domino Program directory. On Microsoft Windows, the
default Domino Program directory is C:\Program Files\Lotus\Domino; on IBM AIX, the default Domino
Program directory is /opt/ibm/lotus/notes/latest/ibmpow. For more information about the DB2 key,
contact your IBM representative.

Complete this procedure to upgrade a beta release of Domino and DB2 to Domino 7 and DB2.

Note: It is imperative that when you upgrade to Domino 7, you also upgrade the DB2 Access server. The
DB2 Access server upgrade should be done at the same time as the update to the Domino server(s)
supported by those DB2 Access servers.

Installing Domino 7 and DB2 over a beta release

If you or any users are using Domino 7 beta release 1, 2 or 3 and you do not have UTF-8 encoding,
complete all of the steps in this procedure. If you are using a post beta 3 version of Domino and DB2, or
if you are sure that you are using UTF-8 encoding, only complete Steps 6 and 7.
1. Back up all DB2 enabled Notes databases to NSF storage and recreate the DB2 database unless it is
encoded as UTF-8. This is necessary because the code page of a DB2 database is set when it is created
and cannot be changed.
2. When the back up of the data is complete, open the Server document - DB2 tab. Take note of the
information in the fields on the DB2 tab and then close the Server document.
3. From the DB2 Command Line Processor, disable DB2 capabilities on the Domino server by typing:
DB2 Stop

Note: The command, DB2 Stop, is not available for post beta 3 releases of Domino and DB2.
4. Shut down the Domino server, and then verify that all server tasks have completed.
5. Drop the existing DB2 database by entering this command from the DB2 CLP:
drop database <DBname>
6. Upgrade your DB2 server to DB2 8.2.2 version by installing the newer DB2 release over your older,
existing version.
7. Install the new Domino server and Domino Administrator over your existing beta install.

Upgrading the DB2 Access server

1. Uninstall the previously-installed version of the DB2 Access server.
2. (Microsoft Windows) Delete the DB2 Access server path and filename from the Path system variables
field on the Environment Variables dialog box. To access the dialog box from the Control Panel, click
System - Advanced tab - Environment Variables.
3. Complete Step 1 through Step 6 of the procedure to install the DB2 Access server on the server
running DB2. DB2 Access creates a configuration-only Domino Directory on the DB2 server. See the
topic ″Installing the DB2 Access server on the DB2 server″ in the Domino Administrator 7.0
documentation.

Chapter 5. Setting up Domino and DB2 177

 Note: In Step 4, you perform the server enablement procedure. You will need to use the information
that you manually noted from the Server document - DB2 tab when you upgraded to the Domino 7
and DB2 release.
4. Complete the procedure to enable the Domino server to communicate with the DB2 server. See the
topic ″Enabling a Domino server to communicate with a DB2 server″ in the Domino Administrator 7.0
documentation.
5. Start the Domino server.
6. Complete this step after you have installed the new Domino 7 server and entered Yes when prompted
to upgrade the Domino Directory. If you mapped any Notes user names and DB2 user names while
using the Domino and DB2 beta software, and you are upgrading from a beta release, remap those
users. Complete the procedure to map Notes user names and DB2 user names. See the topic
″Mapping DB2 user names to Notes user names″ in the Domino Administrator 7.0 documentation.
Map all users who will be utilizing DAVs and QVs.
7. Recreate the DB2 enabled Notes databases from your NSF backups as required.
8. Rebuild your DAVs. Any DB2 enabled Notes databases that were backed up locally and restored to
this new database and that contained DAVs can still be used. (From Domino Designer, run
Create/Update in DB2 and Populate in DB2 for each DAV. See the Domino Designer documentation
for instructions.)

Converting a 32-bit instance to a 64-bit instance on IBM AIX

The information in this topic applies to DB2 8.2.2. If you are using a different version of DB2, see the DB2
Information Center documentation for the most current information. See the chapter Installing - Database
Sections - Uninstalling - DB2 Universal Database (Linux and UNIX) - Removing DB2 FixPaks.

The information in this topic does not apply to Linux.

Note: You cannot revert to a Version 7, 32-bit instance after you have migrated to a Version 8, 64-bit
instance.

To migrate from a DB2 Version 7 database to a DB2 Version 8, 64-bit system:

1. Install DB2 Version 8 on your 64-bit machine. Do not uninstall the previous version.
2. As the instance owner, run this command to ensure that your database can be migrated:
DB2DIR/bin/db2ckmig
3. Back up your existing DB2 Version 7 database.
4. Stop your DB2 Version 7 instance.
5. Run this command
DB2DIR/instance/db2imigr <instance_name>
6. Migrate your databases.
7. If your existing database is within a DB2 Version 7, 32-bit instance on your 64-bit machine, update the
instance to a 64-bit instance. To update your Version 7, 32-bit instance to a Version 7, 64-bit instance,
enter this command:
db2iupdt
For example, when specifying the -w parameter with a value of 64, you would enter:
DB2DIR/instance/db2iupdt -w 64 db2inst
where DB2DIR represents the DB2 Version 8 installation path on the appropriate platform.
8. Restart your DB2 instance.

178 Lotus Domino Administrator 7 Help

Upgrading to DB2 8.2.2 if you have a previous version of DB2 already
installed
Use this procedure if you have a version of DB2, other than DB2 8.2.2, already installed. All of the
commands in this procedure are UNIX-specific.

Prerequisites
1. Complete these tasks before installing DB2 8.2.2:
v Read the Known Problems and Workaround section of the Readme file.
v Ensure that all DB2 processes are stopped.
2. To switch to the root authority, type this command:
su - root

Procedures
1. For each DB2 instance, type these commands:

Note: If you are using hacmp, use the ha_db2stop command instead of db2stop, because db2stop will
trigger a failure event.
su - instancename # instancename represents the name of the instance you created
. $HOME/sqllib/db2profile
db2 force applications all
db2 terminate
db2stop
db2licd -end # run at each physical node
Exit
2. Type these commands:
su - dasownername
. $HOME/das/dasprofile
db2admin stop
Exit
3. Run slibclean to unload unused shared libraries from memory:
/usr/sbin/slibclean
4. Stop all instances, including the Fault Monitor, that are using DB2 version 8.
5. Locate the file fixpak ###.tar.Z. (Where ### refers to the number for DB2 8.2.2, FixPak 9)
6. Uncompress fixpak. ###.tar.Z, and then tar -xvf .fixpak ###tar.
7. Change directory to fixpak ### .
8. Log in as root, and then run installFixPak.
9. Log in as root, and then type this command to update all instances:
INSTHOME/instance/db2iupdt iname
v Where INSTHOME is the installation directory appropriate to your operating system
v Where INAME represents the instance name

Note: If the database administrator server instance exists and is a DB2 8 DAS instance, run this
command to update the DAS instance:
INSTHOME/instance/dasupdt dasname
v Where DASNAME is the DAS owner name
v Where INSTHOME is the installation directory
1010. 10. For each instance, log in as the instance owner and then enter the db2start command to restart each
instance.

Chapter 5. Setting up Domino and DB2 179

11. Log in as the DAS owner, and then run this command to restart the administration server:
db2admin start

Maintaining the Domino and DB2 environment

Use these procedures to administer your Domino and DB2 environment.
v Validating DB2 user names
v Setting, modifying or deleting the Domino server user’s DB2 ID properties
v Setting and modifying DB2 values in the Server document
v Setting a DB2 server ID
v Setting DB2 Log File Size
v Domino and DB2 XA transaction services
v Replicating an NSF to DB2
v Working with views in Domino and DB2
v Copying a DB2 enabled Notes database to another server
v Administering the DB2 Access server

Adjusting buffer pool size

If you are running a DB2-enabled Domino server, where almost all data is in DB2, and Domino and DB2
are installed on the same computer, you can improve performance by using a NOTES.INI variable to
reduce the size of the Domino buffer pool.

Use the NOTES.INI setting, NSF_BUFFER_POOL_SIZE_MB= to adjust buffer pool size. For example,
NSF_BUFFER_POOL_SIZE_MB=128

When using a DB2-enabled Domino server, most data is in DB2; therefore, less memory is required for
Domino’s buffer pool and more memory is required for DB2’s several buffer pools.

Adjust buffer pool size according to the amount of memory on your computer.
v The minimum amount of memory is 512KB -- nothing smaller. A machine with less than 1GB memory
may not work well.
v Reduce buffer pool settings by half for large buffer pools, but leave small buffer pool settings as they
are.
v Double the size of the large buffer pools if you have 2GB - 4GB memory.

If you are using the algorithm for R5, and Domino 7 and DB2 reside on the same computer, set
NSF_BUFFER_POOL_SIZE_MB to a value less than the value suggested by the R5 algorithm. For
example, if the algorithm suggests 200MB, try using 128MB. The exact adjustment depends on the exact
mix of NSF and DB2 enabled Notes databases. If you use very few NSFs, try further reducing the buffer
pool.

Copying a DB2 enabled Notes database to another DB2 enabled

Domino server
You can copy a DB2 enabled Notes database from one DB2 enabled Domino server to another. To do so,
you must create a local copy of the database from the DB2 enabled Domino server and then use the
menu options File - Database - New Copy to copy the database.

Creating a local copy of the database

v Copy the database from the DB2 enabled Domino server to one of the clients.

180 Lotus Domino Administrator 7 Help

Copying a local copy of a database to a DB2 enabled Domino server
1. From the Notes client, open the database you are going to copy.
2. Choose File - Database - New Copy.
3. Next to Server, click the arrow to display a list of servers. Select the DB2 enabled Domino server on
which you want to place the copy.
4. Next to Title, enter a title for the database. The database icon and the Open Database dialog box
display this title.
5. Next to File Name, enter the path and file name of the database.
6. Choose one:
v ″Database design and documents″ to copy the database design and all documents
v ″Database design only″ if you do not want to copy any existing documents
7. Complete these optional steps as necessary:
v 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.
v Select ″Create Full Text index″ to create a full-text index on the new database copy.

Note: You can also create a full-text index later.

v Choose ″Encryption″ to encrypt the new copy of the database.
The encryption 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.

Domino and DB2 XA transaction services

Domino uses DB2’s XA transaction services, but changes a default participation assumption. Domino
add-in developers need to be aware of this change.

When a process starts using XA with DB2, all subsequent new connections are usually created using the
assumption that the new connections will be participating in XA operations unless the
SQL_ATTR_HANDLE_XA_ASSOCIATED connection attribute is explicitly set to FALSE to opt-out of XA.
Setting the attribute SQL_ATTR_HANDLE_XA_ASSOCIATED to FALSE breaks any legacy DB2 calls that
the process makes that did not know about XA, such as DECS and other Domino add-ins that access
DB2.

To avoid requiring these applications to be rewritten to opt-out of XA participation, at startup, all

Domino processes change this DB2 XA participation default from opt-out to opt-in. If you are writing a
Domino add-in that creates DB2 connections and you want to use XA, you must now opt-in each
connection using the following call:

SQLSetConnectAttr(hdbc, SQL_ATTR_HANDLE_XA_ASSOCIATED,
(SQLPOINTER*)SQL_CONNECT_WITH_XA_ON, SQL_IS_INTEGER);

Chapter 5. Setting up Domino and DB2 181

Moving a DB2 database container
Use the DB2 move container tool to move the files in your DB2 default storage database to another
database that you specify. Moving the files provides space for additional data to be saved in the default
DB2 database.
1. From the Domino Administrator, click the Files tab.
2. Select the DB2 database that you are moving to another container.
3. From the Tools panel, click Database - DB2 Move Container.
4. Enter the name of the container to which you are moving the DB2 database.
5. Click Move.

Replicating an NSF to DB2

You can replicate an NSF or DB2 enabled Notes database just as you would any database. The Create
Replica dialog box contains the field, Domino Database datastore. If you want to create a replica that can
be seen by DB2, choose DB2.

When you create a DB2 enabled Notes database from an NSF database, the DB2 enabled Notes database
can require twice as much disk space as the NSF required. With ongoing use, the DB2 enabled Notes
database version can grow much larger. Allot twice as much space for the DB2 enabled Notes database as
you allotted for the NSF.

As databases are maintained, that is, documents are added and deleted, views are built, and DAVs are
created, allow an additional two times as much space for DB2 enabled Notes databases as allowed for
NSF databases. In total, allow four times as much space for each DB2 enabled Notes database as is
allotted for each NSF.

Examples
Example 1 -- One mail database uses 512 MB as an NSF; therefore, you need to allow 1 GB for initial
creation of the DB2 enabled Notes database. Mail files tend to be active with many inserts and deletes.
The DB2 enabled Notes database is an active database; therefore, allow 2 GB for ongoing use.

Example 2 -- A reference database uses 512 MB as an NSF; therefore, allow 1 GB when you create the
DB2 enabled Notes database.

Example 3 -- DB2 enabled Notes databases are stored in groups by default. Ten DB2 enabled Notes
databases use the same group, DB2 tablespace, and DB2 container file. Assume there are ten mail
databases, 512 MB each, and all ten are in the same DB2 group. The NSFs use 5 GB total. When you
create the DB2 enabled Notes databases from the NSFs, allow 10 GB. For ongoing use, allow 20 GB.

Note: Currently there are issues that make it very difficult to free up the unused space, so allow a lot of
space.

Setting a DB2 server ID

Use this procedure to create any DB2 server IDs that you need.
1. From the Domino Administrator, click the Files tab.
2. Select an ID file from the list of displayed files.
3. Click Tools - Database - Set DB2 ID.
4. Complete these fields:

Field Description
DB2 User name Enter the user name for accessing the DB2 server.
DB2 password Enter the password for accessing the DB2 server.

182 Lotus Domino Administrator 7 Help

5. Click Set.
6. (Optional) Select this check box to update the user name and password stored in the system account.
For this beta release, this field only applies to systems running Microsoft Windows. Complete these
fields and then click OK.

Setting and modifying DB2 values in the Server document

When you run the DB2 Server Enablement Tool, the fields on the DB2 tab of the Server document are
updated. If you are not using the DB2 Server Enablement Tool, manually update the Server document.
1. From the Domino Administrator, click the Configuration tab and then expand the Server section.
2. Select the Server document to be edited and then click Edit Server.
3. Click the DB2 tab.
4. Complete these fields on the DB2 tab and then click Save and Close.

Note: If you are modifying one of the DB2 parameters, restart the server after saving your modifications
in order to allow those modifications to take effect.

Field Description
Host Name Host name of the DB2 server. The host is the name of the
remote server on which you are storing data. Remote
configuration only.
Port Number Specify the port number used to access the DB2 server.
Remote configuration only.
Instance The DB2 instance name. The default instance is DB2.
Database Enter the DB2 database name. The default is Domino.
Directory A valid path where DB2-based NSF tablespace containers
will reside. This field defaults to the DB2 server’s default
directory set up by the DB2 administrator.

If you specify multiple paths, containers are dispersed

randomly across different paths. If you choose to provide
multiple paths, use this syntax:
C:\db2data#D:\db2data#E:\db2data

Where the ’#’ is used to separate container locations.

These locations are not used to stripe containers, rather
to disperse newly-created NSF containers randomly
across the different paths.
DB Default Creation The type of database that is created by default when
working in Domino Notes. Choose one:
v DB2 -- Creates a DB2 enabled Notes database, which
you can work with in DB2 and Domino Notes.
v NSF -- Creates a pure NSF which you can only work
with in Domino Notes. NSFs are not recognized by
DB2.
DB2 Access Server Enter the fully-qualified user name of the USER.ID file
that DB2 Access server uses. For example,
DB2AccServ/DomainName
DB2 Access Path Enter the complete path that DB2 uses to load the DB2
Access server DLL. For example, C:\program
files\db2udf\ndomudf.dll. The DB2 Access path must
point to the file ndomudf.dll.

Chapter 5. Setting up Domino and DB2 183

Field Description
Maximum number of NSFs in Group Default setting is 10. The maximum number of DB2
enabled Notes databases permitted in one DB2 group.
You can lock a DB2 group before it reaches the
maximum of 10 groups. When a group is locked or when
it is full because it contains ten groups, any new DB2
enabled Notes databases are added to the next
sequentially numbered DB2 group.

Setting DB2 Log File Size

For this beta release of Domino 7 and DB2, you need to set the DB2 log file size. You can specify these
values as you would any DB2 configuration settings by using either the DB2 Control Center, or by using
the DB2 Command Line Processor (CLP).

For example, from the DB2 CLP, enter a command similar to the following:
db2 update db cfg for <yourdb> using logprimary X

Where the value of <yourdb> is the value you specified for DB2Database in the Server Enablement Tool.
The default value is DOMINO.

Recomended DB2 log settings

The recommended DB2 log file settings are as follows:

For low traffic workloads, use the default setting, ~28MB

Log file size (4KB) (LOGFILSIZ) = 1000

Number of primary log files (LOGPRIMARY) = 5
Number of secondary log files LOGSECOND) = 2

For mid-traffic workloads, the suggested setting is ~240MB

Log file size (4KB) (LOGFILSIZ) = 4000

Number of primary log files (LOGPRIMARY) = 10
Number of secondary log files (LOGSECOND) = 5

Log file size (4KB) (LOGFILSIZ) = 8000

Number of primary log files (LOGPRIMARY) = 10
Number of secondary log files (LOGSECOND) = 5

Setting, modifying or deleting the Domino server user’s DB2 ID

properties
To set, modify or delete the DB2 user account name and password for the Domino server, you must have
DB2 administrator privileges. This DB2 ID and password are the Domino server’s user name and
password that Domino uses to communicate with the DB2 server. The Domino server user account name
and password were set during server enablement.

Use this procedure to modify or delete the Domino server’s DB2 ID properties for the Domino server.
The user name and password are stored in the server’s ID file.
1. From the Domino Administrator, click Configuration - Server.

184 Lotus Domino Administrator 7 Help

2. Choose the server for which you are setting, modifying, or deleting DB2 server ID properties.
3. Click Tools - DB2 Server - Edit DB2 Login Information.
4. Complete these fields:

Field Action
DB2 User name Enter the user name for accessing the DB2 server.
DB2 password Enter the password for accessing the DB2 server.

5. Do one of these:
v To set or modify the DB2 user name or password for the Domino server user, click Set and then
proceed to step 6.
v To delete a DB2 user name and password for the Domino server user, click Clear and then proceed
to step 6.
6. Complete these fields and then click OK.

Field Action
Password verify Do one:
v If you are setting or modifying the DB2 password,
re-enter the new password to verify the password you
entered in the DB2 password field.
v If you are deleting a user account name, re-enter the
existing DB2 password to allow the delete to take
effect.
Update system account Select this check box to update the user name and
password stored in the system account. For this beta
release, this field only applies to systems running
Microsoft Windows.

Validating DB2 user names

You can verify that there are no duplicate DB2 user names, or other naming anomalies, within the
Domino Directory. The Validate DB2 User Name tool scans all network account names and lists any
invalid or duplicate names. You can then correct the names as needed.

Check the log file, LOG.NSF, for more information on any failures reported by the Validate DB2 User
Name tool.
1. From the Domino Administrator, click People and Groups.
2. In the left pane, click People. Select the person whose DB2 user name you are validating.
3. From the Tools panel, click People - Validate DB2 User Names.
4. Specify which Domino Directories you want to validate by choosing one of these:
v The currently selected Domino Directory
v All configured Domino Directories
5. Click OK.

Administering the DB2 Access server

If you make changes to your Domino server configurations that impact the server to which your DB2
Access server is connected, you may need to edit the DB2 Access Server Connection document. Use this
procedure to edit that Connection document:
v Editing the DB2 Access server Connection document

Chapter 5. Setting up Domino and DB2 185

You can also use the following procedures to administer the DB2 Access server:
v Removing a DB2 Access server
v Testing the DB2 Access configuration
v Resolving errors when using SELECT

Editing the DB2 Access server Connection document

The DB2 Access server Connection document is created when you install the DB2 Access server and then
start the Domino server. This DB2 Access server Connection document connects the DB2 Access server
and a Domino server that you previously designated using the Domino Administrator.
1. From the Domino Administrator, click the Configuration tab.
2. From the Tools panel, click DB2 Server - Edit DB2 Access Connection.

Field Action
Source Server Non-modifiable field containing the name of the DB2
Access server.
Source Domain Non-modifiable field containing the name of the domain
in which the DB2 Access server resides.
Destination Server Non-modifiable field that displays the name of the server
to which the Domino Administrator is connected.
Destination Domain Non-modifiable field that displays the name of the
domain to which the Domino Administrator client is
connected.
Use Port(s) Non-modifiable field that is set to TCPIP.
Optional Network Address Enter the TCP network address of the server to which
the Domino Administrator client is connected.

For example, servername.domain.com

Removing a DB2 Access server

Use the DB2 Access Remove command to disable the DB2 Access server from a DB2 server. The DB2
Access Remove command removes the following:
v DB2 Access Views
v DB2 Access server name from the DB2 tab of the Domino server’s Server document
v DB2 Access settings from the Domino server’s NOTES.INI file
1. From the Domino server command line, type
DB2 ACCESS REMOVE
2. Enter this command to shut down the Domino server:
Quit
3. As the instance owner, from DB2 server Command Line Interface, type
DB2 stop
4. Uninstall the DB2 Access server. For example, using a Microsoft Windows configuration, choose Add
and Remove Programs from the Control Panel.

Testing the DB2 Access configuration

Use the DB2 Access Test tool to test the configuration of the DB2 Access server. The DB2 Access Test tool
tests all DB2 Access server’s field parameters from the Server document and all DB2 Access server
settings from the NOTES.INI file. If all fields and settings are correct, it tests the connection between the
DB2 Access server and the selected Domino server, verifies whether the DB2 functions and properties
exist, determines whether the DB2 Access server Connection document is valid, and attempts to open the

186 Lotus Domino Administrator 7 Help

Domino Directory on the DB2 Access Server. If the DB2 Access Test tool locates any problems, the
information is returned to the Domino server console or to the Domino Administrator client.
1. From the Domino Administrator, click the Configuration tab.
2. Click Connections. Select the DB2 Access Server Connection document.
3. From the Tools panel, click DB2 Server - Test DB2 Access.

Working with views in Domino and DB2

As previously mentioned, you can use two new types of views with Domino and DB2, DB2 Access Views
(DAVs) and Query Views. The standard NSF views that you define in Domino Designer are still
available.

DAVs and SQL views are set up using Domino Designer 7, but you use the Domino Administrator for
these activities regarding views:
v Using federated data with query views
v Setting the maximum number of rows in SQL queries
v Building views of large databases
v Views categorized by numeric datatypes

Using federated data with query views

Prerequisite
v Make sure you are running at least DB2 8, fixpak 8, or more recent.

Procedure
1. Set the environment variable, DB2_ALLOW_SETAUTH_WITH_REMOTECONNECT=, in order for
query views to work. Use the following path and command:
C:\Program Files\IBM\SQLLIB\BIN>db2set -i DB2 DB2_ALLOW_SETAUTH_WITH_REMOTECONNECT=1
where -i is the name of your DB2 instance (typically DB2).
2. Restart DB2 to allow the environment variable to take effect.
3. Ensure that your DOMINO database has federated support enabled.
4. Create a federation wrapper in DB2 for the remote server.
5. Add a user mapping to this federation wrapper mapping the DOMINO server user to the remote
connection user name and password. From the DB2 Control Center, choose Server Definitions - DAVS
- User Mapping.
The Domino server user is the account you created for DB2 server enablement.
6. From the DB2 Control Center, create a nickname mapping a local object to the foreign object.
7. Grant privileges to the NICKNAME object as required for those mapped DB2 users to whom you
want to give access to the federated table. Complete these steps from the command prompt or from
the command center:
v Log on to your database as your Domino server user, or as another administrator.
v Use this command to grant privileges:
db2 => grant select on domino.forpeter to <user’s short name>

You can now use a query view with federated data.

ALL users granted access to the federated table have equal access to it, based on the mapped credential
in the federation definition.

Chapter 5. Setting up Domino and DB2 187

Setting the maximum number of rows in SQL queries
By default, the maximum number of rows returned by an SQL query is 500 rows. You can use the
NOTES.INI setting, DB2QUERYVIEWROWLIMIT=value to specify the maximum allowable number of
rows returned by an SQL query when using Query Views on the associated server.

To set the maximum number of rows returned in SQL queries to a value other than 500, add this
NOTES.INI variable to server’s NOTES.INI file:
DB2QUERYVIEWROWLIMIT=value

The default setting is DB2QUERYVIEWROWLIMIT=500

Note: On DB2-enabled Domino servers, designers can set ″Maximum rows returned by an SQL query″ in
the View Properties - Option tab. If the DB2QueryViewRowLimit variable is set at the server level,
designers can still limit the number of rows to a smaller value, and the smaller value will take
precedence.

Building views of large databases

When building a view of a large database for the first time, run the updall task with the -c option. From
the Domino server command line, enter the following:
Load updall <databasename> -c

When building subsequent views of the same database, use the updall command with -R. For example,
enter the following:
Load updall <databasename> -R

For more information about the updall task, see the topic Updating database indexes and views.

Views categorized by numeric datatypes

If a view is categorized by a number datatype, and it contains response notes, the view may not render
correctly.

Domino and DB2 XA transaction services

Domino uses DB2’s XA transaction services, but changes a default participation assumption. Domino
add-in developers need to be aware of this change.

When a process starts using XA with DB2, all subsequent new connections are usually created using the
assumption that the new connections will be participating in XA operations unless the
SQL_ATTR_HANDLE_XA_ASSOCIATED connection attribute is explicitly set to FALSE to opt-out of XA.
Setting the attribute SQL_ATTR_HANDLE_XA_ASSOCIATED to FALSE breaks any legacy DB2 calls that
the process makes that did not know about XA, such as DECS and other Domino add-ins that access
DB2.

To avoid requiring these applications to be rewritten to opt-out of XA participation, at startup, all

Domino processes change this DB2 XA participation default from opt-out to opt-in. If you are writing a
Domino add-in that creates DB2 connections and you want to use XA, you must now opt-in each
connection using the following call:

SQLSetConnectAttr(hdbc, SQL_ATTR_HANDLE_XA_ASSOCIATED,
(SQLPOINTER*)SQL_CONNECT_WITH_XA_ON, SQL_IS_INTEGER);

188 Lotus Domino Administrator 7 Help

Chapter 6. Setting Up Notes Users and Clients
After setting up and configuring the first Lotus Domino 7 server, you can set up Lotus Notes 7 users.

Setting up Notes users

Lotus Notes users are people who use the Notes client to access Domino servers and databases and have
a Notes ID, a Person document, and, if they use Notes Mail, a mail file.

Before you register new Lotus Notes users, you may want to specify default settings that apply to all
users you register. Default settings make user registration easy and fast and ensure that user settings are
consistent.

You can define many default settings, such as what mail server users have or what certifier ID to use for
user registration. You can also specify a default workstation execution control list (ECL) to protect data
from unauthorized workstation access.

To define default settings, use any of these tasks:

1. Create a Registration Settings document to define default user registration settings.
2. Create a user Setup Settings document to populate the user’s Location document and bookmarks.
Setup settings include Internet browser and proxy settings, applet security settings, and desktop and
user preferences.
3. Create a Desktop Settings document to make dynamic changes on user workstations.
4. Create a default workstation execution control list (ECL) to set up workstation security.
5. Specify default user registration settings in Administration Preferences.
6. Specify default user settings in the Register Person dialog box.
For more information on policies and settings documents, see the chapter ″Using Policies.″

To set up Notes users, you can register them in Notes or migrate them from an external mail system or
directory. Before you begin to add users, it is best to specify default settings that Notes applies during
registration.

To add users, you register them and use the Lotus Domino server-based certification authority which
issues the appropriate certificate or use the appropriate certifier ID and password, which generates a user
ID and certificates that allow users appropriate system access. After registering Notes users, you need to
prepare the installation files so users can install Notes on their workstations.

User registration
You need to register users before they can install Notes on their workstations. For each user, the
registration process creates:
v A Person document in the Domino Directory.
v A user ID that is stamped with appropriate certificates (does not apply to non-Notes users).
v A mail file (Optional).

Notes offers different options for registering users. For example, using Basic user registration is fast and
easy because it automatically assigns many default settings to users. If you use Advanced user
registration, you can assign more advanced settings, such as adding a user to an Active Directory group.
You can also register users by importing them from a text file or migrating them from a foreign directory.

189
If you use the Register Person dialog box to register users, you can sort, view, and modify user settings
in the view of the User Registration Queue (USERREG.NSF) that appears in the dialog box. This database
contains information on users pending registration. When you exit the Register Person dialog box, you
can save all users pending registration and register them later. When you access the dialog box again, the
User Registration Queue automatically opens to display all users pending registration.

Before you register users, review your organization’s hierarchical name scheme and decide where each
user fits into that scheme. Based on the name scheme, you know which certifier ID to use to register
users, which server to use as the registration server, and on which server to store the user’s mail files.
When you register users, you must have the appropriate access to each server that you use, and you
must know the password for each certifier ID that you use. If you intend to implement policies in your
organization, create policies and settings documents before you register users so that you can assign
policies during registration.

Note: The registration user interface automatically removes leading spaces and trailing spaces from
passwords. Passwords cannot begin or end with a space. This also applies to certifier registration and
server registration.

For more information on creating non-Notes users, see the topic ″Creating non-Notes, Internet Users″ in
this chapter.

User registration and the server-based certification authority

When registering users, you have the option of using the traditional certifier ID and password
combination or using the Domino server-based certification authority (CA). Prior to registering users, you
need to understand the Domino server-based CA, be familiar with the benefits of using the CA, and
know how to use the Domino server-based CA. An administrator can be designated as a Registration
Authority (RA) for the server-based certification authority (CA). You can now assign to the administrator
responsible for user registration, the role of RA. This allows one administrator to register users with
certificates issued by the server-based certification authority.

For more information on the Domino server-based certification authority, see the chapter ″Setting Up a
Domino Server-Based Certification Authority.″

Example of registering two Notes users

Here is an example of how administrators at the Acme Corporation registered two users based on each
user’s place in the organization’s hierarchy. The users work in different locations and departments.

190 Lotus Domino Administrator 7 Help

Alan Jones works in the Sales department in Acme’s East Coast division. To give Alan appropriate access
within the system and to place him appropriately in the hierarchy, the administrator uses the
Sales/East/Acme certifier ID to register him. Alan Jones’ full hierarchical name then becomes Alan
Jones/Sales/East/Acme.

The administrator specifies Mail-E, which is located on the East Coast Acme LAN, as Alan’s mail server.
Then Alan’s mail server is on the same LAN as his workstation, so that when he receives and sends mail,
he can connect directly to the server that stores his mail file.

Robin Rutherford works in the Accounting department in Acme’s West Coast division. The administrator
uses the Accounting/West/Acme certifier ID to register Robin. Mail-W is Robin’s mail server, and her full
hierarchical name is Robin Rutherford/Accounting/West/Acme.

Customizing user registration

You can define specific options to customize how Domino registers users. If you choose to use a certifier
ID and password instead of the Lotus Domino server-based certification authority (CA), Domino uses the
certifier ID specified in Administration Preferences; or if there is none, it uses the ID specified in the
CertifierIDFile setting in the NOTES.INI file.
1. Make sure to have the following before you begin customizing user registration:
v Access to the certifier ID and its password, if you are not using a certifier enabled for the CA
process.
v Editor access or Author access with Create Document role and the UserCreator privilege in the
Domino Directory. UserCreator role is required regardless of your access level.
v Access to the Domino Directory from the machine you work on. Local or remote access to
USERREG.NSF.
v Create new databases access on the mail server to create user mail files during registration.
v Create document access to CERTLOG.NSF on the registration server.
v GroupModifier role or at least Editor access to add users to groups.

Note: Do note modify the ACL for USERREG.NSF using the File - Database - Access Control menu
commands. Use the User Registration Database Access button on the Advanced Person Registration
Options dialog box.
2. From the Domino Administrator, click the People & Groups tab.
3. From the Servers pane, choose the server to work from.
4. Select Domino Directories, and then click People.
5. From the Tools pane, click People - Register. Enter the password for the certifier that you are currently
using.

Note: While registering a user, you can specify whether you want to register the user with the
server-based CA, or with a certifier ID and password. This selection is made on the ID Info panel in
advanced user registration.
6. Click the Options button, and then choose any of these options:

Option Purpose
Do not continue on registration Stops registration if you have multiple users selected and the registration
errors encounters an error. The default is to continue on registration errors.
Keep successfully registered users Keeps successfully registered users in the queue. The default is to remove
in the queue successfully registered users from the queue.
Try to register queued people with Tries to register queued users, even if their registration status contains errors.
error status For example, if you choose this option, a user whose password is insufficiently
complex will be registered. The default is not to register queued users who
have error status.

Chapter 6. Setting Up Notes Users and Clients 191

Option
Allow registration of previously
registered people
Search all directories for duplicate
names
Enforce short name uniqueness
Don’t prompt for a duplicate
person
Purpose
Allows registration of users who were previously registered in Notes. The
default is not to register previously registered Notes users.
Checks every directory to see if the user’s name already exists.
Forces all short names to be different from one another.
If you choose this option, these additional options appear. Choose one:
v Skip the person registration -- Skips the user registration for both short
name and full name single matches.
v Update the existing address book entry -- Overwrites the existing user if the
single match found is on the full name. Short name uniqueness is then
required.

The default is to prompt for duplicate users.

Don’t prompt for a duplicate mail If you choose this option, these additional options appear. Choose one:
file v Skips the person registration.
v Generates a unique mail file name by appending a number beginning with
1, then 2, etc., to a non-unique mail file name until a unique name is found.
v Replaces the existing mail file - option does not apply when the mail file is
being created in the background via the Administration Process, or if the
current ID does not have delete access to the mail file that is being replaced.

The default is to prompt for a duplicate mail file.

Don’t prompt for a duplicate
roaming directory
If you choose this option, these additional options appear. Choose one:
v Skips the person registration.
v Generates a unique roaming directory name by appending a number
beginning with 1, then 2, etc., to a non-unique roaming file name until a
unique name is found.

The default is to prompt for a duplicate roaming directory.

Generate random user passwords
User Registration Database Access
Click this check box to automatically set random passwords for the users you
are registering. If you select this option, you do not need to specify passwords
for the users you are registering.
Displays the Registration Database Access Control Settings dialog box, where
you can add or remove members from the access control list as well as change
access control settings.

7. Click OK.

Registering users
You can use any of these methods to register Notes users:
v Basic user registration
v Advanced user registration
v Text file registration
v Registration settings
v Migration tools (for people using an external mail system or directory) registration
v Basic user registration from the Web Administrator
v Advanced user registration from the Web Administrator

192 Lotus Domino Administrator 7 Help

The method you use to register people depends on a number of issues, including whether you have
defined default settings, whether you want to assign users more advanced options (such as alternate
names), whether you need to import users from a foreign mail system or directory, and whether your
user settings are in a text file.

Note: When registering users with non-ASCII characters in their user names, Notes attempts to convert
non-ASCII characters to ASCII. If one or more characters cannot be converted to ASCII, the Internet
address is not generated. You need to be aware of this when registering users whose names cannot be
converted to ASCII characters because you will need to create those Internet addresses manually.

Basic registration: For fast and easy registration, use the Basic user registration options. Basic
registration requires you to define user-specific settings, such as user name and password, but also offers
you the convenience of applying some default settings to users. You can define default settings in the
Registration preferences (found in the Administration Preferences dialog); you can define settings in the
Register Person dialog; or you can use Notes default settings. Some of the non-default settings you define
in Basic registration include the user name and password. You can also assign users to specific groups.

All settings available in Basic registration are also available in Advanced registration. You can choose to
view and perform Advanced registration at any time by clicking the Advanced check box in the Register
Person dialog.

Advanced registration: Advanced registration offers all the settings included in Basic registration and
also allows you to change default settings and define advanced or specific settings -- for example, assign
an alternate name to a user or add the user to an Active Directory group.

Text file registration: To register users from a text file -- that is, a file that contains information on one
or more users -- import them into the registration queue from the Register Person dialog box. This action
creates an entry for each user in the User Registration Queue and allows you to modify user settings
individually.

Web registration: User registration can now be done using the Domino Web Administrator. You register
users via the Web in a manner that is very similar to user registration done with the Domino
Administrator.

For more information on registering users with the Web Administrator, see the topic ″Using the Domino
Web Administrator to register users″ in this chapter.

If you are a service provider, for more information on registering users from the hosted organization site,
see the chapter ″Managing a Hosted Environment.″

Registration Settings: To simplify the process of registering users, you can create policies and
Registration Settings documents to preset registration settings for different types of users. For example,
users who work in Human Resources may have different registration settings than users who work in
Sales. You can create Registration settings for Sales, and another set of Registration settings for Human
Resources, and use them to register everyone with the proper settings. In addition, when you add new
users to Human Resources or Sales, the defined Registration settings apply.

Note: Administration preferences (File - Preferences - Administration Preferences) do not apply to user
registration performed with the Web Administrator.

Migration from external mail system or directory: You can migrate users who use an external mail
system or directory into Notes. You register them using migration tools accessed through the Migrate
People button in the Register Person dialog box. After migrating them, you can modify their settings.

The following list details the types of users you can migrate into Notes:
v Microsoft Exchange

Chapter 6. Setting Up Notes Users and Clients 193

v LDIF (from an LDAP directory)
v LDAP
v Windows 2000/Windows 2003
v Active Directory

Using default user settings when registering users

When you use default settings, the user registration process is fast and easy. The default settings can
originate from a variety of sources:
v Notes includes a set of default settings.
v You can define default settings in the registration preferences in the Administration Preferences dialog
box. Define these settings before registering users. The registration preferences do not offer all the
default settings, only some of the more basic ones, such as designating the Registration server.
For more information on registration preferences, see the chapter ″Setting Up and Using Domino
Administration Tools.″
v You can define default settings through the user registration interface using either of two methods: one
method uses settings for a user previously added to the user registration queue, and the other method
uses settings defined on the Register Person - New Entry dialog box.
For example, if you have already added users to the user registration queue, the non-user-specific
settings that were applied to the last user, now serve as defaults for the next user. Similarly, you can
define settings on the Register Person - New Entry dialog box. If you import or migrate users while in
this mode, users inherit settings you defined.

Only settings you define as registration preferences remain from session to session. All other default
settings return to Notes defaults each time you begin a new registration session.

Default Notes user registration settings: This table lists all the default user registration settings that
Notes provides. The values in this table appear only under these conditions:
v Previous values have not been set in Registration preferences
v Previous values have not been set in the Register Person dialog box

User registration fields that do not appear in this table do not have default values.

Field
Registration Server
Password Quality Scale
Set Internet password
Encryption Strength
Internet address
Internet Domain
Address name format
Mail server
Mail file template
Create file now
Mail system
Mail file name
Mail file owner access
Create full text index
Set database quota
Default
Local server if it contains a Domino Directory. Otherwise, server specified in
NewUserServer setting of the NOTES.INI file, or the Administration server.
8
Off
Base strength on RSA key size
FirstnameLastname@Internet domain -- for example, RobinRutherford@Acme.com.
Current TCP/IP host domain
Firstname Lastname
Local server if it contains a Domino Directory or Administration server
Mail(7)
On
Lotus Notes
mail\<firstinitial><first7charactersoflastname>.nsf
Editor with Delete documents rights
Off
Off

194 Lotus Domino Administrator 7 Help

Field Default
Set warning threshold Off
Create a Notes ID for this On
person
Enable roaming for this Off
person
Certifier ID If you are not using the server-based certification authority (CA), Notes uses the
certifier ID specified in Administration Preferences; or if there is none, it uses the ID
specified in the CertifierIDFile setting of the NOTES.INI file.

If you are working in a hosted environment and registering users to a hosted

Security type
Certificate expiration date
Location for storing user ID
Local administrator
Put roaming user files on
mail server
Personal roaming folder
Sub folder format
Create roaming files now
Clean-up action
organization, be sure that you are working with a certifier that was created for that
hosted organization.
Either North American or International
Two years from current date
In Domino Directory
None
On
roaming\
FirstName LastName
Selected
Do not clean up

Roaming users
Users who access Notes from more than one Notes client can access their customized settings and
personal information automatically from any Notes client in the domain. Data for these users, known as
roaming users, replicates between the user’s machine and a roaming user server, where these files are
stored. When a roaming user logs on from a different Notes client, it automatically retrieves the user’s ID
file, Personal Address Book, bookmarks, and journal from the roaming user server. Any changes the user
makes in these files replicate to the roaming user server. This enables the roaming user to have a
consistent experience from any Notes client.

The roaming user feature is supported for the Notes client, Domino Administrator client, and Domino
Designer.

Registering roaming users on DB2-enabled Domino servers: When registering a roaming user, you
have the option of choosing the preferred data store for that user’s roaming files. If DB2 is not enabled
for the roaming server, the database(s) are created as NSF files. If you are registering a roaming user on a
DB2-enabled Domino server, you can choose NSF or DB2 as the data store but be aware that the user’s
local copy of the Domino Directory, NAMES.NSF, is created and stored as an NSF file. NAMES.NSF
cannot be created or stored as a DB2 file.

Creating a roaming user: To create a roaming user, complete the steps in the procedure ″Using
Advanced Notes user registration with the Domino Administrator″ but in addition to the standard
registration selections, be sure to make the roaming user-specific selections listed here.
v From the Basics tab, choose ″Enable roaming for this person″, to enable roaming capabilities for a user.
v Select the Advanced check box.
v Select the Roaming User tab. Complete any of the following Roaming User fields.

Chapter 6. Setting Up Notes Users and Clients 195

 Note: The roaming user fields do not appear if you did not click ″Enable roaming for this person″ on
the Basic tab and ″Create a Notes ID for this person″. Domino uses default values, if available, for
fields you do not modify.
– Put roaming user files on mail server: Click to store the user’s roaming information on the same
server used for mail. If you select this option, the Roaming Server defaults to the user’s mail server.
– Roaming Server: Click to open the ″Choose Roaming User Files Server″ dialog box, where you
specify the server that stores the user’s roaming information.
– Personal roaming folder: This is the subdirectory that contains the user’s roaming information. By
default, this is based on the sub-folder format you specify, but you can customize it.
– Sub-folder format: The method used to name roaming subdirectories on the roaming server. This
determines the default Personal roaming folder for each user.
– Create roaming files now or Create roaming files in background: Choose when you want roaming
files to be created. The ″Create roaming files in background″ option forces the Administration
Process to create the files the next time it runs, and saves time during the user registration process.
– Roaming Replicas: Click this button to open the ″Roaming Files Replica Creations Options″ dialog
box, where you can designate one or more servers on which to create additional replicas of a user’s
roaming databases. This option only applies to clustered servers. Note that roaming replica server(s)
can only be specified during the user registration process.
– Clean-up option: Choose one of the following Roaming User client clean-up options. Clean-up will
only occur on clients that have been installed and configured for multiple users:

Using replication on a roaming server: After you set up a roaming user, when the Roaming User starts
Notes on any computer, Notes replicates three databases: the Personal Address Book, Bookmarks, and the
Personal Journal. If a user has upgraded from non-roaming to roaming, the Personal Journal only
replicates if a personal journal already exists with the default filename, JOURNAL.NSF. Notes also copies
some information from other databases and from the configuration file, NOTES.INI, and stores it in one
of those three databases.

Note: For Macintosh users, it copies the information from the Notes Preferences file.

When a roaming user logs on to a machine for the first time, any databases that exist in the roaming
user’s subdirectory on the roaming server are included with the three databases that Notes replicates by
default. To add other databases, create a replica of those databases in the Roaming User’s directory on the
roaming server.

If you selected the option to allow the user’s personal address book to be replicated by the user, the
user’s Personal Address Book may also contain a Roaming User’s ID and the user’s dictionary as file
attachments. The user ID is double-encrypted for added security before being attached. Because the user
ID replicates, users no longer need to copy their IDs to different computers when it is modified (for
example, by changing the password). Changes may not take effect; however, until replication occurs. In
this case, the roaming user can use the old user ID.

Most of the settings in the User Preferences dialog box, except for those that are specific to the operating
system’s configuration, are replicated. Examples of preferences that do not roam include fonts,
communication ports, background printing, bi-directional language settings, and file paths.

Bookmarks are replicated. Bookmarks include personal Welcome pages, toolbar preferences, all
bookmarked databases, folders, icons, and other bookmark preferences, and settings for framesets.

Personal Journal (journal.nsf)

The personal journal database is replicated if it is named JOURNAL.NSF, or if it has been set via the
Welcome Page.

196 Lotus Domino Administrator 7 Help

Information that does not replicate on a roaming server: The following items do not replicate;
therefore, they do not have the same data on all computers used by the roaming user.
v Signature files
v IMAP and NNTP proxy databases
v NOTES.INI file (except for User Preferences stored in the Personal Address Book)
v DESKTOP.DSK
v CACHE.NDK
v HEADLINE.NSF
v Private views
v Any other data files or databases that are not replicated to the roaming subdirectory on the server

Using Basic Notes user registration with the Domino Administrator

Perform Basic user registration to assign users basic settings, such as a name and password, and to add
users to existing groups. To make registration fast and easy, Basic registration uses default values for all
other user settings. If you have selected the Advanced option, you are using Advanced user registration,
not Basic user registration.

For more information on Advanced user registration, see the topic ″Using Advanced user registration″ in
this chapter.

If you want to assign advanced and/or specific settings to a user -- such as giving users alternate names
-- use Advanced user registration.

Note: To modify user settings after you add the user to the User Registration Queue, select the user from
the queue and then make your changes. To modify certain settings for multiple users at once, select the
names in the queue and then make changes.

Naming conventions: When adding users, user names can consist of uppercase and lowercase alpha
characters (A - Z), numbers (0 - 9), and the ampersand (&), dash (-), dot (.), space ( ) , and underscore (_).

Hosted Environments: If you are working in a hosted environment, when registering users, ensure that
you are using a certifier that was created for the hosted organization into which you are registering the
users. This applies regardless of whether you are using a certifier and password or the server-based CA.

To use Basic registration with the Domino Administrator:

1. Make sure you have the following before you begin registration using the Domino Administrator:
v Access to the certifier ID and its password, if you are not using the Lotus Domino server-based
certification authority (CA) and are using the Domino Administrator.
v Access to the Domino Directory from the machine you work on.
v Editor access or Author access with Create Documents and the UserCreator role in the Domino
Directory on the registration server.
v Create new databases access on the mail server if you plan to create user mail files during
registration.
v Access to the certification log (CERTLOG.NSF) on the registration server.
2. From the Domino Administrator click the People & Groups tab.
3. From the Servers pane, choose the server to work from.
4. Select Domino Directories, and then click People.
5. From the Tools pane, click People - Register. Enter the password for the certifier that you are
currently using.

Chapter 6. Setting Up Notes Users and Clients 197

 Note: While registering a user, you can specify whether you want to register the user with the
server-based CA, or with a certifier ID and password. This selection is made on the ID Info panel in
advanced user registration.
6. Click Registration Server and then select the server that registers all new users, or accept the default,
and then click OK. If you have not defined a registration server in Administration Preferences, the
server is one of these by default:
v The local server if it contains a Domino Directory
v The server specified in NewRegServer setting of the NOTES.INI file
v The administration server
7. Enter a first name, middle name (if necessary), and last name. The user’s Short name and Internet
address are automatically generated. To change the Short name or Internet address, click the
appropriate space and enter the new text.
8. Enter the password for the user ID. Criteria for this password is based on the level set in the
Password Quality Scale in the Password Options dialog box. The default level is 8. The password
you specify must correspond with the password quality that you select in ″Password Options.″
For more information on password quality scale, see the chapter ″Protecting and Managing Notes
IDs.″
9. (Optional) To assign a policy to this user, select one from the Explicit policy list.
For more information on policies, see the chapter ″Using Policies.″
10. (Optional) Click the Policy Synopsis button to see an overview of this user’s effective policies.
11. (Optional) To enable roaming capability for this user, click the ″Enable roaming for this person″
check box.
12. Click the green check mark. The user name appears in the Registration status view (the user
registration queue). Or click the red X to clear all fields and start over.
13. Click Register, and then click OK.

To add the user to a group during user registration: You can add a user to a group during user
registration.
1. Click Advanced, and then click Groups.
2. Choose the group to which you are adding the user, and click Add.
3. Continue the registration process as usual.

Using Advanced Notes user registration with the Domino Administrator

Advanced registration offers all the settings included in Basic registration and also allows you to change
default settings and apply advanced settings to users.

Note: You can modify user settings at any time once you add the user to the User Registration Queue by
selecting the user from the queue and then making changes. You can also modify certain settings for
multiple users at once by selecting the users in the queue and making changes. You can cancel user
registration and clear all fields at any time by clicking the red X.

Hosted Environments: If you are working in a hosted environment, when registering users, ensure that
you are using a certifier that was created for the hosted organization into which you are registering the
users. This applies regardless of whether you are using a certifier and password or the server-based CA.

Roaming users: If you are registering roaming users, on the ID Info tab of the Register Person - New
Entry dialog box, choose ″In Domino Directory″ as the location for storing user IDs if you want roaming
users to access their Notes IDs from their personal Name and Address Book. If you do not choose the ″In
Domino Directory″ option, roaming users must either store their Notes ID on a file server or physically
carry their Notes ID with them on a diskette or other storage media. If you elect to store the user ID in
file and in the Domino Directory, the user IDs are stored in the user’s personal Name and Address Book.

198 Lotus Domino Administrator 7 Help

If you create roaming users and do not elect to store their user IDs in the Domino Directory, but later
decide to store those user IDs in the Domino Directory, disable the roaming user option, select the option
to store the user ID in the Domino Directory, and then enable the roaming user option again.

To use Advanced registration with the Domino Administrator:

1. Make sure you have the following access before you begin registration:
v Access to the certifier ID and its password, if you are not using the Lotus Domino server-based
certification authority (CA).
v Access to the Domino Directory from the machine you work on.
v Editor access or Author access with Create Documents role and the UserCreator privilege in the
Domino Directory on the registration server.
v Create new databases access on the mail server if you plan to create user mail files during
registration.
v Create explicit policies and settings documents if you plan to use policy-based system
administration.
v Access to the certification log (CERTLOG.NSF) on the registration server.
2. From the Domino Administrator, click the People & Groups tab.
3. From the Servers pane, choose the server to work from.
4. Select Domino Directories, and then select People.
5. From the Tools pane, click People - Register.
6. Enter the certifier password and click OK.

Note: The Certifier Information Recovery Warning dialog box appears. Review the information in the
dialog box, select the check box and click OK.
1. Click Advanced.
2. From the Basic tab, complete these fields:

Field Enter
Registration Server Click Registration Server to change the registration server (which is the server that
initially stores the Person document until the Domino Directory replicates), select
the server that registers all new users, and then click OK. If you have not defined a
registration server in Administration Preferences, this server is by default one of
these:
v The local server if it contains a Domino Directory
v The server specified in NewUserServer setting of the NOTES.INI file
v The administration server
First name, Middle name, Last The user’s first and last names and (if necessary) middle name. The user’s Short
name name and Internet address are automatically generated. To change the Short name
or Internet address, click the appropriate space and enter the new text.
Short name A short name in the format FirstInitialLastName is automatically created as you
enter the user’s name. For example, JSmith is the short name for John Smith. You
can modify this field.
Password A password for the user ID.

Chapter 6. Setting Up Notes Users and Clients 199

Field Enter
Password options Click Password options to set a level for the password in the Password Quality
Scale. The default level is 8. For more information, see ″Understanding the
password quality scale.″

Choose the password encryption strength (or password key width). The encryption
key that protects the Notes keys that are stored in the user ID file is derived from
the password. The stronger the encryption strength of the password, the stronger
the encryption key that protects the Notes keys.
v Base strength on RSA key size - encryption strength is determined by the size of
the RSA key stored in the ID file. If the RSA key size is less than 1024 bits, the
password encryption strength is 64 bits; if RSA key size is 1024 or greater, the
password key size is 128 bits.
v Compatible with all releases (64 bits)
v Compatible with 6.0 and later (128 bits)

Click the check box ″Set Internet password″ to give Internet users name and
password access to a Domino server and to set an Internet password in the Person
document. This field is automatically selected if you select the Other Internet, POP,
Domino Web Access, or IMAP mail types.
Mail system Click to change the user’s mail system from the default of Lotus Notes to an
Internet-based system or Domino Web Access.
Explicit policy Select the explicit policy to apply to this user. For more information on policies, see
″Policies.″
Policy synopsis Click to see a summary of this user’s effective policies.
Enable roaming for this person Click to enable roaming capabilities for this user. Doing so enables the Roaming
tab.
Create a Notes ID for this Click to create a Notes ID for this person during the registration process.
person

3. Click the Mail tab and complete any of these fields. Domino uses default values (if available) for any
fields you do not modify.

200 Lotus Domino Administrator 7 Help

Field Enter
Mail system Choose one of the available mail types and complete the necessary associated
fields:
v Lotus Notes (default)
v Other Internet
v POP
v IMAP
v Domino Web Access
v Other
v None

If you select Lotus Notes, POP, or IMAP, the Internet address is automatically
generated.

If you select Other Internet, POP, or IMAP, the Internet password is set by default.

If you select Domino Web Access, you can change other user registration
selections to Domino Web Access defaults by clicking Yes when prompted.

If you select Other or Other Internet, enter a forwarding address. This address is
the user’s current address, where the user wants mail to be sent. For example, if a
user temporarily works at a different location and/or uses a different mail system,
the user can have her mail forwarded to that new address. Or, a user may resign
from the company but leave a forwarding address so that mail addressed to the
old address is forwarded to the new location.
Mail server The user’s mail server. If you have not defined a mail server in Administration
Preferences, this server is (by default) the local server if it contains a Domino
Directory; otherwise, it is the Administration server.
Mail file name The file name of the mail file. By default, the path and file name are
mail\<firstinitial><first7charactersoflastname>.nsf.
Create file in background (Optional) Click Create file in background to force the Administration Process to
create the files in the background. Use this option to save time during the user
registration process. If you do not choose to create the file in the background, mail
files are created during the user registration process.
Mail file template A mail template from the list of available mail templates. For a description of the
template, select the template and click About. The default is Mail(R7)
(MAIL7.NTF).
Create full text index Click to generate a full-text index of the mail database.
Mail file replicas Click to open the Mail Replica Creation Options dialog box on which you can
select the servers to which the mail file will replicate. This option only applies to
clustered servers.
Mail file owner access Select the level of access in the access control list to assign to the user of the mail
database from the Mail file owner access list. By default, mail users have Editor
with Delete documents access to their own mail files; all other users have no
access. This option can be used to prevent mail users and/or owners from
deleting their own mail file. If the mail owner access is Designer or Editor, the
administrator ID currently being used is added to the mail file ACL as Manager.
Set database quota Click to enable, and then specify a size limit (maximum of 10GB) for a user’s mail
database.
Set warning threshold Click to generate a warning when the user’s mail database reaches a certain size,
and then enter the warning size (maximum of 10GB).

4. Click the Address tab, and enter values in any of these fields. Domino uses default values (if
available) for any fields you do not modify.

Chapter 6. Setting Up Notes Users and Clients 201

Field Enter
Internet address The Internet e-mail address assigned to this user.
Internet Domain The domain to be used in the Internet address -- for example, Acme.com.
Address name format The format of the Internet address. The default format is FirstNameLastName@Internet
domain without a separator -- for example, RobinRutherford@Acme.com.
Separator The character inserted between names and initials in the Internet address. The default is
None.

5. Click the ID Info tab, and enter values in any of these fields. Domino uses default values (if
available) for any fields you do not modify.

Field Enter
Create a Notes ID for this Click to create a Notes ID for this user.
person
Certifier Name list Choose a certifier ID to use when creating the user name during user registration
when a Notes user ID is not being created for the user.

This field appears if the check box ″Create a Notes ID for this person″ is not selected.

If you are working in a hosted environment and are registering a user to a hosted
organization, be sure to register that user with a certifier created for that hosted
organization.
Use CA process Click to use the Lotus Domino server-based certification authority (CA) to register this
user. The certifier ID and password will not be needed to complete the user
registration process if you use the Lotus Domino CA.

If you are working in a hosted environment and are registering a user to a hosted
organization, be sure to register that user with a certifier created for that hosted
organization.

This field appears if the check box ″Create a Notes ID for this person″ is selected.
Certifier ID Click if you want to use a certifier ID and password instead of the server-based CA. To
change to a different certifier ID, click Certifier ID, select the new ID, enter the
password, and then click OK.

If you are working in a hosted environment and are registering a user to a hosted
organization, be sure to register that user with a certifier created for that hosted
organization.

This field appears if the check box ″Create a Notes ID for this person″ is selected.
License type Choose either North American or International. The license type determines the type of
ID file created and affects encryption when sending and receiving mail and encrypting
data. North American is the stronger of the two types.

This field appears if the check box ″Create a Notes ID for this person″ is selected.
Certification expiration The expiration date of the user ID in mm-dd-yy format. The default is two years from
date the current date.

This field appears if the check box ″Create a Notes ID for this person″ is selected.

202 Lotus Domino Administrator 7 Help

Field Enter
Location for storing user Choose one:
ID v In Domino Directory (default). The ID file is stored as an attachment to the user’s
Person document. If you are registering roaming users, choose this option to store
their Notes IDs in the Domino Directory. If you do not choose this option for
roaming users, the users must either store their Notes IDs on a file server or carry
their Notes IDs with them on diskette or other storage media. When you choose this
option, the user’s IDs are stored in their personal Name and Address Books.
v In file (default location: <datadirectory>\ids\people\user.id). Click Set ID file to
change path.
v In mail file. This option is only available with Domino Web Access and allows Notes
users to read their encrypted mail while using Domino Web Access.

This field appears if the check box ″Create a Notes ID for this person″ is selected.
Public key specification The public key specification that you use impacts when key rollover is triggered. Key
rollover is the process used to update the set of Notes public and private keys that is
stored in user and server ID files.

Choose one:
v Campatible with all releases (630 Bits)
v Compatible with 6.0 and later (1024 Bits)
Note: For information about the significance of the public key specification and key
rollover, see the topic User and server key rollover.

6. (Optional) To add the user to an existing group:

v Click the Groups tab with the user highlighted (you can highlight multiple users also).
v Select the group or groups to assign and click Add.
For more information on adding users to groups, see the chapter ″Setting Up and Managing
Groups.″
7. (Optional) If you have enabled roaming capabilities for the user, click the Roaming tab, and complete
any of these fields. The fields do not appear if you did not click ″Enable roaming for this person″ on
the Basic tab and ″Create a Notes ID for this person.″ Domino uses default values (if available) for
fields you do not modify.

Field Enter
Put roaming user files Click to store the user’s roaming information on the same server used for mail.
on mail server
Roaming Server Click Roaming Server to open the Choose Roaming User Files Server dialog box on which
you specify the server that stores the user’s roaming information. If you select Put
roaming user files on mail server, the Roaming Server defaults to the user’s mail server.
Personal roaming folder The subdirectory that contains the user’s roaming information. By default, this is based on
the sub-folder format you specify, but you can customize it.
Sub-folder format The method used to name roaming subdirectories on the roaming server. This determines
the default Personal roaming folder for each user.
Create roaming files in (Optional) Click ″Create roaming files in background″ to create the user’s roaming files the
background next time the Administration Process runs. Creating roaming files in the background forces
the Administration Process to create the files and saves time during the user registration
process.

Chapter 6. Setting Up Notes Users and Clients 203

Field Enter
Clean-up option Choose one of the following roaming user client clean-up options. Clean-up will only
occur on clients that have been installed and configured for multiple users.
v Do not clean-up (default). -- Roaming user data will never be deleted from the Notes
client workstation to which the user roamed.
v Clean-up periodically. -- Enables the ″Clean up every N days″ field on which you
specify the number of days that should pass before roaming user data is deleted from
the Notes client workstation.
v Clean-up at Notes shutdown. -- Roaming user data will be deleted from the Notes client
workstation immediately upon Notes shutdown.
v Prompt user -- The user is prompted on exiting the client as to whether they want to
clean up their personal files. If the user chooses Yes, the data directory on that client
workstation is deleted. If the user chooses No, the user is prompted as to whether they
want to be asked again on that client. If the user chooses No, the user is not prompted
again. If the user chooses Yes, the user is prompted again the next time the user exits
the client on that workstation.
Roaming Replicas Click this button to open the ″Roaming Files Replica Creations Options″ dialog box on
which you can designate to which servers a user’s roaming files should replicate. This
option only applies to clustered servers.

8. Click the Other tab, and complete any of these fields. Domino uses default values (if available) for
fields you do not modify.

Field Enter
Setup profile Name of an R5 User Setup profile to assign.
Note: If you are using policies, you cannot use a user setup profile.
Unique org unit A word that distinguishes two users who have the same name and are certified by
the same certifier ID.
Location Departmental or geographical location of the user.
Local administrator The name of a user who has Author access to the Domino Directory but who does
not have the UserModifier role. This setting allows the local administrator to edit
Person documents.
Comment A comment about the user, regarding the user’s registration.
Alternate name language Choice of alternate name language. The certifier ID used to register this user must
contain the alternate name language for it to appear here.
Alternate name The alternate name of the user. The certifier ID used to register this user must
contain the alternate name language for it to appear here.
Alternate org unit A word that distinguishes two users who have the same name and are certified by
the same certifier ID. The certifier ID used to register this user must contain the
alternate name language.
Preferred language Choose a preferred language for the user, that is, the language that the user prefers
to use.
Windows User Options Click to set user options for Windows 2000. Opens the ″Add Person to Windows
NT/2000″ dialog box on which you can specify whether to add the user to the
Windows 2000 Active Directory. Enter the Windows account name for the user, and
select the name of the Windows 2000 group to which you are adding the user.

9. Click the green check mark. The user name appears in the Registration status view (the user
registration queue).
10. Click Register and then click Done.

204 Lotus Domino Administrator 7 Help

Registering users with the Web Administrator
Registering users with the Domino Web Administrator is almost identical to registering users with the
Domino Administrator. Before reviewing this information and before attempting to register users via the
Web Administrator, you need to be familiar with using the Web Administrator and with Notes user
registration in general.

Note: The Registration Preferences (from File - Preferences - Administration Preferences) that can be set
for user registration with the Domino Administrator do not apply to user registration with the Web
Administrator. During user registration on the Web, only registration settings set through policies or
through the server-based CA apply. Other settings are entered manually or are defaults.

For more information on using the Web Administrator, see the chapter ″Setting Up and Using Domino
Administration Tools.″

Web registration and the server-based certification authority: Web registration for Notes users requires
the use of the Domino server-based certification authority (CA). You need to understand what the
Domino CA is, as well as how to set it up and use it.

To register users with the Web Administrator, the Web administrator must be listed as an RA for that
certifier. The server that is running the Web Administrator should also be listed as an RA but that role is
not required for the server. It is required for the administrator. If the server is not listed as an RA, the
administrator that is an RA will need to open the Administration Requests database and approve the
administration request to register the user. You must assign the RA role in the Domino Administrator
client, not in the Web Administrator. To assign the RA role, use the Modify Certifier tool on the
Configuration panel.

For more information on the server-based certification authority, see the chapter ″Setting Up a Domino
Server-Based Certification Authority.″

Web registration and policies: Web user registration, like user registration done from the Domino
Administrator, can be simplified by assigning policies during the registration process. Create the policies
and related policy settings documents, prior to initiating Web user registration. Before registering users,
familiarize yourself with polices in Lotus Domino as well as with using policies with the Web
Administrator.

The use of policies for user registration with the Domino Web Administrator is optional.

For more information on policies, see the chapter ″Using Policies.″

For more information on using policies with the Web Administrator, see the chapter ″Setting Up and
Using Domino Administration Tools.″

To register users with the Web Administrator: Follow the instructions to register a user, with basic or
advanced registration, in these procedures:
v Using Basic user registration with the Web Administrator
v Using Advanced user registration with the Web Administrator

Using Basic user registration with the Web Administrator

Perform Basic user registration from the Web Administrator to assign users’ basic settings, such as a
name and password, and to add users to existing groups from a Web browser instead of from the
Domino Administrator.

When using the Web Administrator client, you need to have set up a server-based certification authority
(CA) to register Notes users. The Web administrator, as well as the server on which the Web
Administrator database resides, must be listed as a registration authority (RA) for that certifier. You must

Chapter 6. Setting Up Notes Users and Clients 205

assign the RA role in the Domino Administrator client, not in the Web Administrator. To assign the RA
role, use the Modify Certifier tool on the Configuration panel.

For more information on the server-based CA and the RA, see the chapter ″Setting Up a Domino
Server-Based Certification Authority.″

Note: The Registration Preferences (from File - Preferences - Administration Preferences) that can be set
in user registration with the Domino Administrator do not apply to user registration with the Web
Administrator. During user registration on the Web, only registration settings set through policies or
through the server-based CA apply. Other settings are entered manually or are defaults.

To use Basic user registration with the Web Administrator:

1. Make sure you have the following before you begin registration:
v The [UserCreator] role in the Domino Directory.
v The registration authority (RA) designation for whatever CA (Certificate Authority) that is selected
for user registration. The Domino Web Administrator requires the user of the server-based CA.
2. From the Web Administrator click the People & Groups tab.
3. From the Servers pane, select Domino Directories, and then click People.
4. From the Tools pane, click People - Register.
5. Choose a CA Certifier.
6. (Optional) Choose an Explicit policy.
7. (Optional) If you would like the selections for CA Certifier and Explicit policy to be set as the
default, click the check box ″Save as default.″
8. Click OK.

Field Action
First name, Middle name, Last name Enter a first name, middle name (if necessary), and last
name.
Short name The user’s Short name is automatically generated. To
change the Short name, enter the new text.
Password Enter the password for the user ID. Criteria for this
password is based on the level set in the Password
Quality Scale in the Password Options dialog box.
Password quality Choose a password quality. The default level is 8. The
password you specify must correspond with the
password quality that you select in ″Password Options.″

206 Lotus Domino Administrator 7 Help

Field Action
Mail System Choose one of the available mail types and complete the
necessary associated fields:
v Lotus Notes (default).
v Other Internet -- choosing this option automatically
selects the ″Set Internet password″ check box.
v POP -- choosing this option automatically selects the
″Set Internet password″ check box.
v IMAP -- choosing this option automatically selects the
″Set Internet password″ check box.
v Domino Web Access -- You are prompted to make
other registration selections for iNotes.
v Other.

If you select Lotus Notes, POP, or IMAP, the Internet

address is automatically generated.

If you select Other Internet, POP, or IMAP, the Internet

password is set by default.

If you select Domino Web Access, you can change other

user registration selections to Domino Web Access
defaults by clicking Yes when prompted.

If you select Other or Other Internet, enter a forwarding

address. This address is the user’s current address, where
the user wants mail to be sent. For example, if a user
temporarily works at a different location and/or uses a
different mail system, the user can have her mail
forwarded to that new address. Or, a user may resign
from the company but leave a forwarding address so
that mail addressed to the old address is forwarded to
the new location.
Set Internet password Click to set an Internet password.
Create a Notes ID for this person Click to create a Notes ID.
Explicit policy (Optional) To assign a policy to this user, select one from
the Explicit policy list.

For more information on password quality scale, see the chapter ″Protecting and Managing Notes
IDs.″
9. Click the green check mark. The user name appears in the Registration status view (the user
registration queue). Or, click the red X to clear all fields and start over.
10. Click Register, and then click OK.

Using Advanced user registration with the Web Administrator

Advanced user registration from the Web Administrator offers all of the registration settings that are
included in Basic user registration from the Web Administrator, and also allows you to change default
settings and apply advanced settings to users.

When using the Web Administrator client, you need to have set up a server-based certification authority
(CA) to register Notes users. The Web administrator, as well as the server on which the Web
Administrator database resides, must be listed as a registration authority (RA) for that certifier. You must
assign the RA role in the Domino Administrator client, not in the Web Administrator. To assign the RA
role, use the Modify Certifier tool on the Configuration panel.

Chapter 6. Setting Up Notes Users and Clients 207

Note: The Registration Preferences (from File - Preferences - Administration Preferences) that can be set
in user registration with the Domino Administrator do not apply to user registration with the Web
Administrator. During user registration on the Web, only registration settings set through policies or
through the server-based CA apply. Other settings are entered manually or are defaults.

To use Advanced user registration with the Web Administrator:

1. Make sure you have the following before you begin registration:
v The [UserCreator] role in the Domino Directory.
v The registration authority (RA) designation for whatever CA (Certificate Authority) that is selected
for user registration. The Domino Web Administrator requires the user of the server-based CA.
2. From the Web Administrator, click the People & Groups tab.
3. From the Servers pane, select Domino Directories, and then click People.
4. From the Tools pane, click People - Register.
5. Choose a CA-configured certifier.
6. (Optional) Choose an Explicit policy.
7. (Optional) If you would like the selections for CA Certifier and Explicit policy to be set as the
default, click the check box ″Save as default.″
8. Click OK.

Field Action
First name, Middle name, Last name Enter a first name, middle name (if necessary), and last
name.
Short name The user’s Short name is automatically generated. To
change the Short name, enter the new text.
Password Enter the password for the user ID. Criteria for this
password is based on the level set in the Password
Quality Scale in the Password Options dialog box.
Password quality Choose a password quality. The default level is 8. The
password you specify must correspond to the password
quality that you select in ″Password Options.″

208 Lotus Domino Administrator 7 Help

Field Action
Mail System Choose one of the available mail types and complete the
necessary associated fields:
v Lotus Notes (default).
v Other Internet -- choosing this option automatically
selects the ″Set Internet password″ check box.
v POP -- choosing this option automatically selects the
″Set Internet password″ check box.
v IMAP -- choosing this option automatically selects the
″Set Internet password″ check box.
v Domino Web Access -- You are prompted to make
other registration selections.
v Other.

If you select Lotus Notes, POP, or IMAP, the Internet

address is automatically generated.

If you select Other Internet, POP, or IMAP, the Internet

password is set by default.

If you select Domino Web Access, you can change other

user registration selections to Domino Web Access
defaults by clicking Yes when prompted.

If you select Other or Other Internet, enter a forwarding

address. This address is the user’s current address, the
address to which the user wants mail to be sent. For
example, if a user temporarily works at a different
location and/or uses a different mail system, the user
can have her mail forwarded to that new address. Or, a
user may resign from the company but leave a
forwarding address so that mail addressed to the old
address is forwarded to the new location.
Set Internet password Click to set an Internet password.
Create a Notes ID for this person Click to create a Notes ID.
Explicit policy (Optional) To assign a policy to this user, select one from
the Explicit policy list.

For more information on password quality scale, see the chapter ″Protecting and Managing Notes
IDs.″
9. Click the Advanced check box to enable advanced settings.

Chapter 6. Setting Up Notes Users and Clients 209

10. Click the Mail tab and complete any of these fields.

Fields Action
Mail System Choose one of the available mail types and complete
the necessary associated fields:
v Lotus Notes (default)
v POP
v IMAP
v Domino Web Access
v Other Internet
v Other
v None
v If you select Lotus Notes, POP, or IMAP the Internet
address is automatically generated.
v If you select Other Internet, POP, or IMAP, the
Internet password is set by default.
v If you select Domino Web Access, you can change
other user registration selections to Domino Web
Access defaults by clicking Yes when prompted.

If you select Other or Other Internet, enter a

forwarding address. This address is the user’s current
address, the address to which the user wants mail to
be sent. For example, if a user temporarily works at a
different location and/or uses a different mail system,
the user can have her mail forwarded to that new
address. Or, a user may resign from the company but
leave a forwarding address so that mail addressed to
the old address is forwarded to the new location.
Mail Server Choose a server to be assigned as the user’s mail
server.
Mail file name The file name of the mail file. By default, the path and
the file name are
mail\<firstinitial><first7charactersoflastname>.nsf.
Mail template Choose a mail template from the list of available mail
templates. For a description of the template, select the
template and click About. The default is Mail(7)
(MAIL7.NTF).
Create full text index Click to generate a full-text index of the mail database.
Mail file owner access Select the level of access in the access control list to
assign to the user of the mail database from the Mail
file owner access list. By default, mail users have
Editor with Delete documents access to their own mail
files; all other users have no access. This option can be
used to prevent mail users and/or owners from
deleting their own mail file. If the mail owner access is
Designer or Editor, the administrator ID currently
being used is added to the mail file ACL as Manager.
Set database quota Click to enable, and then specify a size limit
(maximum 10GB) for a user’s mail database.
Set warning threshold Click to generate a warning when the user’s mail
database reaches a certain size, and then enter the
warning size (maximum of 10GB).

210 Lotus Domino Administrator 7 Help

11. Click the Address tab, and enter values in any of these fields.

Field Action
Internet address The Internet e-mail address assigned to this user.
Internet Domain The domain to be used in the Internet address -- for
example, Acme.com.
Address name format The format of the Internet address. The default format
is FirstNameLastName@Internet domain without a
separator -- for example, RobinRutherford@Acme.com.
Separator The character inserted between names and initials in
the Internet address. The default is None.

12. Click the ID Info tab, and enter values in any of these fields.

Field Action
Create a Notes ID for this person Click to create a Notes ID for this user.
Certifier name list Choose a certifier from the list if you are not creating a
Notes ID for this user.

This field is visible only if you do not select the check

box ″Create a Notes ID for this person.″
CA-configured certifier Choose a CA-configured certifier to use to register the
user.

This field is only visible if you select the check box

″Create a Notes ID for this person.″
Certificate expiration Choose one:
v Months -- Enter the number of months during which
the certifier is valid.
v Date -- Specify the date on which the certificate
expires. The default is two year’s from the current
date.

This field is only visible if you select the check box

″Create a Notes ID for this person.″
Security type Choose either North American or International. The
security type determines the type of ID file created and
affects encryption when sending and receiving mail and
encrypting data. North American is the stronger of the
two types.

This field is only visible if you select the check box

″Create a Notes ID for this person.″
Location for storing user ID Non-modifiable field that displays the location in which
the user’s ID will be stored.

This field is only visible if you select the check box

″Create a Notes ID for this person.″

13. (Optional) Click the Groups tab, and complete these options as desired:
v Enter a group name, or click Search to locate the group name, to which you want to add this user
as a member.
v Select the group or groups to which you want to add the user and click Add.
For more information on adding users to groups, see the chapter ″Setting Up and Managing
Groups.″

Chapter 6. Setting Up Notes Users and Clients 211

14. Click the Replica tab and enter values in any of these fields.

Field
Create replica(s) of mail database.
Select options for creation of mail database replicas
Actions
Click this check box to create replicas of the mail files on
additional servers that you specify.
Use these options as necessary:
v Add -- Click to open the Server for Mail File Replica
Creation dialog box. Use this dialog box to choose the
server(s) on which to create mail file replicas.
v Remove -- Choose one or more servers to remove from
the list of servers on which to create mail file replicas,
and then click Remove.
v Remove All -- Click to remove all servers from this
list.

These options are available only if the check box ″Create

replicas of mail database″ is selected.

15. Click the Roaming tab and enter values in any of these fields.

Field Action
Roaming user Click to activate the roaming user registration options to
register this user as a roaming user.
Put on mail server/ Choose one of these:
v Put on mail server -- Click to place the user’s roaming
Choose a server
files on the user’s mail server.
v Server name -- Click to store the user’s roaming file on
the ″Current Server″ or select another server of your
choice.
Personal roaming folder The subdirectory that contains the user’s roaming
information. By default, this is based on the sub-folder
format you specify, but you can customize it.
Sub-folder format The method used to name roaming subdirectories on the
roaming server. This determines the default Personal
roaming folder for each user.

212 Lotus Domino Administrator 7 Help

Field Action
Clean-up options Choose one of the following roaming user client clean-up
options. Clean-up will only occur on clients that have
been installed and configured for multiple users.
v Do not clean-up (default) -- Roaming user data is not
deleted from the Notes client workstation to which the
user roamed.
v Clean-up every -- Enables the ″Clean up every N
days″ field on which you specify the number of days
that should pass before roaming user data is deleted
from the Notes client workstation.
v Clean-up at Notes shutdown -- Roaming user data is
deleted from the Notes client workstation immediately
upon Notes shutdown.
v Prompt user -- The user is prompted on exiting the
client as to whether they want to clean up their
personal files. If the user chooses Yes, the data
directory on that client workstation is deleted. If the
user chooses No, the user is prompted as to whether
they want to be asked again on that client. If the user
chooses No, the user is not prompted again. If the user
chooses Yes, the user is prompted again the next time
the user exits the client on that workstation.

16. Click Register and Done.

Registering users from a text file

When registering users from a text file, you can import them through the Import Text File button on the
Register Person dialog box, which places users as entries in the User Registration Queue and allows you
to modify user settings individually.

If you want to add the text file to the NOTES.INI file so that Notes does not prompt you to browse for
the text file, enter BatchRegFile= filename to the NOTES.INI file.

You can also define a separator for the text file by adding BatchRegSeparator = character to the
NOTES.INI file. The separator character cannot be a character used in any of the user parameter settings
in the text file. If you do not specify a BatchRegSeparator, a semicolon (;) separator is used.

For more information on this NOTES.INI variable, see the appendix ″NOTES.INI File.″

Settings applied to a group of users: These user settings are available for you to modify before using
the menu (choose People - People - Register) to import and register users. Notes applies these settings to
all users in the group.
v Registration Server
v Password Quality Scale
v Set Internet password
v Internet address
v Internet Domain
v Format
v Mail server
v Mail file template
v Mail system
v Mail file name

Chapter 6. Setting Up Notes Users and Clients 213

v Mail file owner access
v Set database quota
v Set warning threshold
v Certifier ID
v Security type
v Certificate expiration date
v Store user ID in Domino Directory or File
v Add users to selected groups
v Local administrator
v Add NT User Accounts

Setting up the text file: To set up a text file, create a line in the text file for each user. Enter the
parameters for each user in exactly the order shown in the table below. Use one semicolon to separate
parameters, and use one semicolon to take the place of each contiguous parameter that you decide not to
specify.

For example, this line in a text file specifies only a last name and password:
Alexis;;;;password1

This line in a text file specifies a complete name, home server, and User Setup policies:
Alexis;Catherine;R.;;password1;;;Marketing / Acme;;;;;;Marketing Profile

Note that only the last name and password parameters are required.

Order Parameter Enter

1 Last name
2 First name
3 Middle initial
4 Organizational unit
5 Password
6 ID file directory
The last name of the user. This parameter is required.
The first name of the user.
The middle initial of the user.
A name for another level to add to the hierarchical name. This name
distinguishes between two users who have the same name and are certified
by the same certifier.
A password for the user. This parameter is required.
The directory in which you want to store the user’s ID. You can store the ID
in this directory in addition to or instead of as an attachment in the Domino
Directory.

7 ID file name
8 Mail server name
9 Mail file directory
10 Mail file name
You must create the directory before registration. For this parameter to take
effect, select the In File option on the ID Info panel for storing the user ID.
This parameter overrides the default ID directory shown in the Register
Person - New Entry dialog box.
The name you want to assign to the ID file. This file name applies only if
you store an ID in an ID file directory. If you do not specify a user ID file
name, the name on the ID is based on the person’s name.
The name of the user’s mail server. This parameter overrides the one you
select during registration.
The mail file directory for the user.
The name for the user’s mail file. If you do not use this parameter, the name
is based on the person’s name if the person uses Notes mail.

214 Lotus Domino Administrator 7 Help

Order Parameter Enter
11 Location Descriptive location information that is added to the user’s Person
document. If someone addresses mail to this user and there is another user
with the same name, Notes displays the location to help the sender
distinguish the two users.
12 Comment An identifying comment that is added to the user’s Person document.
13 Forwarding address The full route to the user -- for example, JSmith@acme.com. If you don’t
enter this information in the text file, you can edit the Forwarding address
field in the user’s Person document. This parameter is used only for Other
and Other Internet mail users.
14 Profile The name of the user setup profile.
15 Local administrator The name of a user who has Author access to the Domino Directory. This
person can modify the user’s Person document.
16 Internet address The Internet address of the user. This parameter is required for Lotus Notes,
POP3, Domino Web Access, and IMAP mail.
17 Short name This name is entered by default. A short name is used to create a return
Internet address if the Internet address is not entered.
18 Alternate name The alternate name of the user. Note that the certifier ID used to register this
user must contain the alternate name language.
19 Alternate org unit A word that distinguishes two users who have the same name and are
certified by the same certifier ID. Note that the certifier ID used to register
this user must contain the alternate name language.
20 Mail template file The file name of the mail template you want to use.

To register users from a text file: Notes uses the certifier ID specified in Administration Preferences; or
if there is none, it uses the ID specified in the CertifierIDFile setting of the NOTES.INI file.
1. Make sure that you have the following before you begin registration:
v Access to the certifier ID and its password if you are not using the Lotus Domino server-based
certification authority (CA)
v Editor access or the UserCreator role in the Domino Directory on the registration server
v Create new databases access on the mail server if you plan on creating mail files
2. Use a text editor to create a text file that contains ID information for each user.
3. From the Domino Administrator, click the People & Groups tab.
4. From the Servers pane, choose the server to work from.
5. Select Domino Directories and then click People.
6. Complete Step 7 or Step 8, depending on how you want to import and register users.
7. To register users and apply individual settings:
a. From the Tools pane, click People - Register. Enter the certifier password and click OK. The
Certifier Information Warning dialog box may appear. Click OK.
b. Click Import Text File, select the text file, and click Open.
c. To modify user registration settings, select a user from the User Registration Queue and make
your changes on the Register Person user interface.
d. Click Register to register the highlighted user or select multiple users in the registration queue and
click Register All. Click OK.
For more information on specifying registration settings, see the topic ″Using Advanced Notes user
registration″ earlier in this chapter.
8. To register users and apply settings to them as a group:

Chapter 6. Setting Up Notes Users and Clients 215

 a. Set the registration Administration Preferences and create the policies that you want to apply to a
group of users.
b. From the Tools pane, click People - Register.
c. Enter the certifier ID password and click OK.
d. Choose the Explicit Policy that you want to apply to the users you are registering.
e. Click Import Text File, select the text file, and click Open.
f. Click Register or Register All.
For more information on setting Administrator Preferences and Registration Preferences, see the
chapter ″Setting Up and Using Domino Administration Tools.″
For more information on the settings you can modify, see the topic ″Using Advanced Notes user
registration″ earlier in this chapter.

Adding an alternate language and name to a user ID

The alternate naming feature allows you to assign two names to a user: a primary name and alternate
name. The primary name is internationally recognizable; the alternate name is recognizable in the user’s
own native language. Before you can add an alternate name to a user, add an alternate language and
name to the certifier ID by recertifying the certifier ID. You cannot add alternate names to servers.

Alternate names are helpful because they let users use their native language and character set for display
and name lookup purposes. For example, a user can type in a name in a native language and character
set when sending mail or choose to display all documents in a database in a native language and
character set.

Each alternate name is associated with a language specifier that identifies the native language of the
name. Typically, the alternate name is specified in a character set consistent with the specified language;
whereas the primary name is specified in an internationally recognizable character set. Both types of
names provide the same security within the Domino system. Alternate names should not be used in
ACLs, Group documents, and Server documents.

You can add multiple alternate names to an organization certifier (as many alternate names as there are
language specifiers recognized by Notes). An organizational unit certifier may also contain multiple
alternate names, but each name must correspond to one of the language specifiers assigned to its parent
certifier. The organizational unit certifier does not need to contain all the language specifiers that its
parent contains. For example, /Acme may contain five language specifiers, while its child certifier
Sales/Acme contains a subset of those.

A user ID may contain only one alternate name. The language specifier associated with the alternate
name must correspond to a language specifier in the parent certifier ID. When you assign an alternate
name to a user, the alternate name and language specifiers are added to the user ID, to the Notes
certificates issued to the user, and to the user’s Person document.

Note: When assigning an alternate name, do not exceed 79 characters. When alternate names are
renamed, they are automatically truncated at 79 characters. Limiting the alternate name to 79 characters
prevents the name from being truncated because it does not exceed the 79 character limit.

To add an alternate name to a certifier ID: In this procedure, you assign an alternate name and its
associated language to the organization certifier ID and its organizational unit (child) certifiers through
the certification process. You first recertify the organization certifier, and then use the certifier to recertify
its organizational unit certifiers.
1. Have the certifier ID to which you want to add the alternate name accessible, if you are not using
the Lotus Domino server-based certification authority (CA).
2. From the Domino Administrator, click the Configuration tab.
3. Choose Certification, and then click Certify.

216 Lotus Domino Administrator 7 Help

 4. If the server name that is shown is not the registration server, click Server, choose the server you
want to use and click OK.
5. Do one of these:
v To use the server-based CA, click Use the CA process and select a CA-configured certifier from the
list.
v To use a certifier and password, click Supply certifier ID and password, click Certifier ID, select
the certifier ID, and then click OK. Enter the password and click OK.
6. Select the ID you want to recertify and then enter the password and click OK. To add an alternate
language and name to the organization (root) certifier, select the same ID that you chose in the
previous step.
7. Click Add.
8. Choose the alternate language in the Language field. If you are recertifying an organizational unit
certifier, the available languages include all languages associated with the organization (root) certifier
ID.
9. (Optional) Enter a country code for the organization. This option is available only for organization
certifier IDs.
10. Enter a name for the organization/organization unit in the Organization/OrgUnit field.
11. Click OK.
12. (Optional) To add another alternate language, click the Add button and repeat Steps 7 through 11.
13. Click Certify.

To add an alternate name to an existing user ID: Use the Lotus Domino server-enabled certification
authority (CA) or the certifier ID to recertify the user.
1. Make sure that the certifier contains an alternate name with the language specifier you want to use.
2. From the Domino Administrator, click the People & Groups tab.
3. From the Servers pane, choose the server to work from.
4. Click the Configuration tab.
5. Choose Tools - Certification - Certify.
6. If you are not using the Lotus Domino server-based certification authority (CA), select the certifier
ID that certified the user ID to which you are assigning an alternate name and enter the password.
Click OK.
7. Select the user ID to which you are assigning an alternate name and enter the password. Click OK.
8. Click Add. Select a language from the list and enter a new Common Name for that language, and
click OK.
9. (Optional) Specify a new certifier expiration date and a new password quality.
10. Click Certify.
11. You are prompted as to whether you want certify another, click Yes or No, accordingly.

To add an alternate name while registering a new user: Before you add an alternate name to a new
person, make sure you have a certifier that contains the alternate name and language specifier you want
to use. You assign the name and language in the Other pane of the Register Person dialog box during
advanced user registration.

For more information on advanced user registration, see the topic ″Using Advanced Notes user
registration″ earlier in this chapter.

Setting up client installation for users

Depending on the size of your enterprise, you may need to provide an installation method for only a few
users or for thousands of users. In addition, you may need to customize the installation process so that
users install only the features they need. After you register users, decide how to deploy client

Chapter 6. Setting Up Notes Users and Clients 217

installations for users. Users can install all three clients -- the Notes client, Domino Administrator client,
and Domino Designer® -- or they may install only one or two clients.

As an administrator, you can customize the installation process for your users so that they install the
features that they need. The installation information in this section ranges from installing the Domino
clients using the installation CD to creating transform files to customize the installation process.

Before you install Lotus Notes clients

Before you begin installing Lotus Notes clients, make sure that you or your users do the following:
v If the computer on which you are upgrading runs anti-virus software, close the application.
v If you are upgrading Lotus Notes on an Apple computer running OS X, turn off all options in the
Application Sharing tab of the Shared System Preferences panel to avoid any errors.
v To successfully install, upgrade, and use Lotus Notes 7, users must be allowed both Write and Modify
permissions to the Program directory, Data directory, and all associated subdirectories.
v If you are upgrading Lotus Notes on a Windows 2000 or XP computer, you must have administrator
rights to the system.
v Windows 2000 and XP users should log onto their computers with administrative rights to install Lotus
Notes 7. For cases in which administrative rights are not available, enable the setting ″Always install
with elevated privileges.″ The setting ″Always install with elevated privileges″ is a Windows setting
that is part of Window’s User Policies. Refer to your Microsoft Windows documentation for details.
Refer to the Release Notes for the most current information on permissions required when installing as a
non-administrator.
v Options for installing the Lotus Notes client on Restricted or Standard/Power User computers are
described in the Microsoft Windows 2000, Windows XP, and Windows Installer documentation.
v Review options for customizing the Notes client installing and set up.

Installation methods
Domino offers several methods or types of installation that you can make available to the Domino Notes
users in your enterprise.
v Single-user client installation -- This installation is usually done from the CD or from files placed on
the network.

For more information on installing the Domino administration client, see the chapter ″Setting Up and
Using Domino Administration Tools.″
v Multi-user installation -- This option is available only for Notes client installation. Multi-user
installation is not available for installing the Domino Administrator client or Domino Designer.

For more information on multi-user installation, see the topic ″Multi-user installation″ in this chapter.
v Shared installation -- This option installs all program files to a file server while the users’ data files
reside on their local workstations.

For more information on shared installation, see the topic ″Installing the Domino clients in a shared
network directory″ in this chapter.
v Automated client installations (silent installation) -- This option can be used with or without a
transform file depending on whether you want to customize the silent installation.
v Customized installations -- This option uses the transform file to customize the installation process.
v Batch file installation -- This option enables users to install the clients by running a batch file that you
create for them.
v Installation with command line utilities -- This option allows users to install the clients using a
command line utility that you provide for them.
v Scriptable setup -- This option uses a setting in the NOTES.INI file to provide information to the client
setup wizard.

218 Lotus Domino Administrator 7 Help

For information on multi-user installations, see Sharing a Computer with other users if you have installed
Lotus Notes 7 Help. Or, go to http://www.lotus.com/LDD/doc to download or view Lotus Notes 7
Help.

User installation/configuration related topics

v Instant Messaging and client installation and setup
v Custom welcome page deployment
v Deploying the ″My Work″ Welcome page for Notes

Single-user client installation

To perform a basic single-user installation, you use the Lotus Domino 7 CD to install the Notes client, the
Domino Administrator client or the Domino Designer client directly onto the user’s workstation.
1. Before you install the client program files on a Win32 system, do the following:
v Make sure that the required hardware and software components are in place and working.
v Read the Release Notes for disk-space requirements and for any last-minute changes or additions to
the documentation.
v Temporarily disable any screen savers and turn off any virus-detection software.
v Make sure that all other applications are closed. Otherwise, you may corrupt shared files, and the
Install program may not run properly.
v If you are upgrading to Domino from a previous release, see the Upgrade Guide.
2. Run the client install program (SETUP.EXE), which is on the installation CD.

Installing the Domino clients in a shared network directory

As an administrator, you can offer a shared network installation to your users. In a shared network
installation, all program files are installed on a file server, and the users’ data files reside on their local
workstations. Multi-user installation is neither supported in a shared file configuration nor available for
use on Macintosh computers.

During the installation of the network image, all program files for Lotus Notes, Domino Administrator,
and Domino Designer are installed. To run Lotus Notes, Domino Administrator and Domino Designer
client installs from one set of program files on a file server, you create multiple transform files.

Note: To perform a shared installation and run the transform file, end-users must have the Windows
Installer service on their workstations.

After you install the program files to a directory on a server, users can run a shared version of the
software, thereby saving on disk space usage. However, if the server is unavailable, users cannot run
Notes. When users install Notes from this directory, only the data files (DESKTOP.DSK,
BOOKMARK.NTF, and all local databases) are copied to their workstations. The program files remain on
the server, where they are shared among all users. As users run Notes, the program files are read into
memory on their workstations.

Assign to those users who install Notes client software from the file server ″Read″ access to the directory
containing the files.

Note: Set the access to the administrator image on the network to ″Read Access″ -- that is the only
supported access.

Upgrading shared installations: Do not attempt to upgrade over existing network image files. To
upgrade an existing network image, delete all files in the existing network image and install the new
network image files to the same location.

To set up the shared network installation:

1. Before you begin this installation process, do the following:

Chapter 6. Setting Up Notes Users and Clients 219

 v Make sure that the required hardware and software components are in place and working.
v Read the Release Notes for disk-space requirements and for any last-minute changes or additions to
the documentation.
v Temporarily disable any screen savers and turn off any virus-detection software.
v Make sure that all other applications are closed. Otherwise, you may corrupt shared files, and the
Install program may not run properly.
2. Log on as administrator on the drive on which you are installing the program files.
3. From the command line, use this syntax to run setup and create the administrator image on the
network:
E:\path to install kit\setup /A
In this example, drive E represents the drive on which the client installation files are located, which is
usually the drive letter of the CDROM drive containing the Domino CD. The /A creates the
administrator image on the network.
4. Enter the name of the directory that will store the installed files. By default, this directory is the first
network drive accessible from your workstation. To specify a network drive and directory other than
the default, click Change.
5. Click Install. Every client option is installed. A directory structure that is useable and understandable
by the operating system is created. Users can run the install program directly from this directory
structure that you provide using the Lotus Notes 7.msi file created in the root of the directory
structure.
6. Create a transform file for the installation of the end user’s local data files.
For more information on creating a transform file, see the topic ″Creating a transform file″ in this
chapter.

Providing an installation tool (method) for the users: After successfully installing all client files to a
shared directory on the network, you can instruct users to use the transform file to install the client on
their own workstations.

Automating client installation

Automated client installation supports the three Domino clients and simplifies installation for end users
because it presents very few or none of the installation windows; thus, it is called a silent installation.

Before you begin this installation process, do the following:

v Ensure that the required hardware and software components are in place and working.
v Read the Release Notes for disk-space requirements and for any last-minute changes or additions to
the documentation.
v Temporarily disable any screen savers and turn off any virus-detection software.
v Ensure that all other applications are closed. Otherwise, you may corrupt shared files, and the Install
program may not run properly.

To use silent installation: Use one of the three setup commands shown below.
v Use this format to run the install in silent mode without a progress bar:
Setup.exe /s /v"/qn"
When the installation is complete, the shortcut icons appear on the desktop.
v Use this format to display a message when the installation is complete or it has failed. Use the +
parameter as follows:
Setup.exe /s /v"/qn+"
v Use this format to display a progress bar during the installation, in addition to displaying the message
indicating that the installation is complete or it has failed. Use the b parameter as follows:
Setup.exe /s /v"/qb+"

220 Lotus Domino Administrator 7 Help

Running a silent install provides users with the default installation options. To customize the type of
installation or to specify options to install on the user’s system, use a transform file with the silent install.

For more information on how to use a transform file during silent client installs, see the topic ″Using
transform files for end-user installations.″

Multi-user installations
Multi-user installation applies to Microsoft Windows (Win 32) users only. The multi-user installation is
only supported for the Notes client installations; it is not supported for installing the Domino
Administrator client or the Domino Designer. Therefore, the multi-user option is only available in the
Notes installation kit.

Use the multi-user installation if your enterprise has multiple users who share a single workstation. Then
when users log onto the system, they run the Lotus Notes 7 client setup and their own personal data files
-- that is, BOOKMARK.NSF, NAMES.NSF, and other files are created.

The multi-user installation differs from a shared installation in that Program files are located on the local
system in a multi-user install, which can be an advantage. This allows for access to the Notes client
regardless of which network drives are available. In a shared installation, users are dependent on the
availability of shared network drives.

In a multi-user installation, install the Domino Program files to a central location on the local system.
Each user has their own data directory located in the system’s application data directory for the current
user. The actual location varies as follows according to operating system:
v Example 1 -- c:\Documents and Settings\user\Local Settings\Application Data\Lotus\Notes Data
v Example 2 -- c:\winNT\Profiles\user\Local Settings\Application Data\Lotus\Notes Data
v Example 3 -- c:\Bin\Win95\Profiles\user\Local Settings\Application Data\Lotus\Notes Data

Each user’s individual data files are created when the user logs on to the workstation, launches the Lotus
Notes 7 client, and completes the client setup. The multi-user option is only visible to those users with
administrative privileges on the local system. This installation option is not enabled for other users.

Note: Individual Location documents are no longer needed for each user that utilizes the Notes client on
the same workstation, as compared to previous releases where individual Location documents had to be
created for each user when multiple users attempted to use the same Notes client installation on a
workstation.

Multi-user install with multiple language Notes clients: You can install multiple copies of the Notes
client in multiple languages on one operating system. The language files are installed in each
MUI\language directory. For example, in a multi-user installation, if you first install a French Notes client
and then install a Japanese Notes client the user interface (UI) files are installed in individual directories
such as these:
\Program Files\Lotus\Notes\MUI\fr
\Program Files\Lotus\Notes\MUI\ja

The templates, modem, and help files are installed in the next directory, as shown
\Document Setting\All Users\Application Data\Lotus\Data\Shared\mui\fr
\Document Setting\All Users\Application Data\Lotus\Data\Shared\mui\ja

When a user starts the Notes client for the first time, the UI and database language are determined by the
user’s locale setting. If the locale language is not found in the directory \mui, the English user interface is
used and English databases are created to set up the Notes client.

Chapter 6. Setting Up Notes Users and Clients 221

Providing a Batch file for installing the Domino Notes clients
Create a batch file that installs the Domino clients to a user workstation. User’s can then install the client
by running the batch file.

Sample batch file:

msiexec /i "Lotus Notes 7.msi" TRANSFORMS="custom.mst"

Providing command line utilities for installation

Provide command line utilities so that users can install one or more clients on their workstations. This
table presents sample command line utilities that you can modify to suit your needs.

Type of install Sample command line utility

Transform install msiexec /i ″Lotus Notes 7.msi″
TRANSFORMS=″custom.mst″
Transform silent install msiexec /i ″Lotus Notes 7.msi″ /qn
TRANSFORMS=″custom.mst″
Silent install with fail/success prompt msiexec /i ″Lotus Notes 7.msi″ /qn+
Silent install setup.exe /s /v″/qn″
Verbose logging setup.exe /v″/L*v c:\temp\install.log

Customizing client installations

Client installs can be customized to allow you, the administrator, to control the options that are installed
and/or available to users. Use transform files to deselect options -- for example, modem files -- that you
don’t want to install by default. You also use transform files to hide the options that you do not want
users to change -- regardless of whether you choose to install a particular option. Modify the Visible and
Initial State settings for each installation option that you want to designate as hidden or not hidden.

For more information on what you can customize, see the topic ″Installation options available using the
transform file″ in this chapter.

If you prefer, you can allow the user to see and complete most of the fields on numerous windows that
can be displayed during the installation process.

For more information on transform files, see the topics ″Creating a transform file″ and ″Using transform
files for end-user installations″ in this chapter.

Creating a transform file: Creating a transform file requires a third-party tool such as InstallShield
Tuner OEM Edition. Lotus Domino 7 contains a version called InstallShield Tuner for Lotus Notes, that
you can use with Domino to create a transform file to customize the installation process, that is, to add
resources, change defaults, or hide features present in the standard Lotus Notes kit.

Note: The version of InstallShield Tuner for Lotus Notes that is included with Domino works only with
Lotus Domino, not with other products. You can use transform files to set up shared and customized
installations. Access their Web site at http://www.installshield.com for further information.

How to install the InstallShield Tuner for Lotus Notes: From the Lotus Domino 7 installation CD, in the
Apps/InstallShield Tuner for Lotus Notes directory, run the setup file, SETUP.EXE.

How to create a transform file: Use this procedure to create a transform file with InstallShield Tuner for
Lotus Notes. Users can then apply the transform file when installing clients.

For more information on shared installations, see the topic ″Installing the Domino clients in a shared
network directory″ in this chapter.

222 Lotus Domino Administrator 7 Help

1. Invoke the InstallShield Tuner program and browse to locate the configuration file that has a .itw file
name extension. The .itw configuration file is located in the same directory with the Notes installation
that you want to configure.
2. Click Create a new transform file.
3. In the Select an MSI file field for the Windows Installer Package option, select the msi file (Lotus
Notes 7.msi).
4. In the New project name and location field for the Windows Installer Transform option, enter the
custom transform name. Save the file to the same path on which the install kit resides.
5. Click Create.
6. Make any other desired modifications to the default settings provided.
7. Click Save.
For more information on transform files, see the topics ″Installation options available using the
transform file″ and ″Using transform files for end-user installations″ in this chapter.

After creating the transform file, you apply the transform file to the installation process. The installation
process then uses the values that you set in the transform file in place of default values.

Installation options available using the transform file: Using a transform file, you can customize
installation for the users in your enterprise.

Customizing the location of the Install directories: Use this procedure to specify a location other than the
default location in which to store the installation directories. When specifying directory names, use names
that contain eight or fewer characters.
1. From Application Configuration, select Setup Properties.
2. Click Add/Remove Program Settings.
3. Change the PROGDIR property to the location in which you are storing the program files.
4. Change the DATADIR property to the location in which you are storing the data files. This is the new
default data directory.

Setting the installation to Multi-User by default: In a multi-user installation, the administrator installs the
Domino Program files to a central location on the local system. Each user has their own data directory
located in the system’s application data directory for the current user.

Note: End-users must have Administrator rights to choose a multi-user installation and must only install
the Notes Client. End-users must also have Administrator rights to upgrade an existing multi-user
installation.
1. From Application Configuration, select Setup Properties.
2. Change the value in the ApplicationUsers property to AllUsers. By default the installation is now a
multi-user installation.
For more information on multi-user installation, see the topic ″Multi-user installations″ in this chapter.

Adding custom files to a client installation: To add custom files to a client installation, create a transform
file.

Note: This customization option replaces the COPYFILE.TXT feature that was available in previous
releases of Lotus Domino.
1. Copy the custom files to the install directory or place them in a directory within the install directory
-- for example, PathToInstallKit\AllClient\CopyFiles\custom.mdm.
2. Click Target System Configuration - Files.
3. In the top pane, click Browse and locate the source directory, which is the directory from which you
are copying the custom files.

Chapter 6. Setting Up Notes Users and Clients 223

4. In the bottom pane, select the destination directory, for example,
ProgramFiles\Lotus\notes\Data\modems.
5. Drag and drop the custom file from the source directory to the destination directory.

Applying NOTES.INI settings during Notes client installation:

1. Open InstallShield Tuner(6) for Lotus Notes.
2. From the System Configuration section, click the IniFiles item in the System Configuration section.
3. In the center pane, right click Destination Computer and then choose Show Folder - Program Files
Folder.
4. Expand the Program Files Folder directory to access the Lotus\Notes folder
5. Right click the Notes folder and then choose the option, New Inifile.
6. Locate the default notes.ini file, INIFILE1.INI, that was created in the Notes folder. Rename this file
with the name NOTES.INI.
7. Locate the default section, NewSection1, that was created for the NOTES.INI file. Rename the default
section with the name Notes.
8. Select the Notes section and then modify these values that are located in the right-most pane of the
Tuner:
v In the column titled Key, locate New Key and modify the name using an appropriate value such
as ConfigFile.
v In the column titled Value, locate New Value and modify the name using an appropriate value
such as n:\config\setup.txt.
v Verify that the Action value is set to the default value, Add Line.
9. Locate the Additional Tools section, and then click the Direct Editor item in the Additional Tools
section.
10. In the center pane, select the Component table, and then scroll down the component list until you
locate CST_COMPONENT.
11. Change the value in the Directory_ column from NOTES to the new value VDIR_INI.
12. In the center pane, select the table, IniFile, and then scroll down the component list until you locate
CST_INIFILE.
13. Change the value in the DirProperty column from NOTES to the new value VDIR_INI.
14. Make other modifications if necessary.
15. Click Save.

Examples -- Applying scriptable setup using a transform file during Notes client installation: You can
apply NOTES.INI settings during a client install by using a transform file. You can use this example
when setting up a transform file that applies NOTES.INI settings during Notes client installations.

Example 1 -- Including instant messaging parameters in a scriptable setup: You can include instant messaging
information during a scriptable setup of Notes client. The scriptable setup includes a setting that provides
information to the Notes client setup wizard. In this example, add the NOTES.INI setting, CONFIGFILE=,
to point to a text (.txt) file that contains the parameters for the Notes client setup wizard.

The SETUP.TXT file can be placed on shared network resource or distributed to individual workstations.

Note: If you decide that you want to distribute new or modified NOTES.INI settings using a transform
file, use the same method and steps that are explained in this example.

In this example, you need to complete these procedures:

1. Create a SETUP.TXT file.
2. To allow the new SETUP.TXT file to be referenced, open the file, NOTES.INI, and add this setting:
ConfigFile=\\PathToFile\Setup.txt

224 Lotus Domino Administrator 7 Help

3. Use the InstallShield Tuner (6) for Lotus Notes to set up a transform file to distribute the new
ConfigFile= setting in the NOTES.INI file.
4. After completing Steps 1, 2 and 3 above, proceed to the subtopic To apply a transform.

Creating the SETUP.TXT file: Create a SETUP.TXT file using the parameters shown below. Save your file
using the filename SETUP.TXT.
v IM.server=ServerName1.domain.com
v IM.port=1533
v IM.ConnectWhen=0
v IM.Protocol=0
For information about the scriptable setup parameters that you can use in a SETUP.TXT file, see the
topic ″Setting up Notes with a scriptable setup″ in this chapter.

To distribute the CONFIGFILE= parameter to the NOTES.INI file, use the InstallShield Tuner for Lotus
Notes application to create a transform file (.MST). The Tuner is located in the \Apps directory on the
Lotus Notes installation CD.

Setting up the transform file to apply the modified NOTES.INI file: To set up the transform file to distribute
the NOTES.INI settings, use the procedure in the topic ″Installation options available using the transform
file.″

Example 2 -- Disabling instant messaging using a scriptable setup: You can disable instant messaging during
a scriptable install of the Notes client. To do so, you need to complete these steps
1. Create a file, SETUP.TXT, that contains the following parameters and values:
v IM.Server=fakeservername
v IM.Port=80
v IM.Protocol=1
2. Store the file SETUP.TXT, on a shared network resource or distribute the file to individual
workstations
3. Add this setting to NOTES.INI file, ConfigFile=\\PathtoFile\SETUP.TXT, indicating the file is on a
shared network drive.
4. To protect against a user clicking the instant messaging buttons in the Notes client, implement a
desktop policy that sets the Sametime Server field to empty (no server name entered). In the desktop
policy settings document, be sure the Sametime Server field on the Basics tab is empty. This policy
will overwrite the fake server name in the SETUP.TXT file; therefore, Notes does not attempt to
connect to a Sametime server.
5. To ease distribution of this new setting in the NOTES.INI file, use the IS Tuner for Lotus Notes
application to create a transform file. The application is in the directory \apps on the Notes/Domino
install CD.

For more information about using the IS Tuner for Lotus Notes application to create transform files, see
the topic ″Customizing client installations″ in this chapter.

Parameter and value Explanation

IM.Server=fakeservername If you do not enter a value for the IM.Server, the user
will be prompted to do so during the install process.
Specifying a ″fake″ server name prevents the user from
being forced to enter a server name or cancel the install.
IM.Port=80 The IM port number. This can be any positive number.
IM.Protocol=1 Defines whether you connect directly to IM server.
IM.Protocol=1 connects directory to the IM server.

Chapter 6. Setting Up Notes Users and Clients 225

For more information about the parameters in the table, see the topic ″Setting up Notes with a scriptable
setup″ in this chapter.

Using transform files for end-user installations: After creating a transform file, you can use that file for
end-user client installations.

To apply a transform: This section contains two sets of instructions. The first set explains how to apply a
transform file for a user interface (UI) installation -- that is, an installation that presents a user interface.
The second set explains how to apply a transform file for a silent install -- that is, an installation that
does not present a user interface and therefore does not require any user interaction. There is also a
section on using a batch file to launch the command.

For installations using the transform file (and for silent installations) using the msiexec commands, the
network installation should not be the first installation of Notes that you perform unless you are certain
that all of the client workstations contain the Windows Installer Service.

Note: The command line path is the default installation path or the path for the transform file.

User interface (UI) installation

In this example, the ″progdir″ parameter and the ″datadir″ parameter are used to overwrite the default
settings designated by the transform file.
1. Change to the install directory that contains both the Lotus Notes 7.msi and the transform, *.mst, files.
2. Do one of these:
v To install to the default Program and Data directories, enter this command from the command line:
msiexec /i "Lotus Notes 7.msi" TRANSFORMS="custom.mst"
v To overwrite the default Program and Data directories with the ones you specify, enter this
command from the command line:
msiexec /i "Lotus Notes 7.msi" PROGDIR=C:\Test DATADIR=C:\Test\Data TRANSFORMS="custom.mst"

Applying a transform to a silent installation

1. Change directory to the install directory that contains both the Lotus Notes 7.msi and the transform,
*.mst, files.
2. Do one of these:
v If you want to install to the default Program and Data directories, enter this command from the
command line:
msiexec /i "Lotus Notes 7.msi" /qn TRANSFORMS="custom.mst"
v If you want to overwrite the default Program and Data directories with the ones you specify, enter
this command from the command line:
msiexec /i "Lotus Notes 7.msi" /qn PROGDIR=C:\Test DATADIR=C:\Test\Data TRANSFORMS="custom.mst"
For more information on silent installations, see the topic ″Automating client installation″ in this
chapter.

Using a batch file to deploy command line options when applying a transform file

You can also create a batch file that the user launches to start the command. A sample batch file is shown
below:

Sample batch file

msiexec /i "Lotus Notes 7.msi" TRANSFORMS="custom.mst"

226 Lotus Domino Administrator 7 Help

Using the SETUP.INI file setting to apply one transform file to all client installs: Use a setting in the
SETUP.INI file in the install directory to apply one transform file to all installs. Using this method
prevents the end user from having to enter a command line parameter or from using a batch file.

Modify the command line in the SETUP.INI to read as follows:

CmdLine+/l*v %TEMP%\notes6.log TRANSFORMS=custom.mst

The transform file is applied when SETUP.EXE is launched.

Setting up Notes with a scriptable setup

The scriptable setup option uses a setting in the NOTES.INI file to provide information to the client setup
wizard. During installation, the wizard displays only those panels that users need to set up the Notes
client. The NOTES.INI setting ConfigFile= points to a text (.TXT) file that contains the parameters that the
wizard needs. The wizard reads the text file and completes the setup. The user is able to bypass the
wizard screens for which parameters have been provided by the text file.

The settings and parameters that you can use in the text file are listed in this table:

Setting Description
Username User’s hierarchical name -- for example, John
Smith/Acme
KeyfileName Directory path to the user’s ID file name --for example,
c:\program files\lotus\notes\data\jsmith.id
Domino.Name Domino server in the same domain as the user name.
You do not need to enter a hierarchical name.
Domino.Address An address for the Domino server, such as the IP address
of the server, if needed, to connect to the server. For
example, server.acme.com or 123.124.xxx.xxx
Domino.Port Port type, such as TCPIP
Domino.Server 1 to connect to the Domino server, 0 for no connection
AdditionalServices 1 forces display of the ″Additional Services″ panel even
if sufficient information is provided for these services;
the Additional Services panel lists Internet, proxy, and
replication settings.
AdditionalServices.NetworkDial To configure a network dialup connection to Internet
accounts created via Additional Services dialog box
Mail.Incoming.Name Incoming mail account name, a friendly name used to
refer to these settings
Mail.Incoming.Server Incoming mail (POP or IMAP) server name
Mail.Incoming.Protocol 1 for POP; 2 for IMAP
Mail.Incoming.Username Mail account user name or login name
Mail.Incoming.Password Mail account password
Mail.Incoming.SSL 0 to disable; 1 to enable the SSL protocol for incoming
Internet mail
Mail.Outgoing.Name Outgoing mail account name, a friendly name used to
refer to these settings
Mail.Outgoing.Server Outgoing mail (SMTP) server name
Mail.Outgoing.Address User’s Internet mail address, such as user@isp.com
Mail.InternetDomain Internet Mail domain name such as isp.com

Chapter 6. Setting Up Notes Users and Clients 227

Setting Description
Directory.Name Directory account name, a friendly name used to refer to
these settings
Directory.Server Directory (LDAP) server name
News.Name News account name, a friendly name used to refer to
these settings
News.Server News (NNTP) server name
NetworkDial.EntryName Name of remote network dialup phone book entry
NetworkDial.Phonenumber Dial-in number
NetworkDial.Username Remote network user name
NetworkDial.Password Remote network password
NetworkDial.Domain Remote network domain
DirectDial.Phonenumber Phone number of Domino server
DirectDial.Prefix Dialup prefix, if required. For example, 9 to access an
outside line.
DirectDial.Port COM port to which the modem is connected
DirectDial.Modem File specification of modem file
Proxy.HTTP HTTP proxy server and port -- for example,
proxy.isp.com:8080
Proxy.FTP FTP proxy server and port -- for example,
proxy.isp.com:8080
Proxy.Gopher Gopher proxy server and port -- for example,
proxy.isp.com:8080
Proxy.SSL SSL proxy server and port -- for example,
proxy.isp.com:8080
Proxy.HTTPTunnel HTTP tunnel proxy server and port -- for example,
proxy.isp.com:8080
Proxy.SOCKS Socks proxy server and port -- for example,
proxy.isp.com:8080
Proxy.None No proxy for these hosts or domains
Proxy.UseHTTP Use the HTTP proxy server for FTP, Gopher, and SSL
security proxies
Proxy.Username User name if logon is required
Proxy.Password User password
Replication.Threshold Transfer outgoing mail if this number of messages held
in local mailbox
Replication.Schedule Enable replication schedule
IM.Server IBM Lotus Instant Messaging server name required
unless you have set the NOTES.INI variable
IM_NO_SETUP= 1. To use this NOTES.INI variable, you
must also use InstallShield Tuner which is included on
the Notes/Domino CD.

When this variable is set to 1, the IM Configuration

dialog box does not display during new client setup or
client upgrade, and all IM variables in a scriptable client
setup are ignored. If the user wants to configure IM, they
can leave the NOTES.INI variable out of their
NOTES.INI file or set it to 0 (IM_NO_SETUP=0).

228 Lotus Domino Administrator 7 Help

Setting Description
IM.Port IBM Lotus Instant Messaging server port (any positive
number)
IM.ConnectWhen (Optional setting) Defines when to connect to IBM Lotus
Instant Messaging:
v 0 -- At Notes login (default)
v 2 -- Manually
IM.Protocol Use one of these:
v 0 -- Directly to IBM Lotus Instant Messaging server
v 1 -- Directly to IBM Lotus Instant Messaging server
using HTTP protocol
v 2 -- Directly to IBM Lotus Instant Messaging server
using IE HTTP settings
v 3 -- Use a proxy
IM.ProxyType Required if IM.Protocol is set to 3. Use one of these:
v 0 -- SOCKS4 Proxy
v 1 -- SOCKS5 Proxy
v 2 -- HTTPS Proxy
v 3 -- HTTP Proxy
IM.ProxyServer Required if IM.Protocol is set to 3. Name of IBM Lotus
Instant Messaging proxy server
IM.ProxyPort Required if IM.Protocol is set to 3. Port of IBM Lotus
Instant Messaging proxy server (any positive number)
IM.ServerNameResolve Only used if IM.ProxyType is 1 (SOCKS5) but it is not
required. Use one of these values:
v 0 -- Disable IM.ServerNameResolve
v 1 -- Enable IM.ServerNameResolve
IM.ProxyUsername Required if IM.Protocol is set to 3 and IM.ProxyType is
not SOCKS4

Sample Scriptable Setup file: This is a sample scriptable setup file for a LAN connection. All options
are used in this sample file. Username = Joe Employee
KeyFileName=G:\shareddrive\userid\jemployee.id
Domino.Server=1
Domino.Name=servername/domain (For example, server1/sales/enterprise)
Domino.Port=TCP/IP
IM.Server=servername.misc.domain.com
IM.Port=12345
IM.ConnectWhen=2
IM.Protocol=3
IM.ProxyType=2
IM.ProxyServer=sametimeproxy.domain.com
IM.ProxyPort=789
IM.ServerNameResolve=0
IM.ProxyUsername=joeemployee
AdditionalServices=0
Mail.Incoming.Protocol=2
Mail.Incoming.Name=INCOMING INET MAIL

Chapter 6. Setting Up Notes Users and Clients 229

Mail.Incoming.Server=servername.misc.domain.com
Mail.Incoming.Username=jemployee
Mail.Incoming.Password=xyz123
Mail.Incoming.SSL=0
Mail.Outgoing.Name=OUTGOING INET MAIL
Mail.Outgoing.Server=servername.misc.domain.com
Mail.Outgoing.Address=joeemployee@domain.com
Mail.InternetDomain=misc.domain.com
AdditionalServices.NetworkDial=1
NetworkDial.EntryName=TEST 1 Dial-up Connection
NetworkDial.Username=jemployee
NetworkDial.Password=xyz123
NetworkDial.Phonenumber=area code-phone-number (For example, 508-123-4567)
NetworkDial.Domain=domainname
News.Name=NEWS SERVER ACCOUNT
News.Server=server.domain.com
Directory.Name=LDAP DIRECTORY SERVER ACCOUNT
Directory.Server=name.misc.domain.com
Proxy.UseHTTP=0
Proxy.HTTP=proxy.domain.com:8080
Proxy.FTP=proxy.fake.com:8080
Proxy.Gopher=proxy.fake.com:8080
Proxy.SSL=proxy.fake.com:8080
Proxy.SOCKS=proxy.domain.com:1080
Proxy.HTTPTunnel=proxy.domain.com:8080
Proxy.None=domain.com
Replication.Threshold=3
Replication.Schedule=1

Instant messaging and client installation and setup

Instant messaging (IM) allows users to see their co-workers online and to send them instant messages.
Users can also start instant online meetings among three or more co-workers.

Instant messaging is included in the Notes client installation, and is installed when you install the Notes
client. During the Notes client configuration, the Lotus Notes Client Configuration dialog box displays
the check box ″Setup Instant Messaging″ that allows you to specify whether to set up IM during Notes
client setup. By default, the check box is selected to enable the setup of IM. You can deselect that check
box to prevent IM from being set up for users.

Enabling Single Sign-On for instant messaging: As an administrator, you can include IM in single
sign-on with Lotus Notes and push this feature down to users through dynamic configuration. To enable
IM with single sign-on for users, use the NOTES.INI variable, IM_ENABLE_SSO=1. If this variable is set
to 1, IM with single sign-on is enabled; if this variable is set to 0 (zero), IM with single sign-on is disabled
and the user must enter their instant messaging password. There is also a setting on the User Preferences
dialog box that users can set to designate whether they want to use the single sign-on feature, allowing
then to log on once and still connect to multiple applications and servers.

For more information on the NOTES.IN variable, see the appendix ″NOTES.INI File.″

Scriptable setup and instant messaging: If you are using scriptable setup to configure newly installed
clients, IM can be included in the scriptable setup. There are several variables that you use to define the
IM settings for users.

230 Lotus Domino Administrator 7 Help

For more information about using scriptable setup with IM, see the topic ″Setting up Notes with a
scriptable setup″ in this chapter.

Name awareness in view columns and names fields: When Notes displays the online status for a
name, it passes that name as displayed, to the Sametime server for lookup in the Sametime server’s
directory. Usually this is the Notes abbreviated format (for example, John Smith/Austin/Acme), although
exceptions can be found in email because email names can be received from the Internet. In order for the
name to be found in the directory that the Sametime server uses, the directory needs to support a lookup
of a Notes abbreviated name. If the directory that the Sametime server uses is a Domino directory, this
occurs by default. However, if the directory that the Sametime server uses is an LDAP directory, you may
need to configure how the Sametime server performs a name lookup with the LDAP server. You may also
need to ensure that the LDAP directory has a Notes abbreviated name attribute for each of its entries.

For more information about using LDAP with a Sametime server, see the topic ″Configuring the LDAP
Searching Setting″ in the Lotus Sametime Administrator’s Guide. You can download or view the Lotus
Sametime Administrator’s Guide from the Documentation Library of the Lotus Developer Domain at
http://www.lotus.com/ldd/doc.

Instant messaging and policies: Use the desktop policy settings document or the setup policy settings
document to specify a Sametime server for users. Enter the server name in the Sametime server field.
When pushed down to the users, this setting populates the field ″Sametime server″ in the users’ Location
documents. The user can, however, enter a different server name in that field on the Location document
to override the setting from the policy document. The server specified in the Sametime server field is the
server that the user will access for instant messaging. If no server name is entered in this field, the user is
unable to log on to IM. The user would then have to review the settings on the Instant Messaging tab of
their Location document, and make the necessary corrections.

For more information about using policies, the desktop policy settings document and the setup policy
settings document, see the chapter ″Using Policies.″

Using Notes Client single logon to synchronize Notes and OS passwords

If your Notes users Microsoft Windows passwords are synchronized with their Notes passwords,
allowing them to use the same password for both Notes and their operating system you (or they) must
have selected the custom feature ″Client Single Logon″ while installing Notes.

Note: If the feature is not installed, you don’t have to uninstall Notes -- you can use Add/Remove
Programs in Windows to change the current installation. See the topic ″To install and enable single logon″
in the Notes client documentation.

The user’s computer’s name cannot be the same as the operating system (OS) login name when using
Client single logon. The Domino/Notes Client Single Logon feature does not work when the OS login
name is identical to the computer name, and the user logs in with the OS name. If Client Single Logon is
not working properly on a user’s system, change the OS login user name or the user’s computer’s name.

For information on how to change either name, refer to your Microsoft Windows documentation, or see
your Network Administrator.

OS and Domino password policies must be aligned as closely as possible to allow password
synchronization to work. During OS password changes, the Notes Network Provider must be able to
change the Notes ID to the new password provided by the OS. Notes is notified of the new OS password
only after the OS password has been changed. If the new OS password does not meet the Notes
password quality and history requirements, the Notes password change will fail.

During Notes password changes, the Notes Client must be able to change the OS password to the new
Notes password. If the new Notes password does not meet the OS password quality and history
requirements, the OS password change will fail.

Chapter 6. Setting Up Notes Users and Clients 231

For bidirectional password synchronization, the Notes Network Provider must be able to access a user’s
NOTES.INI file and Notes ID file. The table below shows the required location for the NOTES.INI file
according to type of installation:

Install Type Location

Single User The NOTES.INI file must exist in the Notes directory as specified in the
HKEY_LOCAL_MACHINE registry key.
Multi User The NOTES.INI file must be specified in the HKEY_USERS registry key:
(″<sid>\SOFTWARE\Lotus\Notes\7.0\NotesIniPath″)

Operating system (OS) password changes, that is, password changes that are initiated outside of IBM
Lotus Notes, occur in the system access control environment; therefore, the NOTES.INI file and the Notes
ID file must reside on a local drive.

To check whether the single logon feature is already installed, choose File - Security - User Security -
Security Basics. If the client single logon feature is installed, the option ″Login to Notes using your
operating system login″ is enabled.

Using Language Pack Installer with Domino

If you plan to install Language Pack Installer (LPI) to run with Domino, you need to be aware of the
following information before installing and setting up Domino and LPI. You also need to read the
Language Pack Installer file, README.TXT, that was provided with your copy of the LPI software.

To present a non-English language email interface to Domino users, the standard Domino environment is
required, as well as the following:
v The appropriate non-English version of Microsoft Windows for the end user so that users can open file
attachments that contain non-English (multiple-byte) characters in the file name. Providing the
non-English version of Microsoft Windows, also ensures that non-English fonts are present on the
system. Users can then read email subject lines and body text that are comprised of non-English
characters.
v The appropriate non-English mail template that enables folder names, button labels, field labels and
column headers to display in the non-English language. This is not required for users running a POP
or IMAP client.
v A non-English Lotus Notes client to enable menu options and dialog boxes to display in the
non-English language. This is not required for users running a POP, IMAP, or browser client.
v Non-English fonts for Lotus Notes to allow a user’s workstation to display text encoded in the
non-English character set in case the user does not have the non-English version of Microsoft
Windows.

To allow users to work in some languages other than English, you need to enable the setting ″Enable
Unicode display″ in Lotus Notes. Complete these steps:
1. From the user’s Notes client, click File - Preferences - User Preferences.
2. On the Basics panel, in the Additional Options list, check the option, Enable Unicode display.
3. Click OK.

Install the non-English Lotus Notes client and the non-English fonts for Lotus Notes on each workstation.
You can download both from the Passport Advantage site or the Business Partner Zone.

Note: The non-English mail template is installed when you the install the Language Pack Installer. You
can also obtain the non-English mail template from Passport Advantage site or the Business Partner Zone.

Prior to installing and setting up LPI in your Domino environment, review the following information:
v Review the LPI file, README.TXT, to be aware of limitations and restrictions.

232 Lotus Domino Administrator 7 Help

v Extract the language pack on a workstation and then run the appropriate SETUP.EXE file. Running the
file, SETUP.EXE, initiates a Java wizard on the workstation which pushes the language pack to the
server.
v While installing Language Pack Installer, choose the templates to which you are adding the
non-English design element. (Use Domino Designer to view the language of each design element.)
After installing the language pack, the selected templates have English and non-English design
elements. If you manually replace a mail file’s design using File - Database - Replace Design, you can
specify English, or a non-English language for the mail file when prompted to do so in the dialog box.
v Before replacing the design of any mail files that contain custom folders, assign Manager access to the
mail file to LocalDomainAdmins (or to a comparable group of which you are a member).
v After assigning Manager access to the appropriate group, manually run the agent, Update Folder
Design, from the Actions menu in each mail file. When that is complete, run Fixup, Updall, and
Compact -c on each mail file and then replace the mail file’s design. Replacing the design before
upgrading the folders causes the design replace to fail and results in errors stating ’unable to find
referenced note.’
v Do not remove the flag, Prohibit design replace, from folder design elements. Deleting the flag causes
the causes the folders to be deleted.
v If you modify the selected Multilingual options in the database properties’ design tab, the database will
open extremely slowly. Always leave the Multilingual database property unchecked. (Access the
database properties design tab in the Domino Administrator client by clicking the Files tab, selecting a
database, then choosing File - Database - Properties. Click the tab that has an icon of a hammer.)
v Add non-English languages to the Domino Web Access template. Other templates are optional.

Custom welcome page deployment

For a consistent, custom appearance across a company or organization, you can create custom welcome
pages, and then deploy them to users through policies and desktop settings documents. They can be as
simple as a background with a company logo, or sophisticated pages with multiple frames and many
different types of content.

You can create as many welcome pages as you want. However, there is a limit to the number of welcome
pages that will display in the Default Welcome Page menu in the desktop settings. This limit is
approximately ten pages, depending on the character length of the welcome page titles. The limit only
affects how many welcome pages appear in the desktop settings menu. All welcome pages will be
deployed to the user’s bookmarks, no matter how many there are.

Create and work on your corporate welcome page database locally, and then copy it to the server when
you are finished. This keeps users from seeing your changes in progress, ensuring that they only see
finished pages.

Designate a default welcome page for individual users by deploying it in an explicit policy, or for entire
organizations by using organizational policies.

Note: Images that are added to an Image Resource are not added to a Corporate Welcome Page if the
image is added to the Image Resource after the Welcome Page is created, and the Corporate Welcome
Page is then pushed to users.

Tip: To ensure that a custom welcome page is available to set as the default for users, create that page
first to make sure it will be available for selection on the desktop settings menu.

Creating the welcome page database

1. From the Domino Administrator, choose File - Database - New.
2. In the Server field, select Local.

Chapter 6. Setting Up Notes Users and Clients 233

3. In the Title field, enter the name of the new database. The file name is entered by default, but you can
modify it. The file name can be anything except BOOKMARK.NSF.
4. In the Template Server field select Local.
5. Click Show advanced templates.
6. Click the Bookmarks (R6) template.
7. Click OK.

Creating welcome pages

You create corporate welcome pages the same way you create them in the Notes client. For even more
options and control over your welcome pages, open your welcome page database in the Domino
Designer and run the ″Toggle advanced configuration editor″ agent.

When you finish working on welcome pages locally, copy the welcome page database to a server to make
it available to users.

Enabling the Default Welcome Page field in the Desktop policy settings document
You need to enable the Default Welcome Page field in the Desktop policy settings document in order to
select a welcome page. The drop down list that displays the selection of welcome page titles is populated
by the NOTES.INI variable $CurrentLayout. The welcome page titles that exist for this variable are listed
in the drop down list of the Default Welcome Page field.

There are two ways to add the necessary welcome page information to the $CurrentLayout variable; use
one of them.

Method 1 -- Enable advanced configuration

Enabling the advanced configuration provides an additional page to the welcome page wizard which
contains the advanced options. The advanced configuration is set by opening the welcome page database
in the Domino Designer and running the ″Toggle advanced configuration editor″ agent. When you use
this method, the $ is automatically pre-pended to every welcome page name, causing the welcome page
to be added to the NOTES.INI setting ″$CurrentLayout.″

Method 2 -- Manually adding the $ to the welcome page name

If you do not need to use any of the options presented on the advanced page in the welcome page
wizard, you can manually pre-pend the $ to the welcome page name. Type a $ at the beginning of any
welcome page name. The welcome page is then automatically added to the NOTES.INI variable.

Deploying welcome pages using desktop settings

1. Open the welcome page database on the server.
2. From the Domino Administrator click the People & Groups tab.
3. From the menu, choose Create - Policy Settings - Desktop Settings.
4. From the Domino Administrator task bar, click the welcome page database and drag it to the
Corporate Welcome Pages database field. This creates a database link.
5. (optional) From the Default Welcome Page menu, select a welcome page to appear automatically
when users log in.
6. (optional) Click ″Do not allow users to change their home page″ to prevent users from creating or
selecting a home page other than the default.
7. Click Save and Close.

Implement these desktop settings in one or more policies, and then assign them to users to finish
deploying your custom welcome pages. The changes will deploy to users the next time they log in.

For more information on policies, see the chapter ″Using Policies.″

234 Lotus Domino Administrator 7 Help

Delaying the deployment of welcome pages
If you design and create or if you update a Corporate Welcome Page, but you do not immediately deploy
it to users, you can use the administration process to deploy it at a later time. The actual update and
distribution of the Corporate Welcome Page can be initiated by using the server console command ″tell
adminp p all.″

Modifying and redeploying welcome pages

Keep your local copy of the welcome page database, and use it to work on any changes you might want
to make later. Once the changes to the local database are complete, save the database and copy it to the
server again.

You will then need to go back into each of the desktop settings documents that point to the welcome
page database and create new database links to the new version. Once this is complete, the changes will
deploy to users the next time they log in.

Some modifications to welcome pages are deployed to users, while other changes are not:
v When deploying welcome pages, changes to the design are not deployed to users.
v Only welcome pages created and updated by the administrator (and those whose titles begin with a
″$″) are deployed to users.
v Adding a link to the Launcher can only be done locally. Changes to the Launcher are not deployed to
users.
v Design changes can only be made locally.

Chapter 6. Setting Up Notes Users and Clients 235

236 Lotus Domino Administrator 7 Help
Chapter 7. Managing Notes Users
This chapter contains instructions for maintaining your Notes users after registering users and setting up
their Notes clients. Maintaining users includes topics such as recertifying users, renaming users, changing
a user’s roaming status, and other user-related tasks.

Managing users
The Administration Process helps you manage users by automating many of the associated
administrative tasks. For example, if you rename a user, the Administration Process automates changing
the name throughout databases in the Notes domain by generating and carrying out a series of requests,
which are posted in the Administration Requests database (ADMIN4.NSF). Changes are made, for
example, in the Person document, in databases, in ACLs and extended ACLs. However, the
Administration Process can be used only if the database is assigned an administration server.

Rename a user
There are several ways in which you ″rename″ a user. Usually they involve changing a user’s common or
alternate name. However, in Domino Notes, the name hierarchy becomes part of the user’s name. So if a
user is moved and certified by a new hierarchy, then that too is considered renaming. The rename tasks
are:
v Change a Notes user’s common name
v Notify a user of a change to private design elements during a name change
v Rename a Web user
v Move a user name in the name hierarchy
v Upgrade a user name from flat to hierarchical

Change user roaming status

You can change a user’s roaming status via the following tasks:
v Change a roaming user to nonroaming
v Change a nonroaming user to roaming

Move or open a user’s files

In contrast to moving a user from one hierarchy to another, which is a simple renaming action, you may
also need to move a user’s actual files. To do so, you use the following task:
v Moving a user’s mail file and roaming files from the Domino Administrator or the Web Administrator

To quickly open a user’s mail file, complete this procedure:

v Open a user’s mail file

Delete a user name

When you delete a user name, you have the option of maintaining some of the files, while denying the
user access to them. The Administration Process helps you automate the following tasks:
v Delete a user name
v Deleting a user name with the Web Administrator

237
Synchronizing Windows 2000 Active Directory and Notes users
You can synchronize Notes users with users in Windows 2000 Active Directory. You can also manage
Notes users from the Windows 2000 Microsoft Management Console.

Changing Notes user names with the Administration Process

When you change the name of a user, the Administration Process implements the name change by
initiating requests to the affected documents, databases, database ACLs, and Extended ACLs. In the
Domino Administrator, when you change the common name, alternate name, or hierarchical name of a
user, you ″rename″ them. Using rename, you can change the name of one or more users in the following
ways:
v Change a user’s common or alternate name
v Add an alternate name to a user if one is not yet assigned
v Move a user to a new hierarchy
v Upgrade a user name from flat to hierarchical

Administration Process requirements

In order for the Administration Process to facilitate the name changes, the databases must have an
assigned administration server.

In addition, the certifier ID you use and any ancestor of the certifier must have a Certifier document in
the Certificates view of the Domino Directory. For example, if you use the certifier ID for
/Sales/NYC/ACME, the Domino Directory must contain Certifier documents for /ACME,
/NYC/ACME, and /Sales/NYC/ACME.

For more information on assigning an administration server, see the chapter ″Setting Up the
Administration Process.″

For more information on certifiers, see the chapter ″Deploying Domino.″

Viewing user name change requests

To review the administration requests that are generated when renaming a user name, open the
Administration Request (ADMIN4.NSF) database in your Domino Directory.

For more information on processing renaming requests in the Administration Requests database, see the
topic ″Changing Notes user names with the Administration Process″ in this chapter.

Notifying users of changes to private design elements during a name change

You can enable an agent that sends to the user an e-mail message notifying the user of a name change
and containing links to databases in which the user created or modified design elements such as a folder
or view. To update the private design elements with the user’s new name, the user must then open the
database via the database links in the e-mail notification. This update to the user name allows the user to
maintain access to their own private design elements. Enable the Mail Notification agent from within the
administration requests database (ADMIN4.NSF).

Note: The AdminP Mail Notification agent runs only on Domino Release 5.05 or more recent servers and
sends e-mail to Notes Release 5.05 or more recent clients.
1. From the Domino Administrator, click Server - Analyses.
2. Click Administration Requests (7).
3. Locate the administration request to rename the user and then open the request.
4. Choose Actions - Enable/Disable User Notification. The agent is enabled and automatically sends to
the user an e-mail message containing links to databases in which the user created or modified design
elements such as a folder or view.
5. Click OK.

238 Lotus Domino Administrator 7 Help

Troubleshooting name changes
The public key in the Person document must match the one on the user ID. If a public key has been
changed or corrupted in some way, you see this message in the Administration Requests database: ″The
name to act on was not found in the Address Book.″

For more information on correcting this problem, see the chapter ″Setting Up the Administration Process.″

Renaming a Notes user’s common or alternate name

Use this procedure to make any of the following changes to a user or to more than one user name:
v Change the common name
v Change or add an alternate name
v Delete the alternate name
v Synchronize the name change between Notes and Active Directory

When a user is renamed, the user’s Internet address often needs to be changed accordingly. You can
change a user’s Internet address as part of a change to the user’s common or alternate name, but you
cannot use this rename procedure to change only the Internet address. If you attempt to use this
procedure to change only a user’s Internet address, you will generate an error.

When you initiate a user’s name change, the user may be prompted to accept or reject the name change.
If the user rejects the name change, an administration request is generated that requires you to either
accept the user name reverting to the original name or reject the name reverting to the original user
name. The user is prompted if the user has selected the ″Ask your approval before name changes″ option
on the Notes Name Changes dialog box.

Note: The Notes Name Changes dialog box is access from the File -- Security -- User Security -- Your
Identity -- Your Names -- Name Changes menu item in the Notes user interface.

If the expiration date for the name change is reached and the user has not responded, an administration
request is issued asking you to accept a request to retract the name change. You can then either accept
the request to retract the name change, or you can reject that request. If you accept the name change
retraction, the administration request for rejecting a name change are generated.

For more information on changing only a user’s Internet address, see the topic ″Changing a user’s
Internet address″ in this chapter.

For more information on approving or rejecting the administration requests that are generated when a
user rejects a name change, or when a name change is retracted, see the topics Accepting or rejecting
name change requests and Administration Process requests that require the administrator’s approval.

For information on using an agent to notify a user of changes to private design elements during a name
change, see the topic ″Changing Notes user names with the Administration Process″ in this chapter.

Note: To use the Domino alternate name functionality, Domino R5.0.2 or later must be running on all
servers involved with the name change, the user’s workstation, and the administrator’s workstation.

To rename a user’s common name

1. To rename a user, you must have:
v Editor with Create documents access, or UserModifier role to the Domino Directory
v At least Author with Create documents access to the Certification Log
2. From the Domino Administrator, click the People & Groups tab.
3. Click People and select a user name.
4. From the tools pane, click People - Rename.

Chapter 7. Managing Notes Users 239

 5. In the Rename Selected Notes People dialog box, verify the number of days you want to honor the
old name. The default is 21 days. You can change that value if desired.
6. Click ″Change Common Name.″
7. In the ″Choose a Certifier″ dialog box, do the following:

Field Action
Server Do one of these:
v If you are using the Lotus Domino server-based CA, choose the server
that is used to access the Domino Directory to look up the list of
certifiers.
v If you are supplying a certifier ID, select the server that is used to locate
the list of certifiers so that the Certifier ID file can be updated with the
latest set of certificates for itself and all of its ancestors. This is also the
server on which CERTLOG.NSF is updated.
Use the CA process Choose this option if you have configured the Lotus Domino server-based
CA.
v Select a CA configured certifier from the list and click OK.
Supply certifier ID and password Choose this option if you are using a certifier ID and password.
v Choose the certifier ID that certified the user’s ID and click Open. For
example, to rename Joe Smith/Sales/NYC/ACME, use the certifier ID
named SALES.ID.
v Click ″Certifier ID″ to select an ID other than the one displayed.
v Enter the password for the certifier ID and click OK.

8. In the ″Certificate Expiration Date″ dialog box, enter a new certification expiration date if desired.
The default certificate expiration date is two years from the current date. The ″Edit or inspect each
entry before submitting request″ check box is selected and cannot be modified.
9. In the Rename Person dialog box, complete the following fields as appropriate. In this dialog box
you have the option of synchronizing Active Directory user names, and changing primary and
alternate name information where appropriate.

Field Action
New Primary Name Information
First , Middle, and Last Name This is the name with which the user was registered. Make changes to
the user’s name as appropriate.
Qualifying Org. Unit (Optional) A name to differentiate this user from another user with the
same user name, certified by the same certifier. This adds a
differentiating component that appears between the common name and
the certifier name.
Short Name (Optional) Created at registration, the default is first initial, last name.
You can change this name. It does not change automatically based on
changes to the primary name fields. You must make this change
manually.
Internet Address (Optional) Created at registration, the default is first initial, last name.
You can change this name. It does not change automatically based on
changes to the primary name fields. You must make this change
manually.

240 Lotus Domino Administrator 7 Help

 Available only if you are renaming a user whose certifying
New Alternate Name Information organization has alternate names assigned.
Common Name Enter the common name in the alternate language.

To delete an alternate name, simply delete the name and do not enter a
new one.
Qualifying Org. Unit (Optional) A name to differentiate this user from another user with the
same user name, certified by the same certifier. This adds a
differentiating component that appears between the common name and
the certifier name.
Original Language The alternate language currently assigned to the user. (Non modifiable)
New Language Select from the list to assign a new alternate language.

10. Select one of the following:

v OK - to submit the name change.
v Skip - if you are renaming more than one user’s common name and you want to continue to the
next name without submitting a name change for the current name.
v Cancel Remaining Entries - to cancel this name change and name changes for any other names
you selected and have not yet submitted.
11. When the Processing Statistics dialog box appears, review the information to verify that all name
changes have succeeded. If any fail, check the Certifier Log (certlog.nsf) to determine the reason for
the failure.
12. Click OK.

Deleting a user name with the Domino Administrator

You can delete a user name with the Administration Process by initiating a delete person command from
the Domino Administrator, by using the Web Administrator, or by using the Windows 2000 Active
Directory. When you delete a user name, you may want to add that user to a ″termination″ group to
prevent the user from accessing servers. When you create a termination group, assign the group type
″Deny Access″ to the group.

You can also use this procedure to delete a roaming user name.

For more information on the administration requests that are generated when you delete a roaming user,
see the appendix ″Administration Process Requests.″

If the server is running Active Directory, you can delete the user’s Active Directory account as well.

There may be times when you want to maintain a user’s mail file even though you have deleted the user
from the Domino Directory. That option is available to you when you delete a user name. However, if
you choose to delete the user’s mail file, you must approve the mail file deletion in the Administration
Request database (ADMIN4.NSF). If you delete a roaming user name, you must approve replica
deletions.

For more information on Domino and Active Directory directory synchronization, see the chapter ″Using
Domino with Windows Synchronization Tools.″

For more information on the Web Administrator, see the chapter ″Setting Up and Using Domino
Administration Tools.″

To delete a user
1. To delete a user, you must have:

Chapter 7. Managing Notes Users 241

 v Author with delete documents access and the UserModifier role, or Editor access to the Domino
Directory
v Author with Create documents access to the Certification Log
2. From the Domino Administrator, click the People & Groups tab.
3. Click People and select the user names you are deleting.
4. From the tools pane, click People - Delete.
5. Complete these fields:

Field
What should happen with the
user’s mail database(s)?
Add deleted user to Deny
Access Group (This option is
active only if one or more
groups of type Deny Access
exists.)
Delete user’s Windows
NT/2000 account, if existing
Delete user from this Domino
Directory immediately
Enter
Choose the appropriate option(s):
v Do not delete the mail database -- to delete the Person document but leave the
user’s mail files intact.
v Delete the mail database on the user’s home server -- to delete mail files on the
user’s home server only.
v Delete mail replicas on all other servers -- this option is active only if Delete the
mail database on the users home server was chosen. This option deletes all mail
database replicas on other servers.
To deny a user access to servers immediately:
1. Click Groups.
2. Select a Deny Access Group from the list.
3. Click OK.
Select this option to delete the corresponding user account in Windows NT or
Windows 2000 Active Directory account.
Select this option to remove the account from the Domino Directory immediately,
while initiating Administration Process requests to remove the user’s name from
ACLs, Names fields, etc.

Note: If you choose to delete a user’s mail file, you must have at least Editor with delete documents
access to the Administration Requests database and delete documents access to the Domino Directory.
6. Click OK.
For more information on shared mail databases, see the chapter ″Setting Up Shared Mail.″

To approve the mail file deletion

If you chose to delete any mail databases, including replicas, you must approve the requests in the
Administration Requests (ADMIN4.NSF) database.
1. From the Domino Administrator, choose Server - Analysis - Administration Requests (R6).
2. Select the Pending Administrator Approval view.
3. Depending on your choices when you deleted the user name, do one of the following:
v If you are certain that you want to approve one or more requests without looking at detail
information for those requests, select the request, and click Approve Selected Requests and then
click OK.
v If you would like to see detail on one or more requests before approving the deletion, select and
open the request, click Edit Request, review the detail information, then choose Approve Replica
Deletion, or choose Reject Replica Deletion.
4. Click Save and Close.

Deleting a user name with the Web Administrator

You can delete user names via the Web Administrator, as well as from the Domino Administrator. Review
the introductory information in the procedure ″Deleting a user name with the Domino Administrator″
before initiating this procedure.

242 Lotus Domino Administrator 7 Help

1. Make sure you have the following before you begin deleting user names:
v At least Author access and ″Delete documents″ privileges in the Domino Directory.
2. From the Domino Web Administrator, click the People & Groups tab.
3. Click People and select the user names you are deleting.
4. From the tools pane, click People - Delete.
5. Complete these fields:

Field
What should happen with the
user’s mail database(s)?
Add user to Deny Access
Group (This option is active
only if one or more groups of
type Deny Access exists.)
Delete user’s Windows
domain account
Delete user from this Domino
Directory immediately
Enter
Choose the appropriate option(s):
v Do not delete the mail database -- to delete the Person document but leave the
user’s mail files intact.
v Delete the mail database on the user’s home server -- to delete mail files on the
user’s home server only.
v Delete mail replicas on all other servers -- this option is active only if ″Delete the
mail database on the users home server″ was chosen. This option deletes all mail
database replicas on other servers.
To deny a user access to servers immediately:
1. Click Groups.
2. Select a Deny Access Group from the list.
3. Click OK.
Select this option to delete the user’s corresponding Windows domain account.
Select this option to remove the account from the Domino Directory immediately,
while initiating Administration Process requests to remove the user’s name from
ACLs, Names fields, etc.

6. Click OK and then click Close.

To approve the mail file deletion

If you chose to delete any mail databases, including replicas, you must approve the requests in the
Administration Requests (ADMIN4.NSF) database.
1. From the Web Administrator, choose Server - Analyses - Administration Requests (R6).
2. Select the Pending Administrator Approval view.
3. Depending on your choices when you deleted the user name, do one of the following:
v If you are certain you want to approve one or more requests without looking at details for those
requests, select those requests, and click Approve Selected Requests.
v If you want to view detail on one or more requests before approving the deletion, select and open
the request, click Edit Document, review the detail information, and then click Save and Close, or
click Cancel.

Changing a roaming user to nonroaming

When you change a user from roaming to nonroaming, the Administration Process changes the user’s
status in their Person document from roaming to nonroaming and deletes the user’s roaming files and
replicas from the servers on which those files reside.
1. To change a roaming user to a nonroaming user, you must have
v At least Author access to the Domino Directory
v If the user has author access they must have one of the following:
a. UserModifier Role
b. Be listed in the LocalAdmin or Owner field of the user’s Person document
v Must have Delete document privilege in the Domino Directory

Chapter 7. Managing Notes Users 243

2. From the Domino Administrator, click the People & Groups tab.
3. Choose People and select one or more roaming user name(s) you are changing to nonroaming.
4. From the tools pane, click People - Roaming.

Note: If you selected a mixed group of roaming and nonroaming users, the Mixed Roaming Profile
dialog box appears and prompts you to select either roaming or non-roaming. Click the check box
″Remove roaming profiles from <n> selected users. ″ In this case, <n> is the number of roaming users
selected.
5. Click the check box ″Perform updates in background″ to process each user in the background.

Tip: Run the process in the background so that you can use the Administrator client while requests
are processed.

To verify the change

The procedure changes the user’s status in their Person document from roaming to nonroaming. To verify
that the change has been made:
1. From the Domino Administrator, click the People & Groups tab.
2. Click People and then select the user you changed to nonroaming.
3. Click Edit Person to open the user’s Person document.
4. Click the Roaming tab. The ″User Can Roam″ field should display No.

To approve the mail file deletion

If you chose to change a roaming user to nonroaming, you must approve the deletion requests in the
Administration Requests (ADMIN4.NSF) database. Changing a roaming user to nonroaming, requires that
the user’s roaming files and replicas are deleted.
1. From the Domino Administrator, choose Server - Analysis - Administration Requests (R6).
2. Select the Pending Administrator Approval view.
3. Depending on your choices when you changed the user from roaming to nonroaming, do one of
these:
v If you are certain that you want to approve one or more deletion requests without looking at detail
information for those requests, select the requests, and click Approve Selected Requests and then
click OK.
v If you would like to see detail on one or more requests before approving the deletion of roaming
files, select and open the request, click Edit Request, review the detail information, then choose
Approve Replica Deletion, or choose Reject Replica Deletion.
4. Click Save and Close.

Changing a nonroaming user to roaming

When you change a user from nonroaming to roaming, the Administration Process changes the user’s
status in their Person document from nonroaming to roaming and creates a personal subdirectory for
each roaming user. This personal subdirectory contains the roaming user’s files and, by default, is placed
in the Domino/data path unless you specify another location. You can optionally choose a separator
character if you want to include one in the user’s directory name.

Note: Only those users who have a hierarchical ID (for example, CN=Jane Doe/OU=East/O=Acme) can
be upgraded to roaming users. To upgrade a flat user ID, recertify that user ID to a hierarchical format,
and then upgrade the user. For information about recertifying an ID from flat to hierarchical, see the topic
Upgrading a user name from flat to hierarchical.

The roaming user feature requires the use of Dynamic Client Configuration (DCC). If you have used the
NOTES.INI setting, DisableDynConfigClient=1 to disable DCC, remove that NOTES.INI entry or
comment out the entry in the NOTES.INI file and then restart the client. If DCC is disabled, the end-user

244 Lotus Domino Administrator 7 Help

is never prompted as to whether they want to upgrade to roaming status; therefore, the administration
process does not generate the administration requests that are required to perform the upgrade to
roaming status. This applies only to upgrades to roaming status; it does not apply to new roaming user
setups.

Before changing a nonroaming user to roaming, read the roaming user information in the topic Using
Advanced user registration.

To change a nonroaming user to roaming

1. To change a nonroaming user, you must have the following rights or privileges:
v At least author access to the Domino Directory
v If the user has author access, they must have one of the following:
a. UserModifier Role
b. Be listed in the LocalAdmin field of the user’s Person document
v Must be a database administrator on the roaming server (needed to create a folder on a remote
server)
2. From the Domino Administrator, click the People & Groups tab.
3. Select one or more nonroaming user name(s).
4. From the Tools pane, click People - Roaming.

Note: If you selected a mixed group of roaming and nonroaming users, the Mixed Roaming Profile
dialog box appears and prompts you to select either roaming or non-roaming. Click the check box
″Assign roaming profiles to <n> selected users.″ In this case, <n> is the number of nonroaming users
selected.
5. Complete these fields:

Field
Where should the user’s roaming files be stored?
User’s personal roaming folder
Action
Choose one:
v Store on user’s mail server -- Places the user’s roaming
files on the user’s mail server. (The user’s mail server
was designated during user registration.)
v Roaming Server -- Click the button to specify the
server on which you want to store the user’s roaming
files.
v Store user ID in personal address book -- (Optional)
Places the user’s ID in their own local personal
address book.
Choose one:
v Base folder -- Name of the folder in which to store the
user’s roaming files. By default the user’s base folder
is located in the Domino\data directory. For example,
if you want the base folder to be called Roaming for
all your roaming users, enter Roaming to create the
Domino\data\Roaming directory.
v Sub-folder format -- The format to use when naming
the roaming user’s personal subfolder. By default this
is the user’s short name format. You can change this
format if desired and you can optionally choose a
separator character. A personal folder (subfolder) is
created in the Base folder for each user you upgrade to
roaming user.

Chapter 7. Managing Notes Users 245

Field
If folder exists
Client upgrade option - User should be prompted
Client set-up options - User should be prompted
Roaming user client clean up options
Perform updates in background
Action
Choose one:
v Skip person -- if a folder already exists.
v Generate folder name -- to create a new folder.
Choose one:
v Click the check box, User should be prompted, if you
want the user to be prompted as to whether to
suppress the upgrade to a status of roaming user. By
default, the user is prompted as to whether they want
to suppress the upgrade to roaming status.
v Remove the check mark from the check box to prevent
the display of a prompt asking the user whether they
want to be upgraded from a nonroaming user status to
a roaming user status. When this check box is not
marked, the upgrade to roaming user status is done by
default.
Choose one:
v Click the check box, User should be prompted, if you
want the user to be prompted as to whether to
suppress the upgrade to the client. By default, the user
is prompted as to whether they want to suppress the
upgrade.
v Remove the check mark from the check box to prevent
the display of a prompt asking the user whether they
want to upgrade the client. When this check box is not
marked, the roaming user upgrade is done by default.
Choose one:
v Do not cleanup -- No cleanup is performed on
roaming user files.
v Cleanup every <number> days -- Specify a number
between 0 and 365.
v Cleanup at Notes shutdown -- Cleans up files when
Notes is shut down.
v Prompt user -- The user is prompted on exiting the
client as to whether they want to clean up their
personal files. If the user chooses Yes, the data
directory on that client workstation is deleted. If the
user chooses No, the user is prompted as to whether
they want to be asked again on that client. If the user
chooses No, the user is not prompted again. If the user
chooses Yes, the user is prompted again the next time
the user exits the client on that workstation.
Processes requests in the background leaving the
administration client available for other administration
activities.
Note: If you do not choose this option, the
Administration client is busy until the Administration
Process completes the upgrade.

6. Click OK.
A message displays indicating the number of users successfully upgraded from nonroaming to
roaming.

246 Lotus Domino Administrator 7 Help

To verify the change
The procedure changes the user’s status in their Person document from nonroaming to roaming. To verify
that the change has been made:
1. From the Domino Administrator, click the People & Groups tab.
2. Select the user you promoted to roaming.
3. Click ″Edit Person″ to open the user’s Person document.
4. Click the Roaming tab. The ″User Can Roam″ field should display ″In Progress″ or ″Yes.″ The ″In
Progress″ status displays until replication has occurred and all replicas of the user’s files are updated.

Changing a user’s Internet address

To modify only a user’s Internet address, modify the user’s Person document.
1. From the Domino Administrator, click the Files tab and open the Domino Directory (NAMES.NSF).
2. Select the user name and click Edit Person.
3. On the Mail tab, modify the name in the Internet Address field as necessary.
4. Click Save and Close.

You can also modify a user’s Internet name when performing a user rename, such as changing a user’s
common name. To modify the user’s Internet address using the Tools -> People -> Rename feature, you
must also modify another component of the user’s name, such as the short name, at the same time that
you are modifying the Internet address.

For more information on renaming a user with the options on the Tools pane, see the topic ″Renaming a
Notes user’s common or alternate name″ in this chapter.

Upgrading a user name from flat to hierarchical

In order to use the Administration Process to expedite name changes, your organization must use
hierarchical names. Use this procedure to upgrade a user name from a flat format to a hierarchical
format.

Upgrading a user name from flat to hierarchical affects both the primary and alternate name information.
To use the Domino alternate name functionality, Domino 5.0.2 or later must be running on all servers
involved with the name change, the user’s workstation, and the administrator’s workstation.

Note: This procedure does not apply to roaming users.

To upgrade a user name from flat to hierarchical

1. To rename a user you must have:
v Editor with Create documents access, or the UserModifier role to the Domino Directory
v At least Author with Create documents access to the Certification Log
2. From the Domino Administrator, click the People & Groups tab.
3. Click People and select a user name.
4. From the tools pane, click People - Rename.
5. Click ″Upgrade to Hierarchical.″

Chapter 7. Managing Notes Users 247

6. In the ″Choose a Certifier″ dialog box, make the following selections:

Field Action
Server Do one of these:
v If you are using the Lotus Domino server-based CA,
choose the server that is used to access the Domino
Directory to look up the list of certifiers.
v If you are supplying a certifier ID, select the server
that is used to locate the list of certifiers so that the
Certifier ID file can be updated with the latest set of
certificates for itself and all of its ancestors. This is also
the server on which CERTLOG.NSF is updated.
Use the CA process Choose this option if you have configured the Lotus
Domino server-based CA.
v Select a CA-configured certifier from the list and click
OK.
Supply certifier ID and password Choose this option if you are using a certifier ID and
password.
v Choose the certifier ID that certified the user’s ID and
click Open. For example, to rename Joe
Smith/Sales/NYC/ACME, use the certifier ID named
SALES.ID.
v Click ″Certifier ID″ to select an ID other than the one
displayed.
v Enter the password for the certifier ID and click OK.

7. In the ″Certificate Expiration Date″ dialog box, accept or change the new certification expiration date.
The default certificate expiration date is two years from the current date.

Tip: The ″Edit or inspect each entry before submitting request″ check box is selected and cannot be
modified.
8. In the Rename Person dialog box, you have the option of changing the primary or alternate name
information. Then choose one of the following:
v OK - to submit the name change approval.
v Skip - if you are upgrading more than one user name and you want to continue to the next name
without submitting a name change for the current name.
v Cancel Remaining Entries - to cancel this name change and name changes for any other names you
selected and have not yet submitted.
9. When the Processing Statistics dialog box appears, review the information to verify that all name
changes have succeeded. If any fail, check the Certifier Log (certlog.nsf) to determine the reason for
the failure. Click OK.

Moving a user name in the name hierarchy

When you move a user to a different Organizational Unit, the certifier changes, thus the user’s name
hierarchy changes. Since the name hierarchy in Domino Notes is part of the user’s name, when you move
a user to a different certifier you have essentially changed the user’s name. You can use the
Administration Process to move a user name to a different location (Organizational Unit) in the
organization’s hierarchical name scheme or to move a name to a different Organization altogether.

For example, if Alice Brown/Marketing/Acme leaves a job in the Marketing department for a job in
Sales, you can certify her user ID with the /Sales/Acme certifier, which, in effect, moves her to that
Organizational Unit. Her full hierarchical name then becomes Alice Brown/Sales/Acme.

248 Lotus Domino Administrator 7 Help

You can also move a user to another Organization, however to do so, your Domino Directory must
contain cross-certificates between the Organizations involved. So, for example, if Alice
Brown/Marketing/Acme leaves a job at Acme to work for the Acme subsidiary AcmeSub that has its
own Organization Certifier, you can certify her ID with the /AcmeSub certifier so that her name becomes
Alice Brown/AcmeSub. Using this example, the Domino Directory must have cross-certificates between
/Acme and /AcmeSub.

There are two parts to moving a user name:

1. Request the move using the originating certifier.
2. Complete the move by using the target (new) certifier to approve the request and issue the new
certificate.
For more information on the Administration Process, see the chapter ″Setting Up the Administration
Process.″ For more information on cross-certificates, see the chapter ″Protecting and Managing Notes
IDs.″
For information on using an agent to notify a user of changes to private design elements during a
name change, see the topic ″Changing Notes user names with the Administration Process″ in this
chapter.

Changing primary and alternate name information during the move

If an alternate name has been assigned, the administrator who performs the approval phase of the move
automatically has the option to change primary name information. If an alternate name has not been
assigned, you can designate whether the administrator who completes the move can modify primary
name fields. To use the Domino alternate name functionality, Domino 5.0.2 or later must be running on
all servers involved with the name change, the user’s workstation, and the administrator’s workstation.

Synchronizing the name change between Notes and Active Directory

While completing the move, you also have the option of synchronizing the name change between Notes
and Active Directory. To do so, select ″Rename NT user account″ on the Rename Person dialog box.

To move a user name in the name hierarchy

1. To move a user name in the name hierarchy, you must have:
v Access to the certifier you are using
v At least Editor access to the Administration Requests database
2. From the Domino Administrator, click the People & Groups tab.
3. Click People and select a user name.
4. From the tools pane, click People - Rename.
5. The ″Honor old names for up to <x> days″ field is set to 21 days by default. You can change that
value if desired.
6. Click ″Request Move to New Certifier.″
7. In the Choose a Certifier dialog box, complete these fields:

Field Action
Server Do one of these:
v If you are using the Lotus Domino server-based CA, choose the
server that is used to access the Domino Directory to look up the
list of certifiers.
v If you are supplying a certifier ID, select the server that is used
to locate the list of certifiers so that the Certifier ID file can be
updated with the latest set of certificates for itself and all of its
ancestors. This is also the server on which CERTLOG.NSF is
updated.

Chapter 7. Managing Notes Users 249

Field Action
Supply certifier ID and password Choose this option if you are using a certifier ID and password.
v Choose the certifier ID that certified the user’s ID and click
Open. For example, to rename Joe Smith/Sales/NYC/ACME,
use the certifier ID named SALES.ID.
v Click ″Certifier ID″ to select an ID other than the one displayed.
v Enter the password for the certifier ID and click OK.
Use the CA process Choose this option if you have configured the Lotus Domino
server-based CA.
v Select a CA-configured certifier from the list and click OK.

8. In the Request Move For Selected People dialog box, do the following:

Field Action
Old Certifier Verify the information. If it is incorrect, cancel the procedure and
begin again.
New Certifier Enter or select the new certifier. This is the name hierarchy that
issues a certificate for the user in the new hierarchy.

For example, to certify Joe Smith from /Sales/NYC/ACME into

Edit or inspect each entry before submitting
request
/Service/NYC/ACME, enter /Service/NYC/ACME or select from
the list.
Selected by default. Do one:
v Keep selected. The Rename Person dialog box appears with
non-modifiable fields of Primary and Alternate Name
information. Review the information for accuracy. Go to Step 9.
v If you do not want to verify each entry, clear the check box.
Review the processing information that displays to verify that all
name changes were successful. If any fail, check the Certifier Log
to determine the reason for the failure. Go to Step 10, then
complete the procedure ″To approve the name change.″

9. (Optional) Click the ″Allow the primary name to be changed when the name is moved″ check box if
you want the opportunity to change the user’s name when you approve the move.
10. For each name selected, choose one of the following:
v OK - to submit the name change.
v Skip - if you are renaming more than one user name and you want to continue to the next name
without submitting a name change for the current name.
v Cancel Remaining Entries - to cancel this name change and name changes for any other names
you selected and have not yet submitted.

To complete the name change

1. From the Domino Administrator, click Server - Analysis - Administration Requests (7).
2. Choose the Name Move Requests view. This view categorizes submissions by certifier. Each name
awaiting approval is listed under its new certifier. Select the name(s) to move.
3. Click Complete move for selected entries.

250 Lotus Domino Administrator 7 Help

4. To complete the move, in the Choose a Certifier dialog box, make the following selections:

Field Action
Server Do one of these:
v If you are using the Lotus Domino server-based CA, choose
the server that is used to access the Domino Directory to look
up the list of certifiers.
v If you are supplying a certifier ID, select the server that is
used to locate the list of certifiers so that the Certifier ID file
can be updated with the latest set of certificates for itself and
all of its ancestors. This is also the server on which
CERTLOG.NSF is updated.
Use the CA process Choose this option if you have configured the Lotus Domino
server-based CA.
v Select a CA-configured certifier from the list and click OK.
Supply certifier ID and password Choose this option if you are using a certifier ID and password.
v Choose the certifier ID that certified the user’s ID and click
Open. For example, to rename Joe Smith/Sales/NYC/ACME,
use the certifier ID named SALES.ID.
v Click ″Certifier ID″ to select an ID other than the one
displayed.
v Enter the password for the certifier ID and click OK.

5. If you are moving a user name from one hierarchy to another hierarchy, a cross certificate is
required. If your local Domino Directory does not contain a cross certificate for the certifier, you are
prompted to create one. Click Yes.
6. In the ″Certificate Expiration Date″ dialog box, do the following and then click OK:

Field Action
Certifier The name hierarchy of the certifier that will issue the new
certificate (non-modifiable).
New certificate expiration date (Optional) Specify a certifier ID expiration date other than the
default two years from the current date.
Edit or inspect each entry before submitting Selected by default. You can remove the check mark if you do
request not want to verify the entries.

7. In the Rename Person dialog box, make changes to the primary name as needed.

Field Action
New Primary Name Information
First, Middle, and Last Name This is the name with which the user was registered. Make
changes to the user’s name as appropriate.
Qualifying Org. Unit (Optional) A name to differentiate this user from another user
with the same user name, certified by the same certifier. This
adds a differentiating component that appears between the
common name and the certifier name.
Short Name (Optional) Created at registration, the default is first initial, last
name. You can change this name optionally. It does not change
automatically based on changes to the primary name fields. You
must make this change manually.

Chapter 7. Managing Notes Users 251

Field Action
Internet Address (Optional) Created at registration, the default is first initial, last
name. You can change this name optionally. It does not change
automatically based on changes to the primary name fields. You
must make this change manually.
Rename Windows NT User Account Available to Windows NT User Manager or Active Directory
users only. Check this box if you want to synchronize the name
change in both the Domino Notes and Windows NT or Domino
Notes and Active Directory accounts.

8. Complete the following fields as desired. These modifiable fields display only if the user ID has an
alternate name assigned to it.

Available only if you are renaming a user whose certifying

New Alternate Name Information organization has alternate names assigned.
Common Name The common name in the alternate language.
Qualifying Org. Unit (Optional) A name to differentiate this user from another user
with the same user name, certified by the same certifier. This
adds a differentiating component that appears between the
common name and the certifier name.
Original Language The alternate language currently assigned to the user
(non-modifiable).
New Language Select from the list to assign a new alternate language. This
option is available only if the user is moving into an
Organizational Unit or Organization that has an alternate
language assigned.

9. Choose one of the following:

v OK - to submit the name change approval.
v Skip - if you are renaming more than one user and you want to continue to the next name
without submitting a name change for the current name.
v Cancel Remaining Entries - to cancel this name change and name changes for any other names
you selected and have not yet submitted.
10. When the Processing Statistics dialog box appears, review the information to verify that all name
changes have succeeded. If any fail, check the Certifier Log (certlog.nsf) to determine the reason for
the failure. Click OK.

The user name change in hierarchy continues just as a change to a Notes user’s common or alternate
name is completed.

Renaming a Web user

Use the Domino Administrator to rename a Web user. The Administration Process generates an
administration request to rename the user.
1. From the Domino Administrator, click the People & Groups tab.
2. Click People and then select the Web user you are renaming.
3. From the Tools pane, click People - Rename. The ″Rename Selected HTTP, POP3, and IMAP People″
wizard is activated.
4. In the ″Honor old names for up to <21> days″ field, either accept the default or enter a value between
14 and 60 days.
5. Click Next.
6. Select each name whose common name components you want to change, and then change the name
as desired. Repeat for each name you are changing.

252 Lotus Domino Administrator 7 Help

7. Click Next. A message displays indicating the number of Web user names that will be changed.
8. Click Finish.
For information on creating a non-Notes, Internet user, see the topic ″Registering non-Notes, Internet
users″ in this chapter.

Moving a user’s mail file and roaming files from the Domino
Administrator or the Web Administrator
You may need to move mail files when you need more space on a server or when users change jobs.
When a mail file is moved, the Administration Process first moves it to a new server, then issues a
request to delete the old mail file from its original mail server. You must approve this mail file deletion.
The Administration Process also changes the information in the ″Mail file name″ and ″Mail server″ fields
in the user’s Location document.

Moving a user’s mail file to a Lotus Domino Release 7 clustered server allows you to choose additional
servers on which to create replicas. The user interface provides a list of all the servers (cluster mates) you
can choose from. You can also click the server name to specify paths for each server.

Moving a mail database archive

You can move a mail database archive when you move a mail database to another server if the archive is
located on the same server as the mail file. Mail archiving is usually done to save space on mail servers;
therefore, if a mail database archive is on a different server there is typically no reason to move the
archive. Mail databases are often moved for resource balancing purposes.

To move only a mail file

1. To move a user’s mail files, you must have:
v Editor access with Create documents role, or Author access with the UserModifier role in the
Domino Directory
2. From the Domino Administrator or Web Administrator, click the People & Groups tab.
3. Click People and select the person whose mail file you are moving.
4. Click Move to Another server.
5. Choose a destination server to which you are moving the mail file. If the destination server you
choose is a clustered server, it appears ″checked″ in the Additional mail server field on this dialog
box.
6. (Optional) Enter a new directory to which the mail file should be moved. You can accept the default
of mail\.
7. (Optional) Click Link to Object Store if you are using shared mail and want to link the mail file to
the object store.
8. (Optional) Choose one of theses:
v From the Domino Administrator, click Remove all mail replicas if the server is in a cluster and
you want all mail replicas to be deleted.
v From the Web Administrator, click Delete old replicas if the server is in a cluster and you want to
delete mail file replicas from a cluster.
9. If you are working with clustered servers, you can selected additional servers in the cluster to which
the mail database can be moved. To select additional servers, click the check box next to the server
name in the Additional mail server field.
10. Click OK.
11. Click Close.

To approve the mail file deletion

When the mail file is on the new mail server, you must approve the mail file deletion in the
Administration Requests database (ADMIN4.NSF).

Chapter 7. Managing Notes Users 253

1. From the Domino Administrator or the Web Administrator, click Server - Analysis - Administration
Requests (7).
2. Choose the Pending Administrator Approval view.
3. Locate the Approve mail file deletion request and open that request.
4. Click ″Edit Document.″ Review the request.
5. Click ″Approve Mail File Deletion.″
6. Click Save and Close.

To move a user’s mail file and/or roaming files

You can move a user’s roaming files and mail files at the same time to the same destination server.
However, if you want to move a user’s roaming files to one server and the mail files to another server,
you must complete the procedure twice -- once for the roaming files and then once for the mail files. The
roaming files that are moved are journal.nsf, bookmark.nsf, and names.nsf.

You can use this procedure to move any user’s mail files, whether they are roaming users or not.

The files are moved by the Administration Process in the background so that you can continue to
perform administration activities while the files are being moved.
1. To move a user’s mail and/or roaming files, you must have:
v Editor with Create documents access, or Author access with the UserModifier role to the Domino
Directory
v At least Author with Create documents access to the Certification Log (for roaming files move)
v CreateReplica access to the destination server
2. From the Domino Administrator or the Web Administrator, click the People & Groups tab.
3. Click People and select a user name.
4. From the tools pane, click People - Move to Another Server.
5. Complete these fields:

Field Action
Destination Enter the name of the server to which you are moving the
user’s mail and/or roaming files. If the destination server
you choose is a clustered server, it appears ″checked″ in
the Additional mail server field on this dialog box.
Move roaming files into this folder Select this check box if you are moving a user’s roaming
files. This check box is not active if you are moving a
nonroaming user.

Accept the directory that is displayed or click the folder

icon to choose another directory.
Move mail files into this folder on <server> Select this check box if you are moving a user’s mail files.

Accept the directory that is displayed or click the folder

icon to choose another directory.
Link to Object Store If shared mail is enabled on the destination server, select
this check box to link the mail file to the object store.

This is active only if you are moving mail files.

Remove all mail replicas when moving off cluster Select this check box to remove all replicas of mail as well.
There may be instances, during a move for example, when
a user might need access to a replica for a short time.

This is active only if you are moving mail files.

254 Lotus Domino Administrator 7 Help

6. If you are working with clustered servers, you can select additional servers in the cluster to which the
mail database can be moved. To select additional servers, click the check box next to the server name
in the Additional mail server field.
7. Click OK.

To approve the requests

When the mail file is on the new mail server, be sure to open the Administration Requests database
(ADMIN4.NSF). Locate the ″Approve file deletion″ request and approve the request. When the roaming
files are on the new roaming server, locate the ″Approve file deletion″ requests for the roaming files in
ADMIN4.NSF and approve them.
1. From the Domino Administrator or the Web Administrator, click Server - Analysis - Administration
Requests (7).
2. Choose the Pending Administrator Approval view.
3. Locate the Approve mail file deletion request and open that request.
4. Click ″Edit Document.″ Review the request.
5. Click ″Approve Mail File Deletion.″
6. Locate the roaming file approval requests, and repeat steps 4 and 5 to approve the deletion of the
roaming files.
7. Click Save and Close.

Opening a user’s mail file

Use the Open Mail File button to open a user’s mail file from the Domino Administrator client user
interface. You can use the Open Mail File button from within an open Person document in the Domino
Directory or from the People view in the Administrator client.

From the People view

1. From the Domino Administrator, click the People & Groups tab.
2. Click People and select the person whose mail file you are opening.
3. Click Open Mail File.

From an open Person document

1. Open the Domino Directory containing the user’s Person document.
2. Locate the user’s name and double-click to open the Person document.
3. Click Open Mail File.

Finding a user name in the domain with the Domino Administrator or

the Web Administrator
You can search for a user name in the domain and obtain logs that include document links and directory
links to each occurrence of the user name. This procedure can be performed from the Domino
Administrator or from the Web Administrator.

To find references to a user’s name with the Domino Administrator

1. From the Domino Administrator, click the People & Groups tab.
2. Select one or more user name(s) that you want to locate in the domain.
3. From the tools pane, click People - Find Users.
4. Click Yes to initiate the Administration Request to locate all the occurrences of the selected name(s) in
the enterprise.

To find references to a user’s name with the Web Administrator

1. From the Web Administrator, click the People & Groups tab.
2. Enter the name of the user whose name you are trying to find.

Chapter 7. Managing Notes Users 255

3. Click Send.
4. (Optional) Continue adding user names that you want to search for.
5. Click Done.

To view the results of the name search

To view the log of locations where the user name(s) are located:
1. From the Domino Administrator or the Web Administrator, click Server - Analysis - Administration
Request (7).
2. Select the All Requests by Action view and locate the ″Find Name in Domain″ request.
3. Double-click the report to access the Administration Process - Log document.

Broadcasting messages to Notes client users

Use the Domino Administrator to broadcast messages to one or more Notes client workstations. Messages
can be broadcast to display in dialog boxes or in the status bar on the Notes client workstations.
1. From the Domino Administrator, click the Server tab and click Status.
2. Click Notes Users.
3. If you are sending a message to a specific user only, select the user name.
4. From the Tools pane, click User - Broadcast Message.
5. Complete these fields:

Field Action
Broadcast a message to Choose one of these:
v admin/ibm -- Sends a message to the user whose name
you selected prior to opening this dialog box. In the
example shown on the dialog box, it will be sent to
admin/ibm.
v All connected users -- Broadcasts the message to all
connected users.
v All users of a database -- Broadcasts this message to
anyone that has this database open. When you choose this
option, the database name field is enabled. Enter the name
of the database.
Broadcast this message Enter the message that is to be broadcast.
Show as dialog box on user’s workstation Choose this option to present the message to users in a dialog
box. If you do not choose the option, the message displays in
the status bar on the user workstation(s).

6. Click Broadcast.

Recertifying a user ID
Before a user ID reaches its expiration date, recertify the user ID using the original certifier ID. The user
ID is recertified without renaming the user.

Use the Certificate expiration view to determine which certifiers need to be recertified. Access this view
from Files - Certlog.nsf - By Expiration date. All certifiers are listed by expiration date.

For more information on certifiers and certification, see the chapter ″Deploying Domino.″

Note: To recertify a user ID using a certifier other than the certifier used to create the user ID, see
″Moving a user name in the name hierarchy″ in this chapter.

256 Lotus Domino Administrator 7 Help

To recertify a user ID
Follow these steps to use the Administration Process to recertify a hierarchical ID that is about to expire.
1. To recertify a user ID, you must have:
v Author with Create documents access and the UserModifier role, or Editor access to the Domino
Directory
v At least Author with Create documents access to the Certification Log (CERTLOG.NSF)
2. From the Domino Administrator, click the People & Groups tab.
3. Select the user to be recertified with the same certifier.
4. From the tools pane, select People - Recertify.
5. Complete these fields:

Field Action
Server Do one of these:
v If you are using the Lotus Domino server-based CA,
choose the server that is used to access the Domino
Directory to look up the list of certifiers.
v If you are supplying a certifier ID, select the server
that is used to locate the list of certifiers so that the
Certifier ID file can be updated with the latest set of
certificates for itself and all of its ancestors. This is also
the server on which CERTLOG.NSF is updated.
Use the CA process Choose this option if you have configured the Lotus
Domino server-based CA.
v Select a CA configured certifier from the list and click
OK.
Supply certifier ID and password Choose this option if you are using a certifier ID and
password.
v Choose the certifier ID that certified the user’s ID and
click Open. For example, to rename Joe
Smith/Sales/NYC/ACME, use the certifier ID named
SALES.ID.
v Click ″Certifier ID″ to select an ID other than the one
displayed.
v Enter the password for the certifier ID and click OK.

6. Verify the certifying ID information and complete the following fields:

Field
New certificate expiration date
Only renew certificates that will expire before
Edit or inspect each entry before submitting request
Action
(Optional) Specify a certifier ID expiration date other than
the default two years from the current date.
(Optional) Enter a date to recertify only a subset of
selected user IDs, according to their current expiration
dates.
(Optional) Select the option to edit or inspect each entry
before submitting the request if you want to view each
certificate before it is renewed.

7. If you selected the option to view each entry prior to its being submitted, the Recertify Person dialog
box appears with non-modifiable information in the primary and common name fields. Review the
information that displays, then select one of the following:
v OK - to submit the name change.

Chapter 7. Managing Notes Users 257

 v Skip - if you are recertifying more than one user ID and you want to continue to the next without
submitting a recertification for the current name.
v Cancel Remaining Entries - to cancel this recertification, as well as those for any other names you
selected and have not yet submitted.
8. When the Processing Statistics dialog box appears, review the information to verify that all name
changes have succeeded. Click OK. If any fail, check the Certifier Log (certlog.nsf) to determine the
reason for the failure.

Recertifying a certifier ID or a user ID

Use this procedure to recertify a certifier ID or a user ID with the same certifier ID that was used
previously to certify the certifier ID or user ID. Certifier IDs are used to certify other certifiers, servers,
and users. A certifier ID issues a certificate to another user, server or certifier that is on the hierarchical
level immediately below the certifier. For example, in the Organizational Unit Sales/NYC/ACME, NYC is
the certifier for Sales; ACME is the certifier for NYC. The Organization certifier, in this case ACME, can
certify itself.

You can also recertify a user ID with a different certifier ID, that is, a certifier ID other than the one used
to previously certify the user ID. Although recertifying a user ID with a different certifier is allowed, it is
not recommended that you do so using this procedure. In this case, you are renaming the user, which is a
very complex process involving changes to ACLs for various databases, changes to lists of group
members, and other related entries. Recertifying a user ID with a different certifier does not invoke the
Administration Process, so all changes need to be made manually. To recertify a user with a different
certifier ID, we recommend using the Rename tool, and requesting a move to a new certifier.

For more information, see the topic ″moving a user name in the name hierarchy″ in this chapter.

When you recertify an ID you can:

v Provide a new expiration date for certificates about to expire
v Add a new alternate name to the certifier ID
v Change the minimum password quality

Types of IDs you can recertify

You can recertify any of the following types of IDs:
v Organizational unit
v Server
v User
v Organization certifier (when it is used to certify itself)
For more information on certifier IDs, see the chapter ″Deploying Domino.″

To recertify a certifier ID or a user ID

1. From the Domino Administrator, click Configuration.
2. From the tools pane, click Certification - Certify.

258 Lotus Domino Administrator 7 Help

3. In the ″Choose a Certifier″ dialog box, make the following selections:

Field Action
Server Do one of these:
v If you are using the Lotus Domino server-based CA, choose the server
that is used to access the Domino Directory to look up the list of
certifiers.
v If you are supplying a certifier ID, select the server that is used to locate
the list of certifiers so that the Certifier ID file can be updated with the
latest set of certificates for itself and all of its ancestors. This is also the
server on which CERTLOG.NSF is updated.
Supply certifier ID and password Choose the certifier ID that issued the original certificate. For example, to
recertify the certifier ID for /Sales/NYC/ACME, choose the /NYC/ACME
certifier ID, which is NYC.ID.
v Click ″Certifier ID″ to select an ID other than the one displayed.
v Enter the password for the certifier ID and click OK.
Note: Although not recommended, you can choose a different certifier ID
to recertify a user ID, instead of using the original certifying ID.
Use the CA process Choose this option to use the server-based certification authority (CA).
v Select a CA-configured certifier from the list and click OK.

4. In the ″Choose ID to Certify″ box, select the certifier ID or user ID that you want to recertify. For
example, to recertify Sales/NYC/ACME, choose SALES.ID.
5. Enter the password and click OK.
6. In the Certify ID dialog box, complete the following fields as necessary:

Field Enter
Current Server The registration server for the current certifier ID. (nonmodifiable)
Current certifier The name hierarchy of the certifier that issued the certificate.
(nonmodifiable)
Expiration date (Optional) Specify a certifier ID expiration date other than the default
two years from the current date.
Primary key Public half of the primary RSA key pair stored in the Notes ID file. This
RSA key pair is used for electronic signatures on documents and
certificates, and on mail encryption when both the sender and the
recipient have a North American Notes license. This key pair is also used
for network authentication. (nonmodifiable)
International key The public half of the international RSA key pair. This key pair is used
for mail encryption when either the sender or recipient are running with
an International Notes license. (nonmodifiable)
Subject name list Certifier ID(s) you are working with.
Add Click to add and certify an alternate name. Select the alternate language,
country code (optional), and the organization identifier for the language.
Rename Rename the alternate name selected in the Subject name list. This button
is not available when recertifying user Ids. This button is enabled only
when alternate languages have been assigned.
Remove Removes the alternate name selected in the Subject name list.
Password quality Move the slider to change the level of complexity and variety of
characters entered for the password.

7. Click Certify.

Chapter 7. Managing Notes Users 259

 For more information on alternate names, see the chapter ″Setting Up and Managing Notes Users.″

Allowing multiple users to use the same data directory

Multiple Notes client users can log on and use the same data directory at the same time. Domino creates
an autosave database with a unique name for each user to make the data directory available to multiple
users. For example, if a user is named Eric Thiel, the autosave database name would be
as_ethiel.nsf

Domino then makes a new entry for that user in the NOTES.INI file. For example, the new entry for this
user could be:
AUTO_SAVE_USER,Eric Thiel/Westford/IBM=as_ethiel.nsf

If an autosave database with the name as_ethiel.nsf already exists, the number 1 would be appended to
the user name portion of the new database name. For example,
as_ethiel1.nsf

When a user logs in to NOTES with their USER.ID, Domino checks the NOTES.INI file for an entry with
that user’s name. One of these situations occurs:
v The entry exists, and the database name in that entry is used.
v The entry exists but the database cannot be located. Domino creates a new database.
v The user does not have access to the database and an error message is generated.
v The entry cannot be located. A new NOTES.INI entry and database are created using the naming
convention described above.

License Tracking
License Tracking allows you to monitor the number of active Notes users within a Domino domain. You
can use License Tracking to determine how many client licenses you have, whether you need to purchase
additional licenses, and when you need to purchase them.

Note: License Tracking is not supported in a hosted environment.

How license tracking works

When License Tracking is turned on, client usage is tracked on each server and the data is temporarily
stored in the file LICENSE.NCF. When a user authenticates with a server using the Notes client, HTTP,
IMAP, POP3, SMTP, or the LDAP protocol, the user’s full canonical name, protocol, and time and date of
access are collected. Once each day (at midnight) , an administration request sends to the administration
process, information regarding new users and information regarding users who have not accessed the
server within the last 30 days. The administration process running on the administration server processes
the request.

The Domino User License Tracking database is created and resides on the administration server, not on
all servers. The database is not created as soon as the License Tracking feature is enabled; instead, it is
created when the administration process processes the first administration request to update the database.
The administration process creates a new User License document in the Domino User License Tracking
database (USERLICENSES.NSF) for each new user reported in the administration request. Documents are
updated with the new time and date for those users who already have a document in the Domino User
License Tracking database. If a user does not access any servers in the Domino domain for one full year,
the corresponding User License document is deleted from the Domino User License Tracking database.
Daily updates to the database enable you to review this information at any time to obtain an up-to-date
report on the number of client licenses that you have available for use.

Note: If a user is deleted from the Domino Directory, the corresponding document in the Domino User
License Tracking database is deleted. If a user is renamed, the corresponding document is also renamed
accordingly. Existing administration requests are used to maintain this user information.
260 Lotus Domino Administrator 7 Help
By default, administrators have Manager access to the Domino User License Tracking database and users
have no access.

Note: The Miscellaneous/Licenses view that displayed in Domino R5 is not part of the License Tracking
feature.

Enabling or disabling license tracking

Use this procedure to either enable or disable License Tracking.
1. From the Domino administrator, click the Configuration tab.
2. Choose Server - Configurations.
3. Select the server and click Edit Configuration.
4. On the Basics tab, in the License Tracking field, click Disabled or Enabled according to what you want
to do.
5. Click Save and Close.

Calculating the number of licenses in use

Use this procedure to recalculate the number of Notes and/or Domino Web Access users in your domain.
A document is created for each server in your domain, listing the number of Notes and Domino Web
Access users on each server.
1. From the Domino administrator, click the Files tab.
2. Open the Domino User License Tracking database.
3. Choose Licenses or Licenses - By Server and click Recalculate Licenses.

Deploying the ″My Work″ Welcome page for Notes

Notes client users can use the ″My Work″ Welcome page for Notes as their Welcome page. The My Work
page has three tabs which are divided into multiple panes for mail, calendar, To Do list, and other
options that they choose to use.

You can deploy a ″My Work″ Welcome page for users by creating the My Work page using the desktop
policy settings document. If you are deploying a My Work page for your users, as well as a custom
Welcome page for users who choose to use that, use the advanced configuration. The advanced
configuration adds an additional page to the Welcome Page wizard which contains the advanced options.
Use advanced configuration if you want to lock specific items on the My Work page, lock the entire My
Work page, or prevent users from adding Team tabs to the My Work page. If you are deploying only a
″My Work″ Welcome page, and you are not locking it to prevent users from editing the My Work page,
you do not need to use the advanced configuration.

For more information about using the advanced configuration with Welcome pages, see the topic
″Enabling the Default Welcome Page field in the Desktop policy settings document″ in this chapter.

The My Work page option is available to users directly from the Welcome page, as well as from the
Welcome Page wizard. They can set up their My Work page in a manner that best suits their individual
work responsibilities. You cannot disable the My Work page, but you can deploy a My Work page and
lock it so that users do not modify it. If the My Work page is not locked, users are able to modify it from
their desktops. The ″My Work″ Welcome page is created with the template, BOOKMARK.NTF.

For more information about policies, see the chapter ″Using Policies.″

Chapter 7. Managing Notes Users 261

262 Lotus Domino Administrator 7 Help
Chapter 8. Setting Up and Managing Groups
This chapter describes how to create and manage groups.

Using groups
Groups are lists of users, groups, and servers that have common traits. They are useful for mailing lists
and access control lists. Using groups can simplify administration tasks. For example, if you create a
group called ″Terminations″ that lists all former employees, you can enter the Terminations group name
in the ″Not access″ field in the Server Access section of the Security tab on each Server document. When
an employee leaves the company, you add the employee’s name to the Terminations group and then force
replication of the Domino Directory to prevent the employee from having access to all servers in the
domain. Using a Terminations group saves you the time and effort of manually adding individual
employee names to each Server document when employees leave the company.

To create a group, you create a Group document in the Domino Directory. You can add registered users
to the group as you create the Group document and you can add new users to a group as you register
them. There is no limit to the number of names that you can add to a group. However, the total number
of characters used for names in the group cannot exceed 32KB. To keep groups manageable, split a large
list of users into two or more groups.

By default, the Domino Directory contains two groups: LocalDomainServers and OtherDomainServers.
LocalDomainServers includes all servers in the current domain. Domino automatically adds servers that
you register in the current domain to the LocalDomainServers group. OtherDomainServers includes all
servers that are not in the current domain. For example, OtherDomainServers might include the names of
servers in other companies with which your company communicates. If you set up a connection to a
server in another company or domain, add the server name to the OtherDomainServers group.

A third group, LocalDomainAdmins, may reside in the Domino Directory if the ″Add
LocalDomainAdmins group to all databases and templates″ check box was selected during first server
setup for a domain. The LocalDomainAdmins group contains names of the domain administrators.

Each group must have an owner -- usually an administrator or database manager.

Using multiple group names

When you create a group in Domino Administrator, you can specify multiple group names for one group.
You need to be aware of the following information when using multiple group names:
v If you enter multiple group names into this field and separate those names with commas or
semi-colons, they resolve to multiple names separated by semi-colons.
v Any of the group names may be used to address the group. Names other than the first name in the
Group Name field resolve to the first name, and mail is delivered to members of the group.
v When searching the Domino Directory for any of the group names other than the first name entered in
the field, the name will not be found, and the first name in the field will not be offered as a match.

Creating and modifying groups

Create and modify groups from the Domino Administrator. You can nest one or more groups within an
existing group, that is, create a group and then add one or more existing groups as members of the new
group. For mail-routing, you can nest up to five levels of groups. For all other purposes, you can nest up
to six levels of groups. You can also use the Web Administrator to create and modify groups.

263
Creating a group with the Domino Administrator
1. Make sure that you have Editor access or Author access with the GroupCreator role in the Domino
Directory.
2. From the Domino Administrator, click the People & Groups tab.
3. From the Servers pane, select the server to work from.
4. Select Domino Directories, and then select Groups - Add Group.
5. Complete these fields on the Basics tab:

Field Action
Group name Enter a name for the group. It is recommended that you
use only these characters: A - Z, 0 - 9, & - . _ ’
(ampersand, dash, period, space, underscore, and
apostrophe) for the name. It is recommended that you do
not use special characters other than those listed because
some special characters may cause unexpected conflicts
or problems. A group name can be a maximum of 62
characters in length. For easier administration, use a
name without spaces. The only characters that are
expressly prohibited are @ and //.

Do not use a name that is in use as the name of an

organization in the hierarchical name scheme.
Note: Do not create group names containing a / (slash)
unless you are working in a hosted environment. Using
the / in group names in a non-hosted environment
causes confusion with hierarchical naming schemes.
Hierarchical names are required in a hosted environment.
Group type Select a group type. The group type specifies the purpose
of the group and determines the views in the Domino
Directory where the group name appears. For example,
mailing list groups appear in the Mail Users view, and
access control groups appear in the Access Control view.
Using specific group types improves performance by
reducing the size of view indexes in the Domino
Directory.
v Multi-purpose -- Use for a group that has multiple
purposes -- for example, mail, ACLs, and so on. This is
the default.
v Access Control List only -- Use for server and database
access authentication only.
v Mail only -- Use for mailing list groups.
v Servers only -- Use in Connection documents and in
the Domino Administration client’s domain bookmarks
for grouping.
v Deny List only -- Use to control access to servers.
Typically used to prevent terminated employees from
accessing servers, but this type of group can be used
to prevent any user from accessing particular servers.
The Administration Process cannot delete any member
of the group.
Category (Optional) Choose a Category if you have created any.
Use the category field to categorize groups in any way
that you need to.
Description (Optional) Enter a description of the group in the
Description field.

264 Lotus Domino Administrator 7 Help

Field Action
Mail Domain Enter the Domino domain in which this group’s mail
address will reside in the Mail Domain field.
Internet address Enter the Internet e-mail address for this group in the
Internet Address field.
Members Click Members, select users, servers, or groups to add,
click Add, and then click OK.

6. Click the Administration tab and make changes to these fields as necessary:

Field Action
Owners Add an owner name or modify the list of group owners.
Administrators Add an administrator name or modify the list of group
administrators.
Allow foreign directory synchronization Choose one:
v Yes -- To allow synchronization between a post office
directory, such as the cc:Mail post office directory or a
Microsoft Exchange Address Book, and the Domino
Directory
v No -- To prevent synchronization between a post office
directory, such as the cc:Mail post office directory or a
Microsoft Exchange Address Book, and the Domino
Directory
Last modified v Non-modifiable field. Provides the hierarchical name
of the last administrator that made changes to the
Group document.

7. Click Save and Close.

Creating a group with the Web Administrator

Create groups from the Web Administrator, just as you would from the Domino Administrator.
1. Make sure that you have Editor access or Author access with the GroupCreator role in the Domino
Directory.
2. From the Web Administrator, click the People & Groups tab.
3. Select Domino Directories, and then select Groups.
4. Click Add Group.

Chapter 8. Setting Up and Managing Groups 265

5. Complete these fields on the Basics tab:

Field Action
Group name Enter a name for the group. It is recommended that you
use only these characters: A - Z, 0 - 9, & - . _ ’
(ampersand, dash, period, space, underscore, and
apostrophe) for the name. It is recommended that you do
not use special characters other than those listed because
some special characters may cause unexpected conflicts
or problems. A group name can be a maximum of 62
characters in length. For easier administration, use a
name without spaces. The only characters that are
expressly prohibited are @ and //.

Do not use a name that is in use as the name of an

organization in the hierarchical name scheme.
Note: Do not create group names containing a / (slash)
unless you are working in a hosted environment. Using
the / in group names in a non-hosted environment
causes confusion with hierarchical naming schemes.
Hierarchical names are required in a hosted environment.
Group type Select a group type. The group type specifies the purpose
of the group and determines the views in the Domino
Directory where the group name appears. For example,
mailing list groups appear in the Mail Users view, and
access control groups appear in the Access Control view.
Using specific group types improves performance by
reducing the size of view indexes in the Domino
Directory.
v Multi-purpose -- Use for a group that has multiple
purposes -- for example, mail, ACLs, and so on. This is
the default.
v Access Control List only -- Use for server and database
access authentication only.
v Mail only -- Use for mailing list groups.
v Servers only -- Use in Connection documents and in
the Domino Administration client’s domain bookmarks
for grouping.
v Deny List only -- Use to control access to servers.
Typically used to prevent terminated employees from
accessing servers, but this type of group can be used
to prevent any user from accessing particular servers.
The Administration Process cannot delete any member
of the group.
Category (Optional) Choose a Category if you have created any.
Use the category field to categorize groups in any way
that you need to.
Description (Optional) Enter a description of the group in the
Description field.
Mail Domain Enter the Domino domain in which this group’s mail
address will reside in the Mail Domain field.
Internet address Enter the Internet e-mail address for this group in the
Internet Address field.
Members Click the arrow to the right of the Members field, select
users, servers, or groups to add, click Add, and then
click OK.

266 Lotus Domino Administrator 7 Help

6. (Optional) Click the Comments tab and enter comments as desired.
7. Click the Administrator tab and complete these fields as necessary.

Field Action
Owners Add an owner name or modify the list of group owners.
Administrators Add an administrator name or modify the list of group
administrators.
Allow foreign directory synchronization Choose one:
v Yes -- To allow synchronization between a post office
directory, such as the cc:Mail post office directory or a
Microsoft Exchange Address Book, and the Domino
Directory
v No -- To prevent synchronization between a post office
directory, such as the cc:Mail post office directory or a
Microsoft Exchange Address Book, and the Domino
Directory
Last modified v Non-modifiable field. Provides the hierarchical name
of the last administrator that made changes to the
Group document.

8. Click Save and Close.

Modifying groups with the Domino Administrator or Web Administrator

Use the Domino Administrator or the Web Administrator to modify groups.

Adding members to a group with the Domino Administrator or Web Administrator:

1. Make sure that you have Editor access or Author access with Create Documents role and
GroupModifier privilege in the Domino Directory.
2. From the Domino Administrator or Web Administrator, click the People & Groups tab.
3. From the Domino Administrator, from the Servers pane, choose the server to work from. Omit this
step if you are using the Web Administrator.
4. Select Domino Directories, and then select Groups.
5. Select the group to which you are adding members, and click Edit Group.
6. Do one of these:
v From the Domino Administrator, click Members and then select users, servers, or groups to add.
v From the Web Administrator, select the users, servers, or groups to add.
7. Click Add, and then click OK.
8. Click Save and Close.

Deleting members from a group with the Domino Administrator or Web Administrator:
1. Make sure that you have Editor access or Author access with GroupModifier privilege in the Domino
Directory.
2. From the Domino Administrator or Web Administrator, click the People & Groups tab.
3. From the Domino Administrator, from the Servers pane, choose the server to work from. Omit this
step if you are working with the Web Administrator.
4. Select Domino Directories, and then select Groups.
5. Select the group from which you are deleting one or more members, and click Edit Group.
6. Do one of these:
v From the Domino Administrator, click Members and then select users, servers, or groups to delete.
v From the Web Administrator, select the users, servers, or groups to delete.

Chapter 8. Setting Up and Managing Groups 267

7. Click Remove and click OK.

Note: From the Domino Administrator, to remove all members from the group, do not select any
members; just click Remove All, and then click OK.
8. Click Save and Close.

Creating a Terminations group with the Domino Administrator or Web Administrator: You may want
to create a group for employees who no longer have access to specific servers in your organization. When
you are deleting a person from the Domino Directory, you can then add that person’s name to a
Terminations group that is assigned a group type of Deny List Only. This is particularly useful for
preventing terminated employees from accessing servers.
1. Create a group named Terminations and assign it a group type of Deny List Only. For more
information on creating groups, see Creating a group with the Domino Administrator or Creating a
group with the Web Administrator.

Note: Groups of the type ″Deny List Only″ do not have to be named Terminations; assign any name that
you choose. We only suggest the name ″Terminations″ for clarity.
2. From the Domino Administrator or Web Administrator, follow instructions for deleting a user name,
but on the Delete Person dialog box, locate the ″Add deleted user to Deny Access Group″ field and
then click Groups.
For more information about deleting a user name, see the chapter ″Setting Up and Managing Notes
Users.″
3. Continue the delete process as usual, and then click OK.

Managing groups
To manage groups, you can do the following tasks:
v Assign a policy to a group
v Edit a group
v Deleting a group with the Domino Administrator or the Web Administrator
v Finding a group member
v Finding a group name in the domain with the Domino Administrator or Web Administrator
v Use the Manage Groups tool to add and remove group members

While managing groups, you may also need to recertify a certifier ID. To do so, see Recertifying a certifier
ID or a user ID.

Assiging a policy to a group

To apply policy settings to an entire group, you can assign a policy to the group. Assign an Explicit
policy or assign both an Explicit policy and an Organizational policy. An Explicit policy combined with
an Organizational policy creates an effective policy for the group. You can use the Policy Synopsis tool to
view how an effective policy affects the members of a group.

Prior to assigning policies to groups, familiarize yourself with all aspects of policies and how they are
applied.

For more information on policies and policy settings, see the chapter ″Using Policies.″

To assign a policy to a group:

1. From the Domino Administrator, click People & Groups tab.
2. Choose Groups and select the group to which you are assigning a policy.
3. Choose Tools - Groups - Assign Policy.

268 Lotus Domino Administrator 7 Help

4. Complete these fields:

Field Action
Selected Non-modifiable field. Displays the name of the selected
directory and the server on which the directory resides.
For: Non-modifiable field. Displays the number of groups
you have selected. This field is blank prior to finalizing
the assignment of a policy.
Users with an existing policy Non-modifiable field. Displays the number of users in
the selected groups who already have policies applied to
them. Prior to finalizing the assignment of the policy, this
field displays ″Unknown.″ After the policy is applied,
this field displays a value.
Policy Choose an explicit policy from the list. If this field
displays ″None Available,″ you have not created any
explicit policies that can be applied to a group.
Allow replacement of policies Click this check box to allow policies that have already
been applied to users in the selected groups to be
replaced by the policy you are now assigning.
View Policy Synopsis Click this check box only if you also assigning an
organizational policy to the selected groups. A policy
synopsis is composed of an explicit policy and an
organizational policy. The synopsis shows the net effect
of the two policies.

When you click this check box, the Choose

Perform updates in background
Organizational Policy dialog box opens. Choose the
Organizational policy that applies and click OK. The
Policy Synopsis document appears.
Click this check box to update in the background, the
group settings according to what is specified in the
policies. Performing all updates in the background
allows you continue using the Domino Administrator
client while updates are being performed. Updates are
done directly to the Domino Directory without using the
Administration Process.

5. Click OK.

Editing a group
Use this procedure to edit any of the group attributes that are listed on the Group document in the
Domino Directory. You can modify the group name, group type, description, group membership, group
owner, administrator, and specify whether foreign directory synchronization is allowed. Foreign directory
synchronization allows synchronization between a post office directory, such as the cc:Mail post office
directory or a Microsoft Exchange Address Book, and the Domino Directory.

With group renaming, there isn’t any tolerance for simultaneous occurrences of the new and old names
while the name change makes its way across databases in the domain. For example, if a group name
changes in the Domino Directory before it has a chance to change in a database ACL, the old group name
in the database ACL is invalid. (This limitation doesn’t occur with user and server renaming.) As a
workaround, you can initiate the group rename action during non-peak work hours -- for example,
during the weekend -- or you can immediately process the requests, rather than waiting for the changes
to occur according to Administration Process schedules.

To edit a group:
1. To edit a group, you must have:

Chapter 8. Setting Up and Managing Groups 269

 v Editor with Create documents access, or the UserModifier role to the Domino Directory
v At least Author with Create documents access to the Certification Log
2. From the Domino Administrator, click the People & Groups tab.
3. Select Domino Directories, and then select Groups.
4. Select the group that you want to edit, and click Edit Group.
5. Make changes to any of the following fields on the Basics tab:

Field Action
Group name Enter a name for the group. It is recommended that you use only these characters: A - Z,
0 - 9, & - . _ ’ (ampersand, dash, period, space, underscore, and apostrophe) for the
name. It is recommended that you do not use special characters other than those listed
because some special characters may cause unexpected conflicts or problems. A group
name can be a maximum of 62 characters in length. For easier administration, use a
name without spaces. The only characters that are expressly prohibited are @ and //.

Do not use a name that is in use as the name of an organization in the hierarchical name
scheme.
Note: Do not create group names containing a / (slash) unless you are working in a
hosted environment. Using the / in group names in a non-hosted environment causes
confusion with hierarchical naming schemes. Hierarchical names are required in a hosted
environment.
Group type Select one of these:
v Multi-purpose -- Use for a group that has multiple purposes -- for example, mail,
ACLs, and so on. This is the default.
v Access Control List only -- Use for server and database access authentication only.
v Mail only -- Use for mailing list groups.
v Servers Only -- Use in Connection documents and in the Domino Administration
client’s domain bookmarks for grouping.
v Deny List only -- Use to control access to servers. Typically used to prevent terminated
employees from accessing servers, but can be used to prevent any user from accessing
particular servers. The Administration Process cannot delete any member of the group.
Category (Optional) Select a category to which you are adding the group and click OK. The
Category field can be used to categorize your groups in any manner that you want. If the
category that you want to use is not listed in the dialog box, add the category name in
the New Keyword field and click OK.
Description Enter a description of the group.
Mail Domain Enter the name of the mail domain for the group. This is especially useful for enterprises
that have more than one mail domain.
Internet Address Enter the Internet address that applies to the group.

270 Lotus Domino Administrator 7 Help

Field Action
Members Add or remove group members. Type a member name in the field or double-click this
field to open the Select Names dialog box, and then do any of the following:
v Open another address book by selecting
v Find names that begin with a specified string if you are unsure of the spelling or the
complete name
v Add a person or group to the group by selecting the person or group and clicking Add
v Remove a group member by selecting the member in the right pane and clicking
Remove
v Remove all members of a group by clicking Remove All
v Add a member to a group by clicking New, typing the member name, and clicking OK
v View detailed information by selecting a person or group and clicking Details
v Copy an entry from the open address book to the Local address book by selecting the
name and clicking the Address Book icon
v Open another Group document by selecting the group name and clicking Open

6. Click the Administration tab and make changes to any of these fields:

Field Action
Owners Add an owner name or modify the list of group owners.
Administrators Add an administrator name or modify the list of group administrators.
Foreign directory Choose one:
synchronization v Yes -- To allow synchronization between a post office directory, such as the cc:Mail post
allowed office directory or a Microsoft Exchange Address Book, and the Domino Directory
v No -- To prevent synchronization between a post office directory, such as the cc:Mail
post office directory or a Microsoft Exchange Address Book, and the Domino Directory
Last modified Non-modifiable field. Provides the hierarchical name of the last administrator that made
changes to the Group document.

7. (Optional) To sort the list of group members before saving the Group document, click Sort Member
List.
8. Click Save and Close.

To immediately change the name of a group throughout the domain:

1. To process the ″Rename Group in Address Book″ request immediately, choose the group rename
action from the administration server for the Domino Directory and then enter this server command:
tell adminp process new
2. To immediately process the ″Rename in Person Documents″ request, from the administration server
for the Domino Directory, enter the command:
tell adminp process daily
3. Replicate the modified Domino Directory and Administration Requests database from the
administration server for the Domino Directory to all other servers in the domain.
4. To force processing of the ″Rename Group in Access Control List″ and ″Rename Group in
Reader/Author fields″ requests on each server, on each server in the domain, enter the command:
tell adminp process all
For more information on server commands, see the appendix ″Server Commands.″

Deleting a group with the Domino Administrator or the Web Administrator

Follow these steps to use the Administration Process to delete a group from the Domino Directory and
from database ACLs and Extended ACLs.

Chapter 8. Setting Up and Managing Groups 271

If the server is running Active Directory and contains a group account for this group, you can delete that
group account, too.

For more information about synchronizing Domino and Active Directory, see the chapter ″Using Domino
with Windows Synchronization Tools.″

To delete a group with the Domino Administrator:

1. To delete a group, you must have at least Author with delete documents access and the
GroupModifier role, or Editor access to the Domino Directory.
2. From the Domino Administrator, click the People & Groups tab.
3. Select the name of the group you are deleting.
4. Click Delete Group and click Yes to continue.
5. If the server is running Active Directory, Domino prompts you to delete the corresponding group
account from the Windows domain. Click Yes to delete the group account.
6. Select one of the following:
v Yes - to immediately delete all references to the group in this replica of the Domino Directory.
v No - to post a ″Delete in Address Book″ request in the Administration Requests database and have
the Administration Process delete references to the group in the Domino Directory, and database
ACLs and Extended ACLs.
v Cancel - to cancel the request entirely.
7. Click OK.

Tip: You can also delete a group from the Tools panel using Groups - Delete.

To delete a group with the Web Administrator:

1. To delete a group, you must have at least Author with delete documents access and the
GroupModifier role, or Editor access to the Domino Directory.
2. From the Web Administrator, click the People & Groups tab.
3. Select the name of the group you are deleting.
4. Click Tools - Groups - Delete.
5. Choose any of these options on the Delete Groups dialog box.

Field Action
Delete group from this Directory immediately. Click this check box to immediately delete all references
to this group in this replica of the Domino Directory.

If you do not choose this option, a ″Delete in Address

Delete the groups Windows domain account.
Book″ request is posted in the Administrator Requests
database and the Administration Process deletes
references to the group in the Domino Directory,
database ACLs, and Extended ACLs.
Click this check box to delete the group’s corresponding
Windows domain account if one exists.

6. Click OK.
7. Click Close.

Finding a group name in the domain with the Domino Administrator or Web
Administrator
Use this procedure to locate every occurrence of one or more specific group names within a domain. This
is especially useful when moving groups to other servers or domains or when verifying that you have
completely deleted a group name from your domain.

272 Lotus Domino Administrator 7 Help

To find a group name with the Domino Administrator:
1. From the Domino Administrator, click the People & Groups tab.
2. Select one or more group name(s) that you want to locate in the domain.
3. From the Tools pane, click Groups - Find Group(s).
4. Click Yes to initiate the Administration Request to locate all the occurrences of the selected group(s) in
the enterprise.

To find a group name with the Web Administrator:

1. From the Web Administrator, click the People & Groups tab.
2. From the Tools pane, click Groups - Find Group(s).
3. Enter a group name in the Find Groups dialog box and click Send.
4. (Optional)Continue adding group names that you want to search for.
5. Click Done.

To view the log of locations: To view the log of locations where the group name(s) are located:
1. From the Domino Administrator, click Server - Analyses - Administration Requests (7).
2. Select the view All Requests by Action and access the ″Find Name in Domain″ request.
3. Double-click the request to access the Administration Process - Log document. Locate the ″Links to
items found within Domino Directory documents:″ field. This field contains the links to the Group
documents located using the Find Groups action.

Finding a group member

You can quickly locate a group member by completing the following procedure.
1. From the Domino Administrator, click the People & Groups tab, and then click Groups.
2. On the Action bar, click Find Group Member.

Note: You may have to scroll to the right to reveal the button.
3. Enter the common name (for example, Jane Doe) and click OK. If the group member is found, a check
mark appears next to the group or groups in which the member name is located.

Tip: You can also find a group member from the Domino Directory, Groups view.

Using the Manage Groups tool to manage groups

The Manage Groups option on the tools pane provides a quick and easy method for managing existing
Domino groups. You can open any Domino Directory to which you have access, and you can then add or
remove people and groups from groups as necessary. You can also view details on groups.

To use the Manage Groups tool:

1. From the Domino Administrator, click the People & Groups tab.
2. From the tools pane, click Groups - Manage.
3. Complete these fields as necessary:

Field Enter
People and Groups The directory that you want to open. A list of all users and groups in the
directory is displayed.
Look In
Group Hierarchies The directory containing the group you are managing.

Look in

Chapter 8. Setting Up and Managing Groups 273

Field Enter
Show me Choose one:
v All group hierarchies -- To display all of the group hierarchies in the selected
directory.
v Only member hierarchies -- To display all of the groups in which the selected
user is a member.
List alphabetically Lists alphabetically, all people and groups in the selected directory.
List by organization Lists by organization, all people and groups in the selected directory.
Show group type v Multi-purpose -- Use for a group that has multiple purposes -- for example,
mail, ACLs, and so on. This is the default.
v Access Control List only - Use for server and database access authentication
only.
v Mail only -- Use for mailing list groups.
v Servers Only -- Use in Connection documents and in the Domino
Administration client’s domain bookmarks for grouping.
v Deny List only -- Use to control access to servers. Typically used to prevent
terminated employees from accessing servers, but can be used to prevent any
user from accessing particular servers. The Administration Process cannot
delete any member of the group.

4. Do any of the following:

v To add a member to a group, select the group in the Group hierarchies pane, then select the user or
group from the People & Groups list, and click Add.
v To remove a member from a group, select the member from the Group hierarchies pane, and click
Remove. To remove all members from a group, click the Member field, do not select any members,
and click Remove All, and then click OK.
v To view a group document, select the group from the Group hierarchies pane and click Details.
5. When you finish managing groups, click Done.

274 Lotus Domino Administrator 7 Help

Chapter 9. Creating Replicas and Scheduling Replication
This chapter explains how to set up replicas and schedule replication.

Replicas
To make a database available to users in different locations, on different networks, or in different time
zones, you create replicas. All replicas share a replica ID which is assigned when the database is first
created. The file names of two replicas can be different, and each replica can contain different documents
or have a different database design; however, if their replica IDs are identical, replication can occur
between them.

As users add, edit, and delete documents in different replicas of a database, the content in the replicas is
no longer identical. To ensure that the content in all replicas remains synchronized, you use Connection
documents to schedule replication between the servers that store the replicas. Then multiple sites, teams,
and users can make changes to a database and share those changes with everyone else who has access to
that database. In addition, using replicas and scheduling replication reduces network traffic. Users never
need to connect to a single central server that stores the only replica of a particular database. Instead,
they can access a replica of that database on one or more local servers.

These distributed replicas can also be Web sites that are hosted on different Lotus Domino 7 servers.
Then users aren’t dependent on one server when they attempt to access critical applications over the
Internet. If one server is unavailable, users can access another replica of the database on another server.
You can also use replicas to help manage ongoing Web site design. On one server, you can set up a Web
staging area where you design and test new pages. When the design changes are tested and ready to be
released, you can replicate this server with the server storing the replica of the Web site that is available
to users. By using replicas and replication this way, you prevent Web users from seeing your
″work-in-progress.″

A replica of a database isn’t the same as a copy of a database that you make by choosing File - Database -
Copy. Although a copy of a database may look the same as the original database, a copy doesn’t share a
replica ID with the original database and so it can’t replicate with it.

Deciding when to create a replica

Plan your replica strategy carefully, and create replicas on servers only when necessary. The more
replicas, the greater the demand on server and network resources and the greater the need for additional
maintenance. To prevent unnecessary proliferation of replicas, assign Create Replica server access to only
a few administrators. Then tell users and application developers to send their requests for new replicas to
these administrators.

Create a replica of a database to:

v Improve performance of a heavily used database.
v Distribute network traffic.
v Keep a database that you’re redesigning separate from a production version of the database.
v Keep a database available even if one server goes down.
v Make a database available to users in remote locations.
v Provide a replica containing only a subset of information that is relevant to a particular workgroup.
v Set up Domino system administration -- for example, you must create replicas of the Domino Directory,
the Administration Requests database, and other critical system databases.

275
v Place a replica of a master template on each server that stores a database that inherits from the master
template.
v Create a backup database from which you can restore information if data becomes corrupted; since
corrupted data often replicates, use this only as a secondary backup method.

Keep in mind that two replicas will contain slightly different content between replications. If users need
access to the most up-to-date information in a database, you can create replicas on clustered servers and
then set up replication in clusters. In a cluster, all replicas are always identical because each change
immediately replicates to other servers in the cluster.

For more information on setting up individual databases for replication, see the topic ″Creating replicas
using the Administration Process″ in this chapter.

How server-to-server replication works

For server-to-server replication, the Replicator on one server calls another Domino server at scheduled
times. By default, the Replicator is loaded at server startup.

To schedule replication between servers, the servers must be able to connect to each other in order to
update replicas. You may need to create Connection documents to enable server connections, depending
on your server topology. As users add, edit, and delete documents in a database, the replicas contain
slightly different information until the next time the servers replicate. Because replication transfers only
changes to a database, the network traffic, server time, and connection costs are kept to a minimum.

During scheduled replication, by default, the initiating server first pulls changes from the destination
server and then pushes changes to the destination server. As an alternative, you can schedule replication
so that the initiating server and destination server each pull changes or so that the initiating server pulls
changes only or pushes changes only.

You can also use the server commands Pull, Push, and Replicate to initiate replication between servers.

For more information on server connections and Connection documents, see the chapter ″Setting up
Server-to-Server Connections.″

Replication, step-by-step
To fully-understand replication, you need to be familiar with the information in the topics ″Guidelines for
setting server access to databases″ and with ″Setting up a database ACL for server-to-server replication″
in this chapter. You also need to fully familiarize yourself with the information on replication in the
appendix ″Server Commands.″
1. Replication is initiated by a server or a workstation in one of the following ways:
v Replication schedule settings in a Connection document take effect.
v A replication command to replicate immediately is issued at the server console. The server console
commands include replicate, pull, push, and load replica.
v Settings in a Program document. The Program document starts a new task on the server rather than
sending work to an existing task.
v A replication command to replicate immediately is issued by an end-user working in the Notes
client user interface. This is done from a workstation only, not from a server.
v Scheduled replication from a Notes client. This is done from a workstation only.
The servers authenticate each other by finding a certificate in common and testing to be sure that
certificates are authentic.
2. The Replicator constructs a list of local files to replicate and asks the remote server to find those that
have a match with the list of local files.

276 Lotus Domino Administrator 7 Help

 Note: If the server initiating the replication cannot connect to the remote server, or if it cannot search
the remote server (Server B), replication fails.
3. When the Replicator finds a match, it looks at the replication history to find the last time the replicas
replicated. The Replicator uses the history in the local database which is the destination database
when ″pulling″ and is the source database when ″pushing.″ Typically there are two such entries, one
for each direction (push/pull).
v If there is no entry in the replication history, if access rights have changed, or if the selective
replication settings have changed, the Replicator has to search all documents in the source database,
not just those that have changed since the last replication.
4. The Replicator searches the source replica for changes that have occurred since the last replication.
v The Replicator constructs a list of documents in the source database that have changed since the
last successful replication. (For a pull, the source is the database on the remote server; for a push,
the source is the database on the local server.) The list is restricted by the Selective Replication
Settings. The time that the search begins is recorded in the replication history so that succeeding
replications do not process changes that have been replicated.
v If the data in the source database has not changed since last successful replication to the destination
database, no replications take place and the replication history is not updated.
5. Replication between the source database and the destination database occurs. Replication history is
updated fro replication from source database to destination database. If access is sufficient, replication
history for both the source and destination databases is updated.
v If replication is not successful, the replication history is not updated and the next replication will
search the same databases again.
For more information about server console replication commands, see the appendix ″Server
Commands.″
For more information about the Program document, see the appendix ″Server Tasks.″

Guidelines for setting server access to databases

For replication to occur properly, you must assign servers the appropriate access in the database ACL.
Follow these guidelines when you set server access to databases.

Assign an access level that is at least as high as the highest user access level
For example, design changes made to the replica on Server A replicate to Server B only if the replica on
Server B gives Server A at least Designer access.

Include servers in read access lists for database design elements

If a database design element has a read access list associated with it that allows access only to certain
users with Reader access, include the names of replicating servers in the read access list in addition to the
server names with Reader access in the database ACL. For example, if a replica on Server A includes a
form access list that limits who can read documents created with the form, include Server B in the read
access list and give Server B at least Reader access in the ACL to allow Server B to pull new documents
and changes to documents created with the form.

Assign appropriate access to intermediate servers

If replication occurs through an intermediate server, the intermediate server acts first as a destination
server, then as a source server and must have the access level necessary to pass along the changes. For
example, if you want ACL changes on Server A’s replica to replicate to Server C by way of Server B,
Server B’s replica must give Manager access to Server A, and Server C’s replica must give Manager
access to Server B.

Assign Reader access for one-way replication

Give a server Reader access to a replica when you want to allow the server to receive information from
the replica but not to send changes back. For example, to allow Server B to receive changes from a replica
on Server A but not to send changes to Server A, give Server B Reader access to the replica on Server A.

Chapter 9. Creating Replicas and Scheduling Replication 277

Assign Editor access to allow author changes to replicate
If a replica includes an Authors field that allows authors to modify their own documents, a server must
have at least Editor access, not Author access, to replicate these modifications. For example, changes
made to Server A’s replica by someone with Author access only replicate to Server B if Server B’s replica
gives Server A at least Editor access.

Setting up a database ACL for server-to-server replication

You add the names of servers to a database ACL in the same way that you add the names of people. The
access level given to a server in an ACL determines what, if any, changes that server can replicate to the
replica.

For more information on setting up a database ACL, see the chapter ″Controlling User Access to Domino
Databases.″

Default server groups in an ACL

By default, every database ACL includes the server groups LocalDomainServers and
OtherDomainServers.

LocalDomainServers

This group represents servers that are in the same Domino domain as the server that stores the replica.
Typically you assign this group a higher access level in the database ACL than the OtherDomainServers
group.

OtherDomainServers

This group represents servers that are not included in the Domino domain of the server that stores the
replica. Typically you assign this group a lower access level in the database ACL than
LocalDomainServers. For example, assigning this group Reader access in the ACL ensures that the local
Domino domain retains control over the database.

Note: Do not add the names of servers from outside companies to LocalDomainServers or to
OtherDomainServers. Both these groups are included in all databases by default and may have a high
access level in some cases. Instead, create a group specifically for the external servers with which your
company communicates; for example, create a group called ″External Servers.″ Then add this group to
database ACLs as needed.

For more information on setting up groups, see the chapter ″Setting Up and Managing Groups.″

Access level privileges

For each access level, you can select or deselect these privileges:
v Create documents
v Delete documents
v Create personal agents
v Create personal folders/views
v Create shared folders/views
v Create LotusScript/Java agents
v Read public documents
v Write public documents

In general, for servers, enable all the privileges that the selected access level allows. This ensures that the
server has access that is as high as users might have and can replicate all user changes. However, to
prevent certain changes from replicating without deselecting privileges for each user, you can deselect a

278 Lotus Domino Administrator 7 Help

particular privilege for a server entry in the ACL. For example, to prevent all document deletions made
in a database on a particular server from replicating, deselect ″Delete documents″ in the ACL entry for
the server. Then when users who have ″Delete documents″ access in the ACL delete documents, the
deletions don’t replicate.

For more information on setting up database ACLs, see the chapter ″Controlling User Access to Domino
Databases.″

Server access levels

This table describes access levels in terms of server access, from the highest access to the lowest.

Access level Allows a server to push these changes Assign to

Manager ACL settings Servers you want to use as a source for ACL
changes. For tight database security, give this
Database encryption settings access to as few servers as possible. In a
hub-and-spoke server configuration, you
Replication settings typically give the hub server Manager access.
All elements allowed by lower access levels
Designer Design elements Servers you want to use as the source for
design changes. Use Manager access instead if
All elements allowed by lower access levels you want one server to control ACL and design
changes.
Editor All new documents Servers that users use only to add and modify
documents. In a hub-and-spoke configuration,
All changes to documents you typically give the spoke servers Editor
access.
Author New documents No servers. You don’t typically use this access
for servers.
Reader No changes; server can only pull changes Servers that should never make changes.
Servers in the OtherDomainServers group are
often given Reader access.
Depositor New documents. Also prevents the server from No servers. You don’t typically use this access
pulling changes. for servers.
No Access No changes. Also prevents the server from Servers to which you want to deny access.
pulling changes. Servers in the OtherDomainServers group are
sometimes given No Access.

Note: A database that doesn’t replicate should have at least one server in its ACL to serve as the
administration server for the database. This allows the Administration Process on a server to update
names in the ACL when names in the organization change.

For more information on administration servers, see the chapter ″Setting Up the Administration Process.″

Creating replicas using the Administration Process

Through the Domino Administrator you can use the Administration Process to initiate the creation of one
or more replicas. You can create replicas on servers in the same domain or in another domain. You
should make sure that Connection documents are in place to schedule replication between the source and
destination servers, unless the servers are members of the same cluster, in which case this is not strictly
necessary.

For more information on the administration requests that processed while creating a replica see the
appendix ″Administration Process Requests.″
1. If you are creating a replica on a destination server in another domain, make sure that:

Chapter 9. Creating Replicas and Scheduling Replication 279

 v There is an outbound Cross Domain Configuration document in the Administration Requests
database (ADMIN4.NSF) on the source server that allows the Administration Process to export
Create Replica requests to the destination server.
v There is an inbound Cross Domain Configuration document in the Administration Requests
database on the destination server that allows the Administration Process to import Create Replica
requests from the source server’s domain.
v Connection documents enabled for mail are in place that allow the source server to send mail to at
least one server in the destination server’s domain.
v You’ve set up cross-certification if servers in the two domains do not share a common certifier.
2. Make sure that you:
v Have Create Database access in the Server document of the destination server(s).
v Have at least Reader access in the ACL of the databases on the source server.
3. Make sure that the source server:
v Is running the Administration Process.
v Has Create Replica access in the Server document of the destination server(s).

Note: Do not use the wild card character (*) in the ″Create Replica″ field of the destination
server’s Server document because this character causes the request to fail.
4. Make sure each destination server:
v Is running the Administration Process.
v Has at least Reader access in the ACL of the source replica.
5. From the Domino Administrator, select the source server in the server pane on the left. To expand
the server pane, click the servers icon in the server pane.
6. Click the Files tab.
7. In the files window, select one or more databases for which you want to create replicas.
8. From the Tools pane, choose Database - Create Replica. Or, drag the selected database(s) to the
Create Replica tool.
9. (Optional) If the current domain includes a cluster, click ″Show only cluster members″ to display
only destination servers that are members of the cluster.
10. Select one or more destination servers. To select a server if it doesn’t appear in the list, select Other,
specify the hierarchical server name, then click OK.
11. (Optional) Select a destination server, click ″File Names″ to choose a custom file path on the
destination server for any database you’re replicating, and then click OK. You can repeat this
procedure for each destination server. If you don’t choose this option, the database is stored on the
destination server in the same location as on the source server.
To put the replica in a directory below the data directory, type the directory name, backslash, and
then the file name -- for example, JOBS\POSTINGS. If the specified directory does not exist, Domino
creates it for you.
12. Click OK. A dialog box shows the number of databases processed and indicates if any errors
occurred.

Creating replicas by dragging databases to a destination server

You can drag and drop databases to a destination server icon to create replicas on that server. When you
use this method, store all replicas in one, preexisting directory on the destination server. This method
uses the Administration Process to automate creation of the replica.
1. From the Domino Administrator, click the Files tab.
2. Select one or more databases you want to replicate in the files pane.
3. Drag the selected databases to a destination server in the server pane on the left.
4. In the dialog box that appears, select ″Create replica,″ select a directory on the destination server in
which to store the replica(s), then click OK.

280 Lotus Domino Administrator 7 Help

Table of replication settings
By default, two replicas exchange all edits, additions, and deletions if the servers the replicas are on have
the necessary access. However, you can customize replication. For example, to save disk space, you can
prevent the transfer of documents that are not pertinent to your site.

You can specify replication settings on a new replica as you create it or on an existing replica. You can
specify some replication settings for multiple replicas at once from a central source replica. You must
have Manager access to a replica to set replication settings for it.

CAUTION:
Replication settings are not intended to be used as a security measure.

This table summarizes the available replication settings.

Setting Controls Panel option

Remove documents not modified in the
last x days
Only replicate incoming documents saved
or modified after: date
When Domino purges document Space Savers
deletion stubs and, optionally,
unmodified documents
The cutoff date, so that a replica Other
only receives documents created or
modified since the date.

Which documents are scanned

Receive summary and 40KB of rich text
only
Replicate a subset of documents
during the first replication after
clearing the replication history
The size of documents that a replica Space Savers
receives
Which documents a replica receives Space Savers

Replicate
Do not send deletions made in this replica
to other replicas
Do not send changes in database title &
catalog info to other replicas
Do not send changes in local security
property to other replicas
Temporarily disable replication
Scheduled replication priority
CD-ROM publishing date
Advanced
Which non-document elements this Advanced
replica receives
Whether a replica can send Send
document deletions to other replicas
Whether a replica can send changes Send
to the database title and Database
Catalog categories to other replicas
Whether a replica can send changes Send
to the Encryption database property
(in the Basics tab of the Database
Properties box) to other replicas
Whether a replica can replicate Other
The replication priority of a Other
database used in Connection
documents for scheduling
replication
The publishing date for a database Other
on a CD-ROM

You can manage these settings for multiple replicas from a central source replica.

For more information, see the topic ″Specifying replications settings for multiple replicas from one source
replica″ in this chapter.

Chapter 9. Creating Replicas and Scheduling Replication 281

Limiting the contents of a replica
Use the following replication settings to limit the size of a replica or to display a subset of information
relevant to a particular group of users.

Remove documents not modified in the last x days: The number of days specified here, known as the
purge interval, controls when Domino purges deletion stubs from a database. Deletion stubs are markers
that remain from deleted documents so that Domino knows to delete documents in other replicas of the
database. Because deletion stubs take up disk space, Domino regularly removes deletion stubs that are at
least as old as the value specified. It checks for deletion stubs that require removal at 1/3 of the purge
interval. For example, assuming the default value, 90 days, when a user opens a database, Domino
checks if it has been at least 30 days since it removed deletion stubs, and if so it removes any deletion
stubs that are at least 90 days old. The Updall task, which runs by default at 2:00 AM, also removes
deletion stubs.

You can shorten the purge interval, if you want, but be sure to replicate more frequently than the purge
interval; otherwise, deleted documents can be replicated back to the replica.

Optionally, you can select the check box to remove documents in the replica that haven’t changed within
the purge interval. If you select the check box, when Domino removes deletion stubs it also removes
documents that haven’t changed within the specified number of days. These documents are purged,
meaning no deletion stubs remain for the documents, so the documents aren’t deleted in other replicas.
The ″Only Replicate Incoming Documents Saved or Modified After: date″ setting prevents the purged
documents from reappearing through replication. If the other replicas have this check box selected,
similar document purging occurs in them.

CAUTION:
If you select the check box on a non-replicated database, documents are lost and you can only recover
them from a system backup.

Note: Domino regularly removes deletion stubs according to the purge interval even if you don’t select
the check box.

Only Replicate Incoming Documents Saved or Modified After: date: A replica can only receive
documents created or modified since the date specified. If you clear the database replication history,
during the next replication, Domino scans only documents created or modified since the date specified
here. If you clear the date before clearing the replication history, Domino scans all documents in the
database.

Use this option in conjunction with clearing the replication history to solve replication problems. If you
clear or change this date, when Domino next purges deletion stubs, it resets the date to correspond to the
number of days specified in ″Remove documents not modified in the last x days″ setting. For example, if
Domino purges deletion stubs on 1/1/99 and the ″Remove documents not modified in the last x days″
setting is 90, on 1/1/99 Domino resets the date to 10/1/98. If the check box is selected in the ″Remove
documents not modified in the last x days″ setting -- meaning documents that meet the purge interval
criteria are purged as well as deletion stubs -- this automatic date reset insures that the purged
documents aren’t replicated back into the replica.

Receive summary and 40KB of rich text only: If you select this setting, Domino prevents large
attachments from replicating and shortens the documents that this replica receives. The shortened
documents contain only a document summary that includes basic information, such as the author and
subject, and the first 40K of rich text.

When users open a shortened document, they see ″(TRUNCATED)″ in the document title. To view the
entire document, users open it and choose Actions - Retrieve Entire Document.

Keep the following points in mind when using this setting:

282 Lotus Domino Administrator 7 Help

v Users can’t categorize or edit shortened documents.
v Agents don’t work on shortened documents.
v Shortened documents do not replicate unless the destination replica also has this option selected.

Replicate a subset of documents: Use this setting to specify that a replica receives only the documents
in a specific directory or view or only documents that meet selection criteria specified in a formula.
Replication formulas are similar to view selection formulas.

Keep in mind the following points when you use replication formulas:
v You cannot use @DbLookup, @UserName, @Environment, or @Now in a replication formula.
v Using @IsResponseDoc in a replication formula causes all response documents in a database to
replicate, not just those that meet the selection criteria. To avoid this, use @AllChildren or
@AllDescendants instead. If you use @AllChildren or @AllDescendants, make sure the database
performance property ″Don’t support specialized response hierarchy″ is not selected.

Replicate: Use this setting to control which non-document elements a replica receives. This table
describes the options:

Replicate Default Description

Forms, views, and so on Selected If selected, allows a replica to receive design changes, such as
changes to forms, views, and folders from a source replica.

If deselected, prevents a replica from receiving design changes.

Alternatively, you can assign source servers Editor access or
lower in the ACL; however, doing so prevents agents from
replicating.

Don’t select this option when you first create the replica because
the new replica won’t contain any design elements for displaying
information.
Agents Selected If selected, allows a replica to receive agents. If deselected,
prevents the replica from receiving agents, although the replica
still receives changes made by the agents.
Replication formula Not selected If selected, ensures that replication settings specified for multiple
destination replicas from one source replica can replicate. This
option is required if you’re using a central source replica to
manage replication settings for multiple replicas.
Access control list Selected If selected, allows the replica to receive ACL changes from any
server that has Manager access in the replica’s ACL.
Deletions Selected If selected, allows the replica to receive document deletions. If
deselected, the replica won’t receive deletions through replication,
but users assigned ″Delete documents″ access in the replica ACL
can still delete documents from the replica.
Note: If ″Do not send deletions made in this replica to other
replicas″ (on the Send panel of the Replication Settings dialog
box) is selected for the source replica, this replica won’t receive
deletions from the source replica, regardless of this setting.
Fields Not selected If deselected, the replica receives all fields in each document
received. If selected, you select a subset of fields to receive, but
you should only do this if you have a thorough knowledge of
application design.

Limiting what a replica sends

Use these settings to limit what one replica sends to other replicas.

Chapter 9. Creating Replicas and Scheduling Replication 283

Do not send deletions made in this replica to other replicas: This setting prevents deletions made in
this replica from replicating. As an alternative, you can deselect the ACL option ″Delete documents″ for
the server storing this replica.

Do not send changes in database title & catalog info to other replicas: This setting prevents changes
made to this replica’s database title or Database Catalog categories from replicating.

Do not send changes in local security property to other replicas: This setting prevents changes to the
database Encryption property (set by choosing Encryption on the Basics tab of the Database Properties
box). Use this primarily to prevent changes made to this property on a local replica from replicating to a
server. For example, if this setting is selected and you disable the Encryption property on a local replica,
the property remains selected on a server replica.

Assigning miscellaneous replication settings

The Other panel of the Replication Settings dialog box includes these miscellaneous settings.

Temporarily disable replication: Select this to temporarily suspend replication while you troubleshoot a
problem. You can select this for one database, or if you use the Domino Administrator, you can disable
replication of multiple databases. If a database is on a cluster server, disabling replication suspends both
cluster replication and scheduled replication.

For more information on clusters, see Administering Domino Clusters.

Scheduled replication priority: You can assign a priority of High, Medium, or Low to a database. Then
in a Connection document, you can schedule replication so that databases of a particular priority replicate
at specific times. For example, you can schedule low-priority databases to replicate less frequently and
schedule high-priority databases to replicate more frequently. If you assign a different priority to two
replicas, the priority of the replica on the server that initiates the scheduled replication takes precedence.

Replication priority doesn’t apply to replicas on a cluster of servers. Cluster replication occurs whenever
a change occurs, not according to schedules in Connection documents.

CD-ROM publishing date: Some organizations -- for example, publishing companies -- distribute
databases on CD-ROM rather than replicate them. To receive updates, users replicate with a replica on
the organization’s server. The users specify the date the information was published on the CD-ROM so
that the first replication with the organization’s replica scans only documents created or modified since
the publishing date. If users do not specify the date, the initial replication unnecessarily scans the entire
database, which can be a slow process, especially if it occurs over a dial-up connection.

Specifying replication settings for one replica

1. Make sure you understand replication settings.
2. Do one of the following:
v To specify replication settings for a replica as you create it, click Replication Settings in the New
Replica dialog box.
v To modify replication settings on an existing replica, open the replica and choose File - Replication -
Settings. This requires Manager access.
3. Click the Space Savers panel and then select/deselect options.
4. Click the Send panel and then select/deselect options to limit what the replica can send to other
replicas.
5. Click the Other panel and then select/deselect options.
6. Click the Advanced panel and then select/deselect any of the options under ″Replicate.″ Ignore the
options above ″Replicate.″ These are used for managing replication settings for multiple replicas of a
database from one central source replica.
7. Click OK.

284 Lotus Domino Administrator 7 Help

Specifying replication settings for multiple replicas from one source replica
You can customize replication settings for multiple replicas of a database from one central source replica
and then replicate these custom settings to the appropriate replicas. This approach to customizing
replication allows you to centralize replication management and requires that you know the replication
requirements for each replica.

The only replication settings you can specify using centralized management are ″Replicate a subset of
documents,″ to control which documents a replica receives, and ″Replicate,″ to control which
non-document elements a replica receives.

Note that changing centrally-administered replication settings requires two replications for the changes to
take effect: the first replication to replicate the new settings from the source server to the destination
servers and a second replication to replicate based on the new settings. The second replication doesn’t
occur until the source database is updated in some other way; to force the new settings to take effect if
the source database isn’t updated, clear the replication history.
1. Make sure you understand replication settings.
2. Make sure you have Manager access in the ACL of the central source replica. Make sure that the
central source replica has Manager access in the ACL of all destination replicas.
3. Do one of the following:
v Click Replication Settings in the New Replica dialog box to specify replication settings for a new
replica.
v Open the central source replica, and then choose File - Replication - Settings to modify existing
replication settings.
4. Click the Advanced panel.
5. To specify a destination server, click the computer icon next to ″When computer,″ specify the name
of the destination server, select Add Server, then click OK. Or accept the default entry. To specify a
Notes client as a destination server, enter the Notes user’s hierarchical name.
6. To specify a source server, click the computer icon next to ″Receives from,″ specify the name of a
source server, select Add Server, then click OK. Or accept the default entry. To specify the name of a
Notes client as a source server, enter the Notes user’s hierarchical name.
7. To delete a server, click either computer icon, select a server, select Delete Server, then click OK.
8. To have the specified destination replica receive a subset of documents, click ″Replicate a subset of
documents″ and then specify the views/folders to replicate or specify a replication formula.
9. To specify which non-document elements the replica should receive, select appropriate options under
″Replicate.″ You must select ″Replication formula.″
10. Repeat Steps 5 through 9 for each additional destination/source server combination.
11. Click OK.

Examples of specifying replication settings for multiple replicas

Note: Do not use the server’s common name when replicating servers. Only the server’s full hierarchical
name should be used during server-to-server replication. This applies to all instances of server-to-server
replication. For example, when replicating from the server console, Connection documents, or from the
Domino Administrator.

Using the same replication settings for all destination servers: The Acme Corporation has a database
called Technical Support on the server Support-E/East/Acme, which it uses to post information about
customer problems and problem resolutions. The database displays customer suggestions made during
the support calls in a view called Customer Suggestions. Acme has three servers at satellite sales offices:
Sales-Bos-E/East/Acme, Sales-Phil-E/East/Acme, and Sales-Hart-E/East/Acme. The satellite sales offices
are only interested in customer suggestions and not in other details of technical support calls. Therefore,
Acme replicates only the contents of the Customer Suggestions view to these servers. To accomplish this,
it completes the replication settings dialog box on the Technical Support database on

Chapter 9. Creating Replicas and Scheduling Replication 285

Support-E/East/Acme as follows. Note that although the ″When computer″ box shows only
Sales-Bos-E/East/Acme, there are similar settings for Sales-Phil-E/East/Acme and Sales-Hart-
E/East/Acme.

Using separate replication settings for each destination server: The Acme Corporation has a database
called Sales Leads on the server Sales-E/East/Acme. Acme has three servers at satellite sales offices:
Sales-Bos-E/East/Acme, Sales-Phil-E/East/Acme, and Sales-Hart-E/East/Acme. Each satellite sales office
is only interested in leads pertaining to its area. Each document in the Sales Leads database includes the
field ″Office″ with one of these keywords selected: Boston, Philadelphia, Hartford. To replicate only sales
leads pertaining to Boston to Sales-Bos-E/East/Acme, Acme completes the replication settings dialog box
on the Sales Leads database on Sales-E/East/Acme.

Acme sets up replication from Sales-E/East/Acme to Sales-Phil-E/East/Acme and to

Sales-Hart-E/East/Acme in a similar fashion.

Although these examples describe server-to-server replication, you could use similar settings to configure
replication between a central source replica and replicas on Notes clients. For example, salespeople could
replicate directly with the source replica and receive only leads pertinent to their areas. To accomplish
this, specify Notes users’ hierarchical names as destination servers.

Scheduling times for replication

Whenever possible, schedule replication for times when there is less activity on the network -- before or
after work or at lunch time.

You can schedule server-to-server replication to happen at specific times, or you can specify a time range
with a repeat interval. By scheduling replication for a time range, you ensure that the servers exchange
information several times a day. After the server makes a successful connection, it waits the amount of
time specified in the ″Repeat interval of″ field on the Connection document before calling the other server
again.

For example, suppose a Connection document schedules Hub-E/East/Acme to call HR-E/East/Acme

from 8 AM until 5 PM with a repeat interval of 120 minutes. If Hub-E/East/Acme calls and replicates
successfully with HR-E/East/Acme at 8:30 AM, Hub-E/East/Acme does not place the next call until
10:30 AM.

Be sure to consider time zones when you schedule replication between servers in different countries. You
want to replicate the documents created during each time zone’s peak business hours and schedule
replication for an off-peak time. For example, to schedule replication between a server in New York and a
server in Germany, schedule replication between 3 AM and 1 PM Eastern Standard Time (EST) to
correspond to Germany’s business hours, which are six hours later than EST.

The default replication time setting is 8 AM to 10 PM, with a repeat interval of 360 minutes.

Scheduling replication for one specific time

Use a specific time when you schedule replication of low priority databases, when daily updates of
databases are sufficient, or when you’re certain that attempts by the server to connect are successful after
just a few retries -- for example, on different networks at the same site. You might want to replicate
low-priority databases at night when the rates are less expensive or there is less load on the system.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Schedule tab.
6. In the ″Connect at times″ field, enter a specific time -- for example, 8 AM.

286 Lotus Domino Administrator 7 Help

7. In the ″Repeat interval of″ field, enter 0.
8. Click Save and Close.

The server calls and attempts to connect at the exact time you specified. If unsuccessful, the server tries
to connect for an hour. Whether or not the connection succeeds, the next call does not occur until 8 AM
the next morning.

Scheduling replication for a list of times

Use a list of times to schedule replication for medium and low priority databases and for when a few
daily updates of databases are sufficient or when you’re certain that connection attempts will be
successful after just a few retries -- for example, for a connection on different networks at the same site.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Schedule tab.
6. In the ″Connect at times″ field, enter a list of specific times -- for example, 8 AM, 1 PM, 4 PM.
7. In the ″Repeat interval of″ field, enter 0.
8. Click Save and Close.

The server calls at the first time specified, 8 AM. If unsuccessful, the server retries for up to an hour, until
9 AM. Whether or not the call succeeds, the next call occurs at the next scheduled time, 1 PM. If
unsuccessful, the server retries for up to an hour, until 2 PM. This process continues for each specific time
you specify.

Scheduling replication for a time range with a repeat interval

Specify a time range when you schedule replication for high priority databases.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Schedule tab.
6. In the ″Connect at times″ field, enter a time range -- for example, 8 AM - 5 PM.
7. In the ″Repeat interval of″ field, enter how frequently replication should take place -- for example, 120
minutes.
8. Click Save and Close.

If the first call is unsuccessful, the server retries periodically until it successfully establishes a connection
and replicates. If the server cannot connect, it keeps trying until the end of the time range. If the server
successfully replicates, it calls again at the specified repeat interval after the previous call ended.

Scheduling replication for a time range without a repeat interval

Use a time range without a repeat interval for medium and low-priority databases. Also use a time range
without a repeat interval when daily updates of a database are sufficient or when you know that a long
retry period is necessary -- for example, if you have busy phone lines and you know it will take several
attempts to make the connection.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Schedule tab.

Chapter 9. Creating Replicas and Scheduling Replication 287

6. In the ″Connect at times″ field, enter a time range -- for example, 8 AM - 5 PM.
7. In the ″Repeat interval of″ field, enter 0.
8. Click Save and Close.

The server attempts the first call at the start of the time range. If unsuccessful, the server tries again and
again. The time between call attempts increases with each unsuccessful attempt. The server retries the call
for the entire range or until a connection is made. After a failed call, the server retries periodically for the
entire call range. However, it does not call again after a successful exchange of information.

Scheduling replication for different days of the week

You can create a different replication schedule for different days of the week.
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Schedule tab.
6. In the ″Days of week″ field, enter the days on which you want replication to occur.
7. Click Save and Close.

For example, you could create two Connection documents -- one that schedules replication for Monday to
Friday, and another that schedules replication for Saturday and Sunday.

Staggering schedules
You can use staggered schedules on hub-and-spoke topology. For example, you could schedule the first
server to replicate from 8 AM to 10 AM, the second server from 8:05 AM to 10:05 AM, and so on. You can
create a simple round-robin schedule for a hub server and its spokes, repeating as often as is practical.
This process spreads all data within a hub’s sphere of influence quickly.

Scheduling server-to-server replication

For replication to occur between two servers, you create a Connection document that specifies how and
when the information exchange occurs. Connection documents are stored in the Domino Directory. Use
only one Connection document at a time to handle all replication between each pair of servers. Creating
unnecessary Connection documents increases network traffic and congestion.

Both mail routing and replication are enabled by default, but you can change this setting and use
separate Connection documents to schedule each task. This way, you can control the specific time(s), time
range(s), or the repeat interval for replication and mail routing separately, and increase or decrease these
settings, as needed.

How you connect servers for replication depends on the location of the servers. You can connect servers
for replication over a Local Area Network (LAN) or over an intermittently connected serial line, such as a
dial-up modem or Remote access service connection. In addition, you can use passthru servers for
replication.

Replicating over the Internet is performed identically as with a LAN using TCP/IP. The Domino server
must be in the same Notes domain as the Domino server with which you want it to replicate. If it’s not,
your server needs a certificate in common with the other server.

Note: Do not use the server’s common name when replicating servers. Only the server’s full hierarchical
name should be used during server-to-server replication. This applies to all instances of server-to-server
replication.

288 Lotus Domino Administrator 7 Help

To set up Connection documents for replication
Schedule only one server to connect at a time.
1. Make sure that:
v Each pair of servers can connect to each other.
v The Domino Directory is replicating properly.
2. From the Domino Administrator, click the Configuration tab.
3. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
4. Click Server, and then click Connections.
5. Click the connection you want to work with, and then click Edit Connection.
6. On the Basics tab, complete these fields:

Field Enter
Usage priority Choose ″Normal″ to force the server to use the network information in the current
Connection document to make the connection.
Source server The name of the calling server.
Source domain The name of the calling server’s domain.
Use the Port(s) The name of the network port (or protocol) that the calling server uses.

If you don’t want to specify the actual port for making a local area network connection, but
would prefer to have Domino determine the port used, don’t list any ports in the Use the
Port(s) field in the LAN Connection document. Domino uses all the information it has,
including all enabled LAN ports and all enabled or disabled Connection documents, to
determine the best path to use to connect with the other server.
Destination server The name of the answering server. You can also specify a Group name that contains server
names so that the Source server replicates with each server listed in the group you specify.
To do this, you create a group that contains servers only, and specify ″Servers only″ as the
group type. The group cannot contain the names of other groups of servers.
Destination domain The name of the answering server’s domain.

7. Click the Replication/Routing tab, and then complete these fields:

Field Enter
Replication task Choose Enabled.
Replicate databases of Choose one:
Priority v High
v Medium & High
v Low & Medium & High (default)
Replication type Choose one:
v Pull Pull
v Pull Push (default)
v Pull Only
v Push Only
Files/Directories to The names of specific databases or directories of databases that you want to replicate.
Replicate
Separate entries with semicolons (;) and specify the names as they exist on the calling
server. If the database is in a subdirectory to the data directory, include the path relative
to the data directory -- for example, EAST\SALES.NSF.

To specify all files within a directory and any of its subdirectories, enter the directory
name relative to the data directory with the directory slash, for example EAST\. You
can’t use wild cards (*).

Chapter 9. Creating Replicas and Scheduling Replication 289

Field Enter
Replication Time Limit The amount of time, in minutes, that replication has to complete.

8. Click the Schedule tab, and then complete these fields:

Field Enter
Schedule Choose Enabled.
Call at times The times between which you want replication to occur each day; the default is 8 AM -
10 PM.
Repeat interval of The number of minutes between replication attempts; the default is 360 minutes.
Days of week The days of the week to use this replication schedule; the default is Sun, Mon, Tue,
Wed, Thu, Fri, Sat.

9. Click Save and Close.

Customizing server-to-server replication

To customize replication, you can:
v Specify replication direction
v Schedule times for replication
v Replicate only specific databases
v Replicate databases by priority
v Limit replication time
v Use multiple replicators
v Refuse replication requests
v Force immediate replication

Specifying replication direction

When you choose replication direction, you identify which server(s) send and receive changes. The
direction you choose does not affect or restrict the functionality of the replication process itself.

By default, Domino uses Pull-Push as the replication direction. However, you can specify a different
replication direction.
v Pull-Push, the default replication direction, is a two-way process in which the calling server pulls
updates from the answering server and then pushes its own updates to the answering server. Using
Pull-Push, the replicator task on the calling server performs all the work.
v Pull-Pull is a two-way process in which two servers exchange updates. Using Pull-Pull, two replicators
-- one on the calling server and one on the answering server -- share the work of replication.
v Push-only is a one-way process in which the calling server pushes updates to the answering server.
One-way replication always takes less time than two-way replication.
v Pull-only is a one-way process in which the calling server pulls updates from the answering server.
One-way replication always takes less time than two-way replication.

To change the replication direction::

1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Replication/Routing tab.
6. Select the new replication direction from the Replication Type menu.

290 Lotus Domino Administrator 7 Help

You can also specify replication direction when you force replication. For example, you could use the
Push-only or Pull-only method from the server console when there is an update in a Domino Directory
on one server and you want to manually propagate that change to the other servers.

For information on forcing immediate replication, see the topic ″Forcing immediate replication″ later in
this chapter.

Replicating only specific databases

By default, Domino replicates all databases that two servers have in common. To replicate only specific
databases:
1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Replication/Routing tab.
6. In the ″File/Directories to Replicate″ field, enter the database names or directory names of specific
databases you want to replicate. Separate entries with semicolons (;).
7. Click Save and Close.

To specify an individual database, enter the file name of the database, including the NSF extension. If the
database is in a subdirectory of the data directory, include the path relative to the data directory -- for
example, EAST\SALES.NSF.

To specify all files within a directory and any of its subdirectories, enter the directory name relative to the
data directory with the directory slash, for example EAST\. You can’t use wild cards (*).

If the replication type is Pull-Pull, only the connecting server receives the specified databases during
replication. The other server still receives all databases in common with the calling server.

Replicating databases by priority

Database managers assign a replication priority to databases so that Domino administrators can schedule
replication for databases based on priority. For example, you can schedule high-priority databases that are
critical to business operations -- for example, the Domino Directory -- to replicate frequently. You can
schedule low-priority databases to replicate during off-hours.

To replicate databases by priority:

1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Replication/Routing tab.
6. In the ″Replicate databases of″ field, select the priority of databases to replicate.
7. Click Save and Close.

The default setting is Low & Medium & High. Domino automatically replicates all databases that two
servers have in common.

If two replicas are assigned different priorities, Domino uses the priority assigned to the replica on the
server that initiates the replication. If you schedule databases to replicate by priority and a particular
database isn’t replicating often enough, ask the database manager to increase the priority level of that
database.

Chapter 9. Creating Replicas and Scheduling Replication 291

Limiting replication time
Limiting the time a server has to replicate with another server prevents extensive replication sessions and
allows you to control the cost of replication with servers in remote sites. For example, if replication
depends on a long-distance phone call and the database takes time to replicate, you can limit how long
the replication period lasts.

To limit the time a server has to replicate:

1. From the Domino Administrator, click the Configuration tab.
2. Select the connecting server’s Domino Directory in the ″Use Directory on″ field.
3. Click Server, and then click Connections.
4. Click the connection you want to work with, and then click Edit Connection.
5. Click the Replication/Routing tab.
6. In the ″Replication Time Limit″ field, enter the maximum connection time in minutes.
7. Click Save and Close.

If the ″Replication Time Limit″ field has a value in it and the replication isn’t complete at the end of the
specified time or if the server crashes, then replication will begin where it left off once it restarts. When
the field is blank, Domino uses as much time as it needs to complete the replication session.

CAUTION:
If you specify an inappropriately low value and the databases do not have time to replicate
completely, replication terminates upon reaching the time limit, regardless of how little progress, if
any, occurred. The log file (LOG.NSF) records a message indicating that termination has occurred but
that the replication was successful. The replication history isn’t updated so that the next replication
takes place after the last complete replication event.

To limit replication time for all servers, edit the NOTES.INI file to include the ReplicationTimeLimit
setting.

Using multiple replicators

If you create Connection documents that schedule a server for multiple simultaneous or overlapping
replications with different destination servers, set up multiple replicators to handle the replication
sessions simultaneously. Multiple replicators efficiently use server resources, shorten replication cycles
(especially in hub servers), and save replication time.

When you use multiple replicators, each replicator handles only one replication session at a time. For
example, if Hub-E/East/Acme is scheduled to replicate with HR-E/East/Acme and with
Hub-W/West/Acme simultaneously, one replicator handles replication between Hub-E/East/Acme and
HR-E/East/Acme, while a second replicator handles replication between Hub-E/East/Acme and
Hub-W/West/Acme.

Multiple replicators handle multiple replications between one source server and multiple destination
servers simultaneously. Multiple replicators do not handle replications of multiple individual databases
on a source server with a single destination server. For example, if both Database 1 and Database 2 on
Hub-E/East/Acme need to replicate with Hub-W/West/Acme, only one replicator handles each
replication session, one at a time.

Examine the Connection documents that schedule replication on each server. By adjusting the schedules
and enabling multiple replicators, you can shorten the time it takes to complete a replication cycle. With
this shortened cycle, you can schedule one or more additional cycles per day, which means fewer
database updates and speedier replications per cycle. After you start multiple replicators, you can use the
Tell command to stop all replicators; however, you can’t use the Tell command to stop a specific
replicator.

292 Lotus Domino Administrator 7 Help

If you do not enable multiple replicators, do not schedule a server to call another server on different
ports at the same time. For example, if you use one replicator, do not schedule Hub-E/East/Acme to call
Hr-E/East/Acme on COM1 and Hub-E/East/Acme to call Hub-W/west/Acme on COM2
simultaneously.

To enable multiple replicators:

Method
From the NOTES.INI file
From the console
Steps
Edit the Replicators or ServerTasks setting in the NOTES.INI file.
Enter the Load Replica command at the console. Use this method if you need more
replicators and you don’t want to shut down the server to change the NOTES.INI
file. Each time you enter this command, the server loads another replicator.

For more information on settings in the NOTES.INI file, see the appendix ″NOTES.INI File.″ For more
information on entering server commands, see the appendix ″Server Commands.″

Refusing replication requests

To prevent a server from accepting a request for replication, edit the NOTES.INI file to include the setting
ServerNoReplRequests. If this setting is set to 1, the called server refuses all replication requests.

You can use this feature to reduce the replication workload on a particular server or to isolate a server for
troubleshooting. Or you may want to force the calling server to cover the time and cost of the entire
replication process.

Forcing immediate replication

You can replicate changes to critical databases, such as the Domino Directory, without waiting for a
scheduled connection. After you create Connection documents to schedule server-to-server replication,
you can use a server command to force immediate replication.

There are many situations when forcing replication is necessary. For example, you may want to update a
database immediately, without waiting for scheduled replication to occur, or you might need to replicate
with a different server because the usual server is unavailable. You can force immediate replication to
trace replication and mail routing problems or to force changes to critical system databases -- such as in
the Domino Directory -- to spread quickly through the domain. When you force immediate
server-to-server replication, you can initiate replication in one or in both directions.

Command Result
Replicate Replicates changes to databases in both directions; Domino performs
Pull-Push replication.
Pull Replicates changes to databases in one direction where the initiating server
pulls changes from the other server.
Push Replicates changes to databases in one direction where the initiating server
pushes database changes to the other server.

Disabling database replication

You can disable replication of a database -- for example, to stop replication while you troubleshoot
problems. Then, after you correct the problem, enable replication again. You can disable and enable
replication of one database, or if you use the Domino Administrator, you can disable and enable
replication of multiple databases at once.

To disable replication of one database:

1. Open the database and choose File - Replication - Settings.
2. Select Other.

Chapter 9. Creating Replicas and Scheduling Replication 293

3. Select ″Temporarily disable replication″ and then click OK.

To enable replication again, repeat Steps 1 and 2, and in Step 3 deselect ″Temporarily disable replication.″

To disable replication of multiple databases:

1. From the Domino Administrator, select the server in the server pane on the left that stores the
databases. To expand the server pane, click the servers icon in the server pane.
2. Click the Files tab.
3. Select the databases for which you want to disable replication.
4. From Tools, click Database - Replication. Or, drag the selected databases to the Replication tool.
5. Select ″Disable.″
6. (Optional) To clear the replication history, click ″Clear replication history.″
7. Click OK.

To enable replication again, repeat Steps 1 - 4, and in Step 5 select ″Enable replication.″

Forcing a server database to replicate

Replication between database replicas on servers typically occurs according to schedules in Connection
documents. However, there are times when you want to force replication between two replicas, rather
than wait for replication to occur on schedule. For example, you might force replication when you want
to test replication settings or troubleshoot replication problems.

Replicating from the database:

1. Open the database.
2. Choose File - Replication - Replicate.
3. Select ″Replicate with options″ and click OK.
4. Select the server that stores the replica with which you want to replicate.
5. Select ″Send documents to server″ to send updates from the replica you selected on your workspace
to the server you selected in Step 4.
6. Select ″Receive documents from server″ to send updates from the server you selected in Step 4 to the
replica selected on your workspace.
7. Click OK.

Replicating from the server console: You can use a database option with the Replicate, Pull, or Push
server commands to force replication of a specific database that two servers have in common.
v Use the Replicate command to send changes to and receive changes from a specified server
v Use the Pull command to receive changes from a specified server
v Use the Push command to send changes to a specified server

For example, to send changes to the database PRODUCTS.NSF from the server Webstage-E/East/Acme
to the server Web/East/Acme, enter the following command from Webstage-E/East/Acme:
Push Web/East/Acme Products.nsf

Viewing replication schedules and topology maps

You can see a graphical representation of each server’s replication schedule at a glance with the Domino
Administrator. Each server’s replication schedule appears separately, even if the server is a member of a
group listed in the ″Destination server″ field in a Connection document.

You can also see a graphical representation of your replication topology. Replication topology maps are
most useful for quickly displaying the replication topology and for letting you easily follow connections
between servers.

294 Lotus Domino Administrator 7 Help

Each server, network, cluster, and cc:Mail Post Office has its own icon. A line represents each replication
connection. A replication connection between two servers appears as a broken red line. Multiple
connections between servers appear as lines superimposed on each other.

To view replication schedules

1. From the Domino Administrator, click the Replication tab.
2. Click Replication schedule.
3. Patterns represent the replication status of each server: Schedule is being performed; Schedule is
complete; Schedule isn’t complete.

To start the topology Maps task

The Maps task enables you to view replication topology from the Domino Administrator. You only need
to run this task on one server in your domain. The information it gathers will replicate to the other
servers, as long as it has permission to do so. This task refreshes topology information nightly.

This task is not enabled by default. To see replication topology information, enable the Maps task
manually.
1. From the Domino Administrator, click the Servers - Status tab.
2. Click Tools - Start.
3. Select Maps Extractor from the menu and then click Start Task.
4. Click Done.

To display the replication topology map

1. From the Bookmarks pane, select the server for which you want to create a topology map.
2. Click the Replication tab.
3. Do one of the following:
v Click ″Replication topology by connections″ to view connections between the server you selected
and all of the servers connected to it.
v Click ″Replication topology by clusters″ to view all server clusters and their replication patterns.
4. (Optional) Double-click any server in the topology map to make that server the center of the map.
5. (Optional) Double-click a line connecting any two servers to open the corresponding Connection
document in the Domino Directory.

To focus on a specific area of the topology map, use the plus (+) and minus (-) keys to zoom in and out.

Database.nsf.replicate statistics
Domino maintains statistics about replication status. The database.nsf.replicate statistics are:
v NotesMergedBack = The destination note sequence is actually higher than the source note sequence.
Domino will assume a replication merge occurred and will update the source as well
v NotesReceived = If the NSF Database is the source database
v NotesReopened = There is a possible replication conflict; rr Domino could not find a corresponding
item for an incremental note; therefore, Domino cannot perform an incremental update and will try
again with a full note open.
v NotesSent = If the NSF Database is the destination database

Chapter 9. Creating Replicas and Scheduling Replication 295

296 Lotus Domino Administrator 7 Help
Chapter 10. Setting Up Calendars and Scheduling
You can set up the calendar and scheduling features to allow users to schedule meetings and reserve
resources.

Calendars and scheduling

The calendar and scheduling features allow users to check the free time of other users, schedule meetings
with them, and reserve resources, such as conference rooms and equipment. As an administrator, you can
define holidays that are particular to your organization or country. Domino includes a set of default
Holiday documents, which you can modify. Users import this information directly into their personal
calendars.

The calendar and scheduling features use the Schedule Manager (Sched task), the Calendar Connector
(Calconn task), and the Free Time system (a combination of Sched, Calconn, and nnotes tasks) to operate.
When you install Domino on a server (any server except a directory server), the Sched and Calconn tasks
are automatically added to the server’s NOTES.INI file. When you start the server for the first time, the
Schedule Manager creates a Free Time database (BUSYTIME.NSF for non-clustered mail servers and
CLUBUSY.NSF for clustered mail servers) and creates an entry in the database for each user who has
filled out a Calendar Profile and whose mail file is on that server or on one of the clustered servers.

Each user can keep a personal calendar and create a Calendar Profile that identifies who may access the
user’s free time information and specifies when the user is available for meetings. When users invite
other users to meetings, the Free Time system performs the free-time lookups. The Free Time system also
searches for and returns information on the availability of resources. If the lookup involves searching in
Free Time systems on different servers or scheduling applications, the Calendar Connector sends out the
queries. When users schedule appointments in their calendars and reserve resources, the Schedule
Manager task collects and updates that information in the Free Time database.

By default, the Schedule Manager has access to the Free Time database, so you do not have to define the
ACL for this database.

Using clustered Free Time databases

For clustered mail servers, the Schedule Manager creates the clustered Free Time database
(CLUBUSY.NSF) the first time a server starts. The clustered version of the Free Time database works the
same as the Free Time database (BUSYTIME.NSF). Each clustered server has a replica of the clustered
Free Time database, which stores information about users whose mail files exist on servers in the cluster.

If you add a previously non-clustered server to a cluster, the Schedule Manager deletes the
BUSYTIME.NSF database on that server and creates CLUBUSY.NSF, which then replicates to all cluster
members. If you remove a server from a cluster, the opposite occurs: Schedule Manager deletes
CLUBUSY.NSF and creates BUSYTIME.NSF. Until the Schedule Manager validates the database by
checking to see if the location of users’ mail files has changed, the clustered Free Time database contains
information about users whose mail server you removed from the cluster. This validation also occurs
once each day (at 2 AM) to update free-time information for users whose mail files have been added to
or removed from a mail server. You can update the information at any time by entering the Tell Sched
Validate command at the console.

A benefit of clustered scheduling is that schedule information is always available, even when users’ home
servers are down. With non-clustered scheduling, if users’ home servers are not available, the Free Time
database is not available for searching.

297
Other advantages of using clustered scheduling include improved performance and reduced server
traffic. Because the Free Time database is available from other members in a cluster, the server that
receives a user’s query does not have to search another server’s Free Time database for schedule
information about a user whose mail server is in the cluster.

Example of scheduling a meeting

This section describes the process of scheduling a meeting when users share the same mail server and
domain, have different domains, and use different scheduling applications.

In the following examples, Kathy wants to check the free time of and schedule a meeting with three users
-- Bob, who is in the same domain as Kathy; Robin, who is in a different domain; and Susan, who uses a
different scheduling application (Lotus Organizer®).

Users in the same domain

1. Kathy creates a meeting invitation and chooses to search for Bob’s free time.
2. A free time query is sent to Kathy’s mail server.
3. The Free Time system looks for Bob’s name in the Free Time database (BUSYTIME.NSF or
CLUBUSY.NSF) on Kathy’s mail server.
v If Bob and Kathy have the same mail server or if Bob’s and Kathy’s mail servers are part of a
cluster, the Free Time system finds the information and returns Bob’s free time to Kathy.
v If the Free Time system does not find any information on Bob, it converts Bob’s name into a fully
qualified name.
v If Bob’s mail server is unavailable and his Free Time database is not clustered, a message appears
indicating that the server is unavailable, and the Find Time dialog box indicates that Bob’s
information is unavailable.
4. Kathy’s Domino Directory is checked for Bob’s Person document. When the Person document is
found, the Calendar Connector sends the request to Bob’s mail server, the name of which is listed in
Bob’s Person document.
5. The Free Time system on Bob’s mail server looks in its Free Time database and returns the
information to Kathy via the Calendar Connector. If the Free Time system doesn’t find any
information, the query fails, and the Find Time dialog box indicates that Bob’s information is
unavailable.

Users in different domains

1. Kathy creates a meeting invitation and chooses to search for Robin’s free time. In addressing the
invitation, Kathy specifies Robin’s domain.
2. A query is sent to Kathy’s mail server.
3. The Free Time system looks for Robin’s name in the Free Time database on Kathy’s mail server. It
determines Robin’s mail server is in a different domain.
4. Kathy’s Domino Directory is searched for a document that matches Robin’s domain.
v If the Free Time system finds an Adjacent Domain document, it looks at the Calendar server name
field of the document for the name of a server that accepts calendar queries for Robin’s domain.
The Free Time system then forwards the query to this server for processing.
v If the Free Time system finds an Adjacent Domain document with an empty Calendar server name
field, it fails; and the Find Time dialog box indicates that Robin’s information is unavailable.
v If the Free Time system finds a Non-adjacent Domain document, it looks at the ″Route requests
through Calendar server″ field of the document for the name of the server (which is in a domain
adjacent to Kathy’s and Robin’s) that accepts calendar queries for Robin’s domain. The Free Time
system then forwards the query to this server for processing.

298 Lotus Domino Administrator 7 Help

 v If the Free Time system finds a Non-adjacent Domain document with an empty ″Route requests
through Calendar server″ field, it fails; and the Find Time dialog box indicates that Robin’s
information is unavailable.
v If the Free Time system doesn’t find any domain documents, the query fails; and the Find Time
dialog box indicates that Robin’s information is unavailable.

Users in other calendar domains

1. Kathy creates a meeting invitation and chooses to search for Susan’s free time.
2. A query is sent to Kathy’s mail server.
3. The Free Time system looks for Susan’s name in its Free Time database. It does not find the
information, so it converts Susan’s name into a fully qualified one.
4. Kathy’s Domino Directory is searched for Susan’s Person document.
5. The Free Time system looks in Susan’s Person document and locates the name of her mail server in
the Mail server field and the name of her calendar domain in the Calendar Domain field.
6. Because Susan is using Lotus Organizer as her scheduling application, the Free Time system finds that
her calendar domain does not match her mail server domain. The Free Time system then looks for a
Domain document for the calendar domain.
7. The Free Time system finds a Foreign Domain document for Susan’s calendar domain. The Calendar
server field in the Foreign Domain document identifies the name of the server that accepts queries for
Susan’s domain; the ″Calendar system″ field identifies the name of the add-in program -- for example,
Organizer or IBM® OfficeVision® -- that actually does the free-time lookup on Susan’s server. The Free
Time system forwards the query to the appropriate server (the server listed in the Calendar server
field) for processing.

If the Free Time system doesn’t find a Foreign Domain document, the query fails; and the Find Time
dialog box indicates that Susan’s information is unavailable.

Setting up scheduling
How you set up scheduling depends on where users are located -- that is, in the same Domino domain or
in different Domino domains -- and whether users use alternate scheduling applications, such as IBM
OfficeVision.

For users in the same Domino domain

Scheduling is automatically set up for non-clustered and clustered Free Time databases. You need to
create the Resource Reservations database so that users can search for and reserve resources.

For users in adjacent Domino domains

1. Make sure that you have set up Adjacent Domain documents in the Domino Directory to establish
communication between the domains.
For more information on Adjacent Domain documents, see the chapter ″Setting Up Mail Routing.″
2. From the Domino Administrator, click the Configuration tab.
3. Choose the Domino Directory in the ″Use Directory on″ box.
4. Click Messaging - Domains, and then open each appropriate Adjacent Domain document.
5. Click the Calendar Information tab, complete this field, and save the document:

Field Enter
Calendar server name The name of the server in the adjacent domain that accepts and processes all
scheduling queries for that domain.

6. Set up the Resource Reservations database if you want to allow users to search for and reserve
resources.

Chapter 10. Setting Up Calendars and Scheduling 299

For users in non-adjacent Domino domains
In order for two non-adjacent domains to do free-time lookups between each other, you need to define a
Calendar server in an intermediate domain that is adjacent to both the querying and the target domains.

Note: Free-time lookups require reasonable network response time and direct LAN connections from the
intermediate domain to the two separate non-adjacent domains.
1. Make sure that you have set up Non-adjacent Domain documents in the Domino Directory to
establish communication between the domains.
For more information on Non-adjacent Domain documents, see the chapter ″Setting Up Mail
Routing.″
2. From the Domino Administrator, click the Configuration tab.
3. Choose the Domino Directory in the ″Use Directory on″ box.
4. Click Messaging - Domains, and then open each appropriate Non-adjacent Domain document.
5. Click the Calendar Information tab, complete this field, and save the document:

Field Enter
Route requests through The name of a calendar server that is in a domain adjacent to both the querying
calendar server and the target domains. This server accepts and forwards free time queries from the
source to the target non-adjacent domain.

6. Set up the Resource Reservations database if you want to allow users to search for and reserve
resources.

For users of IBM OfficeVision

Domino scheduling works with IBM OfficeVision®. If users want to keep their schedules in this program,
set up scheduling to include it. You need to create a Foreign Domain document for each alternate
scheduling application.
1. Make sure you already set up a Foreign Domain document in the Domino Directory for each alternate
scheduling application.
For more information on Foreign Domain documents, see the chapter ″Setting Up Mail Routing.″
2. From the Domino Administrator, click the Configuration tab.
3. Choose the Domino Directory in the ″Use Directory on″ box.
4. Click Messaging - Domains, and then open each appropriate Foreign Domain document.
5. Click the Calendar Information tab, complete these fields, and save the document:

Field Enter
Calendar server name The name of the server that is running the alternative scheduling program.
Calendar system Choose OfficeVision from the list.

6. For Notes mail users who use a different scheduling application, enter the name of the foreign
domain in the Calendar Domain field of each user’s Person document.
7. Set up the Resource Reservations database if you want to allow users to search for and reserve
resources.

Setting up the Resource Reservations database

The Resource Reservations database is the database in which users schedule and manage meeting
resources. Resources may include conference rooms and equipment, such as overhead projectors and
video machines. Users can select a particular resource and reserve a time for it, or they can choose a time
and let the Resource Reservations database display resources available during that time.

300 Lotus Domino Administrator 7 Help

The Resource Reservations database contains three types of documents: Site Profile, Resource, and
Reservation. A Site Profile document identifies the site where particular resources are located. A Resource
document defines the resource name -- for example, the name or number of the conference room. After
you create Site Profile and Resource documents, the Schedule Manager tracks the free time of a resource
the same way it tracks free time for users. To reserve a resource, a user can either create a Reservation
document or add the resource to a meeting invitation.

To set up the Resource Reservations database

1. From the Domino Administrator, choose File - Database - New.
2. Complete these fields on the New Database dialog box.

Field Action
Server Enter the name of the server on which you are creating
the database.
Title Enter the name of the database.
File Name Enter a file name for the database. Use the file name
extension nsf.
Template server Choose the template server from which you will be
copying the template.
Show advanced templates Click this check box to display additional templates
including the Resource Reservations (RESRC7.NTF)
template.
Inherit future design changes Click the check box if you want the database to inherit
design changes that will be made to the template in the
future.

3. Select the Resource Reservations 7 (RESRC7.NTF) template.

4. Click OK.

Setting up the database ACL for the Resource Reservations database

After creating the Resource Reservations database, set up the ACL for the database. Assign the
CreateResource role to anyone who needs to create a site or a resource. The CreateResource role is
required.
1. From the Domino Administrator, choose File - Database - Access Control.
2. List the names of all users who are authorized to create Resources and Site Profile documents and
assign to them the [CreateResource] role.
3. Click OK.
For more information on setting database ACLs, see the chapter ″Controlling User Access to Domino
Databases.″

Setting up the administration server for the Resource Reservations database

You must set up an administration server for the Resource Reservations database.
1. From the Domino Administrator, click the Files tab.
2. Select the Resource Reservations database.
3. Choose Tools - Database - Manage ACL.
4. Click Advanced.
5. In the Administration Server field, click Server and then specify a server name.
6. Click OK.

Chapter 10. Setting Up Calendars and Scheduling 301

Rooms and Resources Manager
Domino 7 has centralized the processing of room and resource reservations into a new Rooms and
Resources Manager (RnRMgr) task. The Rooms and Resources Manager is designed to prevent
overbooking of rooms or resources and is responsible for both the processing of all workflow that is
related to reserving a room or resource as well as accurately updating the Busytime database. Rooms and
Resources Manager handles functionality previously handled in multiple places such as router, the Rooms
and Resources Template and the Schedule Manager. Regardless of where the reservation request is
created, that is, either in the Resource Reservations database, a user’s calendar, or using the Internet, the
reservation request will not have any conflicts with other reservations. The Rooms and Resources
Manager task accepts the same server console commands that the Schedule Manager does because it
performs the same functionality.

Note: The Schedule Manager task no longer maintains busytime for rooms or resources.

See the Lotus Notes 7 release notes for information about using the Rooms and Resources Manager.

There can be a maximum of two replicas of any Rooms and Resources databases on cluster mates on
which the Rooms and Resources Manager is run. You can have more than two replicas in a cluster if only
two of those replicas are on systems that run Rooms and Resources Manager. For example, if you have
four servers in a cluster but Rooms and Resources Manager only runs on two of them, all Domino 7
servers are permitted to have replicas of the same Rooms and Resources database. Replicas of the Rooms
and Resources database can be created on pre-Domino 7 servers only if the following criteria is met:
v The Router task is not running on the pre-Domino 7 server
v The pre-Domino 7 server is using the Domino 7 Rooms and Resources template
v The Rooms and Resources database resides on a Domino 7 server
v When the list of cluster mates is sorted alphabetically, the pre-Domino 7 server is not one of the first
two servers listed.

The Rooms and Resources Manager task provides automatic failover of request processing when the
current processing server fails. The Rooms and Resources Manager typically processes requests on the
database’s home server, that is, the server on which the database resides. If the Domino server on which
the Rooms and Resources Manager is running fails, the Rooms and Resources Manager on the Domino 7
cluster mate detects the server failure and begins processing reservation requests where the failed server
left off. The Room and Resources Manager on the failover server continues processing reservations until
that server fails. The original server then fails over for the failed server and begins processing requests
again. This failover ability provides sustained availability for the Rooms and Resources Manager.

Creating Site Profile and Resource documents

A Site Profile document defines a particular site where a resource exists and associates that site with a
Resource Reservations database and the Domino Directory. You also designate whether you want to use
″autoreminder.″ When the Resource Reservations autoreminder feature is enabled, the chairperson who
books a resource or a room is automatically sent a reminder notice a specific number of days in advance
of the reservation. You specify when the autoreminders are sent as well as how many, up to three, are
sent for a reservation. You must create at least one Site Profile document before you can create Resource
documents.

When you create a site, you have the option of enabling the Resource Reservations autoreminder feature.
When the autoreminder feature is enabled, automatic reminder notices are sent to the chairperson who
booked the room or resource. You designate how many autoreminders are sent for a particular room or
resource, as well as how many days prior to the reservation date they are sent.

When you create a Resource document, you define the resource name, type, and availability; and you
specify who can reserve the resource. There are three types of resources:

302 Lotus Domino Administrator 7 Help

v Room -- Typically a conference room that you want to allow users to reserve for meetings. When you
set up this resource, you must enter the seating capacity of the room.
v Online Meeting Place -- Meeting held ″online″ via IBM Lotus Instant Messaging.
For more information on setting up IBM Lotus Instant Messaging, see the IBM Lotus Instant Messaging
and Web Conferencing 651 Administrator’s Guide. Go to http://www.notes.net/doc to download
documentation.
v Other -- Resources that are not rooms or online meetings, but that you want to make available for
users to reserve.

After you set up resources, users can search for the free time of a resource and schedule the resource for
a meeting while searching for free time and inviting users to the meeting. For each Resource document
you create, the Administration Process creates a corresponding Resource document in the Domino
Directory. During a free-time query, the Free Time system searches the Free Time database to find the
location of these resources and returns information on the availability of both the resource and the
invitees.

When setting up rooms as resources, enter the room information in a consistent format, either by name or
by number. Doing so will limit the number of errors caused when a room cannot be located in the
database.

When a user reserves a conference room with type-ahead enabled, Lotus Domino searches for the
conference room by room number or by room name, but not by both. Lotus Domino looks up rooms
according to how they have been added to the Resource Reservations database -- either by name or by
number. If a user enters a room name and the room resource is set up by room number, an error is
generated and the room is not located. Setting up all room resources by room name or by room number
helps eliminate this type of error.

When you create a Site Profile or Resource document, the new resource is not available for users to
schedule until the Administration Process adds the resource to the Domino Directory and the addition
replicates to all replicas that are on servers used for scheduling resources of the Domino Directory.

When you create a resource of type Room or Other, you can specify how far in advance reservations can
be created for single meetings and for repeating meetings. Use this feature to prevent users from
scheduling meetings several years in advance, as they are unlikely to need to create reservations years in
advance of the actual date. You can limit advance reservations for a specific number of days or until a
specific date is reached.

To create a Site Profile document

1. Make sure that you have Manager access and the [CreateResource] role in the ACL of the Resource
Reservations database.
2. From the Domino Administrator, click the Files tab.
3. From the Servers pane, select the server from which you want to work.
4. Open the Resource Reservations database, and select any view except Calendar, My Reservations, and
Reservations Waiting for Approval.
5. Click New Site.
6. Complete these fields:

Field Enter
Site name The name of the site where the resource exists -- for example, 50 West Lincoln
Building.
Domain name The name of the domain where the Resource Reservations database resides. By
default, your current Domino domain is entered in this field.

Chapter 10. Setting Up Calendars and Scheduling 303

Field
Resource reservation server
Resource reservation filename
Resource reservation
autoreminder
Enter
Not modifiable. Displays the name of the server on which the Resource
Reservations database resides.
Not modifiable. Displays the name of the Resource Reservations database created
on this server.
Choose one:
v Enabled -- Click enabled to have automatic reminder notices sent to the
chairperson who booked a particular room or reservation. Displays additional
fields. Go to Step 7.
v Disabled -- Click disabled to prohibit the sending of automatic reminder notices
to the chairperson who booked a particular room or reservation. Go to Step 9.

7. If you chose Enabled in the field, Resource reservation autoreminder, complete these fields:

Field Action
Send autoreminder for Choose one:
v All rooms/resources -- Autoreminders are enabled for all rooms and resources in
the specified site. All rooms/resources is the default setting.
v Particular rooms/resources -- The Select rooms/resources field displays. Specify
the rooms/resources to which autoreminders will apply. You can select multiple
entries.

Choose one of these also:

v All reservations -- Autoreminders are enabled for all reservation made for the
specific site. All reservations is the default setting.
v Manually-created reservations only -- Autoreminders are enabled for reservations
created manually in the Resource Reservations database.
When autoreminder should be Choose one:
sent v Weekly -- Specify the day of the week on which to send the autoreminder. For
example, if you specify Monday, on Monday an email is sent advising of any
reservations the user has on Tuesday through the following Monday. The default
setting is Sunday.
v Daily -- You are prompted to specify three different time intervals.
v First autoreminder should be sent -- Specify the number of days in advance of
the reservation that the first autoreminder should be sent.
v Second autoreminder should be sent -- Specify the number of days in advance of
the reservation date that the second autoreminder should be sent. If you specify
0 (zero) no autoreminder will be sent.
v Third autoreminder should be sent -- Specify the number of days in advance of
the reservation date that the second autoreminder should be sent. If you specify
0 (zero) no autoreminder will be sent.

8. Click Save and Close.

If you have enabled autoreminders, you are prompted to confirm that autoreminders are to be
enabled. Click Yes.

To create a Resource document

1. Make sure that you have the [CreateResource] role in the ACL of the Resource Reservations database
and that at least one Site Profile document has already been created.
2. From the Domino Administrator, click the Files tab.
3. From the Servers pane, select the server from which you want to work.
4. Open the Resource Reservations database.
5. Click New Resource.

304 Lotus Domino Administrator 7 Help

6. Complete these fields

Field Enter
Resource Type Choose one:
v Room -- if the resource is a room
v Other -- if the resource is not a room
v Online Meeting Place -- if you will be meeting via IBM Lotus Instant Messaging
server.
Name A unique name that identifies the resource -- for example, a room number.
Site Click to display a list of available sites, and then choose one.
Category Name for category of Resource -- for example, Electronic or AV. This field also
displays names of all previously entered Category values, from which you can
(Appears when you select choose.
Other as Resource Type)
Capacity The capacity of the resource, for example, the seating capacity of a room.

(Appears when you select

Room as Resource Type)
Description A description of the resource -- for example, large conference room with a video
monitor.
Internet address An Internet address that iCalendar users can use to reserve the resource.

The Internet Address field is not visible for Online Meeting Place.

7. Enter the following Owner Options for resources of type Room or Other. If you chose a resource type
of Online Meeting Place, go to Step 9.

Field Enter
Owner restrictions Choose one:
v None -- Click if no owner is assigned to the resource and anyone can reserve the
resource.
v Owner only -- Click to assign a Resource owner. Only the Resource owner can
process Resource requests without special approval. Enter the name of the
resource owner in the Owner’s name field. The owner is the person or group to
whom requests from other users (those not listed in the List of names field) are
forwarded for approval and processing.
v Specific people -- Click to allow only specified users access to the resource. Enter
the names of users allowed to reserve this resource in the List of names field.
v Autoprocessing -- Click to allow only specified users and groups access to the
resource and to assign a resource owner. Enter the name of the resource owner in
the Owner’s name field. The owner is the person or group to whom requests
from other users (those not listed in List of names field) are forwarded for
approval and processing. Enter the names of users allowed to reserve this
resource in the List of names field.
v Disable reservations -- Click to prevent users from reserving a resource from a
meeting notice and directly from the Resource Reservations database.
Availability settings Choose one of these:
v 24 hours everyday -- The resource is available 24 hours each day. When you
select this availability setting, other availability settings are disabled.
v Time zone -- Specify the time zone for the resource. The default is Local Time,
but you can specify others as applicable, such as Eastern Time.
v Days of week and hours of days -- Select the days of the week that the resource
is available. Specify availability start time and end time for each available day
selected.

Chapter 10. Setting Up Calendars and Scheduling 305

Field
Limit how far in advance a
room/resource can be reserved
Note: This option applies to
resources of type Room and
Other.
Other comments
Enter
Click this checkbox to specify how far in advance users can schedule single
meetings and repeating meetings. When you enable this setting, additional options
appear. Choose one of these
v Limit by days -- Displays the Number of days field. Specify the number of days,
including the current day, for which users can schedule meetings. For example, if
you specify 30 days, uses can schedule meeting today and for the next 29 days.
v Limit by date -- Displays a Date field in which you can specify the date up to
which reservations are allowed. Users cannot schedule reservations after that
date.
(Optional) Enter additional comments as necessary.

8. Enter the following Online Resource data for resources of type Online Meeting Place.
.

Field
Online meeting database
External address
IBM Lotus Instant Messaging
server
Audio Video Support
Enter
The default Sametime Conference database, STCONF.NSF, is entered by default. If
the IBM Lotus Instant Messaging server is a UNIX server, the IBM Lotus Instant
Messaging setup may be customized and a name other than STCONF.NSF may be
used for the Sametime Conference database. If the database name has been
changed, enter the name of that database.
Name of the Sametime mail-in database on the IBM Lotus Instant Messaging server.
This database, STCS.NSF, is created during IBM Lotus Instant Messaging
installation. The default name is Sametime Reservations. It must be manually
added to the Domino Directory as a mail-in database. The name that you specify
for the mail-in database, is the name that is added to this External address field.
For information on how to manually add a mail in database to the Domino
Directory, see the topic ″Creating a Mail-in Database document for a new database″
in the Domino Administrator online documentation.
The name of the Domino server on which IBM Lotus Instant Messaging is running.
The mail server must have mail connectivity to the IBM Lotus Instant Messaging
server to deliver the invitations that cause the meetings to be scheduled.
Choose one:
v Audio -- Voice only
v Audio and Video support -- Voice and video display

9. Click Save and Close.

Editing and deleting Resource documents

After you create a Resource document, the information that you can change includes the Availability
Settings, Description, Capacity, Online resource data, Other Comments, and Ownership Options fields.
You can also rename a Resource by changing its name, Site, and, if the Resource is of type ″Other,″ its
category.

Note: Users with manager access and the [CreateResource] role in the Resource Reservations ACL can
rename a room/resource.

New resource information is not available until the Administration Process updates the Resource
document in the Domino Directory and the change replicates to all relevant replicas of the Domino
Directory that are on servers used for scheduling resources. The Rename agent must run to rename
reservations and to send notices to the chairperson. The Rooms and Resources Manager (RnRMgr) task
must also run to rename the Busytime database. The Agent Manager (AMgr) task and the RnRMgr task
must be running in order to allow the Resource Reservations database to function without an
administrator’s intervention.

306 Lotus Domino Administrator 7 Help

If you delete a resource from the Resource Reservations database, an Administration Process Request
document for the resource deletion is created in the Administration Requests database (ADMIN4.NSF). To
delete the resource and remove it from the Domino Directory, you must open the Administration
Requests database and approve the request for deletion. Note that to approve requests you need the
appropriate access in the ACL of the Administration Requests database.

Renaming a resource
After a resource has been renamed (which includes having the site or category changed), all reservation
owners receive email notices stating that the resource has been renamed and lists the former resource
name, new resource name, and a list of dates, times, and chairs for each reservation.

If a reservation owner or chair made the reservation through the Calendar, the resource rename
notification contains an ″Update My Meetings″ button in the body of the message. Clicking this button
then updates all instances all meetings in the chair’s Calendar that employ this resource.

If a reservation owner or chair made the reservation through the Resource Reservations database, the
reservations are updated automatically with the new information, and resource rename notification
indicates this.

If the chair has an assistant who is authorized to receive notices on the chair’s behalf, then the Resource
Rename Notice is forwarded to the assistant as well. This notice is a full copy of the note that is sent to
the chair, including an ″Update My Meetings″ button in the body of the message. The assistant must be
sure to use the ″Update My Meetings″ button in the chair’s message to update the chair’s calendar.

Note: It is important that the chair or calendar manager update their meetings with the new name of the
room or resource. Failure to do so will cause problems if there are subsequent changes to the meeting
(such as rescheduling).

To edit a Resource document

1. Make sure that you have the [CreateResource] role in the ACL of the Resource Reservations
database.
2. From the Domino Administrator, click the Files tab.
3. From the Servers pane, select the server from which you want to work.
4. Open the Resource Reservations database, and then click Resources.
5. Open the Resource document you want to edit and click Edit Resource.
6. Edit any of the following fields for resources of type Room or Other. To edit a resource of type
Online Meeting Place, go to Step 7.

Field Edit
Description Description of the resource.
Capacity (for Rooms only) The capacity of the resource, if it has one -- for example, the seating capacity of a
room.
Internet address An Internet address that iCalendar users can use to reserve the resource.

Chapter 10. Setting Up Calendars and Scheduling 307

Field Edit
Owner restrictions Choose one:
v None -- Click if no owner is assigned to the resource and anyone can reserve the
resource.
v Owner only -- Click to assign a Resource owner. Only the Resource owner can
process Resource requests. Enter the name of the resource owner in the Owner’s
name field.
v Specific people -- Click to allow only specified users access to the resource. Enter
the names of users allowed to reserve this resource in the List of names field.
v Autoprocessing -- Click to allow only specified users access to the resource and to
assign a resource owner. Enter the name of the resource owner in the Owner’s
name field. The owner is the person to whom requests from other users (those not
listed in List of names field) are forwarded for approval and processing. Enter the
names of users allowed to reserve this resource in the List of names field.
v Disable reservations -- Prevent users from reserving a resource from their mail file.
Owner’s name Add, change, or delete owners for this resource.
Availability settings Choose one:
v 24 hours everyday -- The resource is available 24 hours each day. When you select
this availability setting, other availability settings are disabled.
v Time zone -- Specify the time zone for the resource. The default is Local Time, but
you can specify others as applicable, such as Eastern Time.
v Days of week and hours of days -- Select the days of the week that the resource is
available. Specify availability start time and end time for each available day
selected.
Limit how far in advance a Click this checkbox to enable or disable this setting, according to how you editing
room/resource can be the document. If you are enabling the setting, choose one of these
reserved v Limit by days -- Displays the Number of days field. Specify the number of days,
including the current day, for which users can schedule meetings. For example, if
you specify 30 days, uses can schedule meeting today and for the next 29 days.
v Limit by date -- Displays a Date field in which you can specify the date up to
which reservations are allowed. Users cannot schedule reservations after that date.
Other comments Enter additional comments about the resource as necessary.

7. Edit any of the following fields for resources of type of Online Meeting Place. If you are editing a
resource of type Other or Room go to step 8. Do not complete step 7.

Field Enter
Description Description of the resource.
Online Meeting Database The default database, STCONF.NSF, is entered by default. This field cannot be
modified.
External address Name of the mail-in database on the IBM Lotus Instant Messaging server. The name
you enter here must be identical to the name of the Sametime Mail-in database.
IBM Lotus Instant Messaging Name of the IBM Lotus Instant Messaging server hosting the meeting.
server
Audio Video Support Choose one:
v Audio -- voice only
v Audio and Video -- Voice and video display
Other comments Modify or enter comments regarding the resource as desired.

8. To rename the resource, or change its site and/or category, click Rename.

308 Lotus Domino Administrator 7 Help

 9. A message appears notifying you that all chairs with outstanding reservations for this resource will
be notified. Click Yes.
10. Complete the following fields in the Rename Resource dialog.

Field Action
New Name Enter the new name of the resource. This name must be unique.
Site Choose a new Site for this Resource from the drop-down list.
Category (for Other only) Choose a new category for this Resource from the drop-down list.

11. Click Save and Close. A confirmation message appears when the change request is generated
successfully.

To delete a resource
When you delete a resource, an administration request that requires the administrator’s approval is also
generated. After deleting the resource in the user interface, open the Administration Requests database
and approve the deletion there. Instructions for both procedures are included here.
1. Make sure that you have the [CreateResource] role in the ACL of the Resource Reservations database.
2. From the Domino Administrator, click the Files tab.
3. From the Servers pane, select the server from which you want to work.
4. Open the Resource Reservations database, and then click Resources.
5. Open the Resource document that you are deleting, and click Delete Resource.
6. Click Yes and click OK.

To approve the resource deletion

To process the deletion, the request needs approval in the Administration Requests database. Complete
these steps to approve the ″Approve Resource Deletion″ administration request.
1. From the Domino Administrator, click Server - Analysis - Administration Requests.
2. Click Pending Administrator Approval.
3. Open the Approve Resource Deletion request document and click Edit Document.
4. Click Approve Resource Deletion.
5. Choose Yes and then click OK to approve the deletion.

Setting user access rights to edit and delete reservations

To allow a user to delete a reservation in the Resource Reservations database on a Notes Client, assign
Editor access to that user in the database ACL of the Resource Reservations database. The Delete
Reservation button is then enabled.

To allow a Web user to delete a reservation in the Resource Reservations database, via a Web browser,
assign Editor access to that user in the database ACL of the Resource Reservations database. In a Web
view, the Move to Trash and the Empty Trash buttons are then enabled.

Reservations that are created manually or with Calendaring and Scheduling, can be deleted by a
requester with Editor access to the Resource Reservations database, a resource owner with Editor access
to the Resource Reservations database, or by a database manager with Editor access to the Resource
Reservations database and the CreateResource role.

Single-room, non-repeating reservations that are created manually in the Resource Reservations database
can be edited by the requester of the reservation, with Editor access to the Resource Reservations
database, if the reservation has a status of ″waiting for approval″ or if the reservation has been accepted.
Repeating room or resource reservations that are created manually cannot be edited.

Chapter 10. Setting Up Calendars and Scheduling 309

Creating Holiday documents
Holiday documents provide a way for your organization to have a centrally managed collection of
documents that contain information on scheduled holidays and events. Users select the type of Holiday
documents to import and add the information to their personal calendars. Domino includes default
Holiday documents that you can modify or delete; you can also add Holiday documents specific to your
organization’s needs. Holiday documents are stored in the Domino Directory.

You categorize Holiday documents according to a group name. For example, you may have a group
named ″Full-time″ that contains all the company holidays for full-time employees. The default Holiday
documents included with Lotus Domino have group names associated with countries or religions -- for
example, United States or Italy -- and the groups contain documents specific to holidays in each country.
As an administrator, you may want to modify or delete these documents to reflect your organization’s
needs. Then you can advise all users to import a specific group of Holiday documents.

To add a document to an existing group, select the group when you create a new Holiday document. To
create new groups, enter a new group name in the Holiday document. Remember that your users import
Holiday documents according to group name, not document name, so be sure to plan the organization of
documents in groups.

To create a Holiday document

1. From the Domino Administrator, click the Configuration tab.
2. Select the Domino Directory server in the ″Use Directory on″ field.
3. Click Miscellaneous - Holidays.
4. Click Add Holiday.
5. Complete these fields on the Basics tab:

Title Action
Group Do one of these:
v Select a group from the list.
v Add a new group in the New keyword field and then click OK.
Title Enter the name of the holiday -- for example, Christmas
Repeat Specify how often the holiday repeats
v Monthly by Date
v Monthly by Day
v Yearly
v Custom -- If you choose Custom, enter one or more dates on
which the holiday repeats.

6. If you chose Custom in the Repeat field in Step 5, do not complete Step 6. Instead, go to Step 7.

Field Action
Start date Enter the date when the holiday first occurs. This date may be the
actual date of the holiday (such as New Year’s day) or it may be
the date from which to start the holiday. For example, if your
organization gives employees every other Friday off from June
through August, enter June 1 as the Start Date and select ″For″
from the Continuing field to specify an end date of August 31.
Continuing Choose one:
v Until -- Click Until and then enter a specific date in the ″Repeat
Until″ field.
v For -- Click For and then specify the number of months or years
during which the holiday repeats in the ″Repeat For″ field.

310 Lotus Domino Administrator 7 Help

Field Action
Repeat until Enter the last date on which the Holiday should repeat.

(Displays if you select Until in the Continuing

field.)
Repeat For Enter the number of months or years during which the holiday
should repeat.
(Displays if you select For in the Continuing
field.)
Repeat Interval Choose how often the holiday repeats by month and day.

(Applies to Monthly by Date and by Day)

If the date falls on a weekend Choose one:
v Don’t Move
(Applies to Monthly by Date only)
v Move to Friday
v Move to Monday
v Move to Nearest Weekday

7. Complete this step only if you chose Custom in the Repeat field in Step 5.

Field Enter
Repeat Dates Enter the date or dates when the holiday occurs -- for example,
01/01/02, 01/02/2003.
(Applies only to Custom.)

8. Complete these fields:

Choose how each user’s calendar will record this holiday:

v Busy -- This holiday will appear as Busy time in the user’s
schedule so that meetings cannot be scheduled on the holiday.
v Free -- This holiday will appear as Free time in the user’s
Mark time as schedule, so that meetings can be scheduled on that holiday.
Detailed description (Optional) Enter a detailed description of the holiday.

9. Click Save and Close.

To view the default Holiday documents

Lotus Domino includes default Holiday documents that contain information on holidays observed around
the world. The Holiday documents are organized into groups by country or religion. For example, the
Italy group contains documents specific to Italian holidays.
1. From the Domino Administrator, click the Configuration tab.
2. Select the Domino Directory server in the ″Use Directory on″ field.
3. Click Miscellaneous - Holidays to see all the default Holiday documents.

To modify an existing Holiday document

After you modify or delete an existing Holiday document, users receive the modifications only when
they choose to run import from their mail files.
1. From the Domino Administrator, click the Configuration tab.
2. Select the Domino Directory server in the ″Use Directory on″ field.
3. Click Miscellaneous - Holidays.
4. Choose the geographical/religious category for the Holiday.
5. Select the desired Holiday document and click Edit Holiday.

Chapter 10. Setting Up Calendars and Scheduling 311

6. Modify fields as you wish.
For more information on the individual fields, see the topic ″To create a Holiday document″ in this
chapter.

Collecting detailed information from user calendars

If a user requests it, additional detailed data is available to other users. This information is stored in the
Freetime database, BUSYTIME.NSF or CLUBUSY.NSF. For clustered servers, the database is
CLUBUSY.NSF, for non clustered servers, the database is BUSYTIME.NSF. To limit growth of this
database, do not enable the server to collect this data. You can enable or disable this feature across the
entire Domino domain from the server’s Configuration Settings document.

To collect detailed calendar information from user calendars

1. From the Domino Administrator, click the Configuration tab.
2. Choose Server - Configurations.
3. Select the Server Configuration document you want to modify, and click Edit Configuration.
4. On the Basics tab, click the check box ″Use these settings as the default settings for all servers″ if it is
not selected, because the feature is only available on the All Server Configuration document. This
check box must by selected to display the field ″Extract calendar details.″ Select the ″Extract calendar
details″ check box to enable the feature.
5. Choose any of these calendar details to extract:
v Categories -- Allows other users to see if the event has been assigned one or more categories. For
example, an event can be categorized as a Project, indicating that it is project-related, or an event
that involves travel could be categorized as ″Vacation″ if it is a personal vacation, or it could be
categorized as ″Travel″ and ″Project″ if it is project-related business travel.
v Chair -- Allows other users to see who will chair the meeting
v Location -- Allows other users to see the site location of the meeting
v Room -- Allows other users to see the name or other identifier for the room
6. Click Save and Close.

312 Lotus Domino Administrator 7 Help

Chapter 11. Using Policies
Using policies, you can distribute and control a standard set of administrative settings for user
registration and setup, desktop configuration, mail archiving, and security.

Policies
Using a policy, you control how users work with Notes. A policy is a document that identifies a collection
of individual policy settings documents. Each of these policy settings documents defines a set of defaults
that apply to the users and groups to which the policy is assigned. Once a policy is in place, you can
easily change a setting, and it will automatically apply to those users to whom the policy is assigned.

Policy settings documents cover these administrative areas:

v Registration -- If a policy including registration policy settings is in place before you register Notes
users, these settings set default user registration values including user password, Internet address
format, roaming user designation, and mail.
v Setup -- If a policy including setup policy settings is in place before you set up a new Notes client,
these settings are used during the initial Notes client setup to populate the user’s Location document.
Setup settings include Internet browser and proxy settings, applet security settings, and desktop and
user preferences.
v Desktop -- Use desktop policy settings to update the user’s desktop environment or to reinforce setup
policy settings. For example, if a change is made to any of the policy settings, the next time users
authenticate with their home server, the desktop policy settings restore the default settings or distribute
new settings specified in the desktop policy settings document.
v Mail -- Use mail policy settings to set and enforce client settings and preferences for mail and for
Calendaring and Scheduling.
v Mail archiving -- Use archive policy settings to control mail archiving. Archive settings control where
archiving is performed and specify archive criteria.
v Security -- Use security settings to set up administration ECLs and define password-management
options, including the synchronization of Internet and Notes passwords.

Organizational and explicit policies

There are two types of policies: organizational and explicit. Understanding the differences between the
types helps you plan the implementation.

Organizational policies
An organizational policy automatically applies to all users registered in a particular organizational unit.
For example, to distribute default settings to all users registered in Sales/Acme, create an organizational
policy named */Sales/Acme. Then when you use the Sales/Acme certifier ID to register a user, that user
automatically receives the settings in the corresponding organizational policy.

If you move a user within the hierarchical structure -- for example, because the user transfers from the
Sales department to the Marketing department -- the organizational policy for the corresponding certifier
ID is automatically assigned to the user. For example, if you move the user from Sales/Acme to
Marketing/Acme, all settings defined in the desktop, archiving, and security policy settings documents
associated with the */Marketing/Acme organizational policy are assigned to the user. The new policy
settings become effective the first time users authenticate with their home server.

313
Explicit policies
An explicit policy assigns default settings to individual users or groups. For example, to set a six-month
certification period for contract workers in all departments, create an explicit policy and then assign it to
each contract employee or to the group that includes all contract employees.

There are three ways to assign an explicit policy: during user registration, by editing the user’s Person
document, or by using the Assign Policy tool.

For information on assigning an explicit policy, see the topic ″Assigning an explicit policy,″ later in this
chapter.

Using Exceptions
You can assign an exception attribute to either an organizational or explicit policy. You use an exception
to allow the user to override a policy setting that is otherwise enforced throughout an organization.
When you create an exception policy, you specify only the settings that will not be enforced. Then when
you assign the exception policy, it exempts users from enforcement of those settings only.

Exception policies are a way to give someone in an organization special treatment, possibly because of
their position or job requirements. For example, the */Acme policy includes a Registration policy setting
that enforces a mail database quota of 60 MB. However, a small group of employees in Acme need to
exceed this quota. The solution is to create an ″exception″ policy that includes only a Registration policy
settings document, that does not set a quota limitation on the mail database. When this exception policy
is assigned to users, they can override the database quota setting. Because exception policies defeat the
enforcement of policy settings, use them sparingly.

Policy hierarchy and the effective policy

The effective policy for a user is a set of derived policy settings that are dynamically calculated at the
time of execution. The field values in an effective policy may originate from many different policy
settings documents. Each hierarchical level can have an associated policy, so users may have a
combination of policy settings that include the values set at their OU level, and those inherited from a
parent policy. The resolution of those settings, stepping up through the organizational hierarchy,
determines the effective policy for each user.

In addition to organizational policies, users may also have explicit policies assigned to them. In that case,
the order of resolution is that all organization policy settings are resolved first, then any explicit policy
settings are resolved.

For example, if you want all users to use the same Internet mail name format, set that value in the
Registration policy settings document for the top-level policy. Once you have set this value, you do not
have to change it or reenter it in subsequent child policies. You simply ″inherit″ this value from the
parent by selecting the inherit option. However, if you have a select group of international users for
whom this setting is a problem, you can create an explicit policy that applies to the select group only. The
combination of the explicit and organizational policies together provide the control and the flexibility you
need.

There are two tools that help you determine the effective policy governing each user. The Policy Viewer
shows the policy hierarchy and associated settings documents, and a Policy Synopsis report shows the
policy from which each of the effective settings was derived.

Inheritance and the child policy relationship

Inheritance plays an important role in determining a user’s policy settings in both organizational and
explicit policies. Through the parent-child relationship, you create a hierarchy of policies to set your
administrative practices across the enterprise. In a policy hierarchy, policy documents build the
relationship, and policy settings documents determine the value of the fields based on their position in
the hierarchy. Using field inheritance and enforcement, you control the default settings.

314 Lotus Domino Administrator 7 Help

In organizational policies, the hierarchy of policies is determined automatically based on the
Organization’s hierarchy. The policy */Sales/Acme is the child policy of */Acme. Since explicit policies
do not follow the organizational structure, when you create explicit policies, you build in the hierarchy,
based on the naming structure. For example, if you create an explicit policy named /Contractors that
includes several settings that apply only to contract employees who may be employed for six month to a
year. However you want short-term temporary employees, employed for only one or two weeks, to
inherit only some of those settings. You create a child explicit policy called Short term/Contractors.

The following figure shows a policy hierarchy. In this hierarchy, the policy at each organizational level
has set its own password quality setting.

In the following figure, Joe User inherits a password quality setting from a parent policy. Inheriting a
setting occurs in the child policy at the field level in a policy settings document.

Another way that a user ″inherits″ field-level settings is through enforcement. In the illustration below,
the password quality setting is enforced in the parent policy at the field level in the Registration policy
settings document. If settings are enforced in a parent policy, the settings at the child policy level do not
apply.

Chapter 11. Using Policies 315

Example of using policies
The administrator at the Acme company wants to use policies to:
v Set the same Internet address format for all users
v Set users in Acme/Sales to be roaming users
v Set a custom mail template for employees in Acme/Sales
v Set a 24-month certification expiration for permanent employees
v Set a 6-month certification expiration for temp

To accomplish these goals, the administrator creates these policies:

v An organizational policy for all Acme employees (*/Acme) that includes a registration policy settings
document that specifies the Internet mail format and other default settings that will populate the
registration dialog. These default policy settings include a 24-month certification expiration period.
v An organizational policy for Sales/Acme (*/Sales/Acme) that sets roaming options and specifies a
custom mail template.
v An explicit policy for temporary employees that specifies a 6-month certification expiration. When
temporary employees are registered, this explicit policy is applied along with the organizational policy
that correlates to the organizational unit in which the employees are registered.

Client policy lock-down

Use client policy lock-down to specify which policy settings can be modified by end users. The
lock-down feature provides a central location, the policy settings document, from which you can set and
lock down user settings. Client policy lock-down is especially useful for implementing company
procedures and increasing security. The client policy lock-down feature is available in the desktop policy
settings document and the mail policy settings document. In the desktop policy settings document, client
policy lock-down is set on a per-tab basis, not on a per-field basis. The desktop policy settings document
contains the field ″Allow users to change the settings on this tab″ on each tab for which policy lock-down
is available. In the mail policy settings document, client policy lock-down is set on a per-field basis. The
mail policy settings document contains a check box with the field label ″Allow user to change″ next to
any field that you can lock.

Domino uses dynamic configuration to deploy policy settings. When end-users authenticate with their
home servers, information stored in the policy settings documents is deployed (pushed down) to the
end-users. If one or more fields or tabs is set to allow end-user modifications, dynamic configuration does
not overwrite those policy settings. If a field or tab does not allow end users to modify the settings,
dynamic configuration deploys policies using the settings designated by the administrator who set up the
policy settings document.

316 Lotus Domino Administrator 7 Help

Planning and assigning policies
Before you register and set up users, plan and create policies. Then, during user registration, assign the
policies. If users are already registered, you can plan and create policies, but you cannot assign any
registration and setup policy settings, since those apply only once, during user registration and setup.

To plan and assign policies

1. Determine which settings to assign to all users in specific organizational units. For these settings,
create organizational policies.
2. Determine which settings to assign to individual users or groups. For these settings, create explicit
policies.
3. Register users and assign explicit policies during registration.
4. For users who are already registered, assign explicit policies by editing the Person document or using
the Assign Policy tool.
5. (Optional) Create and assign exception policies.

To plan and assign policies for a hosted organization

When you use policies for hosted organizations, your policy must include registration policy settings. You
can use either an organizational or explicit policy. Depending on the type of policy you use, you create
the policy either before you register the hosted organization or during registration.

For a hosted organization, do one of the following:

v Explicit policy -- Create an explicit policy that includes a registration settings document before you
register the hosted organization.
v Organization policy -- When you are registering a hosted organization, create an organizational policy
and a registration settings document when you are prompted to do so.

Using policies to assign NOTES.INI or Location document settings to

Notes client users
You can use a desktop policy settings document to add or set NOTES.INI variables for Notes client users.
This is an easy way to assign NOTES.INI variables to all Notes client users, or to a specific subset of
Notes client users, at one time. You can also use desktop policy settings documents to set field values in
Location documents for users.

To use a policy to assign a NOTES.INI value to Notes client users, use the Domino Designer to add a
new field to the desktop policy settings document. The new field must be named $PrefVariableName,
where VariableName is the name of the NOTES.INI variable you want to set. In the new field on the
desktop policy settings document, enter the value you want assigned to that NOTES.INI variable. That is
the value that is set in the NOTES.INI for the assigned Notes users.

For example, assume that you want to use a policy settings document to add a font size setting of 5 to
your NOTES.INI file. To change the font setting, do the following:
1. From the Domino Designer, open the desktop policy settings document form.
2. Create a new field named $PrefDisplay_font_adjustment.
3. Assign a value of 5 to the field $PrefDisplay_font_adjustment.
4. Save and exit.

To set a Location document setting using a policy document, add a new field to the desktop policy
settings document. The new field must be named LocAllVariableName, where VariableName is the name
of the fields you are setting in the Location documents. In the new field on the policy settings document,
enter the value you want assigned to that Location document field. That is the value that is then assigned
to all of the users’ Location documents.

Chapter 11. Using Policies 317

These new values are set on the assigned users’ clients the next time they authenticate with their home
server.

Note: Some settings require that the Notes client be restarted in order for the settings to take affect.

For more information about adding the new field to desktop policy settings document, see the Domino
Designer documentation.

Notes application plug-in and policies

You can use the Domino policies feature to designate how instant messaging services, within the Notes
application plug-in, are provided to your users. The Notes application plug-in lets Notes users work with
Notes applications in the IBM Workplace Managed Client(TM) just as they would in the Notes 7 client.

The Basics tab of the desktop policies settings document contains a Notes application plug-In section. Use
those settings to define whether IBM Workplace (TM) Collaboration Services or IBM Lotus Sametime will
provide instant messaging services. When you use a policy to define how these services are provided,
users cannot change them using the File - Preferences - User Preferences - Instant Messaging menu
choices. Those menu choices are inactive when the policy settings are invoked.

Note: The Notes application plug-in works only with the IBM Workplace Managed Client. You cannot
use it with other Eclipse applications.

For more information about the Notes application plug-in and the desktop policy settings document, see
the topic ″Creating a desktop policy settings document″ in this chapter.

Creating policies
Creating a policy is a two-step process. If you create an organizational policy, it automatically applies
when you register users. If you create an explicit policy, you assign it manually during user registration,
in the Person document or by using the Policy Assignment tool.

For more information on assigning explicit policies, see the topic ″Assigning an explicit policy,″ later in
this chapter.
1. Create one or more of the following policy settings documents to define default settings that you
want to assign to users:
v Registration policy settings
v Setup policy settings
v Desktop policy settings
v Security policy settings
v Archive policy settings
v Mail policy settings
2. Create a Policy document, which identifies specific policy settings.

Creating a registration policy settings document

If you include a registration policy settings document in a policy, when you register users, many
registration settings are filled in for you. If you use an organizational policy, when you register users with
the corresponding certifier ID, that policy is automatically applied. If you use an explicit policy, you
select the policy during registration.

For more information on user registration settings, see the chapter ″Setting Up and Managing Notes
Users.″ For more information about the password quality scale, see the chapter ″Protecting and Managing
Notes IDs.″

To create registration settings:

318 Lotus Domino Administrator 7 Help

1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a settings document
v PolicyModifier role to modify a settings document
2. From the Domino Administrator, select the People & Groups tab, and then open the Settings view.
3. Click ″Add Settings,″ and then choose Registration.
4. On the Basics tab, complete these fields:

Field Action
Name Enter a name that identifies the users that use these settings.

If you are a server provider, enter the name of the hosted organization.
Description Enter a description of the settings.
Choose a registration server Select the registration server from the list.
Choose a password quality Select a password quality level.

If you are a service provider, you must select a minimum password

quality of ″Any Password″ or, if specifying a number, level 2.

After users authenticate with their home servers, password quality is

Set Internet password
governed by security settings.
Check the ″Set Internet password″ check box to set the password that is
stored in each user’s Person document. This password gives users access
to Internet services. If you are a service provider, you must complete this
field.

5. If you are setting up roaming users, choose ″Roaming User,″ and then complete these fields. If you
are a service provider, note that ″Roaming User″ is not supported for hosted organizations.

Field
Use mail server for roaming server
Create roaming files options
Cleanup options
Action
Do one:
v Select to store the user’s roaming information on the same server used
for mail.
v Deselect and enter the name of the server to store the user’s roaming
information.
Choose one:
v Create roaming files now -- to create the user’s roaming files during
user registration.
v Create roaming files in background -- to use the Administration
Process to create the user’s roaming files after user registration.
Choose one:
v Do not clean up -- No cleanup is performed on roaming user files.
v Clean up every N days -- Specify a number between 0 an 365.
v Clean up periodically -- Cleans up files when Notes is shut down.
v Prompt for user clean up -- The user is prompted on exiting the client
as to whether they want to clean up their personal files. If the user
chooses Yes, the data directory on that client workstation is deleted. If
the user chooses No, the user is prompted as to whether they want to
be asked again on that client. If the user chooses No, the user is not
prompted again. If the user chooses Yes, the user is prompted again
the next time the user exits the client on that workstation.

Chapter 11. Using Policies 319

 6. Click the Mail tab, and complete these fields:

Field Action
Choose the mail system Choose a mail system.
v If you are a service provider, choose Lotus Notes only if you run
Domino Off-Line Services (DOLS) in the hosted organization.
v If you choose Other, Other Internet, or None, continue with Step 8.
Mail server Choose the server that stores the user’s mail file.
v If your organization supports DOLS, choose a DOLS-enabled server.
Mail template Choose one:
v MAIL7.NTF -- if the organization uses Lotus Notes, POP3, or IMAP.
v DWA7.NTF -- if the organization uses Domino Web Access.
v Your organization’s custom mail template
Create mail file Choose one:
v Create mail file now -- to create the mail file immediately.
v Create mail file in the background -- to use the Administration Process
to create the mail file. Choose this option if you are creating many
mail files at once.

7. Under Internet Address options, complete these fields:

Field
Internet Domain
Choose an Internet address format
Choose an Internet address separator
Action
Enter the Internet domain (or, if you are a service provider, the Internet
domain for the hosted organization). This domain becomes part of the
Internet address that is added to the Person document for each user who
receives Internet mail.
Choose the address format for Internet mail.
Choose the separator character to use in the user’s name portion of the
Internet address.

8. Under Advanced Mail Options, complete these fields:

Field
Mail file owner access
Create full text index
Action
Choose the access level. The default is Editor with delete rights.
Note: This is a change from previous versions of Domino in which the
default mail owner access was Manager. The change was made to
prevent users from accidentally deleting mail files.
(Optional) Check this option to allow users to perform a full-text search
on their mail files. The default is unchecked.

Full-text indexing is supported for Lotus Notes, POP3, IMAP, and

Domino Web Access. If you are a service provider, full-text indexing is
supported for only IMAP and Domino Web Access.
Set database quota (Optional) Check this option (default is unchecked) to enforce a database
size quota on mail databases, and then enter a size in MB.
Set warning threshold (Optional) Check this option (default is unchecked) to notify users
automatically when their mail files are nearing the maximum size quota,
and then enter a size in MB.

9. Click the ID/Certifier tab. In the ″Create a Notes ID″ field, do one:
v Uncheck the field if you do not want to create Notes IDs for users, and then continue with Step 9.

320 Lotus Domino Administrator 7 Help

 v Check the field to create Notes IDs. Then complete these fields:

Field
Security Type
Public Key Specification
Password Key Width
Certificate Expiration Date
Location for storing user ID
Action
Choose North American or International
Choose one:
v Compatible with all releases (630 bits)
v Compatible with 6.0 and later (1024 bits)
Choose the password key width (password encryption strength). The
encryption key that protects the Notes keys that are stored in the user ID
file is derived from the password. The stronger the encryption strength of
the password, the stronger the encryption key that protects the Notes keys.
v Base strength on RSA key size -- encryption strength is determined by
the size of the RSA key stored in the ID file. If the RSA key size is less
than 1024 bits, the password encryption strength is 64 bits; if RSA key
size is 1024 or greater, the password key size is 128 bits.
v Compatible with all releases (64 bits)
v Compatible with 6.0 and later (128 bits)
Choose one:
v Static date -- and then enter an expiration date. The default static date is
24 months from the creation.
v Months from user creation -- and then enter the number of months. The
default is 24 months.
Choose one or more:
v In Domino Directory -- to store the ID in the user’s Person document.
v In File -- and then click ″Set ID File″ to select the path and specify the
location to store the ID.
v In Mail File -- to store the ID in the user’s mail file.

For more information on security types, see the chapter ″Encryption and Electronic Signatures″ For
more information on the password quality scale, see the chapter ″Protecting and Managing Notes
IDs.″
10. Click the Miscellaneous tab, and complete any of these fields:

Field Action
Group assignments Choose the group to which you will add all users you register using these
registration settings. Leave this field blank if you are not registering all
users into one group.
Local administrator Enter the name of the administrator.

If you are a service provider, enter the name of the administrator at the
hosted organization in this format:

administrator name/certifying hosted organization

11. Save the document.

Creating a setup policy settings document

Use a setup policy settings document to define the default look and content of the user workspace, to
modify user Location documents, and to create Connection documents for dial-up connections that
simplify server connections. Setup policy settings are applied only once, during user setup. To maintain
these settings, specify the same settings in a desktop policy settings document. If a change is made to any
policy setting, the desktop policy settings will reinforce the setup settings the next time users authenticate
with their home server.

Chapter 11. Using Policies 321

Among the settings you can specify are the user preferences. These are preferences that Notes users can
usually specify for their desktop environment. If you set these preferences in a policy and then reinforce
them using desktop policy settings, Notes users will be able to change their preferences, but the change
will be only temporary.

Before you create a setup policy settings document, set up the Domino system for any or all of the
following:
v Domain search server
v Web Navigator and InterNotes server
v Databases you want to add to the user’s bookmarks in the Favorites folder
v Mobile directory (or client directory) catalogs
v Passthru servers, LAN servers, Internet servers, and remote servers
v TCP/IP and NDS Notes name servers
v Host domains where Java applets are assumed to be safe
v Proxy servers

To create setup policy settings:

1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a settings document
v PolicyModifier role to modify a settings document
2. From the Domino Administrator, select the People & Groups tab, and then open the Settings view.
3. Click ″Add Settings,″ and then choose Setup.
4. On the Basics tab, complete these fields.

Field Action
Name Enter a name that identifies the users (and, if you are a service provider, the
hosted organization) that use these settings.
Description Enter a description of the settings.
Catalog/Domain Search server Choose the name of the server used for domain searches.
Directory server Enter the name of the server whose Domino Directory you want users to use.
IBM Lotus Instant Messaging Enter the name of the server used to connect to IBM Lotus Instant Messaging.
server
Local mailfile Choose this option to create a local copy of the user’s mail file.
Internet browser Choose the Internet browser used from this location.

5. On the Databases tab, complete one or more of these fields to add databases to the user’s workspace:

Note: You cannot use the Web Administrator to create links.

For information about creating a link, see the chapter ″Organizing Databases on a Server.″

Field Action
Default databases added to Create a link for each database to add to the user workspace.
bookmarks Note: If the server that stores a database is down during setup, a bookmark
will not be created.
Create As new replicas on user’s Create a link for each database to add as a new replica to the user workspace.
machine
Mobile directory catalogs Create a link for each mobile directory catalog to add automatically to the user
workspace.

322 Lotus Domino Administrator 7 Help

 6. On the Dial-up Connections tab, enter information about the default passthru and other remote
servers.
7. On the Accounts tab, enter the default account information for Internet servers.
8. On the Name Servers tab, enter the names and addresses of secondary TCP/IP and NDS Notes
name servers.
On the Applet Security tab, complete these fields:

Field Action
Trusted hosts Enter the name of trusted hosts.
Network access for trusted hosts Choose one:
v Disable Java
v No access allowed
v Allow access only to originating host
v Allow access to any trusted host
v Allow access to any host
Network access for untrusted hosts Choose one:
v Disable Java
v No access allowed
v Allow access only to originating host
Trust HTTP proxy Choose one:
v Yes
v No

9. On the Proxies tab, enter the default proxies to assign to users.

10. On the Mail tab, choose the format to use for messages to Internet addresses.
11. On the Preferences tab, choose user preferences.
12. Save the document.
For information on user preferences, see Lotus Notes 7 Help.

Creating a desktop policy settings document

You use a desktop policy settings document to control the user’s workspace. Desktop settings are
enforced the first time a user logs in to Notes and runs setup. After the initial setup, you can use them to
update the user’s desktop settings or to reinforce setup settings desktop settings. Users receive updates to
the settings when any of the policy settings change, and then the desktop policy settings are enforced the
next time users authenticate with their home server.

To use a desktop policy settings document to enforce the settings specified in the setup policy settings
document, specify the same settings in a desktop policy settings document. For example, to ensure that
the IBM Lotus Sametime server specified in the setup policy settings document remains the same each
time the user logs in, enter the IBM Lotus Sametime server name in both the setup and desktop policy
settings documents.

You can use a desktop policy settings document to add or set NOTES.INI variables for Notes client users.
This is an easy way to assign NOTES.INI variables to all Notes client users, or to a specific subset of
Notes client users, at one time.

For more information about using policies to assign NOTES.INI variables to Notes client users, see the
topic Using policies to assign NOTES.INI settings to Notes client users.

To use a desktop policy settings document to add to or update the user’s desktop workspace, change the
setting in the desktop policy settings document. For example, to change the IBM Lotus Sametime server

Chapter 11. Using Policies 323

specified in the setup policy settings document, specify a different server in the desktop policy settings.
Other changes you can make to the user’s desktop workspace that do not reflect setup policy settings
include setting up a default home page, customizing the welcome page, customizing the My Work
Welcome page, upgrading the mail template, enabling automatic diagnostic data collection for client
crashes, specifying how and when Smart Upgrade runs to upgrade the Notes client, and configuring a
Smart Upgrade Tracking Reports database. If you are updating from a previous version of Domino, you
can use a desktop policy settings document to define the settings used when converting previous mail
file templates to the Domino 7 mail template, mail7.ntf. Based on the settings that you enter, an agent can
automatically be run to upgrade the user’s mail folders the first time the user opens their mail file after
the client has been upgraded.

For information about the Smart Upgrade Tracking Reports database, see the topic ″Smart Upgrade
Tracking Reports database″ in the Setting up Notes Users chapter.

Use a desktop policy setting document to modify user Location documents, and to create Connection
documents for dial-up connections that simplify server connections.

You also use a desktop policy settings document to manage and update bookmarks. You can, for
example, set up a bookmark hierarchy for Notes users by creating an outline of bookmarks that includes
folders and links such as database links, document links, and URL links. You can create folders that have
links within the folders. All of the folders and bookmarks in the outline are then placed on the Bookmark
Bar of the Notes client. To add bookmarks to an existing folder on the user’s desktop, such as More
Bookmarks, include the folder in the bookmark outline. Any links included in that folder are merged
with the corresponding folder in the Notes client. You can also create a folder called ″Startup″ that
includes links that open automatically every time the user logs in to Notes.

You can also set user preferences, usually set by Notes users. If you set user preferences, Notes users will
still be able to change their preferences, but the changes will be only temporary. The next time the
desktop policy is enforced, their preferences will be reset to the original policy settings.

The desktop policy settings document includes a Notes Application Plug In section on the Basics tab. Use
these settings to specify whether instant messaging services are provided by IBM Workplace
Collaboration Services, or by IBM Lotus Sametime. You also specify whether instant messaging name
resolution (converting Notes names to Internet names) is performed by IBM Workplace Managed Client
or the Domino Directory. To use the IBM Workplace Managed Client for name resolution, you must have
specified IBM Workplace Collaboration Services as the infrastructure to use to connect to instant
messaging. These settings can also be specified using NOTES.INI settings $USE_ST_IM and
WCT_IM_USE_LOOKUP instead of policies.

Note: If the desktop policy settings document is saved with the default settings selected for the fields in
the Notes Application Plug In section, the ″Use IBM Lotus Sametime instant messaging″ user preference
is de-selected each time the user exits the Notes client. To avoid this, choose IBM Lotus Sametime in the
Instant Messaging Provider field (to always use Sametime) or choose Don’t Change so that the policy
does not affect the current instant messaging selection. The user preferences are in Workplace Managed
Client, File - Preferences - User Preferences.

For more information about the NOTES.INI settings, see the appendix, ″NOTES.INI File.″

Note: An important user preference about which administrators should be aware is the option to ″use
canonical name for instant messaging status lookup.″ Enabling this setting for users lets them display
online awareness for names when your IBM Lotus Sametime server is configured to lookup Notes
canonical hierarchical names (for example CN=John Smith/OU=Sales/O=Acme) instead of Note
abbreviated hierarchical names (for example John Smith/Sales/Acme). (The feature described here is
available only if your company has an IBM Lotus Sametime server, and only for Windows versions of
IBM Lotus Notes.) Enable this setting in Preferences - Instant Messaging.

324 Lotus Domino Administrator 7 Help

Many of the tabs on the desktop policy settings document contain the field ″Allow users to change the
settings on this tab.″ Use this field to designate which tabs contain settings that the end-user can modify.
This is part of the client policy lock-down feature.

To create Desktop settings:

1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a settings document
v PolicyModifier role to modify a settings document
2. From the Domino Administrator, select the People & Groups tab, and open the Settings view.
3. Click ″Add Settings,″ and then choose Desktop.
4. On the Basics tab, complete these fields:
v Name -- Enter a name that identifies the users (and, if you are a service provider, the hosted
organization) that use these settings.
v Description -- Enter a description of the settings.
5. Under Homepage/Welcome Page options, complete these fields:

Field
Corporate Welcome Pages
database
Default Welcome page
Homepage selection
Action
Add the database link to the database containing custom welcome pages
and/or custom My Work pages.
Note: You cannot use the Web Administrator to create links.
Do one:
v Select the welcome page that users see when they start Notes.
v Select Workplace if you want users to see and use the My Work Welcome
page for Notes instead of a default or custom Welcome page.
v Select ″No default Welcome Page″ if there is no default welcome page.
(default)
For the field ″Do not allow users to change their home page″ do one:
v Check to prohibit users from choosing their own home page. If you check this
check box, users cannot change the welcome page or the My Work page to
anything other than what is defined in the policy. The drop-down list is
greyed out.
v Uncheck (default) to allow users to change their home page.

For more information about welcome pages, see the chapter ″Setting Up and Managing Notes
Users.″
6. Enable or disable the option to allow users to create private location documents.
7. If you are using the Notes Application Plug-in, complete these fields to set up instant messaging:

Field Action
Allow users to change the settings in this section Use this field to designate whether end users can modify
the settings in this section of the document. This is part
of the client policy lock-down feature.

Chapter 11. Using Policies 325

Field Action
Instant Messaging Provider Choose one:
v IBM Workplace Collaboration Services -- Default
setting. Choosing this option initiates the display of
the field ″Primary instant messaging name resolution
performed by.″
v IBM Lotus Sametime -- Choose this option if you want
IBM Lotus Sametime and Web Conferencing to
provide instant messaging services.
v Don’t change -- Choose this option to prevent this
policy from changing the instant messaging provider
established for the user in the user preferences for the
Notes client.
Primary instant messaging name resolution performed Choose one:
by: v IBM Workplace Managed Client -- Default setting.
Choose this option if you want name resolution (Notes
names converted to Internet names) performed by the
Workplace Managed client.
v Domino Directory -- Choose this option if you want
name resolution (Notes names converted to Internet
names) performed by the Domino Directory.

8. Specify whether to allow Private Location documents. A private location document is created by a
user, who designates who can use that document in the Only for user field on the Advanced - Basics
tab of the the Location document.
9. In the Server Options section, complete these fields:

Field Action
Catalog/Domain Search server Choose the name of the server used for domain searches.
Directory server Enter the name of the server whose Domino Directory you want users to use.
IBM Lotus Instant Messaging Enter the name of the server used to connect to IBM Lotus Instant Messaging.
server
Local mailfile Choose this option to create a local copy of the user’s mail file.
Internet browser Choose the Internet browser used from this location.
Retrieve/open pages If you chose Notes or Notes with Internet Explorer as the Internet browser,
choose the location from which to run the Web Retriever process.

10. Under Mail Template Information, complete these fields if you are converting from a previous
Domino mail template:

Field
Prompt user before upgrading mail file
Old design template name for your mail files
Action
Do one:
v Check yes to inform users before upgrading their mail
files. Allows users to defer upgrade.
v Uncheck (default) to upgrade without notification.
The default asterisk (*) uses any mail template.

(Optional) Enter the name of the current template you are

using.

326 Lotus Domino Administrator 7 Help

Field
If running this version of Notes:
Use this Mail template
Ignore 200 category limit
Mail file to be used by IMAP mail clients
Upgrade the design of custom folders
Prompt before upgrading folder design
Notify these administrators of mail upgrade status
Action
Enter the build version of the Notes client in the format
Release Vnn Month dd, yyyy (for example, Release 7.0.1
January 21, 2006). To upgrade all versions, use an asterisk *.
Tip: To find the build version, use Help - About Domino
Administrator.
Enter the new mail template file name.
By default the number of folders created during conversion
is limited to 200 folders. Do one:
v Check yes to override that limit and create as many
folders as necessary (default).
v Uncheck to enforce the limit.
Do one:
v Check if mail file will be used by an IMAP mail client.
v Uncheck if IMAP will not be used (default).
The conversion does not upgrade private folders
automatically. Do one:
v Check yes to include custom folders in the design
upgrade (default).
v Uncheck to exclude custom folders in the design upgrade.
Do one:
v Check yes to inform users before upgrading their mail
folder design. Allows users to defer upgrade.
v Uncheck (default) to upgrade folder design without
notifying users.
If you chose to notify users before updating mail template
or folders, enter the names of administrators who should
receive status information.

11. Under Internet Browser, choose the Internet browser used from this location. If you chose Notes or
Notes with Internet Explorer as the Internet browser, choose the location from which to run the Web
Retriever process.
12. Under Calendaring and Scheduling, complete this field:

Field Action
Reschedule repeating meetings using resettles feature Enable to allow users to reset repeating meetings that
have been rescheduled with different start and end times
to the same start and end time. This is disabled by
default.

13. On the Smart Upgrade tab, complete these fields according to whether you use the Smart Upgrade
feature, and if you are using it, according to how you use it.

Field
Upgrade deadline
Remind me every hour after
″upgrade deadline″ has passed
Mail-in Database for Smart
Upgrade reports:
Action
If you use Smart Upgrade, use mm/dd/yyyy format to enter the date by which
users must upgrade. If users to do not upgrade by this date, the upgrade
happens automatically.
Check this field if you want to send an hourly reminder to users who have not
updated their clients by the deadline set in the field ″Upgrade deadline.″
Enable Smart Upgrade Tracking for the user by selecting the mail-in database
name.

Chapter 11. Using Policies 327


Deploy version
Remove Smart Upgrade tracking
files after a specified number of
days:
Number of days to keep Smart
Upgrade Tracking reports files
If you use Smart Upgrade, enter the Notes version to
which you want users to upgrade.
Choose one:
v Yes -- Automatically deletes the Smart Upgrade tracking files when the
specified time period for maintaining files is exceeded and the Notes Client is
restarted. When field appears, enter number of days.
v No -- Maintains the Smart Upgrade tracking files after the specified time for
maintaining the files is exceeded. The files are not deleted.
Enter the number of days to keep the Smart Upgrade Tracking files before they
are deleted. Default is 365 days.
Note: This field appears only if you choose Yes in the field ″Remove Smart
Upgrade Tracking files after a specified number of days:″

14. On the Databases tab, complete one or more of these fields to add databases to the user’s workspace:

Note: You cannot use the Web Administrator to create links.

Field Enter
Create As new replicas on user’s Create a link for each database to add as a new replica to the user workspace.
machine
Mobile directory catalogs Create a link for each mobile directory catalog to add automatically to the user
workspace.
Bookmarks to merge with users’ Drag and drop or copy links to add to the user’s bookmarks. Arrange links in
bookmarks the order you want them to display. However, do not add any links above the
Favorites folder, because they will be added to the bottom of the user’s
bookmarks list.

15. On the Dial-up Connections tab, enter information about the default passthru and other remote
servers.
16. On the Accounts tab, enter the default account information for Internet servers.
17. On the Name Servers tab, enter the names and addresses of secondary TCP/IP, NDS and NetBIOS
Notes name servers. If you want users to be able to change the settings you specify on this tab, click
the check box ″Allow users to change the settings on this tab.″
18. On the SSL tab, complete these fields:

Field Enter
Accepts SSL Site certificates Choose one:
v Yes to allow the 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.
v No to not allow this server to accept site certificates.
Accept expired SSL certificates Choose one:
v Yes to allow clients to access the server, even if the
client certificate is expired.
v No to not allow clients to access the server with
expired client certificates.

328 Lotus Domino Administrator 7 Help

Field Enter
SSL protocol version Choose one:
v V2.0 only to allow only SSL 2.0 connections.
v 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.
v V3.0 only to allow only SSL 3.0 connections.
v 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.
v 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.

19. On the Applet Security tab, complete these fields:

Field Action
Trusted hosts Enter the name of trusted hosts.
Network access for trusted hosts Choose one:
v Disable Java
v No access allowed
v Allow access only to originating host
v Allow access to any trusted host
v Allow access to any host
Network access for untrusted hosts Choose one:
v Disable Java
v No access allowed
v Allow access only to originating host
Trust HTTP proxy Choose one:
v Yes
v No

20. On the Proxies tab, enter the default proxies to assign to users.
21. On the Mail tab, choose the format to use for messages to Internet addresses.
22. On the Preferences tab, choose user preferences.
23. On the Diagnostics tab, if you want to enable automatic diagnostic collection on clients, complete
these fields:

Field Action
Mail-in database for diagnostic reports Click the arrow in the field and then select the database
to which the diagnostic reports from client crashes are
to be mailed and then click OK.

Chapter 11. Using Policies 329

Field
Prompt user to send diagnostic report
Prompt user for comments
Amount (in KB) of diagnostic output file to send
Diagnostic file patterns:
Remove diagnostic files after a specified number of days
Number of days to keep diagnostic files
For more information about automatic diagnostic data collection on clients, see the chapter
″Transaction Logging and Recovery.″
24. Save the document.
For information about user preferences, see Lotus Notes 7 Help.
Creating a security policy settings document
A security policy settings document controls the Administration ECL, as well as Notes and Internet
passwords and public key requirements for Notes IDs.
330 Lotus Domino Administrator 7 Help
Action
Choose one of these:
v Yes -- (Default) Choose Yes to have the user
prompted as to whether they want to send a
diagnostic report to the mail-in database after a client
crash.
v No -- Choose No to make this feature transparent to
the user. The diagnostic report is automatically sent
to the mail-in database by a background process.
Choose one of these:
v Yes -- Choose Yes to display to the user, a message
box in which they can enter information as to what
they were doing when the client crashed. Choose Yes
only if you chose Yes in the ″Prompt user to send
diagnostic report″ field.
v No -- Choose No to prevent the user from entering
any comments.
Use the default value of 10240, or enter another value
between 10mb and 1kb. 10240 is the upper limit. This
value represents the portion of the CONSOLE.LOG file
to be sent, beginning with the end of the file and
moving toward the beginning of the file.
Enter a file name pattern that Domino will search for. If
the pattern is located and it is listed in the file,
DIAGINDEX.NBF, the file will be attached to the
message that is sent to the mail-in database.
DIAGINDEX.NBF contains all of the files associated
with the crashing instance of the client or server. For
example, the following is a file pattern: addin_log*.txt.
These files would be located based on that
pattern:addin_log1.txt,
addin_log_2004_11_23@16_21_20.txt, etc...
Choose one of these:
v No -- (Default) Choose No to accept the default of
never automatically deleting the diagnostic files on
the client.
v Yes -- Choose Yes to enter the number of days after
which the diagnostic files are to be deleted from the
client. Displays the field ″Number of days to keep
diagnostic files.″
Accept the default value of 365 days, or enter another
value representing the number of days after which the
diagnostic files are to be deleted from the client. (This
field displays only if you chose Yes for the ″Remove
diagnostic files after a specified number of days.″)
To create Security settings:
1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a settings document
v PolicyModifier role to modify a settings document
2. From the Domino Administrator, select the People & Groups tab, and then open the Settings view.
3. Click ″Add Settings,″ and then choose Security.
4. On the Basics tab, complete these fields:

Field Action
Name Enter a name that identifies the users (and, if you are a service provider, the
hosted organization) that use these settings.
Description Enter a description of the settings.

5. On the Password Management tab, complete these fields:

Field Action
Password management options
Use custom password policy for Choose one:
Notes clients v No (default)
v Yes - to implement a custom password policy. Custom password policies enable
you to configure specific password parameters so that passwords are not trivial
or predictable. Use settings on the ″Custom Password Policy″ tab to set up the
policy.
Check password on Notes ID Choose one:
file v No (default)
v Yes - to require that all copies of the user ID have the same password
Allow users to change Internet Choose one:
password over HTTP v Yes (default) -- to allow users to use a Web browser to change their Internet
passwords.
v No
Update Internet password when Choose one:
Notes client password changes v No (default)
v Yes -- to synchronize the user Internet password with the Notes client
password.
Enable Notes single logon with Choose one:
Workplace Rich Client v No (default)
v Yes - to allow users to enable single logon with the Notes plug-in for the IBM
Workplace rich client
Password expiration settings

Chapter 11. Using Policies 331

Field
Enforce password expiration
Required change interval
Allowed grace period
Password history (Notes only)
Warning period
Custom warning message
Password quality settings
Required password quality
Use length instead
6. If you have chosen to implement a custom password policy, complete these fields on the Custom
Password Policy tab.
332 Lotus Domino Administrator 7 Help
Action
Choose one:
v Disabled (default) -- to disable password expiration. If you disable password
expiration, do not complete the remaining fields in this section.
Note: If you enable password expiration for any of the following options, the
security settings document defaults change.
v Notes only -- to enable password expiration for only Notes passwords.
v Internet only -- to enable password expiration for only Internet passwords.
v Notes and Internet -- to enable password expiration for both Notes and Internet
passwords.
Note: Internet password expiration settings are recognized only by the HTTP
protocol. This means that Internet passwords can be used with other Internet
protocols (such as LDAP or POP3) indefinitely.
CAUTION:
Do not enable password expiration if users use Smartcards to log in to Domino
servers.
Specify the number of days for which a password is valid before it must be
changed. Default is 0.
Note: If you set this value to less than 30, the value for the ″Warning period″ field
is calculated automatically. The calculated value is 80% of the value entered for
this field.
Specify the number of days that users have to change an expired password before
being locked out. Default is 0.
Specify the number of expired passwords to store. Storing passwords prevents
users from reusing old passwords. Default is 0.
Specify the number of days prior to password expiration at which the user
receives an expiration warning message. Default is 0.
Note: The value of this field is calculated if the ″Required change interval″ setting
is set at less than 30 days. Password expiration must be enabled in order for the
value of this field to be calculated. If this value is calculated, it cannot be
overwritten.
Enter a custom warning message that will be sent to users whose password has
passed the expiration threshold specified in the Warning Period field.
Note: The custom warning message is for Notes clients only, regardless of how
you enabled password expiration. Internet users do not see the warning message.
If you require users to choose passwords based on password quality, specify that
quality by choosing a value from the drop-down list.
For more information on password quality, see the chapter ″Protecting and
Managing Notes IDs.″
If you require users to choose passwords based on length, click Yes. When you do,
the ″Required Password Quality″ field changes to ″Required password length.″
Specify the minimum password length here.
 For more information, see the chapter ″Protecting and Managing Notes IDs.″
Field
Change password on first Notes client use
Allow common name in password
Password length minimum
Password length maximum
Password quality minimum
Minimum number of alphabetic characters required
Minimum number of upper case characters required
Minimum number of lower case characters required
Minimum number of numeric characters required
Minimum number of special characters required
Maximum number of repeated characters required
Minimum number of unique characters required
Minimum number of non-lower case characters
required
Password may not begin with
Password may not end with
7. Complete the fields on the Execution Control List tab to configure the Administration ECL.
Action
Require users to change their passwords the first time they
log in using Notes.
Note: This only works if the policy is applied during user
registration.
Allow combination of common name of user to be used in
passwords. For example: John232 is the password for user
CN=John Doe/O=Mutt, where the common name is John
Doe.
Specify the minimum number of characters that users can
have in their passwords
Specify the maximum number of characters that users can
have in their passwords
Specify the minimum password quality value that users
can have for their passwords
Specify the minimum number of alphabetic characters that
users are allowed to have in their passwords
Specify the minimum number of uppercase characters that
users are allowed to have in their passwords
Specify the minimum number of lowercase characters that
users are allowed to have in their passwords
Specify the minimum number of special characters, namely
punctuation, that users are allowed to have in their
passwords
Specify the minimum number of special characters, namely
punctuation, that users are allowed to have in their
passwords
Specify the maximum number of repeated characters, of
any kind, that are allowed in user passwords.
Specify the minimum number of characters that appear
only once in a password
Specify the minimum number of special characters,
numbers, and upper case characters that you require in
user passwords. A higher value here makes passwords
more difficult to guess.
After you enter a number, a checklist appears, listing the
character types you can specify for this requirement. You
can pick any combination of the following:
v numbers
v special characters
v upper case
Specify the type of characters with which users cannot
begin their passwords
Specify the type of characters with which users cannot end
their passwords
Chapter 11. Using Policies 333
 For more information, see the chapter ″Protecting User Workstations with Execution Control Lists.″

Field Action
Admin ECL The default administration ECL is the default value for this field.

Choose one:
v Edit -- to edit the default administration ECL.
v New -- to create a new administration ECL. Enter the name of the new ECL and
choose options in the Workstation Security: Execution Control List dialog box.
The name of the new ECL appears in this field.
Update Mode Choose one:
v Refresh -- to update workstation ECLs with changes made to the
Administration ECL. If a setting appears in both the administration and
workstation ECL, the administration ECL setting overrides the workstation ECL
setting.
v Replace -- to overwrite the workstation ECL with the Administration ECL. This
option overwrites all workstation ECL settings.
Update Frequency Choose one:
v Once Daily -- to update the workstation ECL when the client authenticates with
the home server and either it has been a day since the last ECL update or the
administration ECL has changed.
v When Admin ECL Changes -- to update the workstation ECL when the client
authenticates with the home server and the administration ECL has changed
since the last update.
v Never -- to prevent the update of the workstation ECL during authentication.

8. Complete the fields on the Keys and Certificates tab to configure key rollover for groups of users. You
specify triggers that initiate key rollover for a group of users. You have the option of spacing out the
rollover process over a specified period of time for the group of users to which this policy applies.
For more information on key rollover, see the chapter ″Protecting and Managing Notes IDs.″

Field
Default Public Key
Requirements
User Public Key Requirements
Minimum Allowable Key
Strength
Maximum Allowable Key
Strength
Preferred Key Strength
Maximum Allowable Age for
Key (in days)
Action
v Inherit public key requirement settings from parent policy
v Enforce public key requirement settings in child policies
Choose one. Keys weaker than the one specified will be rolled over:
v No minimum.
v Maximum compatible with all releases (630 bits).
v Compatible with Release 6 and later (1024 bits).
Choose one. Keys stronger than the one specified will be rolled over.
v Minimum (512 bits)
v Maximum compatible with all releases (630 bits).
v Compatible with Release 6 and later (1024 bits).
Choose the preferred key strength to use when creating new keys:
v Minimum (512 bits).
v Maximum compatible with all releases (630 bits).
v Compatible with Release 6 and later (1024 bits).
Specify the maximum age a key can reach before needing to be rolled over.
Default is 36500 days (100 years).

334 Lotus Domino Administrator 7 Help

Field
Earliest Allowable Key Creation Any key created prior to this date will be rolled over.
Date
Spread new key generation for
all users over this many days:
Maximum number of days the
old key should remain valid
after the new key has been
created
Certificate Expiration Settings
Warning period
Custom warning message
Action
Specify the time period, in days, for new keys to be generated for all users to
whom this security settings policy document applies. User keys are randomly
rolled over during the configured time period. Default is 180 days.
Specify the length of time that the old key can be used during network
authentication. During Notes key verification, all of the certificates, old and new,
and all of the rollover keys are organized into a tree and then that tree is traversed
looking for a set of certificates that can be chained together to verify the key. If a
certificate has expired, it cannot be used in that chain. When rolling over a key
because you fear that it has been compromised, it is a good idea to set a short
value for the length of time the old certificates issued to that key can be used.
Valid values for this setting are 1 to 36500 days, and the default is 365.
Specify the number of days prior to certificate expiration at which the user
receives an expiration warning message. Default is 0.
Enter a custom warning message that will be sent to users whose certificate has
passed the expiration threshold specified in the Warning Period field.

9. Save the document.

Assigning an existing Admin ECL to a security settings document: It is possible to assign an existing
Admin ECL to a security settings document by doing the following:
1. In the Security Settings document, click Execution Control List.
2. Click Edit Settings.
3. Click New, and enter the name of the Admin ECL you want to assign to the Security Settings
document. The Admin ECL appears.
4. Click OK.
For more information about Notes and Internet passwords, see the chapters ″Protecting and Managing
IDs″ and ″Setting Up Name-and-Password and Anonymous Access to Domino Servers.″
For more information about administration and workstation ECLs, see the chapter ″Protecting User
Workstations With Execution Control Lists.″

Creating a mail policy settings document

Mail policy settings provide a mechanism for setting and enforcing client settings and preferences for
mail and for Calendaring and Scheduling. Mail policy settings can be used to:
v Create and manage message disclaimers. Use the Message Disclaimers tab on the Mail policy settings
document to enter the text of the message disclaimer.
v Set user mail preferences such as whether a user can delegate ownership of their mail file to other
people, define Sent view preferences, and set other mail-related preferences.
v Set alarm notification preferences and default alarm settings.
v Set numerous Calendar and To Do preferences for users, including Rooms and Resources settings.

The mail policy settings document contains fields that allow you to specify when a setting is to be
applied and whether end-users can modify the setting.
v Allow user to change -- Click the Allow check box to permit the user to change the setting that you
specified for the field. If you do not check the Allow check box, the user must use the setting that you
specify and is not allowed to make changes to the setting. This setting is part of the client policy
lock-down feature.
v When to Apply this setting -- Use this field to specify when the setting should be applied: Don’t
change, Always, or Initially.

Chapter 11. Using Policies 335

Note: Before using the mail policy settings document to set up message disclaimers, familiarize yourself
with how message disclaimers work. See the topic Setting up and using message disclaimers.

The effective mail policy for a user is stored in that user’s mail database in the calendar profile. The
administration process writes the mail policy to the calendar profile. The administration process checks
for mail policy updates every 12 hours, and when necessary updates the user mail files according to the
changes in the mail policy settings document.

Message disclaimers and character sets: As previously mentioned, message disclaimers can be added
by the server or by the client.

The client adds message disclaimers prior to converting the character set; therefore, the client process for
determining Internet character sets for MIME messages has not changed.
v If the client is configured to disclaim and send Notes RTF messages to the Internet, the client adds the
disclaimer to the message and sends it. When the client adds the message disclaimer, it marks the
message as ″disclaimed.″ The Domino server converts the message from Notes RTF to MIME format
and determines the Internet character set for the message. The Domino server does not disclaim the
message because the client has already marked the message as disclaimed.
v If the client is not configured to disclaim messages, the Domino server disclaims the message as
described. If necessary, the server converts the RTF message to a MIME format message.

When message disclaimers are added by the server, Domino determines the Internet character sets for the
message text and the message disclaimer. If the character sets are the same, Domino adds the message
disclaimer and the message is sent. If the two character sets differ, Domino determines which character
set to use as follows:
v If the ″Multilingual Internet mail″ setting is Use Best Match, Domino uses either the message text’s
character set or the disclaimer’s character set according to which character set best represents the
characters. Any characters that cannot be represented by the correct character are represented by a
substitute character -- typically a question mark (?). Domino then sends the message.
v If the ″Multilingual Internet mail″ setting is Use Unicode (UTF-8), Domino re-codes the message text
and disclaimer text as UTF-8 and sends the message.

Creating a new mail policy settings document:

1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a settings document
v PolicyModifier role to modify a settings document
2. From the Domino Administrator, select the People & Groups tab, and then open the Settings view.
3. Click ″Add Settings,″ and then choose Mail.
4. On the Basics tab, complete these fields:

Field Action
Name Enter a name that identifies the users that use these
settings or that describes the purpose of these settings.
Description Enter a description of the settings.

5. Complete these fields on the Mail File Preferences - Mail - Basics tab:

Field
Allow users to change mail file ownership
Automatically check mail messages for misspellings
before sending
Action
Click the Allow check-box to allow users to change their
mail file ownership setting. Users will be able to modify
the assigned ownership of their mail files.
Click Yes to enable the checking of email messages for
misspellings prior to sending the message.

336 Lotus Domino Administrator 7 Help

Field
Delete/Remove preference for Sent View
Soft delete expire time in hours
Action
Choose one:
v Always Ask -- Notes always asks if the user wants to
save each message when it is sent. If the user selects
Yes, Notes saves the message in the Sent view.
v Always Delete -- Notes always deletes mail messages
after sending them.
v Always Remove -- Notes always removes the mail
message from the current view after sending the
message, but does not delete the message.
Enter the number of hours to elapse prior to
automatically deleting a mail message from the Trash
folder. (The messages in the Trash folder have already
been marked for deletion by the mail file owner.)

Default value is 48 hours.

6. On the Mail File Preferences - Mail - Letterhead tab, click Yes to set a default letterhead for users
mail messages. Select the default letterhead from the list of available letterheads. If you do not want
to set a default letterhead for users, do not check the Yes check box.
7. Complete these fields on the Mail File Preferences - Calendar & To Do - Basics tab:

Field action
Double-clicking on a time slot in calendar creates a Select the default form (meeting, appointment,
anniversary, reminder, or all day event) to open when you
double-click a time slot to create a new Calendar entry.
Duration of a new appointment or meeting (in minutes) Enter a new default duration for new appointment entries
and meeting invitations.

Default is 60 minutes.
Anniversaries repeat for (in years) Enter a new default period for new anniversary entries to
repeat.

Default is 10 years.

8. Complete these fields on the Mail File Preferences - Calendar & To Do - Display tab:

Field Action
How the Calendar view is displayed
Beginning of the work day Beginning of the work day - Specifies the start time for
the first time slot that displays in the calendar. For
example, if you choose 8:00 AM, the calendar displays 8
00 AM as the start time for the first time slot for each day.
End of the work day End of the work day -- Specifies the end time for the last
time slot that displays in the calendar. For example, if you
choose 6:30 PM, the calendar displays 6:30 PM as the end
time for the last time slot each day.
Each time slot lasts Each time slot lasts -- Choose either 60, 30, or 15 minutes
according to the degree of detail you want users to be
able to specify when designating the duration and time of
a meeting. For example, if you choose 15 minutes,
meetings can be set in as few as 15 minute increments.

Chapter 11. Using Policies 337

Field
Start monthly view with current week
Days displayed in a work week
Displaying Calendar Entries in Mail Views
Put C&S documents into a special New Notices Mini
View for processing
Hide new calendar entries and notices in All
Documents view of Mail
Hide new Meeting invitations in the Sent view of Mail
Remove meeting invitations from your Inbox after you
have responded to them
Types of meeting notices to be shown in your Inbox
9. Complete these fields on the Mail File Preferences - Calendar & To Do - Scheduling tab:
Field
Your Availability
When adding an entry to your calendar
Check for conflicts when adding appointments,
accepting meetings, scheduling a new meeting
Note a conflict if entry occurs outside available hours
described above
338 Lotus Domino Administrator 7 Help
Action
Select this option if you want the Calendar view to open
with the current week displayed first, instead of the first
week of the current month (the default setup in Notes).
Note: The Start monthly view with current week option
affects the Calendar only in how it displays when opened
in one of the month view formats (One Month or One
Work Month).
Select the days of the week to display in Work Week view.
Click Yes to display in the New Notices Mini View the
new entries that you need to take action on. Once you
take action on them, the notices disappear from the view.
Click Yes to hide calendar entries in the All Documents
view in Mail.
Click Yes to hide meeting invitations in the Sent view in
Mail. Yes is selected by default.
Click Yes to remove meeting invitations from the user’s
Inbox after the user has responded to them.
Choose one:
v All -- To display all Calendar and To Do notices,
including invitees responses to them, in the user’s
Inbox.
v All except responses -- To display all Calendar and To
Do notices, excluding invitee responses to them, in the
user’s Inbox. To see responses, look in the All
Documents view in Mail, View Invitee Status per
meeting, or look in the Meetings view in Calendar.
v None -- To hide all Calendar and To Do entries in the
user’s Inbox.
Action
Use this setting to establish the user’s free-time schedule.
Select the days of the week the user is available, then
specify the hours the user is available for each selected
day.
Click Yes if you want Notes to check for conflicts when
users are adding appointments, accepting meetings, and
scheduling a new meeting.
Click Yes to show a conflict if someone attempts to
schedule a meeting for a time that is not available
according to the user’s preferences.
This field appears only if chose Yes in the field ″When
adding appointments, accepting meetings, scheduling a
new meeting.″
Field Action
For new meetings, the Scheduler initially shows Choose one:
v Schedule details for each participant -- To view detail
schedule and availability information for each
participant.
v Suggested best times for meetings -- To view a
summary list of suggested meeting times, based on the
invitees, rooms, and resources free time schedule.

10. Complete these fields on the Mail File Preferences - Calendar & To Do - Alarms tab:

Field Action
Enable/Disable Alarms
Enable the display of alarm notifications Click Yes to allow alarm notification to display. Alarms
generate mail or audio reminders.
Default alarm settings when creating a new entry Select the default alarm settings for events
(appointments/meetings, anniversaries, reminders, or all
day events or todos) to apply when creating a new entry.
These display only when ″Enable the display of alarm
notifications″ has been set to ″Yes″.
How far in advance For meetings, appointments, and reminders enter the
number of minutes in advance that the alarm can be set.
For events, anniversaries, and to do items, enter the
number of days in advance that the alarm can be set.
These display only when ″Enable the display of alarm
notifications″ has been set to ″Yes″.

11. Complete these fields on the Mail File Preferences - Calendar & To Do - To Do tab:

Field Action
Hide To Do entries in the calendar Click Yes to prevent To Do entries from displaying in the
Calendar.
Allow Notes to update To Do status and dates for Click Yes to allow Notes to display incomplete To Do’s
incomplete entries on the current day in the Calendar.

12. Complete these fields on the Mail File Preferences - Calendar & To Do - Auto Process tab:

Field Action
Enable automatic responses to meeting invitations Click Yes to allow Notes to automatically process
meeting invitations from all or some users.

When you click Yes, the field ″When a meeting invitation

When a meeting invitation is received from anyone,
automatically accept
is received from anyone″ displays.
Choose one:
v Automatically accept if time is available; if not,
automatically decline.
v Automatically accept if time is available; if not, let me
decide.
v automatically accept even if time is not available --
Allows Notes to automatically accept all invitations
regardless of whether the calendar indicates that time
is available.

Chapter 11. Using Policies 339

Field
When you delete a Calendar Notice from your Inbox or a Choose one:
Mail folder/view
13. Complete these fields on the Mail File Preferences - Calendar & To Do - Rooms & Resources tab:
Field
Default Reservation settings for choosing site
Preferred site
Use the preferred site as the default in the Find Room
and Find Resource dialogs
Prompts to reset your preferred site when scheduling
within a site that is not your current preferred site
Default Meeting Settings For Rooms
Default Meeting Settings for Resources
14. Complete these fields on the Mail File Preferences - Access & Delegation - Access to Your Mail &
Calendar tab:
340 Lotus Domino Administrator 7 Help
Action
v Prompt to confirm deletion -- When deleting a
Calendar notice from an Inbox, a Mail view, or Mail
folder, select this option if you want Notes to always
prompt the user to confirm the deletion.
v Remove from this view or folder without prompting --
When deleting a Calendar notice from an Inbox, a
Mail view, or Mail folder, select this option if you
want Notes to remove the notice from the current Mail
view or folder without prompting the user, but not
delete it from the Mail database (the user can find the
notice in the All Documents view).
Action
Enter the name of the preferred meeting site.
Click Yes to set the preferred site as the default entry in
the Find Room and Find Resources dialog boxes.
Click Yes to prompt users to reset their default preferred
site when scheduling within a site that is not the
preferred site.
Choose one:
v Prompt me to add rooms to my list when scheduling
meetings -- To prompt the user to specify whether
they want to add additional rooms to their preferred
list of rooms. If they answer Yes, they can select the
rooms to add.
v Always add rooms to my list when scheduling
meetings -- To allow Notes to automatically update the
user’s preferred list of rooms whenever additional
rooms are available.
v Never add rooms to my list when scheduling meetings
-- Never permit Notes to update the user’s preferred
list of rooms.
Choose one:
v Prompt me to add resources to my list when
scheduling meetings -- To prompt the user to specify
whether they want to add additional resources to the
preferred list of resources. If they answer Yes, they can
select the resources to add.
v Always add resources to my list when scheduling
meetings -- To allow Notes to automatically update the
user’s preferred list of resources whenever additional
resources are available.
v Never add resources to my list when scheduling
meetings -- Never permit Notes to update the user’s
preferred list of resources
Field
The following people or groups have been delegated
access to your mail file:
Allow users to set up delegees to their mail file:
15. Complete these fields on the Mail File Preferences - Access & Delegation - Access to Your Schedule
tab:
Field
Who is allowed to see it?
What schedule information they can see
Do not include the subject of a calendar entry when
detailed information is made available
16. Complete these fields on the Message Disclaimers tab:
Field
Notes client can add disclaimers
Action
Use the Allow user changes check box to designate
whether users can modify this field.
Action
You can designate how much of, or whether, a user’s
schedule information appears when other people
schedule meetings and click Scheduler to check for your
busy and free times.
Choose one:
v Everyone may see your schedule information --
Everyone can view this user’s schedule.
v No one may see your schedule information -- No one
can view this user’s schedule.
Choose one:
v Only information about when you are busy and
available -- Default setting. Designated individuals just
see time periods designated as busy time or available
time.
v Detailed information about your calendar entries. --
Designated individuals can view detail information in
your schedule. The field ″Do not include the subject of
a calendar entry when detailed information is made
available″ displays.
This field is available only if the option ″Everyone may
see your schedule information″ is selected in the ″Who is
allowed to see it″ field.
Click Yes to prevent the subject line of the calendar entry
from displaying when detailed information about a
user’s calendar entries can be viewed by other users.
Note: This field only displays if ″Detailed information
about your calendar entries″ is selected in the field
″What schedule information they can see.″
Action
Choose one:
v Enabled -- To allow message disclaimers to be added
by the Notes client.
v Disabled -- To prevent message disclaimers from being
added by the Notes client. (Message disclaimers can
still be added by the server if the Message Disclaimers
setting is Enabled on the server’s Configuration
Settings document.)
Chapter 11. Using Policies 341
Field Action
Disclaimer text Enter the message disclaimer text that you want added
to mail messages. The message disclaimer text is read by
the server.
Note: To modify the disclaimer text, click Modify and
enter the modifications. Click OK.
Disclaimer text format Use the Disclaimer text field to specify the format in
which the disclaimer text is entered.

Choose one:
v Plain text -- When adding the disclaimer text in plain
text format.
v HTML -- When adding the disclaimer text in HTML
format.
Note: Enter the HTML tags when you are entering the
text of the message disclaimer. Image files are not
supported in HTML message disclaimers.
Disclaimer position Choose one:
v Append -- To add the message disclaimer at the end of
the mail message.
v Prepend -- To add the message disclaimer at the
beginning of the mail message.
Multilingual Internet mail The character set for Internet mail must be correct for the
message that is created from both the mail message text
and the message disclaimer text. This setting applies to
message disclaimers added by the server.

Choose one:
v Use Best Match --Use this option if you think the mail
recipients’ mail programs can not read Unicode
character sets.
v Use Unicode (UTF-8) -- Unicode is the preferred
method of sending messages in multiple languages.
Use this option if you think the mail recipients’ mail
programs can read Unicode character sets.

17. On the Comments tab, enter or modify comments regarding this policy settings document.
18. On the Administrator tab, enter or select the Owners and Administrators of this document.
19. Click Save & Close.

Mail archiving and policies

Administrators can centrally control mail file archiving using policies. Archiving is particularly useful for
mail databases because when a user sends a mail message, Notes automatically saves a copy of it in the
Sent view, causing the mail file to increase in size. Archiving the mail file frees up space and improves
the performance of the mail database by storing documents in an archive database when they are old or
not in use anymore.

The mail archive database is a Notes database, and can be accessed like any other Notes database. The
views in a user’s mail archive mirror the views in the mail file and includes all the folders that exist
when mail is archived. So users can find and retrieve archived messages easily from within their archive
database. When a document has one or more responses, the entire document hierarchy is archived.

You can also use archiving policy settings to define a document retention policy for your mail files. With
document retention, you define the criteria for old documents, and then simply delete them from the
mail database without archiving them.

342 Lotus Domino Administrator 7 Help

If you choose not to include archiving policy settings in your policies, Notes users can still archive mail
files using database archive settings in the Notes client.

How mail file archiving works: Mail file archiving is a three-step process that includes document
selection, copying files to an archive database, and mail file cleanup.
v Document selection -- choosing which documents to archive based on activity and on folder selection.
For example, you can define an old document as a one that has not been modified for 365 days. You
can then archive all documents that match that criteria, or you can archive only documents in specific
folders that match that criteria.
v Copying -- copying selected documents from the source mail file to an archive database destination.
v Mail file clean up -- reducing the size of the source mail file by deleting archived documents or
reducing them in size. You can reduce the size of the document by first removing attachments, and
then leaving only the header information or leaving the header information and a portion of the mail
document.

Client-based and server-based archiving: When you use policies to manage archiving, you use either
server-based archiving or client-based archiving. In either case you can archive to a server. The terms
server-based or client-based refer to where the archiving process occurs, either on a server or on the
client’s workstation. If you choose to archive on a server, you must create a program document to run the
Compact server task. If you choose client-based archiving, however, the workstation must be running in
order to archive documents. If archiving is scheduled at a time during which the workstation is not
running, archiving will not occur. You can archive mail files to the following:
v Server-based archiving -- Using this option, the mail server archives to the mail server itself, or to
another server that you designate as the archive server.
v Client-based archiving -- Using this option the individual workstations process mail file archiving.
Depending on where the mail file resides, either on a mail server or on their individual workstations,
mail is archived to the mail server, a designated server, or to their local workstations.

For more information on using a program document to run the Compact server task, see the chapter
″Improving Database Performance.″

An example of using policies to manage mail file archiving: Acme’s administrator is happy to learn of
policy-based archiving because of these issues with archiving mail files:
v Space is tight on the mail server.
v Acme needs a centralized archive server.
v Archiving cannot occur during peak work hours.
v End users must not be allowed to control their archive settings.
v Lotus Notes 7 clients will not be rolled out immediately.

To resolve the problems to Acme’s archiving issues, the administrator uses these Archive policy settings,
and applies them to all users, via organizational policies.
v Archive settings are centrally managed and enforced by the administrator; users are prohibited from
changing or creating archive settings.
v Server-based archiving is enabled from a mail server to a designated archive server.
v The designated archive server is a Domino 7 server so that policies can be enforced in a mixed
environment.
v Archiving is scheduled to occur during off hours.
v Optionally, pruning (removing attachments and body of mail, but leaving header information intact)
might be helpful, depending on how tight space is on the mail server.

Using the mail archive log: To monitor mail document archiving, you can log archiving activity to an
archive log database. Information stored in a user’s Archive Log include the log date, the number of

Chapter 11. Using Policies 343

documents stored in the archive database and deleted from the mail file, archive failures, and the
locations of the original mail file source and archives destinations.

You can use the mail archive log, for example, to track a document you thought was deleted. You can
easily scan the Archive Log to see if the document was archived. And since the archive log provides links
to archived documents, you can access the archived document from within the archive log.

Specifying the name and location for the Archive Log database: By default, the archive log database is stored
in c:\notes\data\archive, where archive is the default name for the archive directory. The default name
format for a user’s archive log database file is l_xxxx.nsf, where l_ is the prefix and xxxx is the name of
the user’s mail database. The name of the log database is based on a specified number of characters (the
default is 6) from the user’s ID. For example, for the end user John Smith, whose ID is jsmith, the archive
log database name is l_jsmith.nsf.

For more information about the type of information stored in an Archiving Log, see the chapter
″Improving Database Performance.″

Archive log file title: When a user archives a mail database to an archive log file, the log file title reflects
the name of the user’s mail file. The user can then manually change that log file name if desired. If
logging is turned off for mail archiving, this does not apply.

Creating an archive policy settings document: To set up mail file archiving, you use both archive and
archive criteria policy settings documents. The archive policy settings document enables you to specify
archive policy parameters -- or not specify parameters -- as well as to specify whether Notes users can
archive mail databases, and whether they can set or modify archive settings.

To prohibit all archiving, select the ″Prohibit Archiving″ setting and apply the policy to a set of users. If
you choose to prevent private archiving, users cannot change these settings or create private archive
settings.

If you allow archiving, use the archive policy settings document to define whether archiving is performed
by a server or by a user’s client, and to specify source and destination archive systems. If archiving is
client-based, you can also set the archive schedule. If you choose to, you can change the name and
location of the default archive log file. You can also set a policy designating that archiving is done by the
user’s client, and allow the user to define the schedule and archiving criteria.

To create archive policy settings:

1. Make sure that you have at least Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a settings document
v PolicyModifier role to modify a settings document
2. From the Domino Administrator, select the People & Groups tab, and then open the Settings view.
3. Click ″Add Settings,″ and then select Archive.
4. On the Basics tab, complete these fields:
v Name -- Enter a name that identifies the users or the settings themselves (and, if you are a service
provider, the hosted organization).
v Description -- Enter a description of the settings.
5. (Optional) Under Archiving options, choose one of the following if you want to prohibit archiving.
The default is to allow both.
v Prohibit archiving -- to prohibit all archiving. The ″Allow Calendar Cleanup″ check box displays.
Allow Calendar Cleanup is selected by default but you can deselect if you choose to. Save the
document.
v Prohibit private archiving settings -- to prohibit Notes users from creating private archive settings
or modifying the archive settings defined in this settings document.

344 Lotus Domino Administrator 7 Help

 6. Under Archive locations, choose one:
v Archiving will be performed on user’s local workstation -- to use the Notes client workstation to
perform the archive process (the default).
v Archiving will be performed on a server -- to use a server to perform the archive process.

Note: If you choose ″Archiving will be performed on a server,″ you must create a program
document to run the compact task.
For more information on using a program document to run the Compact server task, see the chapter
″Improving Server Performance.″
7. Under ″Archive source database is on,″ specify the server or workstation on which the mail file that
will be archived is located. Choose one:
v Local -- if the mail file is on the user’s workstation, of if the user has opened a replica of their
mail file. The replica may reside on a client or a server. Local applies to the mail file the user has
open and from which they issue any archiving commands.
v Specific server -- if the mail file is on a server other than the user’s designated mail server. Specify
the name of the server.
v Mail server -- if the mail file is on the mail server specified in the user’s Location document
(default).
8. Under ″Destination database is on,″ specify the server or workstation on which the archive database
will reside. If you allow private archiving, you must give the user Create access on the destination
server to create an archive database. Choose one:
v Local -- to create the mail archive database on the user’s workstation (available for client-based
archiving only).
v Specific server -- to create the mail archive database on a server other than the mail server. Then
specify the name of the server.
v Mail server -- to create the mail archive database on the user’s designated mail server.
9. On the Selection Criteria tab, do one or more of the following:
v Click New Criteria to create a new Archive Criteria Settings document. Then, click Add Criteria
and select your newly-defined criteria document.
v Click Add Criteria, and then choose one or more archive criteria settings documents to add to
your archiving settings.
v Click Remove Criteria, and then choose one or more archive criteria settings document to remove
from your archiving settings.
For information on creating an archive criteria settings document, see the topic ″Creating Criteria for
mail archiving,″ later in this chapter.
10. Click the Logging tab. Under Archive Logging, check the field ″Log all archiving into a log database″
to log archiving activity to a log database (the default).
11. (Optional) Change any of these fields if you want to change the location of the log directory and log
file name.

Field Action
Log Directory The default is archive. Enter a new name if you want to change it.
Log Prefix The default is the letter l, followed by an underscore (_). Enter a new prefix if
you want to change it.
Log Suffix The default is .NSF. Enter the file name that will precede the file name extension
(suffix).
Number of characters from The default is 6. To change this, enter the number of characters you want to use
original filename from the user’s ID to create the archive log name.

12. In the field ″Include document links to archived documents,″ do one:

Chapter 11. Using Policies 345

 v Check the field to include links to archived documents in the log (default). If you include links,
users can open archived documents from within the log database.
v Uncheck the field to exclude links to archived documents in the log. If you exclude links, users
must open the archive database to view archived documents.
13. On the Schedule tab, do one of these:
v Click the check box ″Specify a client-based scheduled archive″ to set up a schedule for client-based
archiving, and then specify the schedule. The schedule you specify becomes the default schedule.
If you also choose ″Allow users to modify the schedule,″ users can set an archiving schedule by
modifying the default schedule. If you do not choose ″Allow users to modify the schedule,″ users
cannot modify the archiving schedule.
v Do not check the option ″Specify a client-based archive schedule.″ No archiving schedule is set for
the users; however, users can still set their own archiving schedule.
14. (optional) If you checked ″Specify a client-based archive schedule″ complete one or more of these
fields.

Field Action
Frequency Choose one:
v Daily and then select the days of the week on which to archive.
v Weekly (default), and then choose the day of the week on which to
archive.
Run at Specify the time. The default is 12:00 PM.
Note: The Notes client must be running for scheduled archiving to occur.

15. Under Location, specify the locations from which to archive. For example, if you are using
client-based archiving, you may want to archive only from a user’s office workstation, not from an
island or if the user has dialed in. Choose one:
v Any location -- to archive from any location.
v Specific location -- and then specify one or more locations.
16. On the Advanced tab, complete these fields:

Field Action
Delete a document only when the criteria can delete all Do one of these:
responses as well v Check (default) to ensure that documents that have
response documents that do not meet archiving criteria
are not deleted from the database. Use this option to
prevent orphaning of documents in hierarchical views.
v Uncheck to delete documents without prior checking
of response documents.
Maximum document retention selection is: Specify for all users to whom the policy applies, the
number of days, months, or years that comprise the
maximum retention period for deleting and archiving
documents. If private archiving is enabled, and a
maximum retention setting is in effect, users cannot
define criteria with a scope that is larger than the
maximum retention setting.

For example, assume the maximum retention is set to

two years. Users can define criteria that selects
documents created, modified, accessed, or expired up to
24 months. An error is generated if users try to save
criteria whose scope is greater than 24 months (two
years).

346 Lotus Domino Administrator 7 Help

Field
Use customer-generated expiration field:
Customer generated expiration field name:
Action
Click to enable administrators to define their own field
name for an archive document expiration date.
Specify a field name for the expiration date of archived
documents.

17. Save the document.

Creating criteria for mail archiving: You use an Archive Criteria policy settings document to define sets
of criteria to use when archiving a Notes user’s mail documents. You create an Archive Criteria policy
settings document from within an Archive policy settings document. After you create archive criteria, you
can use it in one or more archive policy settings documents.

When you specify archive criteria, you determine what to do with old documents in a user’s mail file. Do
you archive them (copy them to an archive database) or just delete them? If you archive them, you
determine how to ″clean up″ the copies of the archived mail documents that remain the user’s mail file.
And finally, you define what an old document is.

Mail file criteria answers these questions:

v How should documents be archived? Archiving can be a combination of copying old documents to an
archive database and then performing clean-up tasks on the users mail file, or just deleting them
v How should documents be cleaned up? Once documents have been copied to an archive database, you
can either delete the copies that remain in the user’s mail file, or reduce the size of the document.
v Which documents should be cleaned up? You provide a definition of an ″old document″ by specifying
age criteria, and then applying that age criteria either to all documents or all documents in specified
folders.

Specifying the name and location for the Archive database: By default, the archive mail database is stored in
the directory archive, located in the data directory. Archive is the default name for the archive directory.
The default name format for a user’s archive database file is a_xxxx.nsf, where a_ is the prefix and xxxx
is the name of the mail database. The name of the archive database is based on a specified number of
characters (the default is 6) from the user’s mail file. For example, for the end user John Smith, whose
mail file is jsmith, the archive database name is a_jsmith.nsf.

To create archive criteria policy settings:

1. From the Domino Administrator, select the People & Groups tab, and then open the Settings view.
2. Do one:
v Select the Archive policy settings document for which you want to create archive criteria settings,
and then click ″Edit Settings.″
v Click ″Add Settings″ and then select Archive to create a new Archive policy settings document.
3. Select the Archive Criteria tab, and then click ″New Criteria.″
4. Provide the following information on the Basics tab.

Field Action
Name Enter a name that identifies the archive criteria. When you add criteria
to a criteria policy settings document, this is the name that appears in
the selection box. This name also appears in the user’s mail folder
outline under tools - archive.
Description Enter a description of the criteria.
Archiving is enabled Do one:
v Check to enable this archive criteria.
v Uncheck if you are creating archive criteria to use later.

Chapter 11. Using Policies 347

 5. For ″How should documents be archived?,″ choose one:
v Copy old documents into archive database; then clean up database -- to archive (copy) documents
to the archive database and then clean up (delete those documents) from the user’s mail database.
v Clean up database without archiving -- to delete documents from the user’s mail database without
copying them into an archive database. Use this setting to enforce document-retention policies that
delete all documents after a specified time.
6. (Optional) If you chose to archive documents and then ″clean up,″ the copies that remain in the
user’s mail file, for ″How should documents be cleaned up?,″ choose one:
v Delete older documents from the database -- to delete copies of archived documents that remain
in the user’s mail database.
v Reduce the size of the documents in the database -- to truncate copies of the archived documents
that remain in the user’s mail database. Then choose one:
Leave summary -- to leave only the header information on the mail document.
Leave summary + 40KB -- to leave the header information and 40KB of the body of the mail
document. This will truncate large documents only.
7. Under ″Which documents should be cleaned up?″ specify the criteria that defines an ″old″
document. This criteria determines which documents are candidates for archive and cleanup, or
deletion. Choose one:
v Created date -- to specify the date the archive criteria settings document was created as the start
date for the document retention period. The created date value is the beginning of the document
retention period and the end of the document retention period is determined by the number of
days, months, or years that you specify.
v Not accessed -- to specify documents not opened in the specified time frame. Do not use this
option unless the database property Maintain Last Accessed is set. If this property is not set, Notes
does not consider a document accessed even if it is opened. Then specify a time period.
v Not modified -- to specify documents that have not been modified in the specified time frame
(default). Then specify a time period. This is the recommended setting.
v Marked expired -- to specify documents that the Notes user has marked expired.
8. (Optional) If you use a custom mail template, complete these fields
v Change template server -- select the name of the server on which your mail template is stored.
v Choose template -- select the name of your custom mail template.
9. For ″In views or folders″ check this option to clean up all documents in the selected views and
folders according to the criteria you established in the settings above.
10. (Optional) Click the Destination tab and change any of these fields if you want to change the
location of the archive database.

Field Action
Archive Directory The default is archive. Enter a new name if you want to change it.
Archive Prefix The default is the letter a, followed by an underscore (_). Enter a new
prefix if you want to change it.
Archive suffix The default is no suffix. Enter a suffix for the archive database name if
you want to add one.
Number of characters from original The default is 6. To change this, enter the number of characters to use
filename from the user’s mail file to create the archive database name.

11. Save the document.

348 Lotus Domino Administrator 7 Help

Creating a policy document
When you create a policy, you use a Policy document to specify which policy settings documents to
include. You can create policy settings documents before you create the policy document, or you can
create them while you create the Policy document.

If you are creating an exception policy, include only the policy settings documents that have settings
whose values you do not want to enforce. For each setting you do not want to enforce, change the value
as required. Exceptions are made at the policy setting level. When the effective policy settings are
resolved, any settings you specify in the exception policy apply.

Policy document names: The names of Policy documents must be in one of the formats below.
However, when you create a Policy document, you do not have to include the asterisk (*) or slash (/)
when you enter a policy name. Domino adds them for you depending on the type of policy you specify.

*/organization -- an organizational policy that is automatically applied at the organization level

*/organizational unit/organization -- an organizational policy that is automatically applied to an

organizational unit

*/hosted organization -- an organizational policy that is automatically applied to a hosted organization

* -- an organizational policy that is automatically applied to everyone in the Domino Directory

/policyname -- an explicit policy that must be assigned manually, but can be assigned at any organizational
level

To create a policy document:

1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a policy document
v PolicyModifier role to modify a policy document
2. From the Domino Administrator, click the People & Groups tab, and then open the Policies view.
3. Click Add Policy.
4. Under Basics, complete these fields:

Field Action
Policy name Enter one:
v A unique name, for an explicit policy.
v The name of the organization or organizational unit, such as Acme or
Sales/Acme
v The name of the hosted organization
Note: To create a policy for all hosted organizations in the Domino Directory, do
not enter a policy name. By default Domino will enter the asterisk for you.
Policy type Choose one:
v Explicit -- to create a policy to assign to specific users and groups.
v Organizational -- to create a policy that is automatically assigned to all users in
the part of the organization specified in the Policy name field.
Description Enter a description of the policy.

5. (Optional) Click Create Child to create a child policy document that includes the name of the parent
policy. You can save the child policy document and return to it at a later time. When you close this
document you return to the parent policy document.
6. To specify the policy settings documents to include in this policy, for each type of settings do one:

Chapter 11. Using Policies 349

 v Select a policy settings document from the list.
v Click ″New″ to create a new policy settings document. Then, after you create the policy settings
document, select it from the list.

Note: If the name of the new policy settings document does not appear as a selection, you may
need to refresh. Press F9)
7. (Optional) To create an exception policy, click the Administration tab and enable ″Exception Policy.″
CAUTION:
Be cautious when creating an exception policy. An exception policy allows a user to override
enforced policy settings.
8. Save the document.
For more information on exception policies, see the topic ″Organizational and explicit policies,″ earlier
in this chapter.

Creating a child policy document

When you create a child policy, you use a Policy document to specify which policy settings documents to
include.

In explicit policies, you create a child policy by setting up the child/parent name structure. For example,
the policy /Contractors may have a child policy called /Short term/Contractors.

In organization policies, child policies follow the hierarchy of the organization. So the child of */Acme is
*/Sales/Acme.

To create a child policy:

1. Make sure that you have Editor access to the Domino Directory and one of these roles:
v PolicyCreator role to create a policy document
v PolicyModifier role to modify a policy document
2. From the Domino Administrator, click the People & Groups tab, and then open the Policies view.
3. Select the name of the policy for whom you want to create a child policy and click Edit Policy.
4. Under Basics, click Create Child.
5. In the Policy Name field do one:
v Organizational policy -- enter the name of the organizational unit, followed by the Organization or
the Organizational unit that displays in the Parent Policy field. For example, if */Acme is in the
Parent policy field and you want to create a child policy for the Sales/Acme organization unit,
enter Sales/Acme. When the policy is saved, the name will be */Sales/Acme.
v Explicit policy -- enter a name for the child policy followed by the text that displays in the Parent
policy field. For example, if the Parent policy field is /Contractors and you want to create a child
named Short term, enter Short term/Contractors. When the policy is saved the name will be /Short
term/Contractors.
6. Complete the remaining fields using the same procedure you used to create a policy document.

Managing policies
To manage policies, you can do any of the following:
v Edit policies
v Delete policies
v Create a report of the effective policy
v View policy relationships
v Assign an explicit policy or change a policy assignment
v Preventing replication of policies to pre-Domino release 4.67a servers

350 Lotus Domino Administrator 7 Help

Editing policies
Use this procedure to edit existing policy and policy settings documents. Although you can delete a
policy from the Domino Directory, you must use the Policy - Delete tool on the Configuration tab to
remove all occurrences of the policy and its settings.
1. Make sure that you have at least Editor access to the Domino Directory and the PolicyModifier role.
2. From the Domino Administrator, click the People & Groups tab.
3. Open the Domino Directory, and choose one of these views:
v Policies -- to edit a policy document.
v Settings -- to edit a policy settings document.
4. Open, edit, and then save the document.

Deleting policies
Use this procedure to delete policy and policy settings documents. This table describes the result of each
type of deletion:

Deletion
Explicit policy
Organizational policy
Settings document
Result
An Administration Process request searches the Person documents of all users in
the domain and deletes all references to the deleted policy.
Deletes the policy document from the Domino Directory. All settings documents
named in the deleted policy remain intact.
Deletes the settings document from the Domino Directory. Deletes references to
the policy settings document from all policy documents.

To delete a policy:
1. From the Domino Administrator, click the Configuration tab, and then open the Policies - Hierarchy
view.
2. Select the policy or settings document you want to delete.
3. Click Tools - Policies - Delete.
The policy tools are not available in the Web Administrator client. For more information on deleting
policies in the Web Administrator, see the chapter ″Setting up and Using Domino Administration
Tools.″

Using the Policy Synopsis tool to determine the effective policy

To determine the effective policy governing a selected user, use the Policy Synopsis tool to generate a
report that is written to the Policy Synopsis Results database (POLCYSYN.NSF).

Note: The policy tools are not available in the Web Administrator client.

To use the Policy Synopsis tool:

1. From the Domino Administrator, click the People & Groups tab.
2. Select the People view, and then select one or more users.
3. From the Tools pane, select Policy Synopsis.
4. Under Select Report Type choose one:
v Summary Only -- (default) to produce a report that lists the hierarchy of policy documents used to
derive the effective policy for the specified user.
v Detailed -- to produce a report that lists the hierarchy of policy documents of the effective policy
for the specified user, and includes the actual values, and the policy and policy settings documents
from which the value was derived. Then select the policy settings documents for which you want
details.
5. Under Results Database choose one:

Chapter 11. Using Policies 351

 v Append to this database -- (default) to add to the list of previous reports.
v Overwrite this database -- to remove reports in the database and write the new reports.
6. (Optional) Click Results Database to change the name or location of the results database. The default
is Policy Synopsis Database on local.
7. Click OK. When the Policy Synopsis Results database (POLCYSYN.NSF) opens, double-click the
report to open it.

Viewing policy relationships

The policy viewer is a convenient tool you can use to view each policy, the settings associated with each
policy, and how they relate to each other. The policy viewer is also versatile because of the number of
ways in which you can view policy documents. For example, you can view the settings for each policy,
the settings by functional area, or the settings assigned to a specific users. You can also view effective
policies on different levels in the policy hierarchy, which helps you to understand the impact of changing
a policy setting. You can view policy documents using one of two views, By Hierarchy and By Settings.

How to use the policy viewer: The policy viewer has three panes. Depending on your selection in the
top left pane, the results in the right top pane differ. The bottom pane always shows either an actual
policy settings document or an effective policy settings document, based on your selections in the top
two panes. You can edit a policy settings document in the policy viewer. You cannot edit an effective
policy because the settings are derived settings.

Example of using the By Settings view: The administrator at the Acme company wants to use the
policy viewer to:
v View all policy settings documents in a domain
v View all policies that use a selected policy settings document
v View and edit a policy settings document
v View the effective policy settings

To view this information the administrator performs these tasks:

v Selects the By Settings view in the policy viewer and looks in the upper left pane to view all policy
settings documents, grouped by administrative area.
v Selects one of the policy settings in the upper left pane. All policies that use that policy settings
document display in the upper right pane. The actual policy settings document displays in the bottom
pane, where it can be edited.
v In the top right pane, selects one of the policies. The effective policy settings display in the bottom
pane. These cannot be edited.

Example of using the By Hierarchy view: The administrator at the Acme company wants to use the
policy viewer to:
v View the policy hierarchy for the Acme domain
v View the policy hierarchy for a Notes user in the Acme domain
v View the settings documents used by each policy
v View the differences between the effective policy and the policy settings for a policy settings document

To view this information the administrator performs these tasks:

v Selects the By Hierarchy view in the policy viewer and in the field ″Show policy hierarchy for,″ selects
Acme domain. Looks in the upper left pane to view the policy hierarchy.
v In the field ″Show policy hierarchy for,″ selects ″Specific User,″ and then selects the name of a user to
view the user’s policy hierarchy in the upper left pane.
v Selects a policy in the left pane to view the policy settings documents used by the selected policy in
the upper right pane.

352 Lotus Domino Administrator 7 Help

v In the top right pane, selects one of the policy settings documents. The administrator can switch from
the effective policy settings to the actual policy settings document in the bottom pane.
v To see how changing a policy setting affects the effective policy, the administrator can edit the policy
settings document and then switch views in the bottom pane.

Using the policy viewer: You use the policy viewer to view the relationships of policies and policy
settings documents in a policy hierarchy.

By Settings view:
1. From the Domino Administrator, click the Configuration tab.
2. Open the Policies view, and then select the By Settings view.
3. Choose any of the following tasks:

Task
View a list of all policy settings documents in your
domain
View a list of all policies that use a policy settings
document (display in the right pane)
View and edit a policy settings document
View the effective policy settings for a functional area
(displays in the bottom pane)
Action
Expand the functional areas in the left pane.
1. In the left pane, select a policy settings document.
2. View the policies that use that policy settings
document display in the right pane.
1. Select a policy settings document in the left pane.
2. The selected policy settings document displays in
bottom pane. Double-click the document to edit it.
1. Select a policy settings document in the left pane.
2. Select a policy document that uses those settings in
the right pane.
3. View the effective policy in the bottom pane.

By hierarchy view:
1. From the Domino Administrator, click the Configuration tab.
2. Open the Policies view, and then select the By Hierarchy view.
3. Choose any of the following tasks:

Task
View the policy hierarchy for the a domain
View the policy hierarchy for a Notes user
View the settings documents used by each policy
Action
1. In the field ″Show policy hierarchy for,″ select a
domain.
2. View the domain’s policy hierarchy in the upper left
pane.
1. In the field ″Show policy hierarchy for,″ select
Specific User, and then select the name of a Notes
user.
2. View the policy hierarchy for the user in the upper
left pane
1. Select a policy in the left pane.
2. View the policy settings documents used by the
selected policy in the upper right pane.

Chapter 11. Using Policies 353

Task Action
View the differences between the effective policy and the 1. In the top right pane, selects a policy settings
policy settings for a policy settings document document and make any changes to the settings.
2. In the bottom pane choose one of the ″Show″ options
to view either the effective policy settings or the
actual policy settings document.

Assigning an explicit policy

You assign explicit policies manually in one of three ways, during user registration, using the Assign
Policy tool, or in the person document. If your policies include setup and registration settings, assign
them during user registration so that you can take advantage of these settings.

Use the Assign Policy tool to apply explicit policies to existing Notes users or to groups, or to change the
assignment from one explicit policy to another.

Note: The Assign Policy tool is not available in the Web Administrator.

You can also add, change, or remove an explicit policy assignment to an individual Notes user in the
Person document. All changes to policy assignments are recorded in the log file (LOG.NSF).

Assigning explicit policies in the Person document: You can assign or change a user’s explicit policies
in the Person document. Changes to the Desktop, Security, or Archive policy settings that are associated
with an explicit policy can be distributed this way. Changes to a user’s settings that were previously
defined using Registration and Setup policy settings are not made retroactively, so you would need to
make any changes to those settings manually in the Person document. For example, roaming user
settings can be defined in a Registration policy setting document. But you cannot change a user’s
roaming user status by changing the Registration policy setting document for that user.

Assigning explicit policies using the Assign Policy tool: You can assign an explicit policy to a user or
group, or you can change the explicit policy assignment using the Assign Policy tool. Use this tool when
you want to make changes to multiple users or groups. You can distribute changes to the Desktop,
Security, or Archive policy settings that are defined in explicit policies using this tool. When you change
the explicit policy for a user or group using this tool, you have the option of viewing the way the policy
assignment change impacts the effective policy for that user or group.

From the Person document:

1. Make sure that you have at least Editor access to the Domino Directory or that you have Author
access with the UserModifer role.
2. From the Domino Administrator, click the People & Groups tab, and then open the People view.
3. Select the name of the person whose policy assignment you want to change, and click ″Edit Person.″
4. In the Person document, click the Administration tab.
5. Under Policy Management, in the Assigned policy field, do one:
v To assign or change an explicit policy assignment, select a policy from the list.
v To remove an explicit policy assignment, select the name of the explicit policy and delete it.
6. Save the document.

From the Assign Policy tool:

1. Make sure that you have at least Editor access to the Domino Directory and the ObjectModifier role.
2. From the Domino Administrator, click the People & Groups tab.
3. Do one:
v Open the People view, select one or more users, and then from the Tools pane, click People.

354 Lotus Domino Administrator 7 Help

 v Open the Groups view, select one or more groups, and then from the Tools pane, click Groups.
4. Choose Assign Policy.
5. For the field ″Allow replacement of an existing policy,″ do one:
v Check this option to replace an existing explicit policy with a new one.
v This option is not available if the selected user or if no users in the selected group have an explicit
policy currently assigned.
6. In the Policy field, select the explicit policy you want to assign from the list.
7. Check the ″Perform updates in background″ option when you are assigning policies to a large number
of users.
8. (Optional) Click ″View policy synopsis″ to see the new effective policy.
9. In the ″Choose Organizational Policy″ dialog box, choose the organizational policy you want to
combine with the explicit policy to create the new effective policy.
The policy tools are not available in the Web Administrator client. For more information on deleting
policies in the Web Administrator, see the chapter ″Setting up and Using Domino Administration
Tools.″

Preventing replication of policies to pre-Domino release 4.67a servers

Policy documents replicating from a Domino 6 or newer server to a server earlier than Domino Release
4.67a can produce the error ″Database has too many unique field names″ repeatedly upon replication.

A readers field ($PolRdrs) has been added to each of the policy forms in the Domino Directory. This field
is blank by default, allowing all entities within a domain to have read access to the documents.
Additionally, a new role, [PolicyReader], has been added to the ACL of the Domino Directory. To
effectively stop the flow of policy documents to servers at levels earlier than 4.67a, complete these two
steps:
1. Using Designer, open the Policy forms, set the default value of the $PolRdrs fields to [PolicyReader]
role.
2. Assign the [PolicyReader] role to all entities (Servers, Administrators, etc.) within a domain that need
to keep reader access to policy documents. Pre-Domino release 4.67a entities do not need reader
access to policy documents.

For information on using Domino Designer, see the Lotus Domino Designer 7 printed documentation or
the Lotus Domino Designer 7 Help Database.

Chapter 11. Using Policies 355

356 Lotus Domino Administrator 7 Help
Chapter 12. Setting Up Domain Search
This chapter describes how to set up Domain Search, which Lotus Notes or Web users can use to search
an entire Domino domain for documents, files, and attachments from a centralized server.

Domain Search
Notes and Web users can use Domain Search to search an entire Domino domain for database
documents, files, and attachments that match a search query.

To support Domain Search, you need to designate a Domino server as the indexing server, which builds a
domain wide index that all Domain Search queries run against. In order for the indexing server to build
the index, you must first create a Domain Catalog on the server -- a database that controls which
databases and file systems get indexed. The indexing server then spiders, or crawls, the servers that
contain the content to be indexed.

When a user submits a query, the results that the indexing server returns contain only database
documents to which that user has appropriate access.

If the indexing server is set up as a Domino Web server, it can support searches from both Lotus Notes
and Web browsers.

Support for multiple languages

With Domain Search, you can index and search on documents regardless of their language. Even
multiple-language documents can be indexed.

If users choose to display document summaries in their search results, Domain Search cannot create these
summaries in all languages. You can use the NOTES.INI setting FT_Summ_Default_Language to specify
which language the summary should default to in these cases.

For more information, see the appendix ″NOTES.INI File.″

Domain Search and single-database full-text search

Single-database full-text indexing and domain indexing are distinct processes in Lotus Notes/Domino,
and most likely you will want to use both.

Use Domain Search for less active databases such as archives and product specifications. Use full-text
indexes for single databases for active databases such as mail files, discussion databases,
problem-tracking databases, or any database used for generating reports. You might also want to have
single-database full-text indexes on servers with restricted user access, or in cases where users already
know what database they want to search in.

For information on setting up full-text indexes for single databases, see the chapter ″Setting Up and
Managing Full-text Indexes.″

Implementing Domain Search

Implementing Domain Search in a Domino domain involves these major tasks:
v Planning the Domain Index
v Creating the Domain Index
v Customizing Domain Search forms

357
v Setting up Notes users for Domain Search
v Setting up Web users for Domain Search

Server configurations for Domain Search

This topic describes required and optional configurations for the servers you use for Domain Search.

Configuration for the Domain Catalog

It is best to set up the Domain Catalog on the same server that indexes the Domino domain. If you have
a very large number of databases to catalog, you can decrease network traffic by running the Catalog task
nightly on all servers. That way, when the Catalog task runs on the server that contains the Domain
Catalog, the Domain Catalog uses pull replication from the local catalogs rather than spiders every
database.

You can shorten the time it takes to run the Catalog task by splitting it among several servers: Server A
catalogs servers 1 to 25, Server B catalogs servers 26 to 50, Server C catalogs servers 51 to 75, and so on.
You can also limit the scope of the Domain Catalog by using the ″Limit domain cataloging to the
following servers″ field.

Configurations for the Domain Index

The indexing server must be capable of handling the load of creating indexes and handling user queries.
The indexing server should be fast, powerful, and have a large amount of disk space. Multiple
processors, a large amount of RAM, and multiple high-volume drives will increase the efficiency and
capabilities of searches.

For indexing servers running Windows 2000/2003, the following minimum configuration is required:
v An Intel Pentium II 350MHz processor
v 256MB RAM
v Free disk space equal to approximately 30 percent of the size of the data being indexed
For information on estimating the size of the data to be indexed, see the topic ″Estimating the size of
the Domain Index″ later in this chapter.

If your organization has more than six Domino servers, dedicating one server as the indexing server
provides optimal performance.

Consider clustering indexing servers to ensure greater reliability and fault-tolerance and to balance the
load from user queries. If you use clustered indexing servers, create a replica of the Domain Catalog on
each of those clustered servers.

Domain Search over a WAN

If your organization is geographically dispersed, cataloging databases over a WAN is the only way that
different locations can share a single Domain Index. The cataloging server should access the WAN
directly rather than through a hub server, because cataloging uses large amounts of processing resources.

To index data in different locations, you can choose to replicate all databases to be indexed to servers in
the same location as the indexing server, thus eliminating the need for the indexing server to spider over
the WAN. The servers containing the databases to be indexed should be ones with fast LAN connections.
Even within the same location, databases on servers with slow LAN connections should be replicated to
ones with fast connections.

358 Lotus Domino Administrator 7 Help

Tip: You can use replication events in the Notes Log as a guide for determining which servers have fast
connections by looking at the information for the Domain Catalog database (CATALOG.NSF). Determine
which servers the Catalog was able to do pull replication with in an average time of less than 1 minute.

Reset the ″Include in multi database index″ database property for each replica on the servers to be
indexed, because this setting does not always replicate.

When you create the Domain Index, use the ″Limit domain wide indexing to the following servers″ field
to limit indexing to these servers.

Planning the Domain Index

Because the initial process of spidering databases and file systems and creating a full-text index for an
entire Domino domain can take days or even weeks, it is important to plan carefully before starting the
indexing server. The more you have thought about what data sources should be indexed, how they
should be categorized in the Domain Catalog and search form, and how much space your Domain Index
requires, the less work you will have to do.

Note: Indexing unnecessary databases causes users’ search results to be less meaningful, takes up space
on the server, and adds time to the indexing process, which indexes about 700MB to 1GB of information
per hour, depending on hardware and the content being indexed. At a minimum, avoid indexing the
following types of databases: Administration Requests databases, database catalogs, database libraries,
Event message databases, log databases, mail databases, portfolio databases, and server statistics
databases.

Here is a methodology for planning the Domain Index.

1. Use the Domain Catalog to control settings for which databases to index.
2. (Optional) Use the Domain Catalog to control settings for which file systems to index.
3. (Optional) Estimate the size of the Domain Index.
4. (Optional) Prevent attachments from being indexed.
5. Use the Domino Administrator to assign each database to be indexed to one or more categories in the
Domain Catalog and the search form.
6. Analyze any security issues that implementing Domain Search in your organization might raise.

The Domain Catalog

The Domain Catalog, a database that uses the CATALOG.NTF template, controls which databases and file
systems get indexed for Domain Search. Even if your organization is not implementing Domain Search,
the Domain Catalog is a useful administrative tool for such tasks as keeping track of the location of
database replicas.

You create the Domain Catalog by enabling the Catalog task on the server that will index the Domino
domain.

The portions of the Domain Catalog of interest to the Domain Search administrator are those that indicate
which databases and file systems the indexing server will include in the Domain Index, as well as the
forms used to search the index. Database designers and managers select a database for indexing by
enabling the database property ″Include in multi database indexing.″ (Administrators can configure this
setting for multiple databases using the Domino Administrator.) These settings are saved to the Domain
Catalog when the Catalog tasks runs. Administrators can also control which databases are included in the
Domain Index by customizing the selection formula for a hidden view ($MultiDbIndex) in the Domain
Catalog.

Administrators specify which file systems to index by adding a File System document to the Domain
Catalog for each file system on a server.

Chapter 12. Setting Up Domain Search 359

Because the Catalog task creates the Domain Catalog by using pull replication of the database catalogs on
individual servers, updating the Domain Catalog is usually not a lengthy process if you have already
created a database catalog on every server. What can be time consuming, however, is rebuilding the
views in the Domain Catalog after an update.

For more information on creating database catalogs, see the chapter ″Setting Up Database Libraries and
Catalogs.″ For more information on rebuilding views, see the chapter ″Maintaining Databases.″

Domain Catalog views

The Domain Catalog’s views provide information about the databases, servers, and users in the Domino
domain.

View Displays
Access control lists ACL information by Database, Level, and Name. Use this view to see who has what
level of access to the different databases in the domain.
Content Documents in the domain by Author, Category, and Date (if your organization has
implemented document content categories).
Databases Databases in the domain by Category, Hierarchy, Replica ID, Server, and Title.
Domain Indexer Status Last-time indexed for databases included in the Domain Index, by both Server and
Indexing Server.
File Systems File systems and servers included in the Domain Catalog.

Hidden views
You can display hidden views in the Domain Catalog by holding down CTRL-SHIFT as you open the
Catalog. Server tasks use hidden views to access information quickly. The hidden views $MultiDbIndex
and $FileSystem are the work queues for the Domain Indexer task. These views show which databases
and file systems will be spidered to create the Domain Index. The $MultiDbIndex view is sorted by
replica ID, number of documents in the replica, and server to ensure that the most recent replica (the one
containing the greatest number of documents) is the one included in the Domain Index.

Creating the Domain Catalog

You create the Domain Catalog by enabling the Catalog task on the server that hosts the Catalog for the
Domino domain. The Catalog task uses pull replication to create the Domain Catalog from the individual
catalogs you have created on servers throughout the Domino domain. You can replicate the Domain
Catalog to other Domain Catalog servers (such as those in a cluster).
1. From the Domino Administrator, select the server that you want to contain the Domain Catalog.
2. Click the Configuration tab.
3. Expand the Server section in the view pane.
4. Click Current Server Document.
5. Click Edit Server, and then click the Server Tasks - Domain Catalog tab.
6. In the Domain Catalog field, select Enabled.
7. Click OK.
8. To change the scope of the Domain Catalog, select the servers that you want to include in the ″Limit
domain cataloging to the following servers″ field. Use wildcard characters to index all servers
certified with a specific certifier -- for example */Sales/East/Acme. If the field is blank (default), all
servers in the domain are cataloged.

Tip: Use this field to limit the scope of the Domain Catalog to regional locations or to expand its
scope to multiple Domino domains by cataloging multiple Domain Catalog servers.
9. Click ″Save and Close.″

360 Lotus Domino Administrator 7 Help

10. Make sure the Catalog task is included in the ServerTasksAt1 setting in the server’s NOTES.INI file,
or use another method (start the Catalog task at the console or create a Program document) to run
the task.

When the Catalog task starts for the first time, Domino creates the Domain Catalog database based on the
CATALOG.NTF template and adds entries to the ACL so the database replicates properly within the
domain. The Administration Process creates the group LocalDomainCatalogServers in the Domino
Directory and adds the server that contains the Domain Catalog to that group.

Selecting which databases to include in the Domain Index

The indexing server spiders databases that have the option ″Include in multi database indexing″ selected
on the Design tab of the Database Properties box.

Begin by using the hidden view $MultiDbIndex in the Domain Catalog to see which databases have
already been selected to be included in the Index by database managers. If you see databases in the view
that should not be in your Domain Index, such as personal mail databases or databases of limited
interest, or if important databases are missing from the view, either customize the $MultiDbIndex view’s
selection formula or use the Domino Administrator to include or exclude databases.

Using $MultiDbIndex to view which databases will be indexed:

1. From the Domino Administrator, choose File - Database - Open.
2. Select the cataloging server for the domain, and then select Domain Catalog.
3. Hold down CTRL-SHIFT and click Open.
The Domain Catalog opens and displays its hidden views.
4. In the view pane, click $MultiDbIndex.
The view displays the replica ID of each database that will be included in the Domain Index, followed
by a line of information about each replica.

Note: If multiple replicas of a database were selected for indexing, Domain Search selects the replica
containing the greatest number of documents.

Using $MultiDbIndex to change which databases will be indexed: Customizing the selection formula
for the $MultiDbIndex view is the simplest and best way to control which databases are included in the
Domain Index.

The following is an example of a custom selection formula. In this example, the indexing server will
ignore ″Include in multi database indexing″ settings and index only databases in the smoketestdata
directory on servers that contain ″hub″ in the server name.
SELECT @IsAvailable(ReplicaID) & @IsUnavailable(RepositoryType) & @Contains((pathname); "smoketestdata") & @Contains((ser

Using Domino Administrator to change which databases will be indexed: You can use the Domino
Administrator to select or deselect the ″Include in multi database indexing″ option on multiple databases
at the same time.
1. From the Domino Administrator, select the server that contains the databases you want to include in
or exclude from the Domain Index.
2. Click the Files tab.
3. Make sure you have Manager access in the ACL for each database you want to include or exclude.

Tip: On the Files tab, you can right-click a database and choose Access Control - Manage to display
its ACL.

Note: If you want to include databases whose ACLs restrict default access, make sure that the
LocalDomainServers or LocalDomainCatalogServers group has at least Reader access to each database
you want to include.

Chapter 12. Setting Up Domain Search 361

4. Select the databases you want to include or exclude.

Note: If you plan to limit the servers to be indexed and have placed replicas on those servers, you
might need to select those replicas now, even if the ″Include in multi database index″ database
property was set in the original databases, because this setting does not always replicate.
5. In the Tools pane on the right, select Database - Multi-Database Index.
6. Select Enable or Disable.
7. Click OK.
8. Assign categories for each database that you included.
For information on assigning categories, see the topic ″Assigning database categories for the Domain
Search form″ later in this chapter.

Selecting which file systems to include in the Domain Index

For each server in a domain, you can create a File System document in the Domain Catalog to specify
which file system directories to include in the Domain Index. You can index any file system that resides
on the indexing server or on a network resource mapped to that server, as long as the server has at least
Read access to the file system.

For file system searches, the indexing server must also be set up as a Domino Web server. This allows the
server to return links to documents in the file system and to return those documents in response to
queries from both Notes and Web clients.

For information on setting up a Web server, see the chapter ″Setting Up the Domino Web Server.″

CAUTION:
Domain Search filtering of results to users based on access works only with Domino databases.

For more information on file system security and Domain Search, see the topic ″Domain Search security″
later in this chapter.

To select which file systems to include: Add a reference to each file system in the File System
document, and then map the URL path to the file system directory so that the Domino Web server can
retrieve the found documents for users. Complete the following steps for each server that has file systems
you want to index.
1. Start the Domino Administrator or Notes client.
2. Choose File - Database - Open.
3. In the Server field, select the server that contains the Domain Catalog.
4. Select the Domain Catalog and click Open.
5. In the view pane, click File Systems.
6. Click ″Add File System.″
7. Select the server that contains the file system you want to index.
8. Beside the ″Current file system list″ box, click Add.
9. In the Add File System dialog box, enter the location of a file system to include, for example
c:\lotus\domino\data\files.
10. Enter a keyword, such as ″files,″ to associate with the file system. You need to use this keyword in
Step 14, as the portion of the incoming URL pattern that follows the forward slash (/).
11. Click OK to add the file system to the list.
12. Repeat Steps 8 through 11 to add more file systems to the list.
13. When you have completed the list, click ″Save and Close.″
14. Create a Web Site Rule document for the Web site for this file system. This step is needed to map the
incoming URL pattern to the file system directory on the target server.

362 Lotus Domino Administrator 7 Help

 For more information, see the chapter ″Setting Up the Domino Web Server.″
15. Restart the server, or enter this command at the server console so that the mapping settings take
effect:
tell http restart

Assigning database categories for the Domain Search form

On the Design tab of the Database Properties box, you can assign one or more categories to each database
to be included in the Domain Index. These categories appear on the 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. You must have Manager access to a database to create the categories.

Note: Searching within categories is supported only for Domino databases. Whenever a user specifies a
category on the search form, search results will not include any documents from file systems.

Use the Categories view in the Domain Catalog to see whether database managers have assigned
databases to appropriate categories. To edit or add categories, use Database Properties for each database.

To view the search categories

1. Open the Domain Catalog.
2. In the view pane, click Databases and then click By Categories to view a list of categories.
3. To see information on the databases that have been included in each category, select View - Expand
All.

To add or change search categories

1. From the Domino Administrator, select the server that contains the databases to which you want to
assign categories.
2. Click the Files tab.
3. Make sure you have Manager access in the ACL for each database to which you want to assign a
category.

Tip: On the Files tab, you can right-click a database and choose Access Control - Manage to display
its ACL.
4. Select the database that you want to categorize.
5. Choose File - Database - Properties.
6. Click the Design tab.
7. Make sure ″List in Database Catalog″ is selected.
8. In the Categories box, enter one or more categories for the database.
Separate category names with a comma.

Estimating the size of the Domain Index

The size of a Domain Index is related to the size of the data being indexed, not to the size of the database.
A small database with a lot of text can generate a larger index than a large database that has a lot of
design elements. There is no easy way to measure the data in a database, but you can use a percentage of
database size to estimate the size of the Domain Index.

You can use the hidden view $MultiDbIndex in the Domain Catalog to find the sizes of all databases
selected for indexing. You can also use this view to find out which of these databases have already been
indexed individually by their database managers -- and use full-text index size as a more accurate
indicator of the space a database will take up in the Domain Index.
1. From the Domino Administrator, choose File - Database - Open.
2. Select the cataloging server for the domain, and then select Domain Catalog.

Chapter 12. Setting Up Domain Search 363

3. Hold down CTRL-SHIFT and click Open.
4. In the view pane, click ($MultiDbIndex).
5. For each database listed, double-click the database entry to display the Database Entry document.

Note: If more than one replica of a database is listed, the indexing server indexes the replica on the
server you include in the ″Limit domain wide indexing to the following servers″ field when you
create the index. If this field is blank, the indexing server indexes the replica with the greatest number
of documents.
6. Do one of the following for each database set to be part of the Domain Index:
v If there is a value in the ″Number of bytes indexed″ field on the Full Text tab, record it.
v If there is no value in the ″Number of bytes indexed″ field, record a number between 20 and 40
percent of the value in the Database size field on the Database tab. Record 20 percent if the
database is heavy on design, 40 percent if it is heavy on text.
7. Add the values from Step 6 to obtain an estimate of the Domain Index in bytes.

Tip: To convert your estimate to megabytes, divide by 1024 twice.

Excluding attachments from the Domain Index

The following types of attachments are excluded from the Domain Index by default: .au, .cca, .dbd, .dll,
.exe, .gif, .img, .jpg, .mp3, .mpg, .mov, .nsf, .ntf, .p7m, .p7s, .pag, .sys, .tar, .tif, .wav, .wpl, .zip.

To exclude all other types of document attachments, set the following NOTES.INI variable for the
indexing server: FT_Index_Attachments=2

Domain Search security

When a user performs a Domain Search on Domino databases, Domain Search checks each result against
the ACL of the database in which the result was found to verify that the user has access to read the
document. To perform this check, the Domain Catalog contains a listing for all databases that includes
each database’s ACL. For Domino to include a link to a result document in a user’s result set, the user
must have the necessary access to read the document -- that is, have at least Reader access to the
database that includes the document and be included in the Readers field, if the document has one. The
security check works as follows:
1. Domino checks the -Default- entry in the database access control list.
v If the -Default- entry has Reader access or greater, the user can read the document, and Domino
returns the result in the result set.
v If the -Default- entry has less than Reader access, Domino checks whether the user has Reader
access or greater in the ACL. If not, Domino does not include the document in the result set
because the user is not authorized to read that document.
2. If the user has Reader access or greater, Domino checks whether the result document has a Readers
field.
v If the result document does not have a Readers field, the user can read the document, and Domino
returns the result in the result set.
v If the result document has a Readers field, Domino checks whether the user is included in the
Readers field. If not, Domino does not include the document in the result set because the user is
not authorized to read that document.
v If the user is included in the Readers field, the user can read the document, and Domino returns
the result in the result set.

364 Lotus Domino Administrator 7 Help

CAUTION:
The security checking works only for search results from Domino databases. Results from file system
searches depend on file system security -- users see the search result even if they are not authorized to
view the document. Thus, users may not be able to access all search results or they might be able to
discern confidential information from the existence of a particular search result. Be sure to set file
system security properly and index only file systems for which security is not a high priority.

Tip: If you want to index file systems for which security is a high priority, you can attach the files to
Notes documents in a database selected for indexing.

Search security and server access lists

If you use server access lists within a domain to limit access to information, you might need to check the
ACLs of databases on those servers to ensure that results are filtered. Otherwise, a search might return a
result to a user who cannot access the result document. In some cases, users might be able to discern
confidential information from a search result.

For example, the Acme corporation has two application servers, App-E/East/Acme and
App-W/West/Acme. Acme users are certified with one of two organizational unit certifiers: /East/Acme
or /West/Acme. App-E/East/Acme does not allow access to any user with a /West/Acme certificate.
Databases on the server have the -Default- setting in their ACLs set to Reader to ensure that /West/Acme
users cannot access those databases.

When Acme implements Domain Search, /West/Acme users who query Domain Search might receive
search results that include links to and summaries of documents in databases on App-E/East/Acme,
because the ACLs of those databases do not prohibit /West/Acme users from seeing those results. (On
Windows systems, document summaries are included in the search results if users select the Detailed
Results option.) The server access lists continue to maintain database security in this environment,
because /West/Acme users cannot access documents from those links, but the mere existence of links
and summaries could reveal confidential information to the /West/Acme users.

To avoid this issue, check the ACLs for databases that are protected by server access lists to ensure that
they are set to filter correctly. To do this, assume that the server access list does not exist. Change the
ACL so that, in the absence of a server access list, the database would be secured appropriately. This
ensures that when Domain Search checks the database ACL, it filters out results that users cannot access.

If you are running Domino on Windows and are not sure that you can properly maintain database ACLs,
you might want to prevent anyone from seeing document summaries by setting the indexing server’s
NOTES.INI variable to FTG_No_Summary=1.

Note: This example assumes that the indexing server has a certificate that allows access to both
App-E/East/Acme and App-W/West/Acme.

Creating and updating the Domain Index

The indexing server relies on the Domain Catalog to tell it which databases and file systems to include in
the Domain Index. You use the Server document to enable the Domain Indexer task and set a schedule
for it to run. By default, the Domain Indexer task runs once an hour.

To set the Domain Indexer task

1. If you have Web clients, make sure you have set up the indexing server, as well as each server to be
spidered by the indexer, as a Domino Web server.
For more information on setting up a Domino Web server, see the chapter ″Setting Up the Domino
Web Server.″
2. Make sure you have created the Domain Catalog on the indexing server.
For more information, see the topic ″The Domain Catalog″ earlier in this chapter.

Chapter 12. Setting Up Domain Search 365

 Note: The Catalog task that creates the Domain Catalog must have finished before you start the
Domain Indexer task.
3. From the Domino Administrator, select the server that you want to be the indexing server.
4. Click the Configuration tab.
5. Expand the Server section in the view pane.
6. Click Current Server Document.
7. Click ″Edit Server,″ and then click the Server Tasks - Domain Indexer tab.
8. In the Schedule field, select Enabled.
9. Click OK.
10. Set the indexing schedule to meet the needs of your organization.
11. Select the servers that you want to include in the index in the ″Limit domain wide indexing to the
following servers″ field. Use wildcard characters to index all servers certified with a specific certifier
-- for example */Sales/East/Acme. If the field is blank (default), the Domain Indexer indexes all
databases for which the ″Include in multi database indexing″ property is enabled.
12. If you have Web clients, do the following to allow the indexing server to form valid URLs when the
results of a search are displayed in a browser:
a. Click the Internet Protocols - HTTP tab.
b. For the host name, enter the fully qualified name of the computer that serves as the indexing
server, for example, servername.acme.com.
c. Click the Domino Web Engine tab.
d. Under Generating References to this Server, enter the information for the indexing server. Make
sure you use the server’s fully qualified domain name in the Host name field.
e. Under Conversion/Display, in the ″Redirect to resolve external links″ field, select ″By Database.″
Selecting ″By Database″ allows the indexing server to resolve more URLs for users. If the indexing
server can’t resolve the database link in a URL, it checks with the Domain Catalog to locate a replica
of the database.
13. Click ″Save and Close.″
14. Restart the server by entering this command:
restart server
The Domain Indexer runs when next scheduled.

Note: The indexing server must complete the initial indexing pass before users can perform searches.
Check the Domain Indexer Status view in the Domain Catalog to be sure the initial pass is complete.

Tuning Domain Indexer performance

Each time the Domain Indexer task runs, it looks in the Domain Catalog for new databases that have the
″Include in multi database indexing″ property enabled. It then looks for documents and files in existing
databases and file systems that are new or changed since the last time it ran, and adds them to the
Domain Index.

To meet the specific needs of your organization, adjust the frequency with which the Domain Indexer
runs. Greater frequency results in more up-to-date indexes, but consumes greater CPU resources. By
default, the Domain Indexer task runs every 60 minutes. Experiment with different indexing frequencies
to yield the best results for your organization.

You can also enhance search performance by tuning the number of indexing threads used by Domain
Search. Each indexing thread indexes one repository at a time. With a greater number of threads, the
indexing server can index more databases simultaneously, but this requires more CPU utilization, and
response to search queries may be slow. With fewer indexing threads, response to queries is faster
because of greater CPU availability, but changes are not reflected in the index as quickly.

366 Lotus Domino Administrator 7 Help

By default, the indexing server uses two indexing threads per CPU, so a server with two CPUs uses four
indexing threads when indexing. By adding the variable FT_Domain_Idxthds=n to the NOTES.INI file of
the indexing server, you can control the total number of threads used for indexing on that server. For
example, by adding ″FT_Domain_Idxthds=8″ to the NOTES.INI file of an indexing server with two CPUs,
you change the number of indexing threads to eight.

Note: Do not exceed eight threads per server or you may degrade the performance of the server, even on
servers with more than four CPUs.

Changing the location of Domain Index files

By default Domain Index files are placed in a directory named FTDOMAIN.DI in the Domino data
directory of the indexing server. You can change the location of the Index files by specifying a different
directory in the following NOTES.INI setting:

FT_Domain_Directory_Name=directory

Deleting databases from the Domain Index

You must have Manager access to a database to delete it from the Domain Index.

The database will be deleted from the index after the next update has been performed by both the
Catalog task and the Domain Indexer task.
1. From the Domino Administrator, select the server that contains the databases that you want to delete
from the Domain Index.
2. Click the Files tab.
3. Make sure you have Manager access in the ACL for each database you want to delete.

Tip: On the Files tab, you can right-click a database and choose Access Control - Manage to display
its ACL.
4. Select the databases you want to delete.
5. In the Tools pane on the right, click Database and then select Multi-Database Index.
6. Select Disable.
7. Click OK.

Note: Removing a database from the Domain Catalog or deleting every copy of a database also has the
effect of deleting the database from the Domain Index.

Backing up the Domain Index and Catalog

Back up the Domain Index and the Domain Catalog as often as necessary to be useful to your
organization. Weekly backups are probably sufficient for most organizations.

Backing up the Domain Index

Make sure you back up the entire FTDOMAIN.DI subdirectory on the indexing server as soon as the
server has completed building the index for the first time.

CAUTION:
Before you back up the Domain Index, check the Domain Indexer Status view in the Domain Catalog
to make sure that the Domain Indexer task has finished -- if you attempt to back up the Domain
Index while the Domain Indexer task is running, catastrophic data loss can result.

Backing up the Domain Catalog

You can include the Domain Catalog (CATALOG.NSF) in the databases for transaction logging. However,
do not back up the Catalog while the Catalog task is running.

Chapter 12. Setting Up Domain Search 367

For more information on transaction logging, see the chapter ″Transaction Logging and Recovery.″

Customizing Domain Search forms

Domain Search includes several default forms, including forms for searching, specifying file systems, and
presenting results.

Both the search and results forms can be customized to suit organization-specific needs. An application
developer can, for example, add a corporate logo to either form, or rearrange the fields.

For more information on customizing search forms, see the book Application Development with Domino
Designer.

The developer can create additional search forms, and you can use setup policy settings (for new users)
or desktop policy settings (for existing users) to provide bookmarks to the new forms to users. For
example, users might use one form to search only Human Resources databases, or use another form to
store searches for future use. The bookmarks for search forms appear in the user’s More Bookmarks
folder.

For more information on using policy settings, see the chapter ″Using Policies.″

Results forms -- where do the document titles come from?

When viewing a Domain Search results form, it can be helpful to know where the Domain Indexer finds
the document titles that it displays in the results. The Indexer checks each document for the following
Notes fields or items that might represent the document’s title: Title, Subject, Headline, and Topic field;
window title (as designated by the developer of that Domino application); and view summary (using the
default form and default view). If the Indexer can’t find any of these items, ″Document has no title″ is
displayed in the results.

Note: Computing the window title for large numbers of documents requires CPU utilization. You can
omit this computation by adding the following setting in the indexing server’s NOTES.INI file:
FT_No_Compwintitle=1

In file systems such as IBM Lotus SmartSuite® or Microsoft® Office, the title and author are extracted
from the document properties fields. For HTML files, TITLE and AUTHOR tags are used.

Setting up Notes users for Domain Search

Notes users can perform domain searches as soon as you add the designated indexing server to the
″Catalog/Domain Search server″ field in their Location documents.

For information on how users perform domain searches, see Lotus Notes 7 Help.

Using Policies
After you set up a Domain Search server for a Domino domain, you can use policies to automate the
process of setting up Domain Search for new or existing Notes users in that domain. For new users,
record the name of the Domain Search server in setup policy settings; for existing users, record the
server’s name in desktop policy settings. Setup policy settings populate the new user’s Location
document at registration. Whenever existing users authenticate with their home server, Lotus Notes
checks desktop policy settings and updates the current Location document with the name of the Domain
Search server.

For more information on policy settings, see the chapter ″Using Policies.″

368 Lotus Domino Administrator 7 Help

Manual setup from a Notes workstation
The following circumstances require users to set up Domain Search at their workstations.
v A new user wants to do a domain search before the workstation has authenticated with its home
server.
v A user wants to be able to do domain searches from alternate Notes locations.
v A user wants to do a domain search in a Domino domain other than the one to which the user
belongs.

To perform the setup:

1. Start the Notes client.
2. Choose File - Mobile - Edit Current Location.
3. Do the following for each location for which you want to use Domain Search:
a. Click the Servers tab.
b. In the ″Catalog/domain search server″ field, enter the name of the indexing server.
c. Click Save and Close.

Note: If the user enters the name of the indexing server incorrectly or specifies a server that is not an
indexing server, Notes returns an error.

Tip: If users enter the name of an indexing server in a Domino domain other than their own but you
have included the name of their indexing server in the desktop policy settings applied to them, the
″Catalog/domain search server″ field reverts to the policy setting the next time the users authenticate
with their home server. To preserve links to an indexing server in another Domino domain, users can
bookmark the search form from that server while they are performing a search.

Setting up Web users for Domain Search

For Web users to have access to Domain Search functionality, the indexing server, as well as all the
servers being spidered by the indexer, must be set up as Domino Web servers.

For information on setting up a Domino Web server, see the chapter ″Setting Up the Domino Web
Server.″

When you are ready to roll out Domain Search to Web users, the Web application developer must add to
the site’s home page a link to the search form, which is contained in the Domain Catalog on the indexing
server.

To see for yourself what performing a domain search is like for a browser user, you can use a URL
command in your browser to simulate such a link. Enter the following command in your browser,
substituting the common name of your indexing server for servername:

http://servername/catalog.nsf/domainquery

When the search form displays, you can define your search. If you have properly configured the indexing
server and the servers holding the data, your search results display links that can be successfully
followed to each document found.

Using content maps with Domain Search

Content maps let users browse for information rather than search for it using full-text search. Content
maps organize documents by topics, or content, into categories that are similar to the categories on sites
such as AltaVista and Yahoo!

Chapter 12. Setting Up Domain Search 369

You can assign document content categories for documents in the Domain Catalog to organize
information in a content map.

To assign content categories

You can assign content categories to both Lotus Notes documents and Web URLs. You assign content
categories from a Lotus Notes client, and you must have Author access to the Domain Catalog database.
1. Start the Lotus Notes client.
2. Do one of the following:
v To categorize a Notes document, navigate to the document. You must have at least Editor access to
the document (or Author access if you created the document).
v To categorize a Web URL, make sure that the default browser in your Location document is set to
Lotus Notes. Then, in the Lotus Notes client, navigate to the Web page by clicking the Open URL
icon (top right) and entering the URL in the Address field.
3. Choose File - Document Properties.
4. Click the Meta tab (plus sign).
5. Do one of the following:
v To assign the document to an existing category, click Categorize, select one or more categories, and
click OK.
v To assign the document to a new category, type the category name in the Keywords field.
6. Click ″Post to Catalog.″

Note: If the ″Post to Catalog″ button is dimmed, try clicking another field on the Meta tab, or click
another tab and then return to the Meta tab, to enable it.
For a Lotus Notes document, click the ″Post to Catalog″ button to add content category information to
hidden meta fields in the document header and to add a content categories document for the
document to the Content by Category view in the Domain Catalog. For a Web URL, click this button
to add a content categories document for the URL to the Content by Category view in the Domain
Catalog.

To view content categories

The Domain Catalog displays content categories in the Content - By Category view.
1. Start the Lotus Notes client.
2. Click the arrow to the right of the search icon:
3. Choose Domain Search.
4. Click Browse Catalog.
5. In the view pane, click Content and then click By Category.
6. Expand the categories to display document and URL titles.
7. Double-click a document or URL title to open a link to the document or URL.

You can customize the Content by Category view to suit organization-specific needs.

For more information on customizing views, see the book Application Development with Domino Designer.

To change content categories

You change content categories by editing the DocContent Link documents in the Domain Catalog. You
must have Editor access to the Domain Catalog.
1. Start the Lotus Notes client.
2. Click the arrow to the right of the search icon.
3. Choose Domain Search.

370 Lotus Domino Administrator 7 Help

4. Click Browse Catalog.
5. In the view pane, click Content and then click By Category.
6. Expand the categories to display document or URL titles.
7. Select an entry to re-categorize and choose Actions - Edit Document.
This displays the DocContent Link document for the entry.
8. Specify a new category in the Keyword field.
9. Click ″Save and Close.″

Note: This procedure updates the category information for this entry in the Domain Catalog but does not
change the category information saved in the meta fields of the document itself.

Chapter 12. Setting Up Domain Search 371

372 Lotus Domino Administrator 7 Help
Chapter 13. Setting Up Domino Off-Line Services
This chapter explains how to enable an application to go offline with Domino Off-Line Services (DOLS),
and to administer DOLS applications on the Domino 7 server.

Domino Off-Line Services

Domino Off-Line Services (DOLS) provides a way for users to take IBM Lotus Domino 7 Web
applications offline, work in them, and synchronize the changes with an online replica on the Domino
server. Users are not required to have IBM Lotus Notes 7 client because the applications are accessed
with a browser.

Nearly all Notes functionality is retained when a DOLS-enabled application (called a subscription) is
taken offline. Users can compose, edit, delete, sort, and categorize Notes documents, and perform full-text
searches. DOLS subscriptions can make full use of Java applets, agent execution, and workflow. DOLS
also supports full data replication, retains application logic, and supports the full Notes security model.

The developer and administrator must set up and configure a DOLS subscription for offline use.

The developer copies a number of elements into the subscription, makes design changes if necessary, and
configures the subscription in the Offline Subscription Configuration Profile document.

The administrator makes sure DOLS is installed properly on the server, sets security for the subscription,
sets up agents, makes changes to the Offline Subscription Configuration Profile document if necessary,
and helps users install the subscription.

Once the subscription is enabled, users can access it on the server using a browser. The user clicks ″Go
Offline″ or ″Install Subscription″ from the Online menu on the subscription’s main page and the
subscription is installed on their computer.

Also installed on their computer is the Lotus Domino Sync Manager (previously the iNotes(TM) Sync
Manager), a utility for managing DOLS subscriptions. Users can open subscriptions online or offline,
synchronize, and set subscription properties with the Sync Manager.

For more information, see the following:

v Lotus Domino Sync Manager Help (available from the Help menu of the Lotus Domino Sync Manager)

Configuring the DOLS subscription

You choose configuration settings for the subscription in the Offline Subscription Configuration Profile
document. You must edit and save a configuration document in every subscription even if you make no
changes to the document. A subscription can have only one configuration document, even if the
subscription has multiple databases. The configuration document must be stored in the main database.
The main database is the database in the subscription from which the user downloads the subscription.

You can change configuration settings even after users have downloaded the subscription.

To edit the configuration document

1. Copy the appropriate design elements into the main database.
2. Open the database in Notes.

373
 3. Choose Actions - Edit Offline Configuration to open the document. Note that some of the fields have
default values, which you can change. You can use wild card characters in any field.
4. Click the Basics tab. The name of the main database should be in the ″Subscription title″ field. If it is
not, enter it.
5. Click the Services tab and fill in the following fields.

Name of Field Action

Domino services to install offline
v Basic services (required)
v Full-Text Indexing
v LotusScript and unscheduled agents
v Java classes and applets
v Custom Services
v MAPI enablement
v Default Language
Custom services to install offline
The offline subscription may need support for full-text indexing,
LotusScript and unscheduled agents (such as Web open), Java
back-end classes and applets, MAPI enablement, or custom services.
Select the appropriate boxes so that only files the users actually need
are downloaded to their machine.
MAPI enablement is available only when you use the Extended Mail
Template (MAIL6EX.NTF) for Web mail.
Choose a default language for the Web Control menu and the Domino
Sync Manager. Users can override this setting by selecting a different
language from the Web Control menu.
This field is available only when you select the ″Custom services″ box.

Enter the name of custom service files to be unpacked and executed on

the user’s computer during installation of the subscription. Custom
services have the following syntax: CustomServiceName [Setup.exe
[SetupArguments]]. For example:

mycustomname mysetupfile.exe -z -r -u

If you specify more than custom service, separate the services with
commas. For example:

mycustomname mysetupfile.exe -z -r -u, mycustomname2

mysetupfile2.exe -z -r -u

For more information on custom file sets, see the topic ″Creating
custom file sets for a DOLS subscription.″

6. Click the Schedule tab and complete the following fields. Note that the user can override most of
these fields from within the Subscription Properties box of the Domino Sync Manager.

Name of Field Action

Type of schedule
Daily Select this field, then specify the time of day you want synchronization
to occur.
Weekly Select this field, then check the days you want the synchronization to
occur.
Monthly Select this field, then specify the day of the month you want the
synchronization to occur.
Start time Enter the time of day for the subscription to start scheduled
synchronization.
Frequency
Repeating schedule Select this box if you want synchronization to repeat at certain
intervals after the initial start time.

374 Lotus Domino Administrator 7 Help

Name of Field Action
Interval Specify the time between repeating synchronizations. Enter a number
and then choose either minutes or hours. For example, you can enter
180 minutes or 3 hours.
Limitations
Stop synchronization at Specify the time you want the synchronization to stop.
Recurrence exceptions
Schedule disabled Select this box to make a disabled synchronization schedule the default
state. The subscription only synchronizes once, when it is installed.
The user can override this setting in the offline synchronization
properties.

7. Click the Sync Options tab and complete the following fields:

Name of Field Description

File Rules
Required files to replicate Enter the subscription’s required files. Required files are databases,
templates or directories that are automatically installed offline, and are
replicated every time the subscription is synchronized.

All required files and directories must be specified relative to the

server’s data directory.

Optional files to replicate
For tips on using directory names and wildcards when you specify
more than one Required file or Optional file, see the topic ″Creating
multiple database DOLS subscriptions.″
Enter the subscription’s optional files. Optional files are databases,
templates or directories that can be enabled or disabled in the sync
manager for offline installation and replication. For example, in
addition to the required file(s), you may want to download a related
Help database or an archived discussion database as an optional file.

All optional files and directories must be specified relative to the

server’s data directory.

Optional databases replicate as ″stubs,″ meaning only the design is

replicated. Users can open Sync Properties, click the Sync Options tab,
select the database, and deselect the disable box. The data is then
replicated at the next synchronization. To save disk space, users can
disable an optional file, and the data is removed at next
synchronization.

Enable replication of optional files by default:

Select this box to automatically download and synchronize new

databases found in the subscription’s directories on the server. For
example, if one of the optional databases is designed to create new
databases, the new databases are automatically downloaded and
synchronized.

Chapter 13. Setting Up Domino Off-Line Services 375

Name of Field Description
Directory catalog Synchronize directory catalog:

Select this box to install a directory catalog with the subscription. Then
enter the file name, including directory path, of the catalog database
on the server (for example, dircats\mydircat.nsf). If the server
administrator has specified a default offline directory catalog for the
server by adding $DOLSDirectoryCatalog = nameofcatalog.nsf to the
NOTES.INI on the server, you can leave this field blank and the
server’s default offline catalog is replicated with the subscription. A
catalog filename specified here will override the server’s default offline
directory catalog.

Choose the ″Replicate as an optional file″ checkbox to specify the

catalog as an optional file. If the directory catalog is specified an
optional file, the ″Enable replication of optional files by default″
checkbox must be checked for the catalog to replicate the first time.

In order for Domino Web Access for Web Mail users, to take a
directory catalog offline, you must add the name of a directory catalog,
including the NSF extension, to the $DOLSDirectoryCatalog setting in
the server’s NOTES.INI file.

For more information on using directory catalogs with DOLS, see the
topic ″Adding a directory catalog to the application″ before adding one
to your subscription.
Encryption Encrypt this subscription:

Select the box to enable encryption. Then select the level of encryption.
Encryption prevents an unauthorized user from accessing the offline
subscription’s data using another software product.
v If the subscription has multiple databases, all of these databases are
encrypted.
v If the subscription has a shared file, you must encrypt all
susbcriptions sharing the file. An unencrypted subscription may not
be able to open an encrypted file.
v Using strong encryption causes a database to open more slowly than
it would using a weaker encryption or no encryption.
Note: Do not encrypt the database from the Database Properties box.
Use the Offline Subscription Configuration document to prevent
unauthorized users from reading subscription data using other
applications.

Syc Options
Date Filtering Only sync documents modified within the last [number] days:

Select this box to preset a default, date-based filter on all databases

created offline. For example, if you specify 30 days, only documents
created or modified in the last 30 days will synchronize. Once
installed, users can reset this for each subscription file using the
Domino Sync Manager.

376 Lotus Domino Administrator 7 Help

Syc Options
Halt Conditions
Sync Options: Optional actions
Full-Text Index subscription after sync
Compact subscription after sync
Notify on completion of sync
Route mail on client shutdown
Replicate on client shutdown
Use multi-user data directory
Allow per-user shared subscription data
v Limit database size to [number] MB: Select this box to specify the
maximum size in megabytes of the offline database. You cannot
specify a number less than 10.
v Limit subscription size to [number] MB: Select this box to specify the
maximum size in megabytes of the entire offline subscription. You
cannot specify a number less than 10.
You can preset an automatic halt to the offline synchronization when a
database exceeds a particular size, or when the subscription as a whole
exceeds a particular size. The user can override this setting.
Note: Be careful not to specify a size that may be too limiting. The
offline subscription may not be fully operational if synchronization is
interrupted prematurely.
Select this box to force full-text indexing of the subscription after
synchronization. The user can override this setting.
Select this box to force the subscription to compact after
synchronization.
Select this box if you want the user to receive a message when
synchronization is complete. The user can override this setting.
If warnings are displayed during the synchronization process, and this
option is selected, each warning message will display.
Select this box so that pending outgoing mail messages are sent before
the user exits from the Domino Sync Manager. The user can override
this setting.
Select this box so that synchronization occurs before the user exits
from the Domino Sync Manager. The user can override this setting.
Select this box so that the subscription can be installed to a client with
a Notes multi-user setup. Subscription data is stored in the user’s
personal profile data directory.
Select this box to allow the subscription to share a file with another
subscription, as long as as the same user has installed both files.
For example, a user installs this subscription with the directory catalog
dircat1.nsf. If the user then installs another subscription that uses
dircat1.nsf., and also selects this option, the two subscriptions share
dircat1.nsf.
All subscriptions that share the same file must be either encrypted or
not encrypted. Non-encrypted subscriptions may not be able to share a
file that is encrypted.
Chapter 13. Setting Up Domino Off-Line Services 377
 8. Click the Admin tab and complete the following fields:
Name of field
Push subscription settings:
Read only subscription settings:
Passthru server settings:
378 Lotus Domino Administrator 7 Help
Action
Push subscription settings to Domino Sync Manager.
Select this box to push changes made to the active Off-Line Subscription
Configuration Profile Document (on the server), down to the Domino
Sync Manager (on the client), without requiring a reinstallation of the
subscription.
The following are the only settings and actions that cannot be changed
on the user’s computer unless the user deletes and reinstalls the
subscription.
Encryption
Per-user shared subscriptions
Multi-user data directories
Passthru server settings
Optional TCP/IP addresses
A change in the subscription title
Adding new services or custom filesets
Deleting or moving the main.nsf
Force user to accept subscription changes. This box is only visible when
″Push subscription settings to Domino Sync Manager″ is selected. Select
this box to force the user to accept changes in the Offline Subscription
Configuration Profile document. Not selecting this box allows users to
prevent the changes from occurring on their subscriptions.
Make schedule read-only. Select this box to dim the scheduled
replication settings in the Properties dialog - Schedule tab of the
subscription on the user’s computer. You can push this to users by
selecting it before they install the subscription, or by using the ″Push
subscription settings″ feature.
Make sync options read-only. Select this box to dim the Sync Options
settings in the Properties dialog - Sync Options tab of the subscription
on the user’s computer. You can push this to users by selecting it before
they install the subscription, or by using the ″Push subscription
settings″ feature.
Use passthru server to connect to destination server. Select this box to
use a passthru server to connect to the Domino server that hosts the
subscription. You must enter the name of the passthru server.
Name of field Action
Network Settings: Use optional TCP/IP address to connect to destination server. Select this
box to provide primary and/or secondary TCPIP addresses for the
destination Domino server hosting the subscription. This is especially
useful for users who access the server through both an intranet and an
extranet. If the primary address is not reachable, the Domino Sync
Manager tries the secondary address to connect to the server.

Then enter the name of the primary and secondary addresses. If users
connect to the host server through a passthru server, the addresses must
be for the passthru server.

Alternatively, an administrator can configure these settings for all the

subscriptions hosted on a particular server by adding addresses to the
$DOLS_TCPIPAddress and $DOLS_TCPIPAddress2 settings in the
server’s NOTES.INI.
Security Settings: Enable this setting so that the user’s offline Internet password remains
synchronized with their online Internet password. This setting works
only when the Online Configuration document Security Settings field
″Keep Internet Password Synchronized″ is enabled.

9. (Optional) At the bottom of the configuration document, select whether to display the default
download page or create your own download page. The download page is what users see while
they’re installing a subscription. It’s useful for showing instructions, company graphics, warnings, or
tips. Do one of the following:
v Leave ″Display default download page contents″ selected to have the download page contain the
default text and graphics. You can add text, HTML, or images in the rich-text field below the
default text and graphics.
v Select ″Display only the custom contents below″ to create a download page. A rich-text field
appears in which you can add text, HTML, or images.
10. Save and close the configuration document.
11. Save and close the subscription.
12. (Optional) Customize the subscription. For more information on customizing the subscription, see
the topic ″Optional tasks for DOLS developers.″

Overview of DOLS administrator tasks

Developers and administrators perform different tasks to prepare a DOLS subscription for users.
Administrators perform the following tasks:
1. Setting up DOLS on a server.
For more information on setting up DOLS on the server, see the chapter ″Installation.″
2. Creating a DOLS Offline Security Policy document.
3. Increasing security for DOLS subscriptions.
4. Increasing the server’s output timeout for DOLS downloads.
5. Configuring the DOLS subscription.
6. Setting up agents for the DOLS subscription.
7. Send users the URL of the subscription. If the offline security policy is ″Prompt for ID,″ also make
sure they have a Notes user ID and Internet password so they can open the subscription.

Chapter 13. Setting Up Domino Off-Line Services 379

How DOLS works
The following diagrams show how the Domino Sync Manager gets installed, and how it supports Web
applications offline.

Typically, the first step is for a user to enter the URL of a Domino server, along with the path and name
of a DOLS-enabled Web application on that server, into their browser. The browser contacts the server
through the Web Server task, also called the nHTTP task (1a)., and the Web Server then communicates
with the Web application (1b).

If the Web application has appropriate security levels set in the ACL, the user is prompted to log-in to
the Web application using their name and Internet password. This authentication is also handled by the
Web Server.

380 Lotus Domino Administrator 7 Help

If the application is DOLS-enabled, and an Offline Configuration Document (OCD) was created and
saved, the user sees the DOLS Web Control when they open the application. The user clicks the Web
control and selects ″Install Subscription...″ to start downloading the application to their computer.

When the user selects ″Install Subscription...,″ the application requests the OCD (2a). A special DSAPI
filter file on the server, listening for URL Web server requests, notices the OCD request. The filter queries
the client to determine if the Domino Sync Manager (iNSM) client software is already installed. If not, the
filter tells the browser to begin downloading a set of DOLS File Sets to the client over the HTTP
connection (2b). These file sets are used to install the Domino Sync Manager software.

Chapter 13. Setting Up Domino Off-Line Services 381

Once the DOLS File Sets are downloaded, they are uncompressed, and the Domino Sync Manager
launches (3). The Sync Manager then configures the client for the incoming application, and launches a
Sync Task, which initiates a Remote Procedure Call (nRPC) connection with the Domino server (4a). This
secure, Domino replication connection performs a number of operations to download and initialize the
application on the client (4b). When synchronization is complete, a subscription of the application exists
on the client. A subscription includes all databases that were listed in the OCD as making up the
application. Their contents are adjusted according to Administrator and user settings, as well as security
information to ensure that the user on the client has access to only the data to which they had access on
the server. Also, full-text indexes of all offline databases can be created if the user requests it.

382 Lotus Domino Administrator 7 Help

When the user wants to open the application offline, they select it from a list in the Sync Manager and
click ″Open Offline.″ The Sync Manager launches a local copy of the Web Server and the local browser
(5a). The Sync Manager tells the local Web server to connect with the local browser (5b), and with the
offline copy of the application (5c). The local Web Server then validates the user’s login and password
information, and displays the application offline (locally) just as it would display it online (on the server).
Any data the user creates, modifies, and saves while using the offline application is stored in the local
version of the application.

Chapter 13. Setting Up Domino Off-Line Services 383

In order to synchronize the data between the offline and online versions of the application, the Sync
Manager, either by the user’s command or automatically on a schedule, launches the Sync Task, which
again creates an nRPC connection to the Domino server (6a). The Sync Task then replicates any or all
data between the client copy of the application to the server copy. Any changes to the security levels of
the online application are synchronized offline. Any outgoing e-mail which has accumuIated in the local
mail.box file is copied to the server and dispatched to the mail router task for delivery. When
synchronization is complete, the user may disconnect from the network and continue using the
application offline.

Creating a DOLS Offline Security Policy document

Use Offline Security Policy documents to set different ID policies for users in different domains. For
example, you can generate IDs automatically for users inside the company, but require users in a domain
outside the company to provide IDs you have given them.

To create an Offline Security Policy Document, do the following:

1. Open Lotus Domino Administrator 7.
2. Click the Configuration tab.
3. Click Offline Services.
4. Click Security.
5. Click ″New Security Policy.″

384 Lotus Domino Administrator 7 Help

6. Fill out the following fields in the Basics tab:

Field Description
Security domain Enter the domain that this policy affects. For example,
/US/Company, or /Company (include the leading
slash). All users in this domain are subject to the
deployment policy you set in this document.

The domain specified in this field includes users one

Prompt for ID during download
Automatically generate user IDs
level down from the root. For example,
Cambridge/Lotus includes users in
/Security/Cambridge/Lotus and
/Dev/Cambridge/Lotus.
Before the subscription installs, users are asked to specify
where on their computer their user ID is stored. The
administrator must provide an ID to the user. This is the
default ID deployment policy.
Before installation, a certifier ID is generated for the user
automatically.

The Automatic tab appears when this option is selected.

Click this tab and attach the certifer ID to be generated,
set the password, and set the ID expiration date.

It is recommended that you do not attach the absolute

Use the Domino Directory for ID lookup
root certifier for your organization (for example, /Lotus).
Instead, you should automatically generate a user ID
against a subcertifier (for example, /NewUsers/Lotus).
You may also want to generate the user ID in a new
domain.
Before installation, the server looks for an existing user
ID in the Domino Directory (formerly called the Names
and Address book).

The Lookup tab appears when this option is selected.

Enter the relative path for the Domino Directory that
contains the IDs.
Roaming User Override security policy for roaming users. Select this
box to set the Domino server to behave appropriately
with ″Roaming users″ who access the subscription. The
server will recognize the user as a Roaming user, ignore
the current security policy, and find the user’s ID on the
user’s home server.
ID Management Overwrite existing user IDs. Select this box to have
user’s offline ID overwritten with a new ID each time
they install a subscription.

Caution! This setting should not be turned on in an

enterprise that uses encrypted subscriptions. Users
whose IDs are overwritten will not be able to open an
offline subscription encrypted with a key from the
previous ID.

Chapter 13. Setting Up Domino Off-Line Services 385

7. If you selected ″Automatically generate user IDs,″ fill out the following fields in the Automatic tab:
Field
Certifier ID to use
Password for certifier ID
Expiration date to set on created user IDs
8. If you selected ″Use NAB for ID lookup,″ fill out the following fields in the Lookup tab:
Field
Address book to look up ID files from
Increasing security for DOLS subscriptions
You have several options for increasing security on DOLS subscriptions:
Option
Tighten access to the database
Tighten security on the configuration document
Tighten security on offline data
386 Lotus Domino Administrator 7 Help
Description
Attach a certifier ID to this rich text field. The certifier ID
must support the Security domain field specified in the
″Security domain″ field.
For example, if the Security domain is /A/B/C, then
either /A/B/C, /B/C, or /C would be acceptable
certifiers.
The certifier ID file attached here must share the same
root certifier as the server’s ID for DOLS. If they do not
share the same root certifier, the user may receive
replication errors about a lack of cross-certifiers.
Enter the password for the certifier ID. The password,
which is case-sensitive, must be correct or the user will
not be able to install.
Make sure you protect stored passwords by
appropriately restricting the ACL of this database
(doladmin.nsf).
Select or enter an expiration date for the ID. For
example, 03/31/2006.
Description
Enter the database filename, with relative path, of the
directory where your server’s user IDs reside. The target
database must have standard NAB views & documents,
with ID files attached to each person document.
Description
Open the ACL for the subscription and add the users
and groups to whom you want to grant access.
Anonymous must have ″No Access.″
To limit who can open and edit the Offline Subscription
Configuration Profile document for a particular
subscription, open the subscription’s ″DOLS Offline
Configuration″ form in Lotus Domino Designer 7 and
change security settings in the Form properties.
To ensure that unsanctioned users cannot access the
subscription data offline using another software product,
encrypt the subscription in the Offline Subscription
Configuration Profile document.
Option
Tighten security for all subscriptions on the server
Description
To propagate a security setting to all the existing DOLS
subscriptions on a server, make sure the subscriptions are
set to inherit design changes from the DOLS Resource
template (DOLRES.NTF); change the setting in
DOLRES.NTF; then run the Designer task.

For more information on the Designer task, see the topic

″Synchonizing databases with master templates.″

Increasing the server’s output timeout for DOLS downloads

DOLS administrators should increase the output timeout time if users will be installing the DOLS file set
over a phone line. To increase the server output time:
1. Open Lotus Domino Administrator 7.
2. In the navigation pane, click Server - Current Server Document.
3. Click the Internet Protocols tab, then the HTTP tab. Change the ″Output timeout″ field to 18000
seconds to allow enough time for downloads. Change this accordingly, depending on the speed of
your connection.

Setting up agents for the DOLS subscription

Agents are small programs that perform actions in a subscription. Because they can be powerful tools,
they must have permission from the server to perform their actions. Agents inherit the permissions of
their ″signer.″ An agent’s signer can be the user who created it, or a user or organization designated by
an administrator. An administrator can also register a ″dummy″ user on the server and make it the signer
of agents. This provides more control and security, because the dummy user won’t do anything the
administrator doesn’t want done.

For an agent to perform actions on a server an administrator must add its signer, or a group the signer is
in, to the Server document (Security - Agent Restrictions).

Agents can perform both unrestricted actions and restricted actions. Restricted actions can potentially
cause serious damage to the server, so administrators must be careful about the permissions of agents
that perform restricted actions.

Note: There are also two kinds of agents: triggered and scheduled. Triggered agents are activated by a
user action, like clicking a button or selecting a menu item. Scheduled agents run automatically, on a
schedule, or when events happen inside a database, such as a new mail document arriving. Only
triggered agents work offline.

If a subscription contains triggered agents, do the following to make them work offline.
1. If the subscription contains restricted agents, create a group called ″DOLS_Restricted_Agents″ in the
Domino Directory.
2. Add the full names of the signers of the restricted agents to the ″DOLS_Restricted_Agents″ group.
If an agent has been configured to run as a Web user (Agent Properties - Design tab - Run as Web
user), use the full name of its signer. Otherwise, use the full name of the signer who modified it last
(for example, NewDevelopment/IBM).
3. If the subscription uses unrestricted agents, create a group called ″DOLS_Unrestricted_Agents″ in the
Domino Directory.
4. Add the full names of the signers of the unrestricted agents to the ″DOLS_Unrestricted_Agents″
group.

Chapter 13. Setting Up Domino Off-Line Services 387

 If an agent has been configured to run as a Web user (Agent Properties - Design tab - Run as web
user), use the full name of its signer. Otherwise, use the full name of the signer who modified it last
(for example, NewDevelopment/IBM).
5. In the Server document, on the Security tab - Agent Restrictions section, add
″DOLS_Restricted_Agents″ to the ″Run restricted LotusScript/Java agents″ field. Add
″DOLS_Unrestricted_Agents″ to the ″Run unrestricted LotusScript/Java agents″ field.
6. Make sure agent signers have at least Editor access in the ACLs of all databases where the agent runs.
7. Use the DOLCert.id (in the Domino data directory) as the certifier ID to create cross-certificates for
each user or organization you specified as being able to execute agents. DOLCert.id creates
cross-certificates issued by ″O=DOLS.″ There may already be cross-certificates issued by the Lotus
Domino 7 server for these names. You can use the ID file or public key for the agent user and
organization to generate cross-certificates.

Note: If a database uses agents, make sure they’re all signed and that the server’s CERT.ID is
cross-certified with the DOLCERT.ID.

Optional tasks for DOLS administrators

In addition to required administration tasks, there are a few optional tasks for the administrator:

Adding a directory catalog to the subscription

Viewing DOLS download information

Reducing DOLS download time with the client installation CD

Reducing DOLS download time with selective replication

Web Control instructions for DOLS users

Adding a directory catalog to a DOLS subscription

Adding a directory catalog to a DOLS subscription allows users to take Domino Directory information
offline. When you add this NOTES.INI setting, the option ″Include server’s Domino Directory″ is
available in the Domino Web Access Offline preferences. Users need to enable this option to allow
address look ups, which is necessary to encrypt mail offline. To add a directory catalog to a subscription:
1. Read the following.
v Adding a catalog means more for a user to download. To keep download time reasonable, you may
want to create a directory catalog specifically for offline users, which contains only the information
they absolutely need.
v To add a default catalog, open the NOTES.INI file on the server and add the line
$DOLSDirectoryCatalog=nameofcatalog.nsf (nameofcatalog being the actual name of the catalog).
Once you do this, you don’t need to specify a catalog in the ″Directory catalog to replicate″ field in
the Offline Configuration Profile document.
v From the DOLS Customize subform, you can create a field that looks up a catalog’s name on the
server record and populates the ″Directory catalog to replicate″ field with that name.
2. Open the Offline Subscription Configuration Profile document.
3. Enter the name of the catalog in the ″Directory Catalog″ field in the Rules tab.
4. Restart the server.

388 Lotus Domino Administrator 7 Help

Viewing DOLS download information
To view information on subscription use, click the Configuration tab in Lotus Domino Administrator 7.
Then click Offline Services - Users. In the Users view, you can see the name of each user who has
installed a subscription, the names of the security domains, the names of the applications downloaded,
and the download dates and times.

Click a column header to change the order of the data in the view. Open a document to see all the
information on a particular download.

Reducing DOLS download time with the client installation CD

The DOLS Client Pre-Installer CD is an alternative to having users install subscriptions from the server
over a slow connection. The CD includes client drivers and Domino Web Access file sets. You can add
database subscriptions, custom file sets that were created for the subscriptions, and custom programs
intended to run after the installation.

To obtain a CD, contact your IBM Software Services for Lotus representative. Or you can download the
CD code from www.lotus.com/dols and create your own CD.

Perform the following steps to add subscriptions, custom file sets, and custom programs:

To add a subscription
1. Create new replicas of all databases belonging to the subscription. Any database you add to the CD
must have the same replica ID as the original. For example, you cannot make a new ″copy″ of a
database with the Notes client, because copies have new IDs.
2. In the directory \Content\Subscriptions on the CD, create one folder for each subscription. Name
each folder with the replica ID of the main database of the subscription. For example:
\Content\Subscriptions\72638271927F46D8
The hidden field ″ReplicaID″ in the Offline Configuration Profile Document contains the database’s
replica ID. If you open the Offline Configuration Profile Document in Notes, open document
properties, click the Fields tab, and select this field, you can copy and paste the ID to create the folder
name.
3. In each subscription folder, add the subscription itself in a directory structure exactly matching the
directory structure under the Data directory on the Lotus Domino 7 server. For example, if the
DOLS-enabled mail database joe.nsf was located in \Data\Mail on the server, you would add the
following:
\Content\Subscriptions\72638271927F46D8\Mail\joe.nsf
4. If the subscription has a directory catalog, create a DirectoryCatalog folder under
\Content\Subscriptions\<ID> and add a replica of the catalog. For example, if you wanted to add a
directory catalog to the joe.nsf subscription, you would add the following:
\Content\Subscriptions\72638271927F46D8\DirectoryCatalog\nameofcatalog.nsf
5. Open the Offline Configuration Profile Document of the original subscription on the server. Click the
Rules tab and add the names of the subscription’s Required and Optional databases to the Required
and Optional fields.

To add a custom file set

1. Add custom file sets to the directory \Content\CustomFilesets on the CD. Each custom file set should
have an EXE file and an INF file, both having the same name.
2. Open the Offline Configuration Profile Document of the original subscription on the server. Click the
Services tab and select ″Custom services.″ A ″Custom services to install offline″ field appears. Add the
custom file set commands to it.

Chapter 13. Setting Up Domino Off-Line Services 389

To create a custom program for the DOLS subscription
To create a custom program to run immediately after installation:
1. Create a file called DOLSCONTENT.INI in the directory \Content on the CD.
2. Make the first line [DOLS]; the second line SetupProgram=; and the third line SetupCommandLine=.
You can also add the optional setting Nowait. When you add Nowait, the DOLS Pre-Installer will not
wait for the custom program to finish running before displaying the ″Setup Complete″ dialog box.
3. Add the name of the program you want run to the SetupProgram= line. Add any specific commands
you want to the SetupCommandLine line. For example, if the first thing you want to happen after
installation is for the user’s Explorer browser to open to the URL of the subscription ″offlineapp.nsf,″
add the following to DOLSCONTENT.INI:
[DOLS]
SetupProgram= C:\Program Files\Internet Explorer\IexploreEXE
SetupCommandLine=http://www.foo.com/offlineapp.nsf
Nowait=1

Note: You cannot launch more than one program.

Distributing the CD to users

After you’ve prepared the CD, distribute copies to your users. The installer runs automatically when the
user puts the CD in the drive. If it doesn’t run, the user should double-click setup.EXE on the CD.

If users delete a subscription from the Domino Sync Manager, they must run the CD installer again, then
re-install the subscription to restore it. If they install the subscription from the server, they’ll only get the
online version of it, with none of your customizations.

Note: See the readme file on the CD for system and browser requirements, tasks for administrators and
users, and more reference information.

Reducing DOLS download time with selective replication

By controlling which is replicated offline, you can control the size of a subscription and reduce download
time for remote users who may have a slow connection. To set limits on what users take offline, do the
following:
1. Open the main subscription.
2. Open the Database Properties box.
3. From the Database Basics tab, click ″Replication Settings.″
4. In the ″Replication Settings″ dialog box, click Advanced.
5. Enter one of the following in the ″When computer″ field:
v ″OfflineSync/DOLS″ - Settings apply to all users of the subscription.
v User/Domain - Settings apply to that user only.

Note: Individual user settings take precedence over ″OfflineSync/DOLS″ settings.

6. Choose replication settings:
For example, you can check ″Replicate a subset of documents″ and choose the folders and views you
want synchronized to the user’s machine. You can also have the documents synchronized by formula.
For example, you can check ″Select by Formula″ and enter a formula so that only selected users are
able to synchronize a selected folder.

Note: DOLS requires that you add the following text to any selective replication formula that you
create. If you forget to add this text, offline users will not be able to open their offline applications:
|Form="DOLSOfflineConfiguration"
The following example shows a selective replication formula with the required text:

390 Lotus Domino Administrator 7 Help

 SELECT From=@UserName|Form="DOLSOfflineConfiguration"
7. To save the settings, click OK.

Web Control instructions for DOLS users

The Web Control is a pop-up menu in the subscription from which users can install the subscription,
synchronize, choose a language for the interface text, and open the subscription online or offline. To open
the pop-up menu, users click on either the words ″Go Offline,″ or an image in a frame on the main Web
page of the subscription.

For more information on customizing how users install the subscription, see ″Customizing how users
install the DOLS subscription″ in the Lotus Domino Designer 7 Help.

To access the Web Control menu using shortcuts

The following are instructions on installing a DOLS subscription with minimal use of a mouse. Along
with a username, password, and address, you may want to send these instructions to users who want or
require alternative access to software features.

To take a subscription offline:

1. Open the subscription online.
2. Click once anywhere on the Web page.
3. Press TAB to move the focus to different frames until the focus is on the image or words ″Go Offline.″
This is the Web Control.
4. Press ENTER. The pop-up menu opens.
5. (Optional) Press the up and down arrow keys to navigate to the Language menu item, then press the
right arrow key. The list of languages opens. Press the up and down arrow keys to navigate to a
language and press ENTER. This is the language the subscription interface appears in offline.
6. Open the pop-up menu again.
7. Press the up and down arrow keys to select Install Subscription.

Note: There are no keyboard shortcuts for the Languages menu.

DOLS troubleshooting and error messages

If you have problems configuring a subscription to go offline, you may want to look at the following log
files:
v DOL.LOG (found in the \Program Files\Lotus iNotes directory on the client machine).
v LOG.NSF (found in the \Program Files\Lotus iNotes\Data directory on the client machine). To open
this file from a browser while offline, enter http://127.0.0.1:89/LOG.NSF.

Error messages
The following table lists client and server error messages you may see as you use DOLS. These error
messages are logged in LOG.NSF under Miscellaneous Events. You can locate LOG.NSF in the \Program
Files\Lotus iNotes\Data directory on the client machine. To open this file from a browser while offline,
enter http://127.0.0.1:89/LOG.NSF.

Error Message Description

Error requesting offline configuration from the server.
This subscription is not configured correctly to go
offline.
The Offline Subscription Configuration Profile document
is missing or you may have a connection error. Open
LOG.NSF to see the corresponding server error message.
An error occurred during download. Open LOG.NSF to
see the corresponding server error message.

Chapter 13. Setting Up Domino Off-Line Services 391

Error Message Description
Unable to download file set component information for This is an HTTP request error and involves an access
this subscription. restriction. Open LOG.NSF to see the corresponding
server error message.
HTTP Error 404. The Offline Subscription Configuration Profile document
may be missing.
The remote server is not a known TCP/IP host. Synchronization failure.

392 Lotus Domino Administrator 7 Help

Chapter 14. Planning the Service Provider Environment
This chapter describes the server and IP configurations and discusses configuration-related decisions that
you will make before you set up an xSP server.

Planning the xSP server environment

The generic term ″xSP″ can refer to many different types of service providers -- application, Internet,
storage, and management -- to name just a few.

A Domino service provider delivers services to small-and medium-sized businesses, or multiple hosted
organizations from a single Domino domain. To those hosted organization, the service provider offers
Internet protocol-based access to a specific set of applications running on Domino servers. By using a
service provider, a company can outsource the administration of applications and services that were
formerly run on the company’s computer infrastructure.

This portion of the documentation focuses on the decisions you will be making when planning and
setting up your xSP server environment. You can then use your xSP server to host small and medium
businesses.

The Domino service provider administrator

The responsibilities of a service provider administrator, include maintaining both the server environment
at the host site and to varying degrees, the hosted organizations.

First and foremost, the service provider administrator is responsible for setting up and maintaining xSP
servers -- that is, protocol and database servers -- as well as any Domino clusters and network routers.

Although the hosted organization administrator can perform some of the user and group maintenance,
the service provider administrator performs a significant amount of the administrative tasks required to
maintain a hosted organization. At a minimum, the service provider administrator is responsible for
registering and maintaining hosted organizations and controlling which applications the hosted
organization uses. In addition, the service provider administrator must create and maintain a mechanism
that the hosted organization’s administrators use to communicate problems and issues that require the
intervention of the service provider administrator.

Ways to set up a service provider environment

There are two ways to set up a service provider environment. You can set up an xSP server, which
features a shared Domino Directory or you can user server partitioning. The term ″shared Domino
Directory″ indicates that there is one Domino Directory shared by multiple hosted organizations. All data
is secured and accessible only by the small or medium business that owns the data. A second option is
Domino server partitioning, which you use to run multiple instances of the Domino server on a single
computer.

Set up an xSP server to offer pure Internet protocol-based access to a specific set of applications on
Domino servers. For example, Domino Web Access is such an application. Using an xSP server reduces
the total cost of ownership for a designated set of services, offered to several customers accessing the
server through standard Internet protocols. In a service provider environment, you are hosting multiple
companies in one Domino domain.

Use Domino partitioning to offer a Domino server where the customer can have Notes Client access and
can create and run their own Domino applications. Setting up a partitioned server is particularly effective

393
when the partitions are in different Domino domains. Partitioning provides a completely separate server
for each customer, as well as a completely separate Domino Directory.

For more information on partitioned servers, see the chapter ″Setting Up the Domino Network.″

Securing the service provider environment

The Domino service provider environment uses all of the standard Domino security features to ensure
complete security for the service provider and the hosted organizations that subscribe to the service
provider services. An xSP environment that has multiple hosted organizations has potentially thousands
of users whose access must be restricted to their own data only.

In addition, the service provider configuration uses extended ACLs in the Domino Directory to protect
the data of each hosted organization from access by users in other hosted organizations. The extended
ACLs required to support the xSP security model are automatically established when new hosted
organizations are created. Plan and test carefully if you want to modify ACLs and extended ACLs in an
xSP environment -- security is extremely important.

The authentication controls in Site documents control only who can authenticate and use the Internet
protocols. After authentication, ACLs and extended ACLs control the data that can be read from and
written to the Domino Directory.

For more information on extended ACLs, see the chapter ″Setting Up Extended ACLs″ and for more
information on ACLs, see the chapter ″Controlling User Access to Domino Databases.″

A user in a hosted organization cannot directly access databases in any subdirectories other than the
hosted organization’s directory. Exceptions are the ″help″ and ″common″ subdirectories of the Domino
data directory which contains databases accessible to users in all hosted organizations.

To provide users with access to databases outside that of the hosted organization’s subdirectory, create a
directory link within the hosted organization’s directory.

For more information on how directory links work and how to create them, see the chapter ″Organizing
Databases on a Server.″

Using Domino features in a hosted server environment

There are several Domino features that need to be set up for a hosted environment, just as they would
need to be set up in a non-hosted, enterprise environment. This section describes the features are required
in a hosted environment and explains when to set them up.

Domino certificate authority

For some Internet certificates and for Domino Off-Line Services (DOLS), you must use the Domino
certificate authority (CA). The Domino CA is required only if a hosted organization uses DOLS or wants
to generate Notes IDs. For example, a hosted organization may require Notes IDs for its users if it uses a
third-party application that uses the C API to perform a function. If a hosted organization uses the Web
Administrator to manage their own users and groups, the hosted organization must use certifiers issued
by the Domino server-based CA.

If a hosted organization’s users are registered at the service provider site, they can be registered with
certifier IDs and passwords or with the Domino server-based CA.

Using SSL in a hosted environment

To use SSL in a hosted environment, you must do the following for each hosted organization:
v Create a new Domino server-based Certificate Authority (CA). Two or more hosted organizations
cannot share the same Domino CA.
v Create a Certificate Requests database.

394 Lotus Domino Administrator 7 Help

 For more information on setting up and using the Domino server-based CA and creating the Certificate
Requests database, see the chapter ″Setting Up a Domino Server-Based Certification Authority.″

Directory Assistance
Directory assistance is not supported in a hosted environment. You cannot use Domino’s directory
assistance feature with Domino’s xSP configuration. The Directory assistance database name field on the
xSP Server document should be blank.

Policies
Policies are required when using the Domino service provider software. Before registering a hosted
organization, the service provider administrator must decide which policy settings to implement. Before
registering a hosted organization, the service provider administrator can create policy documents and
policy settings documents and then assign those documents during registration, or the service provider
administrator can create the documents during the hosted organization registration process.

For more information on policies, see the chapter ″Using Policies″ and see the topic ″Using Policy
Documents in a hosted environment″ later in this chapter.

Domino Off-Line Services

Domino Off-Line Services (DOLS) is supported in a hosted environment. If a hosted organization uses
DOLS, the hosted organization must be registered with the Domino server-based CA. The registration
process for hosted organizations that support DOLS is almost identical to the setup and registration of
hosted organizations that do not support DOLS.

For more information on Domino Off-Line Services (DOLS), see the chapter ″Setting Up Domino Off-Line
Services.″

Using the C API Extension Manager in a hosted environment

The C API Extension Manager is fully supported in a hosted environment; however, there can be only
one Extension Manager on a server. If the Extension Manager must provide different services for each
hosted organization, program the Extension Manager to do the filtering.

For more information, see the C API User’s Guide and the C API Reference Guide on the IBM Web site,
www.ibm.com.

Planning the IP Address configurations in a hosted environment

A crucial step in planning an xSP configuration is to determine which of the following IP address
configurations to use:
v One IP address that is shared by multiple hosted organizations
v One IP address for each individual hosted organization
v A combination of the above two configurations

The IP address configuration that you choose will have an impact on your entire xSP configuration.

One IP address that is shared by multiple hosted organizations

The following figure shows xSPserver1 supporting multiple hosted organizations sharing IP address
92.32.2.0.

Chapter 14. Planning the Service Provider Environment 395

Note: SSL is not supported in this configuration because Domino does not provide server authentication
on a per-hosted-organization basis.

If the configuration features one IP address shared by multiple hosted organizations, POP3, IMAP, HTTP,
SMTP, LDAP and Domino IIOP are the available protocols. In this configuration, each IP address entered
on the Internet Site documents must be the same for each protocol. The POP3, IMAP, and LDAP users
must use their Internet e-mail addresses to authenticate. This configuration does not support anonymous
access to LDAP.

One IP address for each individual hosted organization

If you are using SSL, use a unique IP address for each hosted organization. To use this configuration, you
must bind the IP address to the xSP server.

For more information on binding an IP address to a hosting server, see the chapter ″Setting Up the
Service Provider Environment.″

The following figure shows xSPserver2 supporting three hosted organizations, each with its own unique
IP address.

396 Lotus Domino Administrator 7 Help

Combination of IP address configurations
You can use a combination of the two IP address configurations shown above. The following figure
shows three servers that collectively host many hosted organizations.

Planning the distribution of hosted organization data

The following four configurations are supported for distributing hosted organization data within the
service provider environment.

When you configure a hosted environment, databases must reside on the xSP server -- that is, the server
to which the hosted organizations are connecting.
Chapter 14. Planning the Service Provider Environment 397
Hosted organization data on one server
All of a hosted organization’s data can reside on one server. As the number of hosted organizations
increases, you can easily add additional servers.

Multiple organizations on one server with a shared application

Multiple hosted organizations can share an application that is served from a single server. Data for the
hosted organizations resides on the server with the application.

A hosted organization’s data distributed across multiple servers

A hosted organization’s data can be distributed across multiple servers that all run the same set of
applications on each server to provide load distribution and hot backups. You can include Domino
clusters and network routers in this configuration.

398 Lotus Domino Administrator 7 Help

Combined configuration
You can use any combination of the above configurations.

Chapter 14. Planning the Service Provider Environment 399

Deciding which protocols and services to offer in the xSP environment
Another aspect of planning a hosted environment is determining which services to offer to customers.
There are some considerations unique to the Lotus Domino service provider environment that you will
need to take into consideration when determining which protocols (services) you are offering to hosted
organizations.

If you are offering mail services, you must provide the protocols to support them. If you do not offer
mail services, you do not need the POP3, IMAP, or SMTP protocols.

Protocol/Service Requirement
HTTP with Domino Web Access When sending mail via Domino Web Access, enable
HTTP on the server that stores the mail file.
IIOP Domino IIOP is required to run Java code.
LDAP If you use POP3 or IMAP and the client mail application
supports LDAP, you can also use LDAP to provide the
mail clients with addressing services.

Lightweight Directory Access Protocol (LDAP) is a

standard Internet protocol for accessing and managing
directory information. If LDAP will be used with the
Domino Directory, the LDAP protocol must be started.
POP3 and IMAP POP3 and IMAP are access protocols only, that is, they
retrieve mail. SMTP is required to enable POP3 and
IMAP users to send mail. Additionally, the POP3 or
IMAP client must be configured to send mail via an
SMTP server.
SSL SSL can be used in addition to Domino’s security
services. SSL supports data encryption to and from
clients and provides message-tampering detection and
optional client authentication.
Note: SSL is supported only for hosted environments
that use a unique IP address configuration.

Resolving mail addresses in a hosted environment

IP addresses are resolved via the Domain Name System (DNS), local host file, or a combination of the
two.

For ease-of-access and ease-of-administration, you can use host names and Web site names to resolve
mail addresses and to process transactions. The following table indicates which names are used by each
protocol.

Name Protocol
Server host name POP3 and IMAP clients use server host names to locate
host servers when retrieving mail.
For example, serverA.corporation.com
Inbound HTTP transactions can use server host names
when resolving transactions.

LDAP clients use server host names when performing

directory lookups.

Web browsers can use server host names in URLs, in

addition to other types of DNS names.
Web site name For example, www.corporation.com HTTP transactions are resolved via Web site name.

400 Lotus Domino Administrator 7 Help

Name
The domain portion of an Internet e-mail address. For
example, the corporation.com portion of the e-mail
address JUser@corporation.com
Protocol
SMTP mail transactions use the domain portion of an
Internet e-mail address. This domain name must also be
entered in the Global Domain document. MX records
must designate the IP addresses for the servers receiving
SMTP mail.

For information on the Domain Name Service (DNS) and MX records, see the chapter ″Overview of the
Domino Mail System.″

For more information on the Domain Name System (DNS) and MX records, see the topics The Domain
Name System (DNS) and SMTP mail routing and Examples of using multiple MX records.

Deciding which applications to offer multiple hosted organizations

In addition to deciding which protocols and services to offer, you must decide which applications to host.
You can make a single application available to multiple hosted organizations; you can offer individual
applications to each hosted organization; or, you can offer a combination of the two.

Suggested criteria
Prior to choosing and installing applications for hosted organizations, do the following:
1. Decide how to track the applications available to each hosted organization. Lotus Notes/Domino 7
does not include an application to track installed applications.
2. Evaluate applications. For example, if an application is Notes-based, it may need to access external
files, or, it may be a Java application.
3. Evaluate the reliability of the application. Is the application reliable or does it cause the server to stop
or crash? Determine the impact, if any, that each application has on server performance.
4. Determine if the application presents any security risks. Ensure that the application does not allow
users to navigate the file system or add or run their own executable programs.
5. Evaluate how well the new application integrates with the existing configuration.
6. Test each application on a non-production server before installing it on an xSP server. Make sure that
each application is easy to install for each hosted organization.

Note: Domino does not support the use of servlets for xSP servers.

Using activity logging for billing at hosted organizations

Using activity logging, you can collect data about the server activity generated by users -- such as, user
activity on a POP3 server -- and server activity not generated by users -- such as, replication of a hosted
organization’s databases. The log file (LOG.NSF) records activity logging data. To create reports of
activity data, write a Notes API program to access the information in the log file.

Note: The activity logging C API is included in the Lotus C API Toolkit for Domino and Notes 7. This
public C API can be used to read activity data.

For more information on activity logging, see the chapter ″Setting Up Activity Logging.″

Activity records
Many sessions that the Domino server hosts last for an extended period of time. To avoid losing activity
information, many activity types generate regular checkpoint records. For example, a two-hour Notes
session creates eight records: one open record, six checkpoint records and one close record, assuming that
the default checkpoint interval of 15 minutes is used. You need only review the most recent checkpoint
record for any activity because each checkpoint record shows all logged activity data.

Chapter 14. Planning the Service Provider Environment 401

Billing methods
You will want to consider various billing methods based on your business requirements. Consider one of
these billing methods:
v Number of users at the hosted organization site.
v Number of users at the hosted organization site, plus disk space usage.
v Actual use. To collect activity data by database, use activity logging. To collect the data by individual
hosted organization, use the activity logging API to write a custom application that sorts the data by
hosted organization. Then, you can bill each hosted organization accordingly.

Example of planning a hosted environment

xSP International is a Domino service provider that plans to host Web applications and offer services and
protocols to many hosted organizations. To configure the hosted environment, xSP international plans to
set up a Domino domain that includes clustered servers, allowing them to define physical storage
locations, other than the default, for their hosted organizations.

xSP International plans to support SSL; therefore, they will use unique IP addresses. They begin by
installing two servers in their Domino domain: Server1 and Server2. Although each server will contain
data for multiple hosted organizations, the data for each individual hosted organization will reside on
only one server. The data for a hosted organization will not be distributed across multiple servers.
Identical applications will run on each server. If needed, xSP International can add additional servers to
this configuration.

The following figure illustrates this configuration.

xSP International will initially register four hosted organizations in this domain. To set up the first hosted
organization, CompanyA, the service provider administrator does the following:

402 Lotus Domino Administrator 7 Help

1. Reads the topic ″Installing the first server or additional servers for hosted environments″ prior to
installation. After reading all of the information in the chapters listed in Step 2, the service provider
completes the ″Installing the first server or additional server for hosted environments″ procedure.
2. Reads the information in the chapter ″Deploying Domino″ and then reads the chapter ″Installing and
Setting Up Domino Servers″. After installing the initial xSP server, the service provider completes as
many procedures from these chapters as necessary.
3. Determines that a billing strategy based on actual usage suits the requirements of CompanyA and xSP
International.
4. Enables activity logging on all servers in the domain.
5. Uses the activity logging API to write a custom application to sort data by hosted organization so that
xSP International can bill each hosted organization according to actual usage.

Chapter 14. Planning the Service Provider Environment 403

404 Lotus Domino Administrator 7 Help
Chapter 15. Setting Up the Service Provider Environment
This chapter explains how to set up a hosted organization, lists and explains the files and documents
created when you register a hosted organization, and provides other related information.

Setting up the service provider environment

Setting up the service environment consists of understanding the information presented in the topics
below so that you can make decisions based on the services you are providing to customers, as well as
completing the tasks in the topics listed below.
v Installing the first server or additional servers for hosted environments
v Setting up the Domino Certificate Authority for hosted organizations
v Using Policy Documents in a hosted environment
v What happens during hosted organization registration?
v Binding the IP addresses of the hosted organization to the xSP server
v Creating Loopback addresses in a hosted environment
v Using Internet Site documents in a hosted environment
v Configuring Internet sites with Web Site and Internet Site documents
v Using Global Web Settings documents
v Configuring activity logging for billing hosted organizations

Installing the first server or additional servers for hosted environments

All servers in an xSP domain run as xSP servers; therefore, you only use the ″-asp″ portion of the setup
command when you install the first server in an xSP domain. All servers subsequently installed into the
domain are automatically configured as xSP servers.

Configuring the first or an additional server for a hosted environment does the following:
v Creates an All Servers Configuration Settings document if there is no Configuration Settings document.
v Modifies the All Servers Configuration Settings document to set proper defaults for service providers.

CAUTION:
Do not delete the All Servers Configuration Settings document for your hosted environment. If you
do so, you will be unable to delete or create hosted organizations. Instead, just modify the All Servers
Configuration Settings document and then save the revised document.
v Sets up an extended ACL for the Domino Directory (NAMES.NSF) and the Administration Requests
database (ADMIN4.NSF) to limit access to only users and/or administrators in the same hosted
organization.
v Modifies the Server document to set proper defaults for service providers.
v Sets the ACL on databases in the data directory.
v Modifies a server-specific Configuration Settings document (if one exists) to set defaults for service
providers.
v Modifies the database ACL for Anonymous from ″NoAccess″ to ″Reader.″

The service provider configuration provides services to multiple hosted organizations from a single
Domino Directory.

Before performing this procedure, see the chapter ″Installing and Setting Up Domino Servers.″
1. To install the first xSP server, do one:

405
 v For Win32 systems, run this command from the directory in which the SETUP.EXE file is located:
setup -xsp
v For UNIX, run this command:
install
v At the prompt ″Do you want to configure this server with ASP functionality?, enter
Yes
For more information on installing Domino on UNIX, see the chapter ″Installing and Setting Up
Domino Servers.″
2. Start the server.
3. Choose the Domino Enterprise server setup.
4. As the Setup wizard runs, enter the information appropriate to your configuration.

Setting up a hosted organization

To set up a hosted organization, complete these procedures:
1. (Optional) Set up a server-based certification authority (CA)
2. Create a policy document
3. Create a registration policy settings document
4. Register a hosted organization
5. Bind the IP addresses of the hosted organization to the xSP server
6. Create the necessary Internet Site documents and the Web Site document

Setting up the Domino certificate authority for hosted organizations

When registering hosted organizations, you can use the Domino server-based certification authority (CA).
If you don’t use the server-based CA, you can use Domino’s certifier ID and password for security
purposes.

A CA vouches for the identity of both server and client by issuing Internet certificates that are stamped
with the CA’s digital signature. The digital signature ensures the client and server that both the client
certificate and the server certificate can be trusted. The CA also issues trusted root certificates, which
allow clients and servers with certificates created by different CAs to communicate with each another.

Each hosted organization must have its own Domino CA. If the hosted organization uses DOLS or if they
require Notes IDs, the hosted organization must use the Domino server-based CA. If the hosted
organization administrator plans to use the Web Administrator, that hosted organization must use the
Domino server-based CA to register users.

As part of setting up a CA, create a Certificate Requests database. Then, using the Certificate Requests
database, you can submit Internet certificate requests through a browser, pick up new or renewed
certificates, and receive notification regarding request status.

For more information on the Domino CA and the Certificate Requests database, see the chapter ″Setting
Up a Domino Server-Based Certification Authority.″

Using policies in a hosted environment

Policies are required in a hosted environment. To establish the registration settings that are required for
hosted organizations, create a policy document and a registration policy settings document.

Each hosted organization must have its own, unique registration policy settings document. Multiple
hosted organizations cannot share a registration policy settings document.

For more information on policies, see the chapter ″Using Policies.″

406 Lotus Domino Administrator 7 Help

To meet the requirements for creating policy and registration policy settings documents, you can create
the policy before registering the hosted organization, or you can create the policy during the registration
of the hosted organization.
v To create the policy before registering the hosted organization Create an explicit policy prior to
registering the hosted organization. Create the registration policy settings document before creating the
hosted organization. Before attempting to use the explicit policy, make sure that you have referenced
the appropriate registration policy settings document in that policy document.
v To create the policy while registering the hosted organization Create an organizational policy and a
registration policy settings document when prompted during hosted organization registration. The
Register Hosted Organization user interface displays the documents that you need to create for hosted
organizations during the registration process. These documents are presented in the order in which
they need to be created.

Requirements for the registration settings document for hosted organizations

For a hosted organization, the registration settings documents must include the following settings:
v The Policy Name field must contain a valid registration policy settings document name.
v The Password Quality field must have a value of at least ″Any Password.″ Do not choose ″Password is
optional.″
v ″Set Internet Password″ must be selected.

What happens when you register a hosted organization?

You must use the Register Hosted Organization user interface to register each hosted organization. When
you register a hosted organization, the following files and documents are created:
v The certificate for the hosted organization is created. If a modification to the certificate is ever required,
you can locate the certificate as follows: From the Domino Administrator, click the People & Groups
tab. Click Certificates.
v The hosted organization certificate is cross-certified with the service provider’s certificate. A Cross
Certification document is created. To verify that cross certificates were created, from the Domino
Administrator, click the Configuration tab. Click Server - Miscellaneous - Certificates. Click Notes Cross
Certificates.
v The service provider’s certificate is cross-certified with the hosted organization certificate. A Cross
Certification document is created.
v A Global Domain document is created. The Global Domain document stores the primary Internet
domain name by which the hosted organization is known and stores secondary Internet domain names
by which the hosted organization can receive Internet mail.
v A data directory is created for the hosted organization. This directory is assigned the name that is
specified in the Directory field on the Storage panel of the Register Hosted Organization interface. By
default, for Win32 systems, the hosted organization’s data directory is placed directly beneath
Domino/data. On UNIX systems, the default is /local/notesdata. You can specify another location in
the Physical Storage Location field on the Storage panel of the Register Hosted Organization interface.
v A mail subdirectory for the hosted organization is created beneath the hosted organization’s data
directory.
v A mail file is created for the hosted organization’s administrator. This is an NSF and resides in the mail
subdirectory for the hosted organization.
v An ACL file is created for each hosted organization to provide security for the hosted organization’s
directory. The ACL file prevents users in one hosted organization from traversing a directory that
belongs to another hosted organization. If a hosted organization’s ACL file is deleted, users in other
hosted organizations may be able to review the content of the directories belonging to the hosted
organization that is no longer protected by an ACL file. Do not confuse hosted organization ACL files
with database ACLs, which control server, user, and group access to databases that reside on a Domino
server. The actual databases may or may not be protected according to how individual database ACLs
are set. The ACL file resides in the Domino data directory and is named hosted organization name.ACL.

Chapter 15. Setting Up the Service Provider Environment 407

For more information on setting database ACLs, see the chapter ″Controlling User Access to Domino
Databases.″
v An extended ACL is applied to the Administration Requests database (ADMIN4.NSF) and the Domino
Directory (NAMES.NSF) to restrict access to the data in those databases. The extended ACL is enabled
on the Domino Directory when the first hosted organization is registered.
v The database ACL entry for ″Anonymous″ is changed from NoAccess to Reader access in NAMES.NSF
when the first hosted organization is registered.
v Entries are made for the hosted organization administrator in the database ACLs and the extended
ACLs to allow the hosted organization administrators to Browse, Read, Create, Delete, and Write
documents for their hosted organization.
v Extended ACL entries are created for all users and groups in a hosted organization
(*/HostedOrganizationName) providing Browse and Read access to that hosted organization only.
v An extended ACL entry is created for ″Anonymous″ for each hosted organization with all access
disabled. Entries are also made in the Form and Field Access in extended ACLs with Read Deny
checked for the following fields:
Schema: Domino, Form: Group, Attributes: InternetAddress, MailDomain, Members, and Type.
Form:Person, Attributes: AltFullName, Certificate, FirstName, InternetAddress, LastName, Location,
MailAddress, MailDomain, o, OfficeCity, OfficeCountry, OfficeState, OfficeStreetAddress, OU,
ShortName, UserCertificate, PublicKey, and Type. Schema: LDAP, Form:DominoPerson, Attribute: cn.
If LDAP Anonymous access is allowed to a hosted organization, the above fields match the ″default″
ACL for LDAP set in the Domain Configuration document. This list can be modified. Plan and test
carefully before you modify ACLs and extended ACLs in an xSP environment -- security is extremely
important.

For more information on extended ACLs, see the chapter ″Setting up Extended ACLs″ and for more
information on modifying the default extended ACL settings established during hosted organization
registration, see the topic ″Modifying the extended ACL settings established during hosted organization
registration″ in this chapter.
v An Internet Site document is created for each Internet service for which you provide an IP address or
host name on the Internet panel of the Register Hosted Organization interface. The documents that are
created contain default information for the protocol. You provide additional, detailed information for
these documents during hosted organization registration. If you provide an address or host name for
multiple protocols, you are prompted to create the Internet Site document for each Internet protocol.
You must create the Internet Site document in order to use the corresponding Internet protocol. You are
also prompted to create one Web Site document for each hosted organization. The Web Site document
is the Internet Site document for the HTTP protocol. If a hosted organization has multiple Web sites,
create one additional Web Site document for each additional Web site.

Note: The Basics tab on the Server document contains the field ″Loads Internet configurations from
Server/Internet Sites documents,″ which is enabled by default and cannot be changed in a hosted
environment. When this field is enabled, settings on the Internet Site document take precedence over
settings on the Server document. This field is set when the servers are installed.

For more information on Web Site documents, see the chapter ″Setting up the Domino Web Server.″ For
more information on Internet Site documents, see the chapter ″Installing and Setting Up Domino
Servers.″
v If you are using clustered servers, you can use the Storage panel on the Register Hosted Organization
interface to create additional storage for the hosted organization on one or more servers in the cluster.

Note: The HostedOrganizationAdmin group is created by default (when you set up the hosted
environment) and administrators are automatically added to that group. Administrator groups enable
you to administer groups of people with administrator rights at one time instead of individually
establishing rights and settings for each hosted organization administrator.

408 Lotus Domino Administrator 7 Help

Where to store data for hosted organizations
To decide where to store a hosted organization’s data, evaluate whether you are saving private data or
shared data. Store a hosted organization’s private data in a directory belonging to the hosted
organization. Store shared data in a common data directory accessible to all.

Registering hosted organizations with names requiring a server in UTF-8 locale

If you will be registering hosted organizations that have names containing characters from more than one
character set, the registration server must be run in a UTF-8 locale. For example, if both Korean and
Japanese hosted organization names must be supported, the server must be in a UTF-8 locale. If only the
Japanese hosted organization names are supported, the server can be run in Japanese locale.

Opening databases on an xSP server

When the service provider administrator uses the File - Database - Open menu commands to open a
database, the Open Database dialog box does not list all of the databases on the server, but all of the
databases are available by typing the database name in the Filename field, and then clicking Open. For
convenience, create bookmarks for the most frequently opened databases.

Directory assistance is not supported in a hosted environment

Directory assistance is not supported in a hosted environment. You cannot use Domino’s directory
assistance feature with Domino’s xSP configuration. The Directory assistance database name field on the
xSP Server document should be blank.

Registering a hosted organization

The information that you enter in the fields on the Register Hosted Organization interface is used to
populate many of the documents that define the hosted organization. For example, you select the policy
that applies to the hosted organization from a list of available policies. Otherwise, the policy can be
created during the hosted organization registration process. Additionally, the Internet-related information
determines which Internet Site documents are created for the hosted organization. The Internet Site
documents contain the information needed to run the Internet servers in a service provider configuration
and support all possible configurations of IP addresses and DNS host names. In a hosted environment, a
Site document is required for each protocol that the hosted organization uses.

For more information on the Web Site document, see the chapter ″Setting Up the Domino Web Server″
and for more information on Internet Site documents, see the chapter ″Installing and Setting Up Domino
Servers.″
1. Ensure that you are working with the xSP server you just installed. If you need to change to another
server, choose File - Open Server, or File - Preferences - Administration Preferences to select the
server.
2. From the Domino Administrator, click the Configuration tab.
3. From the Tools pane, click Hosted Org - Create.
4. Enter the certifier’s password, and click OK.
5. Complete these fields on the Basics panel of the Register Hosted Organization interface:

Field Action
Registration Server Enter the name of the server to use during the
registration process. The Domino Administrator contacts
the registration server while performing registration
tasks.

Chapter 15. Setting Up the Service Provider Environment 409

Field Action
Organization name Enter a unique name for the hosted organization. The
name must be fewer than 28 characters and cannot
contain a period (.) because the hosted organization
name is also used as the hosted organization’s virtual
Domino domain name for routing purposes. For
ease-of-administration, use a short name with no spaces.
Organization name is a required entry that is also used
in the Internet Site documents.
Organization supports DOLS Choose this option if the hosted organization supports
Domino Off-Line Services (DOLS).
Password Enter a case-sensitive password for the certifier. The
characters you use for this password depend on the level
set in the Password quality scale.
Password quality Displays the Password Quality Scale that you can use to
define the complexity of the password. Do not choose
″Password is optional.″
Explicit Policy Choose the explicit policy document that is the ancestor
of the registration policy settings document you are
assigning to the hosted organization. Click None
Available if you have not yet created the necessary
policies and/or settings documents.
First Name, Middle Name, Last Name Enter the name of the hosted organization administrator.
Password Enter a password for the hosted organization
administrator.

6. Complete as many of these fields as needed to enable the corresponding protocols for the hosted
organization. When you enter the host name or IP address for a protocol, that protocol is enabled
when the corresponding Site document is created. You are prompted to complete the corresponding
Site document later during this registration process.

Field Action
Internet Domain Enter the name of the Internet domain. By default, the
exact Internet domain name that you specified for this
hosted organization on the Mail tab of the registration
policy settings document is entered. For example,
enterprise.com.
HTTP Host/Address Enter the host name or IP address of the HTTP server for
the hosted organization.
SMTP Host/Address Enter the host name or IP address of the server that
receives SMTP transactions for the hosted organization.
POP3 Host/Address Enter the host name or IP address of the POP3 server for
the hosted organization.
IMAP Host/Address Enter the host name or IP address of the IMAP server for
the hosted organization.
Directory Host/Address Enter the host name or IP address of the LDAP server
for the hosted organization.
IIOP Host/Address Enter the host name or IP address of the Domino IIOP
server for the hosted organization.

410 Lotus Domino Administrator 7 Help

7. Complete these fields on the ID Info panel:

Field Action
CA Enabled Choose this option if the hosted organization supports
DOLS or uses Notes IDs.
CA Server Enter the name of the server on which you created the
Domino CA. This is the server on which the CA process
will create Internet Certificates. This button is active only
if you have created a Domino CA.
Set ID file Specify the drive and directory in which the ID file is to
be stored. By default, the certifier ID name matches the
hosted organization name. The certifier ID must be
unique to the hosted organization.

8. Complete these fields on the Storage panel:

Field Action
Mail Server By default, this field contains the name of the mail server
for the hosted organization exactly as you entered it in
registration policy settings document for the hosted
organization. The hosted organization and the
administrator’s mail file will be stored on this server.
This field cannot be modified.
Directory By default, this field contains the name of the directory
in which the hosted organization’s data resides. For
ease-of-administration, the directory name is created for
you and is identical to the hosted organization name.
This field cannot be modified.
Host Indicates whether the corresponding server hosts the
hosted organization. This field cannot be modified for
the first entry in this list. The first server entry in this list
has a check mark because that server is identified in the
registration policy settings document as the mail server
for the hosted organization.

For all other servers, a check mark in this box identifies

that server as a host server for the hosted organization.
Server Name Name of the server that is hosting the hosted
organization. If multiple server names appear in this list,
the first server in the list is the hosting server; other
servers are the cluster mates.
Physical Storage location The directory name that is displayed is an alternate
location where the hosted organization’s data directory
will reside if you do not use the default location.

Chapter 15. Setting Up the Service Provider Environment 411

Field Action
Physical Storage location for <server name> Use this field to create a directory link to an additional
storage location for the hosted organization you are
registering. This field is activated when you select a
server in the Server Name field. The check box for the
server must be checked in order to select it.

To add a directory link, enter the full path for the storage
location and then click the check box so that the
directory link displays in the Physical Storage Location
field.

To delete a directory link, select the link in the

ServerName/Physical Storage Location fields. When the
path displays in the modifiable ″Physical Storage
Location for <server>″ field, click the X..

9. (Optional) Complete these fields on the Other panel:

Field Action
Location Enter text to define the location of the hosted
organization.
Comment Enter text to define the hosted organization’s name and
other information.

10. If you have not selected an explicit policy for this hosted organization, this message appears:
"You must configure the organizational registration policy
for the hosted organization. This policy must contain the
necessary hosted organization settings. Do you want to
configure that policy now?"
11. Click Yes. If you click No, the hosted organization is not created.
12. Click Register. The Internet Site document for the first protocol you specified appears. Modify the
defaults, and add new information as necessary.

Note: If the hosted organization supports DOLS, on the Web Site document, specify a DSAPI filter file
name according to the operating system of the xSP server that hosts that hosted organization. Win32
requires the file ndolextn; and Linux, AIX, Solaris/Sparc, S390, and iSeries require libdolextn.

For more information on Internet Site documents, see the chapter ″Installing and Setting Up Domino
Servers″ and for more information on the Web Site document, see the chapter ″Setting Up the Domino
Web Server.″

Modifying the extended ACL settings established during hosted organization registration: Plan and
test carefully before you modify ACLs and extended ACLs in an xSP environment -- security is extremely
important.

When hosted organization registration is complete, all actions that are identified in the topic ″What
happens when you register a hosted organization?″ are complete. You may want to enable Read access on
some fields for a hosted organization. To allow Read access to fields for the anonymous entry in a hosted
organization, in the extended ACL settings, change Browse from Deny to Allow. In the Forms and Fields
Access section, select Show Modified, and change the fields from Read Deny to Read Allow.

Note: The individual fields are listed in the topic ″What happens when you register a hosted
organization?″ in this chapter.

412 Lotus Domino Administrator 7 Help

For more information on extended ACLs, see the chapter ″Setting Up Extended ACLs.″

Binding the IP addresses of the hosted organization to the xSP server

If you assign an individual IP address to each hosted organization, use one of the following procedures
to bind the IP address of each hosted organization to the network interface card in the xSP server. This
procedure applies only to configurations that include unique IP addresses.

For more information on the IP configurations that you can use in a hosted environment, see the chapter
″Planning the Service Provider Environment.″

SUNSolaris: Enter these commands as the root user, where <hme0> is the network interface card.

ifconfig <hme0>:1 plumb

ifconfig <hme0>:1 <hosted_company1_ip> <server_ip> up

ifconfig <hme0>:2 plumb

ifconfig <hme0>:2 <hosted_company2_ip> <server_ip> up

ifconfig <hme0>:x plumb

ifconfig <hme0>:x <hosted_companyx_ip> <server_ip> up

IBM AIX: Enter the following command as the root user, where <en0> is the network interface card.

ifconfig <en0> alias <IP address of hosted organization> netmask 255.0.0.0

Microsoft Windows 2000:

1. From the Windows 2000 desktop, right-click the Network Neighborhood desktop icon and choose
Properties.
2. Right-click the Ethernet adapter, and then select Properties.
3. From the Adapter Properties box, double-click Internet Protocol (TCP/IP).
4. Click Advanced.
5. Click Add to add additional hosted organization IP addresses. Accept the default subnet mask of
255.0.0.0.

Creating loopback addresses in a hosted environment

If you use a network router in the xSP configuration and you assigned a unique IP address to each
hosted organization, you must create a loopback address for each hosted organization. The instructions
vary by platform.

SUN Solaris: Enter these commands as the root user:

ifconfig <lo0>:1 plumb

ifconfig <lo0>:1 <hosted_company1_ip> <server_ip> up

ifconfig <lo0>:2 plumb

Chapter 15. Setting Up the Service Provider Environment 413

ifconfig <lo0>:2 <hosted_company2_ip> <server_ip> up

ifconfig <lo0>:x plumb

ifconfig <lo0>:x <hosted_companyx_ip> <server_ip> up

IBM AIX: Enter this command as the root user:

ifconfig <lo0> alias <IP address of hosted organization> netmask 255.0.0.0

Microsoft Windows 2000:

1. From the Windows 2000 desktop, right-click the Network Neighborhood icon, and choose Properties.
2. Right-click the Ethernet adapter and choose Properties.
3. From the Adapter Properties box, double-click Internet Protocol (TCP/IP).
4. Click Advanced.
5. Click Add to add an additional IP address. Accept the default subnet mask of 255.0.0.0.

Example of registering a hosted organization

In this example, Acme Printing, a small business, subscribes to messaging services and some
transaction-processing services offered by xSP International, a Domino service provider.

To register Acme Printing as a hosted organization, the service provider administrator at xSP
International answers these questions:
v Does Acme Printing support DOLS users? Do they need Notes IDs? If Acme Printing supports DOLS
or needs Notes IDs for any purpose, a Domino CA needs to be created for the hosted organization. If
not, they can use certifier IDs and passwords. Acme Printing does support DOLS users.
v Which mail protocol does Acme Printing use? If they use POP3 or IMAP, they need SMTP on the same
server. Acme uses POP3, so they need SMTP.
v Which registration settings are needed for the registration policy settings document for Acme Printing?
The service provider administrator determines that Acme Printing needs the CA-related settings and
POP3-related mail settings. Other default settings can also be used.
v Does Acme Printing require storage locations in addition to the default storage locations? If the service
provider administrator set up Acme Printing on a clustered server, they’ll be able to use additional
storage on servers in the cluster. On what server and directory will that storage be located?
v Later, when an administrator is ready to register users for the hosted organization, they can determine
whether they can simplify user registration by creating additional policy settings documents, such as
desktop policy settings documents and security policy settings documents. An administrator can create
these policy settings documents as he would for any Lotus Domino enterprise. User registration for
Acme Printing employees is done by the service provider administrator instead of by an Acme Printing
administrator using the Web Administrator.

The service provider administrator at the service provider site, does the following from the Domino
Administrator:
1. Creates a Domino server-based CA for Acme Printing because they support DOLS. Each hosted
organization that needs a server-based CA requires its own Domino CA because the CA cannot be
shared across multiple hosted organizations.
2. Creates an explicit policy named AcmePolicy and an associated registration policy settings document.

414 Lotus Domino Administrator 7 Help

3. Chooses Tools - Hosted Organization - Create to open the Register Hosted Organization interface.
4. The service provider administrator begins completing the required fields on each panel and enters
information in these optional fields:
v On the Basics panel, selects the option ″Organization supports DOLS″ and chooses the explicit
policy named AcmePolicy.
v On the Internet panel, enters an IP address in the HTTP Host/Address, SMTP Host/Address, POP3
Host/Address, and Directory Host/Address fields because Acme requires these for its Web site, for
POP3 messaging with SMTP, and for LDAP services, respectively.
v On the ID Info panel, chooses CA Enabled and chooses the CA Server on which the Acme CA was
created because Acme supports DOLS users.
v On the Storage panel, because Acme will be hosted on a clustered server at the service provider site
he enters an additional physical storage location in ″Physical Storage location for server name″.
5. After entering information in the Register Hosted Organization interface, clicks the Register button.
6. Completes the Web Site document, the POP3 Site document, the SMTP Site document, and the LDAP
Site document. While completing the Web Site document, the service provider administrator follows
the instructions for enabling the correct DSAPI filter file name to support DOLS.
For more information on specifying the DSAPI filter file name in the Web Site document, see the
chapter ″Installing and Setting Up Domino Servers.″
7. Completes the procedure to bind the hosted organization’s IP address to the Network Interface Card
on the xSP server because the IP Address configuration includes individual IP addresses for each
hosted organization.
8. Checks the following views and directories to see the documents and files that have been created for
the hosted organization, Acme Printing.
v From the Domino Administrator, People & Groups tab, he clicks Certificates to verify that Acme
Printing’s certificate has been created. He also verifies that Acme Printing’s certificate is
cross-certified with xSP International’s certificate, and that xSP International’s certificate has been
cross-certified with Acme Printing’s certificate.
v From the Domino Administrator, he opens the Domino Directory and chooses Servers - Domains to
see the Global Domain document for the Acme Printing. On the Basics tab, the field ″Local primary
Internet domain″ contains the primary Internet domain name by which the hosted organization is
known. He also enters a secondary Internet domain name in the ″Alternate Internet domain aliases″
field by which Acme Printing can receive Internet mail.
v Verifies that the hosted organization’s data directory was created, as well as the hosted
organization’s mail directory. The service provider administrator also verifies that the ACL file,
Acme Printing.acl was created and that the mail file for the hosted organization’s administrator has
been created.
v From the Domino Administrator, he opens the Domino Directory and checks the Server - Internet
Sites view. The service provider administrator sees that these documents exist for Acme: Web Site
document, SMTP Site document, POP3 Site document and LDAP Site document. This view also
contains a Global Web Settings document for xSP International and three Web Site Rule documents.
v From the Domino Administrator, opens the Policy view and checks the explicit policy (AcmePolicy)
and the associated registration policy settings document (Acme).

Using Internet and Web Site documents in a hosted environment

The Internet Site documents and the Web site document contain configuration settings for the Internet
protocols. A Site document is created for each protocol for which you enter an IP address or a host name
on the Internet panel of the Register Hosted Organization interface. The Site document is created
containing default information; you must to enter additional information in each Site document either
during hosted organization registration or later. The Internet protocol is not active until the corresponding
Internet Site or Web Site document is completed and saved.

Chapter 15. Setting Up the Service Provider Environment 415

The Site documents contain the information needed to run the Internet servers in a service provider
configuration. They support all possible configurations of IP addresses and DNS host names.

Internet Sites view

Using the Internet Sites view, you can view all Internet Site documents, sorted according to hosted
organization name. The Global Web Settings documents and Web Site Rule documents also display in this
view. The following table describes each document shown in the view.

Internet Site document Description

Web Site document Web Site documents are generated for the HTTP protocol. Each
hosted organization has one Web site document that can be
created during hosted organization registration. If a hosted
organization has multiple Web sites, you must create one Web
Site document for each additional Web site.
Note: See the chapter ″Installing and Setting Up Domino
Servers″ for information on configuring Web Site documents.
IMAP Site document These are the mail protocol Internet Site documents. An
individual Internet Site document is created for each mail
POP3 Site document protocol for which you enter an IP address on the Internet
panel of the Register Hosted Organization interface.
SMTP Inbound Site document
LDAP Site document This document is generated for LDAP servers.
IIOP Site document Domino IIOP (DIIOP) uses the information in the IIOP Internet
Site document to define the scope of the Domino Directory
used to validate users. DIIOP enables you to use any Java code
running on any server on the network. DIIOP is not yet
supported in a shared IP address configuration.
Global Web Settings document The Global Web Settings document applies one or more Web
Site Rule documents to all servers in the Domino domain or
only to specified servers in the Domino domain. The Global
Web Settings document is automatically created during setup
of a hosted organization.
Web Site Rule document The Web Site Rule document is created from within the
corresponding Web Site document. The three Web Site Rule
documents that are automatically created in a hosted
environment are DOLS, iNotes help files, and iNotes.cab.

Viewing Web Site and Internet Site documents for a hosted organization
1. From the Domino Administrator, click Files and open the Domino Directory (NAMES.NSF).
2. Choose Server - Internet Sites.
3. Select the name of the hosted organization whose Internet Site documents you want to view.
4. Double-click a document name to open it.
For more information on creating an Internet Site document, see the chapter ″Installing and Setting
Up Domino Servers″ and for information on creating a Web Site document, see the chapter ″Setting
Up the Domino Web Server.″

Configuring Internet sites with Web Site and Internet Site documents
In a hosted environment, each Internet Site document defines the configuration settings for an Internet
protocol for a hosted organization. When you register a hosted organization, you are prompted to create
one or more Internet Site documents as part of the hosted organization registration process.

Note: You have the option of not creating the Internet Site document during hosted organization
registration. You must then create the Internet Site document in order to use the protocol.

416 Lotus Domino Administrator 7 Help

For more information on Internet Site documents, see the topic ″Using Internet and Web Site documents
in a hosted environment″ in this chapter.

A Web Site document is required for the HTTP protocol. You are prompted to create one during the
hosted organization registration process. If multiple Web sites are assigned to one IP address -- that is,
multiple DNS names are registered to one IP address -- create a Web site document for each Web site.

Note: If the hosted organization supports DOLS, on the Web Site document, specify a DSAPI filter file
name according to the operating system of the xSP server that hosts that hosted organization. Win32
requires the file ndolextn; and Linux, AIX, Solaris/Sparc, S390, and iSeries require libdolextn.

For more information on specifying the DSAPI filter file name in the Web Site document, see the chapter
″Installing and Setting Up Domino Servers.

For security purposes, you can create a File Protection document for each server. A File Protection
document controls the access that Web browser clients have to the files on a server’s hard drive. Create
the File Protection document after creating any Web Site document(s) and/or Internet Site documents
that you need.

For more information on File Protection documents, see the chapter ″Controlling Access to Domino
Servers.″

Global Web Settings documents and the service provider environment

Domino automatically creates a Global Web Settings document when you install the Lotus Domino
service provider software. The Global Web Settings document is associated with three Web Site Rule
documents that automatically create several directories that may be required by numerous users at any
hosted organization. The Web Site Rule documents make files accessible from one central location on the
server, so that these files do not need to be individually downloaded for each hosted organization. The
benefit is a substantial savings in disk space because the service provider can provide the files to all users
that need them without having to duplicate them for each individual hosted organization.

By default, the Global Web Settings document applies to all servers in a Domino domain. If you do not
want the Global Web Settings to apply to all servers in a Domino domain, edit the document and specify
the servers to which the document applies.

The directories that are created via the Global Web Settings document reside in the hosted
organization\domino\ directory path.

Three associated Web Site Rule documents that contain the following settings are created when the
Global Web Setting document is created in a hosted environment:

Web Site Rule document Type of rule Incoming rule pattern Target server directory
DOLS Directory /download/* domino\html\download
iNotes help files Directory /inotes5/help/* domino\html\inotes5\help
iNotes.cab Redirection /iNotes.cab domino\html\iNotes.cab

The Web Site Rule document for DOLS-enabled hosted organizations downloads to a central location files
that are required when the hosted organization tries to access a DOLS-enabled database.

The iNotes.cab file is an archive file that contains controls that are installed into a browser and make
iNotes features available to browsers.

The iNotes help files are downloaded to a central location on the server so that they do not have to be
individually downloaded for each hosted organization.

Chapter 15. Setting Up the Service Provider Environment 417

The Global Web Settings document and the Web Site Rule documents appear in the Internet Sites view.
You can be review, edit, or delete them from this view.

Editing a Global Web Settings document

Edit the Global Web Settings document to apply one or more Web Site Rules to one or more servers in a
Domino domain.
1. From the Domino Administrator, click the Files tab.
2. Open the Domino Directory (NAMES.NSF).
3. Choose Server - Internet Sites.
4. Select the Global Web Settings document that you want to modify, and click Edit Global Web Settings.
5. On the Basics tab, edit these fields as necessary:

Field Action
Descriptive name for this site Enter a name that describes the Web Site Rules that will be associated
with this document.
Domino servers that host this site Enter one:
v An asterisk (*) if the document is to apply to all servers in the
Domino domain.
v One or more names of servers to which this document applies.

6. Click Save and Close.

Configuring activity logging for billing hosted organizations

You can configure activity logging to collect transaction information that is stored in the log file
(LOG.NSF) and can be used for billing purposes. Set up the Configuration Settings document to enable
activity logging on specific servers that you designate. You can enable activity logging on one server, or
more than one server, or on all servers in your domain.
1. From the Domino Administrator, click Configuration - Server - Configurations.
2. Do one of these:
v To enable activity logging on all servers in the domain, open the existing All Servers Configuration
Settings document.
v To enable activity logging on all servers except one (or a small number of servers), open the
existing All Servers Configuration Settings document and complete the fields on the Activity
Logging tab as shown below. Click Add Configuration to create a new Configuration Settings
document for each server that is an exception to the settings in the All Servers Configuration
Settings document. Disable activity logging for the servers on which you are not running activity
logging.
v To enable activity logging for one server, create a Configuration Settings document.
3. On the Activity Logging tab, complete these fields:

Field Action
Activity logging is enabled Select this check box to enable activity logging on each
server that you designate.
Enabled Logging Types Select all logging types for which you want to collect
billing information.
Checkpoint interval Enter the number of minutes that transpire between
activity logging updates to LOG.NSF. The checkpoint
interval applies to the logging types that you selected
and that have open, active sessions.

418 Lotus Domino Administrator 7 Help

Field Action
Log checkpoint at midnight (Optional) Select this check box to create Notes session
and Notes database checkpoint records every day at
midnight.
Log checkpoints for prime shift (Optional) Select this check box to create Notes session
and Notes database checkpoint records at the beginning
and end of a specific time period. Specify the start and
end times for the time period.

4. Click Save and Close.

Viewing logged activity data in a hosted environment

By default, logged activity data is stored in binary format in the log file, LOG.NSF. A service provider
administrator can create a Results database to view the logged data for a hosted organization.
1. From the Domino Administrator, click the Server - Analysis tab.
2. From the Tools panel, click Analyze - Activity.
3. On the Server Activity Analysis dialog box, complete these fields:

Field Action
Select server activity types to search for Click the check box to and then do one of these:
v Select an activity type to view, and then click Add. Repeat to
continue adding types.
v Click Select All to view all activity types.
Start Date Select the start date and end date of the time period for which you
want to analyze logged activity data. Activity data for the time
End Date period you specify is stored in the Results database.
Start Time Select the start time and end time of the logged activity data you
want to analyze. Activity data for the specified time period is
End Time stored in the Results database.
Results Database Do the following:
1. Click this button to open the Results Database dialog box.
2. Specify the server on which the Results database will reside, the
title (name) of the database, and the file name.
3. Click OK.

4. Choose one:
v Append to this database -- To append the data to the existing Results database.
v Overwrite this database -- To overwrite the data in the existing Results database with new data.
5. Click OK. When the message box displays ″Analysis Completed,″ click OK. The Log Analysis - Log
Events view opens.

Chapter 15. Setting Up the Service Provider Environment 419

420 Lotus Domino Administrator 7 Help
Chapter 16. Managing a Hosted Environment
This chapter contains instructions for moving a hosted organization from one server to another,
modifying the Server document, adding a hosted organization to a server to provide new Web
applications, viewing hosted organizations, using the Web Administrator to manage users and groups at
a hosted organization site, and performing other actions required to maintain a hosted environment.

Maintaining hosted organizations

As a service provider administrator, maintaining the hosted organizations in your hosted environment is
of primary importance. Responsibilities include maintaining the servers that host your organizations,
maintaining the hosted organizations and their data, as well as the users at those sites.

The majority of the administration activities that are performed in a hosted environment are exactly the
same as the same activities in a non-hosted environment. The following topics explain how to complete
activities that are unique to or different in a hosted environment. Where necessary, there is also
explanatory information.
v Adding a hosted organization to an additional server to provide new Web applications
v Deleting a hosted organization
v Disabling services temporarily for a hosted organization
v Enabling anonymous access to a hosted organization’s database
v Managing Users at a hosted organization
v Moving a hosted organization from one server to another server
v Removing a hosted organization from a backup or load-balancing server
v Restoring a hosted environment after a server crash
v Temporarily disabling services for a hosted organization
v Using a browser to access a hosted organization’s Web site
v Using the Resource Reservations database in a hosted environment
v Viewing a hosted organization
v Web Administration from the hosted organization site

Using a browser to access a hosted organization’s Web site

Use a browser to access a hosted organization’s Web site; include the name of the hosted organization’s
directory in the URL. Use this syntax:
http://Web_site_name/hosted_organization/database_name

For example, to access the home page for the hosted organization Acme Printing, enter:
www.acmeprinting.com/acme_printing/homepage.nsf

For example, to access your own mail file named JSMITH.NSF, at the hosted organization named Acme
Printing, enter:
www.acmeprinting.com/acme_printing/mail/jsmith.nsf

Note: You can use a Web Site document to redirect users to other Web sites.

For more information on redirecting users to other Web sites, see the chapters ″Setting Up the Domino
Web Server″ and ″Installing and Setting Up Domino Servers.″

421
Adding a hosted organization to an additional server to provide new
Web applications
A hosted server environment can be configured to allow multiple servers to provide Web applications to
one or more hosted organizations. Part of managing a hosted environment is enabling additional servers
to serve Web applications to a hosted organization. Web applications can be distributed across multiple
servers, while serving as many hosted organizations as you designate.

You can enable a hosted organization that is currently being served applications by one or more servers
to be served a Web application by an additional server.

To add a hosted organization to an additional server to provide new Web

applications
1. Create a data directory for the hosted organization on the target server.
2. Create an ACL file for the hosted organization in the data directory of the target server.
3. Create a Web Site document for the hosted organization, where the new Web Site document’s DNS
name resolves to the target server’s IP address or name. This new Web Site document allows servers
and routers to distinguish between servers. Use the Basics tab on the new Web Site document to enter
the host names or addresses that map to the site and the Domino servers that host the site.
4. To support the hosted organization, make other Web application-specific modifications -- for example,
configure the Welcome page.
5. For Web applications only, create the DNS names that direct users to this server and to this hosted
organization’s Web site.
For more information on setting up a Web Site document, see the chapter ″Setting Up a Domino Web
Server.″

Restoring a hosted environment after a server crash

To recover quickly from various system failures and server crashes, implement transaction logging in the
hosted environment. Also, create a daily backup so that you can restore current data if necessary.

Restoring the Domino Directory and extended ACLs

If the Domino Directory in a hosted environment becomes corrupted, you also lose the extended ACLs
for NAMES.NSF and for ADMIN4.NSF. Restart the servers so that transaction logging will restore the
data, including the content of the Domino Directory. You cannot recreate the Domino Directory from the
template. You must use transaction logging and/or a recent backup of NAMES.NSF in order to restore
the Domino Directory and the extended ACLs.

If you are not using transaction logging, restore the Domino Directory from the most recent daily backup.

For more information on transaction logging, see the topics Transaction logging and How transaction
logging works.

For more information on transaction logging, see the chapter ″Transaction Logging.″

How the Domino service provider software responds to a DNS outage

The Domino service provider software can withstand DNS outages. After the Internet Site documents
have been loaded into the Domino ASP cache, on subsequent loading of the cache, if there are any
DNS-lookup errors, cache entries are not immediately removed but are instead removed slowly over
time. DNS-lookup errors occur when DNS is unavailable or host names cannot be resolved into IP
addresses. If there are any invalid host names in your Internet Site documents or if DNS is unavailable,
then the DNS recovery code is activated. Cache deletions then require more time -- up to two hours.

For example, a cache deletion results when you remove an IP address or host name from an Internet Site
document or remove a server from the list of Domino servers that host the site.

422 Lotus Domino Administrator 7 Help

The Domino service provider software recognizes Internet Site documents during the resulting time-out
period. To minimize this recovery time-out, ensure that there are no invalid host names in your Internet
Site documents. If there are no invalid host names and DNS is available, then cache deletions occur
within five minutes.

The following console message is logged if there are invalid host names in the Internet Site documents
(excluding the Web Site document):
Lookup of IP address for host hostname.com failed

Deleting a hosted organization

The service provider administrator is responsible for deleting a hosted organization when the hosted
organization stops subscribing to a service provider’s services. When you delete a hosted organization,
the following documents, files, and directories for the hosted organization are deleted:
v Data directory
v Cross certificates
v ACL file
v Extended ACL entries in the Domino Directory’s ACL file
v HostedOrganizationAdmins group
v Global Domain document
v Internet Site documents
v Policy document

To delete a hosted organization

1. From the Domino Administrator, click the Configuration tab.
2. Click Tools - Hosted Organization - Delete.
3. Select the name of the hosted organization to delete.
4. Choose one of these Processing types:
v Immediately clean up Domino Directory -- To remove all references to the hosted organization from
the Domino Directory immediately
v Use Administration Process only -- To remove all references to the hosted organization from the
Domino Directory when the ″Delete hosted organization″ administration request runs

Note: Both processing types generate administration requests and both require that you open the
Administration Requests (ADMIN4.NSF) database and approve the deletion of hosted organization
storage.
5. Click OK. You are prompted to confirm the deletion. Click Yes, and then click OK.

To approve the deletion request

1. Click the Server - Analyses tabs.
2. Click Administration Requests (7).
3. Open the ″All Requests by Name″ view.
4. Open the ″Approve Deletion of Hosted Organization Storage″ request.
5. Click Edit Document. Click ″Approve Hosted Organization Storage Deletion″ to approve the request.
6. Click Yes, and then click OK.

Temporarily disabling services for a hosted organization

To disable all Internet services for a hosted organization, use the Internet Site documents to set all
authentication options to No for all Internet protocols for a hosted organization. To enable Internet
service for that hosted organization at a later time, set the authentication options to Yes.
1. From the Domino Administrator, choose Files and open the Domino Directory (NAMES.NSF).

Chapter 16. Managing a Hosted Environment 423

2. Choose Servers - Internet Sites.
3. Select the Internet Site document that contains the settings you want to modify, and click Edit
Document.
4. Click Security. Set the ″Anonymous″ and ″Name and Password″ fields to No to disable the service for
the hosted organization. To enable the service at a later time, reset these same fields to Yes.
For more information on the Authentication fields on the Security tab of the Site documents, see the
chapter ″Installing and Setting Up Domino Servers.″

Enabling anonymous access to a hosted organization’s database

To make a hosted organization’s database available to anonymous Web site users, add ″Anonymous″ to
the ACL file. Adding Anonymous to the ACL file does not expose all of the hosted organization’s data to
anonymous users. For example, anonymous Web users cannot browse a hosted organization’s directory
because browsing is disabled.

Do not confuse an ACL file, which provides security for the hosted organization itself, with a database
ACL, which controls the access that server, users, and groups have to a database.

Sample ACL file

The content of a sample ACL file for a hosted organization named company1 with Anonymous access is
shown below.
.
ASP Admin/ASP
*/company1
Anonymous
LocalDomainServers
LocalDomainAdmins
[owner=company1]

In addition to modifying the ACL file, modify the hosted organization’s database ACL to allow
anonymous access to the database.

For more information on modifying a database ACL, see the chapter ″Controlling User Access to Domino
Databases″ and for more information on modifying the Web Site document security settings, see the
chapter ″Installing and Setting Up Domino Servers.″

Preventing users from viewing ADMIN4.NSF in a hosted environment

By default, access to the Administration Requests database (ADMIN4.NSF) is set to ″Author″ for hosted
organization administrators and for -Default-. With this level of access, anyone with a Notes ID at a
hosted organization can open ADMIN4.NSF with a Notes client and view user activity in the database.
This is a security risk.

To prevent users at a hosted organization site from accessing ADMIN4.NSF, do the following:
1. As the service provider administrator, open ADMIN4.NSF and select File - Database - Properties.
2. Select the i Tab and click User Detail.
3. In the User Activity interface, select the check box ″Activity is confidential.″
4. Click OK. Click X to close out of Properties.

Moving a hosted organization to another server

You may need to modify some of the procedures in this section to better fit your individual
configuration. For example, you may need to modify your network router configuration if your
configuration includes a network router.

424 Lotus Domino Administrator 7 Help

Moving a hosted organization that has a unique IP address varies somewhat from moving a hosted
organization that has a shared IP address.

Moving a hosted organization that has a unique IP address

To move a hosted organization that has a unique IP address, complete these procedures:
1. Re-create the hosted organization infrastructure on the destination server.
2. Open the registration policy settings document for the hosted organization that you are moving and
change the original mail server name to the name of the destination server -- that is, the new mail
server.
3. Use the Domino Administrator to move databases and move users that have mail files from the
source server to the destination server.
4. Prohibit access to the source server.
5. Move non-database files from the source to the destination server.
6. Enable access to the destination server.
7. From the source server, remove the infrastructure for the relocated hosted organization.

Moving a hosted organization that has a shared IP address

To move a hosted organization that shares an IP address with other hosted organizations, you must
change the IP address of the hosted organization that you are moving. In addition, you must modify the
server information in the documents, as well as the DNS entries for the hosted organization you are
moving. DNS entries are often cached and may require a substantial amount of time to process a change.

Complete these procedures:

1. Prohibit access to the source server.
2. Enter the destination server name in the ″Domino servers that host this site″ field in all of the Site
documents for the hosted organization.
3. Create a hosted organization infrastructure on the destination server.
4. Open the registration policy settings document and change the original mail server name to the name
of the destination server -- that is, the new mail server.
5. For users who have mail files, use the Domino Administrator to move the users from the source
server to the destination server.
6. Move nondatabase files from the source server to the destination server.
7. Enable access to the destination server.
8. Remove the infrastructure from the source server.

To create the hosted organization’s infrastructure on the destination server

1. On the destination server, do one of these:
v Create a subdirectory of the data directory. The new subdirectory name must be identical to the
subdirectory name on the source server.
v Create a new data directory and a directory link.
2. If any directory links, database links, or Web site directory references are located outside of the hosted
organization’s subdirectory, create new directories for those links.
3. Copy the hosted organization’s ACL file from the source server’s data directory to the destination
server’s data directory.
4. If any Web application requires a ″per hosted organization infrastructure,″ create that infrastructure.

To edit the hosted organization’s registration policy settings document

1. From the Domino Administrator, open the Domino Directory.
2. Choose Policies - Settings.
3. Select the registration policy settings document you want to edit.

Chapter 16. Managing a Hosted Environment 425

4. Click Edit Settings.
5. On the Mail tab, choose the name of the destination mail server from the list displayed in the ″Choose
the mail server″ field.
6. Click Save and Close.

To move the mail file and other databases

CAUTION:
During this procedure, do not approve the mail file deletion in the Administration Requests database
(ADMIN4.NSF) If you approve the deletion too soon, the user will not have access to the mail file on
the source server. Approve the mail file deletion later, when doing so will not impact user access to
the mail file.
1. Make sure that you and the source server have Create Replica access to the destination server.
2. From the Domino Administrator, click People & Groups.
3. Select the person whose mail file you are moving.
4. From the Tools panel, click People - Move.
5. Enter the destination mail server name in the Destination field. Include the hosted organization
subdirectory.
6. Select the server and paths on which you want to create mail files. Replicas will be created at the
location you select.
7. Click OK.
For more information on moving mail files, see the chapter ″Setting Up and Managing Notes Users.″

To enable access to the destination server

1. Associate the hosted organization’s IP address with the destination server according to your particular
setup. You may need to update host files, DNS server settings, and the IP address assigned to the
TCP/IP stack.
2. You may need to stop and restart the server depending on your TCP/IP stack. Whether or not you
can modify the IP addresses that are served without restarting the server depends on your individual
configuration.

To prevent access to the source server

Complete this procedure after you have successfully initiated as many ″Move mail file″ actions as
necessary. This procedure applies only to moving a hosted organization that has a unique IP address.
1. Shut down the Domino server on the source server.
2. Disassociate the hosted organization’s IP address from the source server. You may need to modify
host files or DNS server settings, as well as the IP address assigned to the TCP/IP stack.

To move non-database files from the source server to the destination server
1. Copy all database files from the source server to the destination server.
2. From the source server, recursively delete the non-database files that you copied to the destination
server.
3. Copy all non-database files in directories that are not within the hosted organization’s data directory.
Copy the files from the source server to the destination server.
4. Determine whether any Web application requires per-hosted-organization data that has not already
been copied. Copy that data to the destination server, and then delete it from the source server.
5. (Optional) Replicate the data from the source server to the destination server to ensure that all
changes made to the source server appear on the destination server.
6. Change the IP addresses hosted by the destination server to include the new addresses -- that is, those
formerly hosted by the source server. Modify all Internet Site documents as necessary.
7. Restart the Domino server on the destination server.

426 Lotus Domino Administrator 7 Help

 For more information on the Internet Site documents, see the chapters ″Setting Up the Service
Provider Environment″ and ″Installing and Setting Up Domino Servers.″ For more information on the
Web Site document, see the chapter ″Setting Up a Domino Web Server.″

To remove the infrastructure from the source server

1. Open the Administration Requests database (ADMIN4.NSF) and approve the requests to delete the
source databases. When all requests have been successfully processed -- that is, when the databases
have been deleted -- proceed to the Step 2.
2. Delete the hosted organization’s subdirectory from the source server.
3. Delete any directories that are specific to the hosted organization and that reside outside of the hosted
organization’s data directory.
4. Delete the hosted organization’s ACL file from the data directory on the source server.
For more information on approving administration requests, see the chapter ″Setting Up the
Administration Process.″

To prevent access to the source server

1. Shut down the Domino server on the source server.
2. Disassociate the hosted organization’s DNS names from the source server’s IP address. Associate those
DNS names with the destination server’s IP address.
3. If SSL was used for encryption, do not copy the old key ring file to the destination server. Use the
destination server’s key ring file.
4. Open each Internet Site document to modify the IP address for the hosted organization on the
destination server. Make sure that Web site names are correct.
For more information on Internet Site documents, see the topics Internet Site documents and Using
Internet Site documents in a hosted environment.
5. Restart the Domino server on the source server.

Removing a hosted organization from a backup or load-balancing

server
Use this procedure to remove a hosted organization and all of its services from a server that provides
hot-backup or load-balancing capability. In this configuration, one unique IP address is used for each
hosted organization. You do not need to modify the Internet Site documents because the network router
controls redirection connections for load-balancing and for hot-backups.

To remove a hosted organization from a backup or load-balancing server

1. Perform the necessary steps to do one of these:
v Prevent the network router from distributing the data from this hosted organization to the
destination server
v Deconfigure the hot-backup server
2. Delete files and databases from the hosted organization’s data directories and from any other
directories in which hosted organization files reside.
3. Delete the hosted organization’s data directory.
4. Delete the hosted organization’s ACL file from the Domino data directory.

To remove a hosted organization from a server that provides Web-application

support
1. Remove the DNS name for the Web application.
2. Delete the Web Site document for the Web application.
3. Modify common data for the application to remove support for the hosted organization.
4. Delete the content of the hosted organization’s data directory.
5. Delete the hosted organization’s ACL file.

Chapter 16. Managing a Hosted Environment 427

Managing Users at a hosted organization
As a service provider administrator, you have varying levels of responsibilities for user management,
according to the agreements you have with your various hosted organizations. To perform user
management actions from the service provider site, use the Domino Administrator to register, delete, or
perform any user or group management action.

If you will be performing all user management actions from the service provider site, see specific areas of
the documentation that explain the actions you want to perform. For example, you would most likely
want to access these areas of the documentation:
v Registering users
v Managing users
v Creating and modifying groups
v Managing groups
v Deleting a group with the Domino Administrator or the Web Administrator

User management from the hosted organization site

To enable hosted organizations to use the Web Administrator to add and delete users and groups, see the
topic Web Administration from the hosted organization site in this chapter.

Using the Web Administrator to manage users at a hosted organization

The hosted organization administrator can use the Domino Web Administrator to maintain users and
groups. Before using the Web Administrator, the hosted organization administrator must be familiar with
the Web Administrator.

For more information on the Web Administrator, see the chapter ″Setting Up and Using Domino
Administration Tools.″

To use the Web Administrator, you must also use the server-based certification authority (CA). Set up and
load the CA before attempting to access and use the Web Administrator.

For more information on the server-based CA, see the chapter ″Setting Up a Domino Server-Based
Certification Authority.″

Note: If a hosted organization’s users are registered at the service provider site, they can be registered
with certifier IDs and passwords or with the Domino server-based CA. To register a user for a particular
hosted organization, ensure that the service provider administrator is using a certifier created for that
hosted organization. Users registered by the hosted organization administrator at the hosted organization
site must be registered using the Domino server-based CA.

To set up access to the Web Administrator at a hosted organization site: Before using the Web
Administrator, the hosted organization administrator must have rights in the ACL for WEBADMIN.NSF,
NAMES.NSF, and ADMIN4.NSF. The service provider administrator must assign these rights to the
hosted organization administrators who are responsible for managing users and groups with the Web
Administrator.
v Add the hosted organization administrator to the HostedOrganizationAdmins group and assign Author
access with the People&Groups role in the ACL.
v Add the hosted organization administrator to the LocalDomainAdmins group and assign Manager
access and All roles in the ACL.

The hosted organization administrator needs special access in NAMES.NSF. The service provider
administrator assigns these rights to the hosted organization administrators:

428 Lotus Domino Administrator 7 Help

v Add the hosted organization administrator to the HostedOrganizationAdmins group and assign Editor
access with default roles -- that is, Create documents, Delete documents, Read public documents, Write
public documents, and Replicate or copy documents. Also assign the GroupCreator, GroupModifier,
UserCreator, UserModifier roles.

Give the hosted organization administrator the following access to the Administration Request Database
(ADMIN4.NSF):
v Author access with the Create documents and Read public documents roles.

To use the Web Administrator to manage users and groups: To maintain users and groups with the
Web Administrator, the hosted organization administrator performs these tasks:
v Registering users with the Web Administrator
v Deleting a user name with the Web Administrator
v Creating a group with the Web Administrator
v Deleting a group with the Web Administrator

Addressing messages to users at a hosted organization

To send mail to users and administrators at a hosted organization, the user names and group names in
the senders address book must contain full name references that include the Internet domain name in the
address or that use a Notes address that includes the domain name. For example:
v An address that includes the Internet name: Robert_Owens@Acme.com Where Acme is the Internet
domain name
v A Notes address that includes the domain name: Robert Owens/hosted_organization@Acme Where
″hosted_organization″ is the hosted organization name and Acme is the Internet domain name

Using the Resource Reservations database in a hosted environment

You can create a Resource Reservations database that can be used for the service provider site and for all
hosted organizations. This Resource Reservations database is created in the Domino data directory.

To create the Resource Reservations database

1. Use the template RESRC60.NTF to create the Resource Reservations database.
2. After creating the database, open the new database.
3. Edit the database ACL as follows:
a. To the service provider administrator, assign the ″Create Resource″ role which allows the
administrator to create new entries in the database.
b. To default users, assign the ″NoAccess″ role to prevent users outside of the hosted organization
from accessing the database.
4. Close the database.

For information on creating a database, see the topic Creating a Database if you have installed Lotus
Notes 7 Help. Or, go to http://www.notes.net/doc to download or view Lotus Notes 7 Help.

CAUTION:
Do not assign access rights and roles directly to a hosted organization. Because the Resource
Reservations database is not automatically protected by an extended ACL, if you assign access rights
and roles to a hosted organization, users in the hosted organization will be able to open the Resource
Reservations database for other hosted organizations.

To create a Site Profile document to support a hosted organization

In the Resource Reservations database, each hosted organization is treated as a site. Create a Site Profile
document for each individual hosted organization.
1. From the Domino Administrator, open the new Resource Reservations database.

Chapter 16. Managing a Hosted Environment 429

2. To add a new hosted organization, click Add Site.
3. Enter the hosted organization name in the Site name field. Using the hosted organization name sets
the extended ACLs on the Resource/Reservations database for the site, thereby preventing
unauthorized users from accessing this database.
4. Enter the name of the hosted organization in the Domain name field.
5. Click Save and Close.
6. Add resources and reservations to the database.
For more information on the Resource Reservations database, see the chapter ″Setting Up Calendars
and Scheduling.″

Viewing hosted organizations

The People and Groups views in the Domino Administrator are categorized by organization name or by
non-hierarchical (flat) name. The non-hierarchical view is the default. To use the organization view, click
People or click Groups and then click by Organization.

There are also three ″categorized″ views available. They are

v People by Category
v Groups by Category
v Mail-in Databases and Resources by Category

To open the categorized views:

1. From the Domino Administrator, open the Domino Directory (NAMES.NSF).
2. Click People to access the People by Category view or click Groups to access the Groups by Category
view.
3. To access the Mail-in Databases and Resources by Category views, click Server - Mail-in Databases
and Resources view.

Note: You can view a list of the hosted organizations and corresponding Site documents in the Domino
Directory.

For more information on viewing Web Site and Internet Site documents, see the chapter ″Setting Up the
Service Provider Environment″

430 Lotus Domino Administrator 7 Help

Chapter 17. Setting Up the Administration Process
This chapter describes how to set up the Administration Process, a program that simplifies administrative
tasks, such as deleting users, creating replicas, and editing ACLs.

The Administration Process

The Administration Process is a program that automates many routine administrative tasks. For example,
if you delete a user, the Administration Process locates that user’s name in the Domino Directory and
removes it, locates and removes the user’s name from ACLs, and makes any other necessary deletions for
that user. If you want to delete all replicas of a database, the Administration Process finds the replicas on
servers in the domain and provides an interface for deleting them.

The Administration Process automates these tasks:

v Name management tasks, such as rename person, rename group, delete person, delete group, delete
server name, recertify users, and store Internet certificate.
v Mail file management tasks, such as delete mail file and move mail file.
v Server document-management tasks, such as store CPU count, store platform, and place network
protocol information in Server document.
v Roaming user management, such as roaming user setup, move roaming users to other servers, upgrade
a nonroaming user to roaming status, and downgrade roaming user to nonroaming status.
v User mail file management tasks, such as performing Access Control List (ACL) changes and enabling
agents. For example, the ″Out of Office″ agent is enabled and disabled by Notes client users.
v Person document management tasks, such as storing the user’s Notes version and client platform
information.
v Replica management tasks, such as create replica, move replica, or delete all replicas of a database.

Administration servers
Administration servers control how the Administration Process does its work. You specify an
administration server for the Domino Directory and for specific databases. By default, the first Lotus
Domino server you set up in a domain is the administration server for the Domino Directory. The
administration server for the Domino Directory maintains the Domino Directory’s ACL, performs deletion
and name change operations in that Domino Directory, and these changes are replicated to other servers
in the domain. If you have multiple directories in your domain -- not replicas of other domain’s
directories, but more than one of your own -- you can specify an administration server for each of the
directories in your domain. Do not specify an administration server in your domain for a replica of
another domain’s Domino Directory.

All databases need an administration server to manage name changes and deletions that apply to the
database -- for example, changes to the ACL, Readers and Authors fields, or Names fields. If a database
has replicas, you assign an administration server to only one replica. Then the Administration Process
makes all changes to that replica, and replication for that database carries out the changes in all other
replicas.

You can also set up one or more extended administration servers to distribute across multiple servers the
processing of administration requests that modify the Domino Directory.

For more information on extended administration servers, see the topic ″Using an extended
administration server″ later in this chapter.

431
The Administration Requests database
The Administration Requests database (ADMIN4.NSF) is created on the administration server for the
Domino Directory when that server starts for the first time. Requests for work to be done by the
Administration Process are stored in the Administration Requests database. The status of work done by
the Administration Process is also stored there as response Log documents to the requests, in the form of
Administration Request documents. To complete tasks, the Administration Process posts and responds to
requests in the Administration Requests database. Domino servers use replicas of this database to
distribute requests made on one server to other servers in the domain.

When other servers start, if the Administration Requests database does not exist, the server creates a
replica stub of the Administration Requests database and waits for it to be initialized from another server
in the domain. Every server in the domain stores a replica of the Administration Requests database and
the Domino Directory.

The Administration Requests database also acts as the interface to the Domino Certificate Authority
requests. It is the responsibility of the Registration Authority to monitor the status of the Certification
Authority (CA) Requests. The CA requests can be removed from the view or resubmitted for processing
in the same manner as the Administration Process Requests.

For more information on working with requests see the topics ″The Administration Requests database″
and ″Managing Administration Process requests″ in this chapter.

For more information on the Registration Authority (RA), see the chapter ″Setting Up a Domino
Server-Based Certification Authority.″

The Certification Log

To use the Administration Process to perform name changes and recertifications, the Certification Log
(CERTLOG.NSF) must reside on the server that stores the Domino Directory in which you will initiate
the name change or recertification. If the Certification Log exists on another server, move the Certification
Log to the server containing the Domino Directory on which you are initiating the name change or
recertification. The Certification Log contains a permanent record of how you register servers and users,
including information about the certifier ID. The Certification Log also contains messages that describe
the results of recertification requests that the Administration Process is processing.

For more information on the Certification Log, see the chapter ″Installing and Setting Up Domino
Servers.″

Specifying the administration server for the Domino Directory

Choosing the administration server for the Domino Directory depends on your network setup, the
available equipment, and the anticipated changes that will be made to the Domino Directory via the
Administration Process. Large numbers of name-management operations -- rename and delete requests
for example -- result in many changes to the Domino Directory with the subsequent view rebuilding and
thereby affecting performance. Making a heavilly-accessed server the administration server of the Domino
Directory results in slow server performance from a user’s perspective. Giving only one, or a few servers
the responsibility of being the administration server of many databases may result in that server
continually processing delete and name change requests. Choosing the administration server also involves
planning how to assign administration servers for other databases in the domain because all name
management operations require extensive searching of databases to determine which server is the
administration server for the ACLs, Reader and Author fields, Name fields and unread lists. When
choosing the administration server for databases in a domain, your choices include:
v Using a hub server as the administration server for the Domino Directory and for other databases.
v Using a dedicated registration server as the administration server for the Domino Directory and using
one or more separate hub servers as administration servers for other databases.

432 Lotus Domino Administrator 7 Help

v Using a multifunction server as the administration server for the Domino Directory and distributing
administration responsibilities for the other databases to other servers.
v Setting multiple administration servers, called extended administration servers, for the Domino
Directory to provide for less centralized, more regional, directory management.

If the domain has only a few servers, consider using one administration server for both the Domino
Directory and for other databases. The majority of the administration server resources are used for
updating the Domino Directory and replicating to keep the Domino Directory consistent across the
domain. The responsibility of the administration server of other databases is to maintain ACLs, Reader,
Authors, and Names fields; and unread lists during name management operations. While this option
centralizes administration, it may result in slower server performance as the domain grows and the use
of the Administration Process to update the Domino Directory and maintain databases increases.

A second option involves using a dedicated registration server as the administration server for the
Domino Directory. You limit this server’s responsibility to the processing of Domino Directory changes.
You can then use other servers, such as database hubs, for processing ACL changes to other databases. To
do so, specify the database hub as the administration server for those databases. You can divide the
responsibility for database ACL changes among several administration servers; but, you must make sure
that when there are multiple replicas of a database in the domain, you assign an administration server for
only one replica.

A third option involves using multiple servers to maintain the Domino Directory. If your domain is
geographically dispersed, having a single administration server for the Domino Directory means all
administration requests for Domino Directory changes have to replicate to this one server and the
resultant changes have to replicate back. If your company is organized hierarchically, that is, it is
composed of multiple organizations and organizational units, extended administration servers can be
assigned to maintain the directory documents associated with people, groups, and servers whose names
have that organization or organizational unit component.

Using a server that contains mail and other databases as the administration server for the Domino
Directory is possible, but is not recommended for performance reasons.

Always run the most recent version of Lotus Domino 7 on the administration server of the Domino
Directory and the extended administration servers, so that you can use all of the newest Administration
Process features.

Note: If you use an LDAP client to administer the Domino Directory, the Administration Process is not
aware of these changes and does not extend the changes to other databases. For example, if you delete a
Person document, you must manually remove references to that person’s name in other places that it
occurs because the Administration Process does not do this for you.

For more information on extended administration servers, see the topic ″Using an extended
administration server″ later in this chapter.

Setting up the Administration Process

To set up the Administration Process, you must complete these tasks:
1. Specify the administration server for the Domino Directory in the domain. This is done during
installation.
For more information on installing a server, see Installing and Setting Up Domino Servers.
2. Specify an administration server for databases in the domain.
3. (Optional) Set up cross-domain processing to enable an administration server in one domain to export
requests to and/or import requests from an administration server in another domain.
4. Verify that the administration process is set up correctly.
5. Set up ACLs for the Administration Process.

Chapter 17. Setting Up the Administration Process 433

Specifying an administration server for databases
The Administration Process uses administration servers to manage administrative changes that apply to
databases. Either the administrator or the database manager can specify the administration server for a
database. Perform this procedure on an as-needed basis.

Note: To change the administration server for a database, you must have Manager access to the database
or be designated as a Full access administrator on the Security tab of the Server document.
1. From the Domino Administrator, open the domain containing the server with the database for which
you are setting an administration server.
2. From the Servers pane, select the server containing the database you are setting as an administration
server.
3. Click the Files tab and then select the database to which you are assigning an administration server.
4. From the Tools pane, click Tools - Database - Manage ACL.
5. Click Advanced.
6. Complete these fields and then click OK:

Field Enter
Administration Server Choose one of these:
v None -- If you do not want an administration server assigned for the
database.
v Server -- Select a server from the list.
Choose one of these according to whether you want modifications to the
indicated fields to occur during a rename group, rename user, or rename
server action; or during a delete server, delete group, or delete user action:
v Do not modify Names fields -- Names fields are not updated during any of
the above rename and delete actions.
v Modify all Readers and Authors fields -- Reader and Author fields are
updated during the rename and delete actions listed above.
v Modify all Names fields -- All names fields are updated during any of the
rename or delete actions listed above.

7. If you will be processing administration requests across domains, complete the procedure ″Creating a
Cross-domain Configuration document.″

Verifying that the Administration Process is set up correctly

After you set up the administration server and the Administration Process, verify that both are running
correctly.
1. From the Domino Administrator, click Server - Analyses - Administration Requests(7).
2. Open the ″All Requests by Action″ view.
3. Verify that the request ″Put server’s Notes build number into Server record″ appears in the view.
4. Sixty minutes after the Administration Process begins running, open the Administration Requests
database again and open the response Log document for the request.

Note: Log documents are listed directly beneath the request that the document pertains to. The
heading Administration Request - Log appears at the top of each Log document.
5. Review the information in the response Log document to ensure that the request has run.
6. Complete the procedure, ″Setting up ACLs for the Administration Process.″

434 Lotus Domino Administrator 7 Help

Administration Process support of secondary Domino Directories
Domino supports the use of secondary Domino Directories for maintaining user names and groups that
you want to store in a directory other than your primary Domino Directory, NAMES.NSF. For example,
you may want to maintain Notes users with Notes IDs in NAMES.NSF, but maintain Web-only users in a
secondary Domino Directory.

A secondary Domino Directory can use the same administration server as your primary Domino
Directory, NAMES.NSF, or you can designate another server as the administration server for the
secondary directory.

When you initiate a name-management or group-management action from a secondary Domino

Directory, the administration process records, in the Administration Request document, the replica ID of
the secondary directory. When a server locates and then attempts to process a name-management or
group-management administration request, the server checks for the replica ID. If there is no replica ID
stored in the Administration Request document, the administration server for NAMES.NSF processes the
request.

If a replica ID is located, the server attempts to open the database. If it is successful, the server checks the
ACL to determine whether it is the administration server for that directory. If so, the server processes the
request. If it is not the administration server for that directory, the server leaves the request to be
processed by the appropriate administration server. If the server is unable to open the database, it ignores
the request.

For more information on secondary Domino Directories, see the chapter ″Setting up Directory
Assistance.″

For more information on designating a server as an administration server, see the topic ″Specifying an
administration server for databases″ earlier in this chapter.

Processing administration requests across domains

You set up Cross-domain Configuration documents to enable a server in one domain to mail
administration requests to a server in another domain. Set up the Cross-domain Configuration document
after you specify an administration server for the Domino Directory in each domain. The Administration
Process for the Domino Directory must be set up on a server in each domain. Cross-domain processing
works only when the administration server of the Domino Directory is a Lotus Domino Release 5 or more
recent server.

These tasks can be processed across domains:

v Delete person in Domino Directory
v Delete server in Domino Directory
v Rename server in Domino Directory -- that is, upgrade the server name from flat to hierarchical
v Rename person in Domino Directory
v Create replica
v Get replica information for deletion -- This request is generated when you delete a database and its
replicas

Note: During cross-domain processing, any requests imported from another domain and any subsequent
requests created by the imported requests are processed by Lotus Domino Release 5 and more recent
servers only.

Setting up cross-domain processing of administration requests

To set up cross-domain processing of administration requests, you need to do the following:

Chapter 17. Setting Up the Administration Process 435

v Create the necessary cross-certificate documents in the Domino Directory. Requests going to another
domain require cross certificates between the two domains.
v Create a Connection document in the Domino Directory allowing a server in one domain to connect to
a server in another domain. Each domain must have a Connection document.
v Create one or more Cross-domain Configuration documents in the administration requests database for
each domain from which you will import administration requests and to which you will export
administration requests.
v Set up an administration server for the outbound domain to allow processing of the outbound
requests.

Edit the Directory Profile document for the Domino Directory to include the names of anyone allowed to
create a Cross-domain Configuration document. On the Directory Profile document, add the
administrators names to the ″List of administrators who are allowed to create Cross-domain
Configuration documents in the administration requests database″ field. If a Cross-domain configuration
document is created by someone whose name is not in that field or who is not a manager of the Domino
Directory, that configuration will be ignored.

The Administration Requests database contains Cross-domain Configuration documents that specify how
domains exchange and process administration requests. When you configure a Cross-domain
Configuration document, you designate the trusted entities, which are persons, servers, or certifiers. All
requests received from the domain must be signed by one of its trusted entities. Rename requests are the
exception; they are signed by certifiers so their validity is determined by the certificates and the
cross-certificate in the destination domain’s Domino Directory. For Rename requests going to another
domain, there must be appropriate cross-certificates between the two domains. Additionally, the Domino
Directory of the destination domain must either have all Certifier documents, with the certifier’s public
key, for the organizational structure represented in the name change request, or it must be able to access
those Certifier documents from a trusted Directory specified via Directory Assistance.

Note: Check the Connection documents for the servers involved in the cross-domain request processing.
The fields on the Connection document that have particular impact on the processing of administration
requests across domains are on the Basics tab: Source server, Source domain, Destination server, and
Destination domain fields.

Other fields on the Connection should be set up to allow for replication and communication between
source and destination servers as usual.

For more information on setting up trusted directories via Directory Assistance, see the chapter ″Setting
Up Directory Assistance.″

For more information on Certifier documents, see the chapter ″Installing and Setting Up Domino
Servers.″ For more information on cross-certificates, see the chapter ″Protecting and Managing Notes
IDs.″

Benefits of cross-domain processing

Cross-domain processing offers these benefits:
1. Processing administration requests across domains can protect the integrity of the data in databases.
For example, if a person is deleted from the directory in one domain, corresponding deletions occur
in the other domains.
2. Access to information is enhanced because a name change is propagated to other domains. For
example, people and servers registered in one domain can also be listed in the directory documents
and database ACLs in another domain. Cross-domain processing allows users and servers to have
access to databases and servers in both domains.
3. Applications are easily distributed because databases are easily replicated from servers in one domain
to servers in other domains. Administrators do not have to install and update applications
individually on all servers.
436 Lotus Domino Administrator 7 Help
Creating a Cross-domain Configuration document
1. Make sure that you have already set up the necessary Connection documents and cross certificates to
allow communication between the servers.
2. From the Domino Administrator, choose Server - Analysis - Administration Requests(7).
3. Choose the Cross Domain Configuration view and click ″Add Configuration.″
4. On the Configuration Type tab, choose one of these:
v Inbound to create an inbound request configuration
v Outbound to create an outbound request configuration
5. If you chose Inbound in Step 4, click Inbound Request Configuration and then complete these fields:

Field
Receive AdminP requests from domains
List of AdminP requests allowed from other
domains
Only allow Create Replica requests if
intended for one of the following servers
Enter
The name of one or more domains from which this server will
receive requests.
Select any of these requests that this server will accept from other
domains and then click OK.
v Create Replica
v Delete Person in Address Book
v Delete Server in Address Book
v Get Replica Information for Deletion
v Rename Person in Address Book
v Rename Server in Address Book
Server names in your current domain that will accept Create Replica
requests from other domains.

This field displays if the Create Replica request is selected.

List of approved signers Names of approved signers -- that is, a trusted signer for the request
type for the destination domain. An inbound request is rejected if it
is signed by someone who is not a trusted signer.

If you selected Create Replica requests from the list above, the
request’s author is required to have Create Replica access to the
destination server. Create Replica requests must be signed by the
source server.

6. If you chose Outbound in Step 4, click Outbound Request Configuration and then complete these
fields:

Field
Domains to submit AdminP requests to
List of AdminP requests to submit
Enter
The name of one domain to which the server will send requests. If
you need to send AdminP requests to multiple domains, create a
separate Cross-Domain Configuration document for each domain to
which you will send requests.
Select the type of requests that this server will send and then click
OK.
v Create Replica
v Delete Person in Address Book
v Delete Server in Address Book
v Get Replica Information for Deletion
v Rename Person in Address Book
v Rename Server in Address Book

Chapter 17. Setting Up the Administration Process 437

Field Enter
Only submit Create Replica requests to the Server names to which you will send Create Replica requests. Also
domains listed above if the destination server enter the domain names in which the servers reside.
is one of the following
This field displays if the Create Replica request is selected.
List of approved signers Names of approved signers -- that is, a trusted signer for the request
type from the creation domain. An outbound request will not be
sent if it signed by someone who is not a trusted signer.

If you selected the Create Replica request from the list above, the
request’s author is required to have Create Replica access to the
destination server. Create Replica requests must be signed by the
source server.

7. Click Save and Close.

8. Complete the procedure ″Verifying that the Administration Process is set up correctly.″

Setting up ACLs for the Administration Process

Each administrator who uses the Administration Process to perform tasks must have the appropriate
access rights and roles in the Domino Directory (NAMES.NSF), secondary directories -- if applicable,
Administration Requests database (ADMIN4.NSF), and the Certification Log database (CERTLOG.NSF).

The quickest way to provide administrators with the access they need is to give them the minimum
levels of access:
v For the Domino Directory, create an administrator group of type Person Group with Editor access, and
list the administrators in the group.
v For the Administration Requests database, give administrators Author access. If an administrator will
be approving requests, give Editor access.
v For the Certification Log database, give administrators Author with Create documents access.

To assign access to administrators so they can perform only specific tasks, see the table below which
specifies the access that administrators need in the ACLs of the Domino Directory, secondary directories
-- if applicable, Administration Requests database, and Certification Log database. If an error occurs
during any administrative task, the administrator must have Editor access in the ACL of the
Administration Requests database to perform the task again.

For more information on setting up and modifying an ACL, see the chapter ″Controlling User Access to
Domino Databases.″

Note: If extended ACLs are enabled and you have specified who can modify documents for an
organization, administration requests will fail if they are initiated by anyone not specified in the extended
ACL.

Administrator needs this Administrator needs

access in the Domino
Task Directory
Add a resource to or None. However, the
delete a resource from Administration Process
the Resource updates the Domino
Reservations database Directory to reflect the change
Add group Author with Create
documents and the
ServerModifier role
this access in Administrator needs this access
ADMIN4.NSF in other databases
Author with Create CreateResource role in the
documents access Resource Reservations database
Author with Create
documents access and
GroupModifier role

438 Lotus Domino Administrator 7 Help

 Administrator needs this Administrator needs
access in the Domino this access in Administrator needs this access
Task Directory ADMIN4.NSF in other databases
Add users to group Author with GroupModifier
role. If administrator has
access greater than Author,
that access is sufficient
Add servers to and One of these: Author with Create None
remove servers from a v Author access and documents access
cluster ServerModifier role
v Editor access
Approve a request to One of these: Editor access Author with Create documents
move a user name to v Author with Create access to the Certification Log
another hierarchy documents access and
UserModifier/Server
Modifier role
v Editor access
Approve the deletion of a Delete documents access Editor access None
resource from the
Resource Reservations
database
Create mail files Author access and the Author with Create Create new database access on
automatically during user UserCreator role documents access the registration server
registration
Create replicas of No requirement Author with Create All of these:
databases documents access v Create replica access to the
destination server
v Reader access to the database
on the source server
v In addition, the source server
must have Create replica
access to the destination
server, and the destination
server must have Reader
access to one replica of the
database.
Delete group One of these: Author with Create None
v Author with Delete documents access
documents access and the
GroupModifier role
v Editor access
Delete servers One of these: Author with Create None
v Author with Delete documents access
documents and the
ServerModifier role
v Editor access
Delete users* One of these: Author with Create None
v Author with Delete documents access
documents access and the
UserModifier role
v Editor access

Chapter 17. Setting Up the Administration Process 439

 Administrator needs this Administrator needs
access in the Domino this access in Administrator needs this access
Task Directory ADMIN4.NSF in other databases
Delete users and their One of these: Editor None
mail files* v Author with Delete
documents and the
Delete users and their
UserModifier role
private design elements
v Editor with Delete
documents access
Enable Editor access Author with Create None
password-checking documents access
during authentication
Find name Editor access with None None
UserModifier role
Move replicas from a None Author with Create Both of these:
cluster server documents access v Same access as ″Create replicas
of databases″
v Manager access to the original
database
Move replicas from a None Editor Both of these:
non-clustered server v Same access as ″Create replicas
of databases″
v Manager access to the original
database
Move user to another One of these: Editor Create replica access on the new
server v Author access and mail server
UserModifier role
In addition, the old mail server
v Editor access must have Create replica access
to the new mail server, and the
person whose mail file is being
moved must be running a Notes
Release 5 or higher client.
Recertify user IDs and One of these: Author with Create Author with Create documents
server IDs v Author with Create documents access access to the Certification Log
documents access and
UserModifier/Server
Modifier role
v Editor access
Register user Author with Create Author with Create If creating mail files/roaming
documents access and documents access if files, Create database access on
User/Creater role using Administration the mail server and/or roaming
Process for server, accordingly.
background
processing If creating replicas, Create
Replica access on the replica
servers.

If CERTLOG.NSF resides on the

registration server, Create
document access to
CERTLOG.NSF is required.
Remove all replicas of a None None None
database

440 Lotus Domino Administrator 7 Help

 Administrator needs this
access in the Domino
Task Directory
Rename users and One of these:
convert users and servers v Author with Create
to hierarchical naming documents access and
UserModifier/Server
Modifier role
v Editor access
Sign database None
Specify the Master One of these:
Address Book name in v Author access with
Server documents ServerModifier role
v Editor access
Add Internet certificate Editor
Update client information None
in Person record
Administrator needs
this access in Administrator needs this access
ADMIN4.NSF in other databases
Author with Create Author with Create documents
documents access access to the Certification Log
None None
Author with Create None
documents access
Author with Create None
documents access
None None

For more information on Active Directory procedures, see the chapter, ″Using Domino With Windows
Synchronization Tools.″

The Administration Requests database

Information about each administrative task that you want the Administration Process to handle is stored
in the Administration Requests database (ADMIN4.NSF). This database lists both the specific task and
also the requests and responses that the Administration Process posts and processes to complete the task.
At least once each day, check the views described in the table below for requests that require
administrator attention or approval; also check for errors. The list of views is shown in the order in
which these views appear when you open ADMIN4.NSF using Server - Analyses - Administration
Requests.

For more information on how the Administration Process completes specific administrative tasks, see the
appendix ″Administration Process Requests.″

View
Administrative Attention Required
All Activity by Server
All Errors by Date
All Errors by Server
All Requests by Action
All Requests by Name
All Requests by Originating Author
All Requests by Server
All Requests by Time Initiated
Displays
Requests that warrant attention and may require action on the part of the
administrator.
Responses to requests, sorted by server.
Responses with errors encountered, sorted by date.
Responses with errors encountered, sorted by server.
Requests and responses, sorted by action.
Requests and responses, sorted by name.
Requests sorted by server name, administrator name, or user name,
according to how the request was initiated. This view allows one
administrator to monitor the activity of other administrators in the
Administration Requests database.
Requests and responses, sorted by server.
The ″All Requests by Time Initiated″ view sorts all administration requests
by the date and the time that the request was initiated.

Chapter 17. Setting Up the Administration Process 441

View Displays
CA Modification Requests Requests that have generated updates to the Certifier document in the
Domino Directory and the Certificate Authority Configuration document in
Configuration Updates the Issued Certificate List (ICL) database.
Note: When you open ADMIN4.NSF from the Domino Directory, this view
is called ″Configuration Updates.″
CA Recovery Updates Requests to update the recovery information for a certifier. This view is
typically monitored by the administrator who has been designated
Recovery Information Updates Certification Authority and Registration Authority.

Certificate Requests
Cross Domain - Configuration
Cross Domain - Delivery Failures
Enrollment Requests
Individual Approval Required
Name Move Requests
Pending Administrator Approval
For more information on ID recovery, see the topics ″ID recovery″ and
″Recovering an ID″ in the chapter ″Protecting and Managing Notes IDs.″
Note: When you open ADMIN4.NSF from the Domino Directory, this view
is called ″Recovery Information Updates.″
Requests to create an Internet certificate and requests to create a Notes
certificate. This view is typically monitored by the administrator who has
been designated Certification Authority and Registration Authority.
Cross-domain configurations sorted by domain and then by inbound
requests that are accepted and outbound requests that are accepted
Requests that cannot be delivered to the inbound domain
This view is not yet implemented.
The ″Individual Approval Required″ view shows the requests that must be
individually approved, that is, they cannot be approved by selecting
multiple requests in ADMIN4.NSF and clicking ″Approve Selected
Requests.″
Requests to move a user’s name in the name hierarchy
Requests that are pending the approval by the administrator. There are
additional views associated with this view. They are:
v Pending by Age -- Shows all requests that are pending administrator
approval, sorted by the number of days that the request has been in
ADMIN4.NSF awaiting approval. Requests are sorted in increments such
as 7 days, 14 days, and so forth, up to requests older than 90 days.
v Pending by Server -- Shows all requests that are pending administrator
approval, sorted by the name of the server on which the request will be
processed.
Note: When you open ADMIN4.NSF from the Domino Directory, the
″Individual Administrator Approval″ view is listed here instead of as a
separate view.

The Administration Requests database (ADMIN4.NSF) also contains these processing options that are
available as buttons on the administration requests, according to whether to processing option applies to
a particular request.

New Processing Option Description

Remove from View The ″Remove From View″ button appears in the ″Administration Attention
Required,″ ″all Errors by Date″ and ″All Errors by Server″ views in
ADMIN4.NSF and is used to remove one or more requests from these views
after an administrator has attended to the warning or reported error. Select
the request that you want to remove from the view and click ″Remove From
View.″

442 Lotus Domino Administrator 7 Help

New Processing Option
Reprocess Selected Requests
Complete Move for selected entries
Description
The ″Reprocess Selected Requests″ button appears in the ″All Errors by
Date″ and ″All Errors by Server″ views in ADMIN4.NSF and is used to
reprocess one or more requests that previously failed during processing.
Select the requests that you want to reprocess and click ″Reprocess Selected
Requests.″
The ″Complete Move for selected entries″ button appears in the ″Name
Move Requests″ view of ADMIN4.NSF and is used to complete a move to
another hierarchy for one of more requests. If multiple requests are selected,
the destination hierarchy must be the same for all of them. Select the
requests that you want to complete and click ″Reprocess Move for selected
entries.″

To view documents in the Administration Requests database, you can use either the Domino
Administrator or the Web Administrator.

For information about messages that appear in the Administration Requests database, see the chapter
″Troubleshooting.″

Administration Process requests that require the administrator’s approval

When administration requests that cannot be processed without the administrator’s approval are received,
they are stored in the Administration Requests database and are flagged as requiring approval.

Administrator actions that generate

Administration Process requests requiring
approval
Delete database (with ″Delete all replicas of this
database″ selected on the Delete File dialog box).
Delete mail file during a delete person in Domino
Directory
Delete roaming user
Result of approving the administration request
Approving an ″Approve Replica Deletion″ administration
request posts the ″Request Replica Deletion″ administration
request to begin the process of removing all replicas of the
database that is being deleted.
Approving an ″Approve file deletion″ request during a Delete
person in Domino Directory action posts the ″Request file
deletion″ administration request so that a user’s mail file can
be deleted.
Approving the ″Approve mail file deletion″ administration
request posts the ″Request mail file deletion″ administration
request to begin the process of deleting the mail files from the
mail server.

Approving the ″Approve replica deletion″ administration

Delete user in Domino Directory
Move a database from a non-clustered server
request posts the ″Request Replica Deletion″ administration
request to begin the process of deleting the roaming file
replicas from the roaming server.
Approving the ″Approve deletion of private design elements″
administration request posts the ″Request to delete private
design elements″ request so that private design elements can
be deleted. Private design elements are private agents, views,
and folders signed by the person who has been deleted.
Approving the ″Approve deletion of moved replica″ request
posts a ″Request to delete non-cluster move replica″ so that the
original database can be removed from the source server.

Chapter 17. Setting Up the Administration Process 443

Administrator actions that generate
Administration Process requests requiring
approval
Move person’s name in hierarchy
(From the ″Name Move Requests″ view)
Moving a mail file from one server to another
Moving roaming files from one server to another
Remove resource
Rename user
Request a Notes certificate or request an Internet
certificate.
These actions initiated for nonhierarchical names,
across domains:
v Delete person in Domino Directory
v Delete server in Domino Directory
v Rename person in Domino Directory
v Rename server in Domino Directory
For more information on the administration requests and how they are processed, see the appendix
″Administration Process Requests.″
Request status Icons in the Administration Request database
The Administration Request database contains icons that indicate the current status of each
administration request that is in the Administration Requests database. Use these icons to just glance at a
request to determine its status.
444 Lotus Domino Administrator 7 Help
Result of approving the administration request
Approving the ″Move person’s name in hierarchy″ is done by
the administrator of the target organization. This approval
allows for the posting of the ″Initiate rename in Domino
Directory″ request to begin the moving of the user’s name to a
new hierarchy.
Approving the ″Approve file deletion″ administration request
posts the ″Request file deletion″ administration request to
begin the process of deleting the old mail file from the old
home mail server after the mail file is moved to the new mail
server.
Approving the ″Approve replica deletion″ administration
request post the ″Request Replica Deletion″ administration
request to begin the process of deleting the roaming file
replicas from the old roaming server.
Approving the ″Approve mail file deletion″ administration
request posts the ″Request mail file deletion″ administration
request to begin the process of deleting the old mail files from
the old mail server after the mail files have been moved to the
new mail server.
Approving the ″Approve resource delete″ administration
request posts the ″Remove resource″ administration request so
that a resource, such as a conference room name, can be
deleted from the Domino Directory.
Approving the ″Approve Retract Name Change″
administration request cancels a user name change request and
causes the user’s previous name to remain in effect.
An ″Approve Certificate Request″ administration request is
generated when you use the CA to issue a new Notes or
Internet certificate, and the request needs to be approved by a
registration authority. Approving the ″Approve Certificate
Request″ allows the process to continue to the next step.
An Approval request is generated in the destination domain
when an identical, nonhierarchical user name or server name
is located. The Approval request allows the administrator to
determine whether the user name or server name is the one
that should be deleted or renamed. Approving the request
allows the rename or delete process to occur.
Adminstration Request Documents:

Icon and corresponding timing Description

Icon displays for all immediate requests. Immediate
Immediate
requests are usually processed within one minute.
Icon displays for these requests:
Daily
v All new and modified daily requests to update Person
documents in the Domino Directory.
v Any outstanding ″Rename Person in Unread List″
requests.
Icon displays for all new and modified requests to delete
Timed
unlinked mail files.
Icon displays for all new and modified delayed requests.
Delayed
These are requests that are usually carried out according
to the ″Start executing on″ and ″Start executing at″
settings in the Server document.
Icon displays for all Administration Process Request
Approved documents that are marked as ″Approved″ by an
administrator taking action from within the ″Pending
Administrator Attention″ view.
Icon displays for all Administration Process Request
Rejected documents that are marked as ″Rejected″ by an
administrator taking action from within the ″Pending
Administrator Attention″ view.
Icon displays for all interval requests. These requests are
Interval
processed according to the Interval setting in the Server
document.
Icon displays for all requests that are posted for an
Needs Approval Administration Approval. These requests show up in the
″Pending Administrator Approval″ view until acted
upon.

Administration Request - Response (Log) documents:

Icon and schedule Description

Icon displays when Administration Process Log
Reprocess
documents have been selected for reprocessing. When
errors occur, the Log documents appear in the ″All
Errors by Server″ or ″All Errors by Date″ views and can
be reprocessed by selecting one or more documents and
clicking the ″Reprocess Selected Requests″ button. The
Log documents can also be reprocessed individually by
editing the Log document and checking ″Perform request
again.″
Icon displays for all Administration Process Log
Attention
documents that report non-error type conditions. These
requests show up in the ″Administrative Attention
Required″ view for easy access.

Chapter 17. Setting Up the Administration Process 445

Icon and schedule Description
Icon displays when Administration Process Log
Processed
documents have been marked as processed. Processed
means an Administrator has reviewed the log and wishes
to remove it from the view. Mark one or more Log
documents as ″processed″ by clicking the ″Remove From
View″ button in the ″Administrative Attention Required″,
″All Errors by Server″ or ″All Errors by Date″ views.
Icon displays for all Administration Process Log
Completed documents that represent requests that have successfully
completed work on specific databases.
Icon displays for all Administration Process Log
Error documents that report error type conditions. These
requests appear in the ″All Errors by Server″ and ″All
Errors by Date″ views for easy viewing.
Icon displays for all Administration Process Log
In Progress documents to indicate a potential blocking condition. A
blocking condition can occur when a request is waiting
for some other event to occur in order to process
through.

Controlling the size of the Administration Requests Database

When administrators make full use of the Administration Process, a large number of request documents
and the resulting response Log documents are generated in the Administration Requests database
(ADMIN4.NSF), and the database can become quite large. Access Control List (ACL) management;
Readers, Authors and Names fields management; and mail file management requests are processed by all
servers in the domain with resulting response Log documents created with the status ″This name did not
appear anywhere″ or ″This file is not on this server.″

To prevent these types of documents from being saved, the field ″Store Admin Process log entries when
status of no change is recorded″ on the Server Tasks tab of the Server document is set to No by default.
Response log documents that report that no action was performed by the server are not posted to the
Administration Requests database.

For more information on the Administration Process and the settings in the All Servers document, see the
topic ″Scheduling administration request processing″ later in this chapter.

Using Space Saver settings: Check the ″Space Saver″ settings of ADMIN4.NSF on all servers because
these settings do not replicate in the domain and ensure that the ″Remove documents not modified in the
last # days″ is checked. Be sure the value entered for this setting is a reasonable number -- depending on
how long you want to keep the history of the activity of the administration requests -- for example, less
than 90 days. This information is stored in Catalog documents. If you run the catalog, you can create a
view that displays this information.
1. From the Domino Administrator, choose Files and then right-click Administration Requests database.
2. Choose Properties and click Replication Settings - Space Savers.
3. Click ″Remove documents not modified in the last # days″ and choose a number of days from the list.
Click OK.

Using a Program document to compact the Administration Requests database: Create a Program
document that will compact ADMIN4.NSF on the servers in your domain on a regular basis.

For more information on using Program documents to compact a database, see the chapter ″Improving
Database Performance″.

446 Lotus Domino Administrator 7 Help

Using Selective Replication formulas: Use a selective replication formula to prevent the response Log
documents in ADMIN4.NSF from replicating. Information in Log documents is a record of the status of
the work a server does in response to an administration request. This response Log is interesting to you,
the administrator, and to the server that created it, but not to every server in the domain. As a result, you
may want to go to the ″Space Saver″ section of the database replicator settings of ADMIN4.NSF and
create a selective replication formula that prevents Log documents from replicating. Response Log
documents have the type ″Type=AdminLog.″ Change the type to ″Type!=AdminLog.″ Another option is
to use a type that only replicates the documents to one server in the domain, therefore, you have only
one server on which to check status. After you create this formula, check the box that allows replication
formulas to replicate.

For more information on setting up and using replication formulas, see Limiting the contents of a replica
if you have installed Lotus Domino Designer 7 Help. Or, go to http://www.notes.net/doc to download
or view Lotus Domino Designer 7 Help.

Suspending administration request processing

As previously mentioned, name management administration requests that are processed on the
administration server of the Domino Directory can result in modifications to the Domino Directory,
causing re-indexing and replication of the Domino Directory. For some domains, the impact of these
changes on this server is burdensome during normal working hours. Therefore, controls are present in
the Server document for suspending the operation of the Administration Process over a daily interval.

To suspend administration request processing:

1. From the Domino Administrator, click the Configuration tab.
2. Choose Server - All Server Documents.
3. Select the server whose Server document you are editing.
4. Click the Server Tasks - Administration Process tab.
5. Complete these fields, and then click Save and Close.

Field Action
Suspend Admin Process at Enter the time at which administration processing of
administration requests stops.
Restart Admin Process at Enter the time at which administration processing of
administration requests resumes.

6. Click Save and Close.

For more information on scheduling processing of administration requests, see the topic ″Scheduling
Administration Request processing″ later in this chapter.

Controlling user access to the Administration Requests database

Some administration requests are created by Notes client users during specific phases of an
administrative operation, such as while moving a roaming user’s mail file. If a user has multiple clients,
for example, one at home and one at work, before the client creates one of these administration requests,
it checks whether an identical request has been created either by itself or by the user running on another
client. To perform this check, and to avoid creating possible redundant administration requests, the user
needs Author access to the Administration Requests database because of the detailed administration
information that appears in that database. Some administrators prefer that their users not see the
information in the Administration Requests database. If you want to run in a manner that prevents users
from seeing the content of the Administration Requests database, the default access on ADMIN4.NSF can
be set to Depositor. Setting this type of access can result in multiple requests for users appearing from the
same operation because the client cannot determine whether a request that it is about to create already
exists.

Chapter 17. Setting Up the Administration Process 447

Once you have upgraded all of your clients to Lotus Notes 7, the default access to ADMIN4.NSF can be
set to ″None″ because the client will just mail requests to the Administration Requests database if the
user does not have access.

Managing Administration Process requests

Managing administration process requests involves approving requests, forcing requests when they must
be processed immediately, and checking the Administration Requests database for errors.
v Accepting or rejecting name change requests
v Approving an administration process request
v Forcing an administration process request to run
v Checking for errors in ADMIN4.NSF
v Reprocessing a failed administration process request

Accepting or rejecting name change requests

There are two situations that are unique to user name change requests. One situation generates a request
to revert to the original user name, another situation generates a request to retract the user’s name
change. You are required to accept or reject these requests whenever they are posted to ADMIN4.NSF.

When you initiate a user’s name change, the user is prompted to accept or reject the name change. If the
user rejects the name change, an administration request is generated that requires you to either accept the
user name reverting back to the original name or reject the user name reverting back to the original user
name. For example, if a user refuses a name change, the administration request ″Approve refused name
change″ is posted to ADMIN4.NSF.

If the expiration date for the name change is reached and the user has not responded, an administration
request is issued asking you to accept a request to retract the name change. You can then either accept
the request to retract the name change, or you can reject that request. If you accept the name change
retraction, the administration requests for rejecting a name change are generated.
1. From the Domino Administrator, choose Server - Analyses - Administration Requests.
2. Select the server and then open the Administration Requests (ADMIN4.NSF) database.
3. Open the Pending Administrator Approval view.
4. Open one of these views according to how you want to accept or reject requests that have been
generated by users accepting, rejecting, or ignoring name changes.
v Individual Approval Required -- Use this view to individually approve or reject each request. Select
and open the request and then click Approve or Delete.
v Pending by Age or Pending by Server -- Use one of these views to approve or reject multiple
requests at one time. Select the requests that you are accepting or rejecting, and then click Approve
Selected Requests or Delete Selected Requests.
5. Close the Administration Requests database.

Approving an administration process request

Check the Administration Requests database daily for requests that require approval.
1. From the Domino Administrator, choose Server - Analyses - Administration Requests(7).
2. Select the server and then open the Administration Requests (ADMIN4.NSF) database.
3. Open the Pending Administrator Approval view.
4. Open the request and click Edit Document.
5. Click Approve request type. For example, if you are deleting a user’s mail file, click Approve Mail File
Deletion.
6. Click Save and Close.

448 Lotus Domino Administrator 7 Help

Forcing an administration process request to run
The recommended method of forcing an administration process request to run is to issue one of these
commands from the Domino server console:

Command Abbreviated command Description

tell adminp process new tell adminp p ne Processes requests scheduled as
immediate or interval
tell adminp process immediate tell adminp p im Processes requests scheduled as
immediate
tell adminp process interval tell adminp p in Processes requests scheduled as interval
tell adminp process daily tell adminp p da Processes requests scheduled as daily
tell adminp process delayed tell adminp p de Processes requests scheduled as delayed
tell adminp process mail policy tell adminp p ma Applies mail policy to affected user’s
mail file

Follow this procedure to force a request to occur immediately instead of waiting for the Administration
Process to initiate the request based on the timing schedule.
1. From the Domino Administrator, select the remote server.
2. Choose Server - Status - Server Console.
3. In the Domino Command field, enter a command from table above and click Send.

These commands check ADMIN4.NSF for new unprocessed requests that match the criteria specified in
the command. For example, the command ″tell adminp process interval″ checks ADMIN4.NSF for new
interval requests and queues those requests as if the interval time has expired.

Do not use the command ″tell adminp process all″ due to performance issues that are created when you
run that command. The ″tell adminp process all″ command simulates a restart of the administration
process; therefore, this command waits until all previous requests are processed before starting the next
request process. This ″wait″ is in the main thread of the administration process; therefore, new requests
that are received after the console command is issued will wait as well, regardless of request schedule.
This command slows the rate at which the administration process requests are run. This is especially true
for requests that require a lengthy processing time, such as changing a name in an ACL.

Checking for errors in ADMIN4.NSF

Check the Administration Requests database daily for errors which appear in response Log documents
marked with a red X.
1. From the Domino Administrator, choose Server - Analyses - Administration Requests.
2. Open the ″All Errors by Date″ or ″All Errors by Server″ view to review errors.
3. Select any errors that you want to delete and click ″Remove from view.″
4. To reprocess one or more failed requests, select the requests and click ″Reprocess Selected Requests.″
The error is removed from this view and can be viewed in another view showing requests to be
processed, such as ″All Activity by Server.″

Reprocessing a failed administration process request

1. From the ″All Errors by Date″ or ″All Errors by Server″ view, review the reason that the request
failed.
2. Make the appropriate corrections so that the request does not fail again.
3. Choose the request and click ″Reprocess Selected Requests.″
4. Check the Administration Requests database later to verify that the request was processed without
error.

Chapter 17. Setting Up the Administration Process 449

Customizing the Administration Process
To customize the Administration Process, you can do any of these tasks:
v Change the number of threads used to process a request
v Control the size of the Administration Requests database
v Create a customized view
v Create a third-party administration request
v Enhance the core Administration Process through the Extension Manager
v Schedule administration request processing
v Set up an extended administration server
v Suspend the processing of administration requests

Scheduling Administration Request processing

Each setting in the Administration Process section of the Server document controls the timing of specific
types of requests. Interval settings and replication schedules for each server determine how quickly the
administrative settings replicate throughout the domain. As these requests are carried out, the speed with
which they are replicated to the appropriate databases in the domain depends on the replication schedule
for those servers. If necessary, you can schedule separate replication events for more immediate updates.

To adjust the default timing of when administration requests are carried out, edit the Server document.
You may want to force a request to occur immediately if the administration request is critical.

For more information on using server console commands to force administration request processing, see
the topic ″Managing Administration Process requests″ earlier in this chapter.

To schedule Administration Process requests:

1. From the Domino Administrator, click the Configuration tab.
2. Choose Server - All Server Documents.
3. Select the server whose server document you are editing.
4. Click the Server Tasks - Administration Process tab.
5. Complete these fields, and then click Save and Close.

Field
Interval
Execute once a day requests at
Interval between purging mail file
and deleting when using object store
Start executing on
Start executing at
Mail file moves expire after
Enter
The number of minutes that pass between the processing of
name-management requests -- rename, delete, and recertify. The default is 60
minutes.
The time when updates to Person documents occur and ″Rename person in
unread lists″ requests run. The default is 12 AM.
The number of days that pass between running the Object Collect task
against a mail file that uses shared mail and deleting the mail file. The
default is 14 days.
The day on which Updates to Authors and Readers fields in a database and
discovery of shared and private design elements for a deleted person occur.
The default is Sunday.
The time when the updates to Authors and Readers fields in a database and
discovery of shared and private design elements for a deleted person occur.
The default is 12 AM.
The number of days during which the Notes client will update mail-related
changes. The default is 21 days. Valid values are 7 to 60, inclusive.

450 Lotus Domino Administrator 7 Help

Field Enter
Store Admin Process log entries when Logs a ″No change″ status entry in the Administration Process log each time
status of no change is recorded a database is scanned to determine whether an administration request
requires a change to that database and no change is made. The default is
No. Keeping this field set to ″No″ may greatly reduce the size of the
Administration Request database.

For more information controlling the size of the Administration Requests

Suspend Admin Process at
database, see the topic ″Controlling the size of the Administration Requests
database.″
(Optional) Time when the Administration Process stops processing requests.
To conserve server resources, suspend the Administration Process during
peak computer hours.

For more information on suspending the Administration Process, see the

Restart Admin Process at
topic ″Suspending administration request processing.″
(Optional) Time when the Administration Process starts processing requests
again. To conserve server resources, set the Administration Process to restart
during non-peak computer usage hours. For more information on
suspending the Administration Process, see the topic ″Suspending
administration request processing.″

Changing the number of threads used by the Administration Process

By default, the Administration Process uses three threads to process requests. To improve Administration
Process performance, increase the number of threads.
1. From the Domino Administrator, click Configuration - Server - Current Server Document.

Note: If you want to edit a Server document for another server, click Configuration - Server - All Server
Documents and then select the document you want to edit.
2. Click Edit Document and then click Server Tasks.
3. Enter a value greater than 3 in the ″Maximum number of threads″ field in the Basics section of the
tab.
4. Click Save and Close.
5. To allow the change to take effect, stop the Administration Process and then restart it. Enter these
commands from the server console:
tell adminp q
load adminp

Creating an $AdminP view

By default, the Administration Process scans all documents in a database looking for matches in the
Readers and Authors fields or Names fields, when an Administration Request for a particular value in
that field is received. You can create a view that restricts the scanning for matches in Readers and
Authors fields, or Names fields, to the documents appearing in that view. The view must be assigned the
name $AdminP.

For information on creating a view, see Application Development with Domino Designer.

Enhancing the Administration Process through the Extension Manager

You can extend the Administration Process to enhance its current core functionality -- that is, processing
all administration requests created through the Notes user interface or by a Domino server. Using the
Extension Manager to extend the Administration Process, you can use the core Administration Process
functionality and develop additional tasks based on Administration Process actions.

Chapter 17. Setting Up the Administration Process 451

For more information on creating and using an Extension Manager program, see the Lotus C API User
Guide. For more information on creating an Extension Manager for the Administration Process, see the
ProcessRequestEMCallback function entry in the Lotus C API Reference.

Creating a third-party Administration Request: You can extend the Administration Process by creating
an administration request directed to a third-party server add-in task that interprets the request and acts
on it. When creating a third-party administration request, specify:
v The Message Queue name in the ProxyProcess field of the request. The Administration Process uses
this data to pass the request’s and response’s note IDs.
v The Server name in the ProxyServer field of the request to identify the Domino server on which the
server add-in task is running.
v A Text version of an identifier, greater than ″5000,″ in the ProxyAction field.

The Administration Process acts on third-party requests by opening the message queue and placing a
message with the IDs of the administration request and log notes in it. The add-in task monitors the
message queue and then performs the required processing.

For information on creating a server add-in task that processes third-party administration requests, see
the Lotus C API User Guide.

To verify which task is processing a request: To verify whether AdminP or another task is processing
an administration request:
1. From the Domino Administrator, choose Server - Analyses - Administration Requests(7).
2. Open the ″All Requests by Action″ view.
3. Select the request, right-click the mouse button and choose Document Properties.
4. Click the Field tab, and then locate the ProxyProcess field which contains the name of the task that is
processing the administration request.

The ProxyProcess field is set by the program that created the request.

Using an extended administration server

An extended administration server is an administration server that processes Domino Directory
administration requests. The target documents in the Domino Directory are added to, modified, or
deleted only if they belong to a particular namespace within the Domino Directory. A namespace is
defined by a certification hierarchy, for example, OU=Sales/O=Acme, where the organization is Acme
and the organizational unit is Sales. You can specify the organization or one or more organizational units
as a namespace for which an extended administration server is used to process administration requests.
The traditional administration server modifies all of the target documents in a Domino Directory which
either do not belong to any namespace or to which an extended administration server has not been
assigned.

You can designate extended administration servers for one Domino Directory by selecting a namespace in
the Domino Directory’s extended access interface and designating a particular server as an administrator
for that namespace. The new interface allows you to specify the exact namespace that an individual
administration server is responsible for.

The extended administration server distributes the administration responsibilities across multiple servers
which is especially useful for remote administration of servers that are geographically dispersed. The
concept of the extended administration server was developed in order to make remote administration
available to administrators.

All of the Domino servers in the domain must Lotus Domino 7 servers or newer to use the extended
administration server feature.

452 Lotus Domino Administrator 7 Help

Setting up an extended administration server: Complete these instructions to set up an extended
administration server.
1. From the Domino Administrator, click the Files tab and then open the Domino Directory
(NAMES.NSF).
2. Choose Files - Database - Access Control.
3. Click Advanced and select Enable Extended Access.
4. Click Basics and click Extended Access.
5. In the Names list, select the namespace (an organization or one or more organizational units) for
which you are assigning an administration server.
6. Select the server that you are designating as an administration server.
7. Choose one of these ″Access applies to″ settings:
v This entry only -- to assign the selected administration server to the selected namespace only.
Namespaces that are subordinate to the selected namespace are not affected by this selection.
v This entry and all descendants -- to assign the selected administration server to the selected
namespace and to all subordinate namespaces.
8. In the Access field, in the Allow column, click Administer.
9. Click OK.
10. Click Yes.

Removing an extended administration server: Complete these instructions to remove an extended

administration server.
1. From the Domino Administrator, click the Files tab and then open the Domino Directory
(NAMES.NSF).
2. Choose Files - Database - Access Control.
3. Click Extended Access.
4. In the Names list, select the namespace (an organization or one or more organizational units) from
which you are removing an administration server.
5. Select the server that will no longer be an administration server for the selected namespace.
6. Click Remove.
7. Click OK.
8. Click Yes.

Adminstration Process Statistics

Use the Administration Process statistics to monitor and review the administration process activity on the
servers in your Domino domains.

Administration Process statistics and their descriptions are listed in this table.

Administration Process Statistic Reason for update to statistic

ACLsModified Statistic is updated when the Administration Process
modifies a database ACL.
ReaderAuthorModified Statistic is updated when the Administration Process
modifies a database due to a user name change, resulting
in a change to Reader and/or Author fields for that
database.
ReplicasDeleted Statistic is updated when the Administration Process
deletes a mail file due to a mail database move, or when
user, the user’s mail file and replica are deleted. This
statistic is also updated when replicas are removed due
to a Delete Database request.

Chapter 17. Setting Up the Administration Process 453

Administration Process Statistic Reason for update to statistic
ReplicasCreated Statistic is updated when the Administration Process
creates a mail file due to a mail file move.
AppointmentsModified Statistic is updated when the Administration Process
updates an appointment due to a name change.
ProfilesModified Statistic is updated when the Administration Process
updates the calendar profiles due to a user’s name
change.
DesignElementsDeleted Statistic is updated when the Administration Process
removes a design element from a database. In most cases
this occurs when a user is deleted and the agents that
were created by the user are removed from a database.
DirectoryDocumentsDeleted Statistic is updated when the Administration Process
deletes entries from the Domino Directory, for example,
deletions due to deleting a user or a server.
DirectoryDocumentsModified Statistic is updated when the Administration Process
modifies entries in the Domino Directory, for example,
when a user is renamed.
DirectoryDocumentsAdded Statistic is updated when the Administration Process
updates entries in the Domino Directory, for example,
when Mail-In database entries are added for future
processing.
Cross Domain Request Sent Statistic is updated when the Administration Process
sends requests from one domain to another domain. This
occurs when cross-domain processing is enabled.
Cross Domain Request Rejected Statistic is updated when the Administration Process
receives or rejects requests from another domain. This
occurs when cross-domain processing is enabled.
Cross Domain Request Accepted Statistic is updated when the Administration Process
receives or accepts requests from another domain. This
occurs when cross-domain processing is enabled.

Administration request messages

The response Log documents in the Administration Requests database contain error messages that
describe any errors that occur during the processing of an administration request. Error messages also
appear on the console of the administration server. Administrators who want to be notified when one of
these events occurs on a server, can create an Event Handler document in EVENTS4.NSF to define how
they want to be notified.

For more information on Event Handlers, see the chapter ″Monitoring the Domino Server.″

For details on what the particular messages mean and for information on the corrective actions that can
be taken, see the documentation in EVENTS4.NSF for that message.

This table describes the messages and, in some cases, the causes of messages that appear in the
Administration Requests database. In addition, the table indicates the corrective action to take, where
appropriate.

454 Lotus Domino Administrator 7 Help

Message Occurs during Corrective action to take
The time after which this request can be Renaming When the time arrives, select ″Perform request
processed has not been reached. This again″ in the response Log document.
request cannot be processed until time; Recertification
check the Perform request again? box after
time.
The date after which this request is no Renaming Resubmit the request from the Domino
longer valid has passed. This request could Directory.
only be processed until time; the current Recertification
date and time is time.
This name does not appear in the ACLs of Renaming None
any databases designating server as their
Administration Server. Deletion
The mail file was previously deleted on Delete all replicas of a None
server by a Delete Mail File administration mail file when
request. deleting a user name
The mail file specified for this person in the Delete all replicas of a None
Address Book does not exist on this server. mail file when
deleting a user name
A replica of this person’s mail file does not Delete all replicas of a None
exist on this server. mail file when
deleting a user name
The signature on this request has expired. Renaming Resubmit the request from the Domino
Directory.
The issuer of this request does not have the Renaming Resubmit the request from the Domino
proper authority. Directory. Be sure to use a certifier ID that is
an ancestor of the user ID.
All of the required fields in the request Any request Resubmit the request from the Domino
have not been signed. Directory.

Cause of error - An unauthorized person or

a non-Domino program edited a posted
request. This indicates a failed security
attack.
The request’s new public key does not Copy Server’s Delete the request, and then shut down and
match the designated server. Certified Public Key restart the appropriate server to issue a new
request.
Cause of error - The key in the request
doesn’t match that in the Server document. Delete the public key from the Server
document.
The existing public key is newer than the Copy Server’s None
public key in the request. Certified Public Key

Cause of error - The server was recertified

before this request could be carried out.
The request’s signer and the designated Place Server’s Notes Delete the original request and then restart
server are not the same. Build number into the server. Click ″Perform request again″ in
Server Record the response Log document.
Cause of error - The server specified in the
request did not sign the request. This may
indicate a failed security attack from a
forged request or a request generated by a
non-Domino program.

Chapter 17. Setting Up the Administration Process 455

Message Occurs during Corrective action to take
The selected certifier is not the target Request Move to New Reissue the request and specify the correct
certifier in the move request. Certifier certifier.

Cause of error - The target certifier is not

the one you specified when you issued the
original request.
A required certifier was not found in the Initiate Rename in Do the following:
Address Book. Domino Directory 1. Create the necessary Certifier document(s)
in the Domino Directory.
If you see the error when the administrator Recertify Server in
is performing an action, the Certifier or Domino Directory 2. For each Certifier document, copy the
Cross-Certifier document is identified in the certified public key from the certifier ID to
Notes Log on the administrator’s client. Recertify Person in the Certifier document in the Domino
Domino Directory Directory.
If the Administration Process reports the 3. At the server console, enter load updall
error, the Certifier or Cross-domain Certifier Rename Person in names.nsf -t $certifiers.
document is identified in the log Domino Directory
4. Click ″Perform request again″ in the
(LOG.NSF) of the server that reported the
Rename Server in response Log document.
error.
Domino Directory
The change request was not for a server or Rename Resubmit the request from the Domino
person. Directory.

Cause of error - An unauthorized person or

a non-Domino program edited a posted
request. This can indicate a failed security
attack.
The Administration Process cannot set the Delete Unlinked Mail Restart the server, and then click ″Perform
target time for processing requests. File request again″ in the response Log document.
This type of Administration Request cannot All requests except Upgrade the server to hierarchical naming so
be performed on a non-hierarchical server. Copy Server’s you can complete all Administration Process
Certified Public Key requests on it.
and Place Server’s
Notes Build Number
Into Server Record
The Administration Process is not designed When a server Upgrade the server to the current release.
to support this type of Administration running an older
Request. version of Notes
encounters a Domino
5.0 Administration
Request. An older
server is unable to
process the request.

456 Lotus Domino Administrator 7 Help

Message
The name to act on was not found in the
Address Book.
Cause of error - The public key is corrupt
in the Person or Server document.
The administrator or database manager
requesting the delete action needs Author
access (or greater) to the Address Book.
The requests require at least Author (with
Delete documents) access with the
appropriate role (UserModifier,
ServerModifier, or GroupModifier). The
person must have access to the replica of
the Domino Directory used to submit the
request and to the replica on the
administration server for the Domino
Directory.
The person requesting the delete action
cannot delete documents in the Address
Book.
Cause of error - This can indicate a failed
attempt by an unauthorized person to
delete documents from the Domino
Directory.
The Administration Process cannot set the
execution time for a spawned request.
This server is not currently a member of a
cluster. This database cannot be marked for
deletion.
The Author of the Administration Request
is not allowed to create databases on this
server.
Occurs during Corrective action to take
Renaming Delete the corrupted public key from the
Server or Person document.
Recertification
From a Server document:
1. From the Domino Administrator, select a
server and click the Configuration tab.
2. Click Edit document.
3. Click the Miscellaneous tab.
4. Delete the public key from the Certified
Public Key field, or if you are adding one,
enter a public key.
5. Click Save and Close.
From a Person document:
1. From the Domino Administrator, click the
People & Groups tab.
2. Select the person whose Person document
you are modifying.
3. Click Edit Person.
4. Click the Public Keys tab.
5. Delete the public key from the Certified
Public Key field, or if you are adding one,
enter a public key.
6. Click Save and Close.
Delete user, server, or Give the person making the request the
group appropriate access to the Domino Directory,
and then select ″Perform request again″ in the
response Log document.
Delete users, servers, The person submitting the request doesn’t
groups, or resources have appropriate access to the replica of the
Domino Directory.
Give the person making the request the
appropriate access to the Domino Directory.
Delete Mail file Restart the server and then click ″Perform
request again″ in the response Log document.
Remove Server from Manually delete the database.
Cluster
Create Replica Give the person making the request Create
Database access to the destination server.
Move Replica Then click ″Perform request again″ in the
response Log document.
Chapter 17. Setting Up the Administration Process 457
Message Occurs during Corrective action to take
Mail file already exists. New mail file not Create Mail File None
created.
The person requesting this move action Move Replica Give the person making the request Manager
needs at least Manager access to the with Delete documents access. Then select
database. Non-cluster move ″Perform request again″ in the response Log
replica document.
Server name not found in Public Address Rename in Access Wait for the name change to replicate to the
book. Control List Domino Directory on this server. Then select
″Perform request again″ in the response Log
document.

458 Lotus Domino Administrator 7 Help

Chapter 18. Setting Up and Using Domino Administration
Tools
This chapter explains how to install and navigate the Domino Administrator. It also includes information
on setting up and using the Web Administrator, which allows you to administer a Domino server using a
browser.

The Domino Administrator

The Domino Administrator is the administration client for Notes and Domino. You can use the Domino
Administrator to perform most administration tasks. You can administer the Domino system using the
local Domino Administrator or using the Web Administrator.

Information about the Domino Administrator in this section includes:

v Domino Administrator installation
v Setting up and starting the Domino Administrator
v Selecting a server to administer in the Domino Administrator
v Setting Domino Administrator preferences
v Navigating Domino Administrator
v How administrative tasks are organized on the Domino Administrator tabs

Note: The Domino Administrator client also offers Domino domain monitoring (DDM) which you can
use to view the overall status of multiple servers across one or more domains, and then use the
information provided by DDM to quickly resolve problems.

For more information about Domino domain monitoring, see the chapter ″Domino Domain Monitoring.″

Installing the Domino Administrator

When you install and set up a Domino server, the Server Setup program does not install the Domino
Administrator, which is the administration client. You must run the Domino Administrator client setup to
install the Domino Administrator client. There are many ways to set up your Administrator client
installation.

Do not install the Domino Administrator on the same system on which you installed the Domino server.
Doing so compromises Domino’s security and impairs server performance.

For more information on installing the Domino clients, including the Domino Administrator, see the
chapter, ″Setting Up and Managing Notes Users.″

Setting up the Domino Administrator

1. Make sure the Domino server is running.
2. Start the Domino Administrator.
3. The first time you start the Domino Administrator, a setup wizard starts. After you answer the
questions displayed by the setup wizard, the Domino Administrator client opens automatically.

Starting the Domino Administrator

There are several ways to start Domino Administrator.
1. Make sure the Domino server is running.

459
2. Do one:
v From the Windows® control panel, click Start - Programs - Lotus Applications - Lotus Domino
Administrator.
v Click the Domino Administrator icon on the desktop.
v From the Notes client, click the Domino Administrator bookmark button or choose File - Tools -
Server Administration.

Navigating Domino Administrator

The user interface for the Domino Administrator is divided into four panes. Clicking in one pane
dynamically updates information in other panes.

Server pane
The server pane displays the servers in the domain, grouped in different views. For example, you can
view all servers in the domain or view them by clusters or networks. To ″pin″ the server pane open, click
the pin icon at the top of the server pane.

Task pane
The tasks pane provides a logical grouping of administration tasks organized by tabs. Each tab includes
all the tasks associated with a specific area of administration. For example, to manage the files located on
a particular server, select a server and click the Files tab.

Results pane
The appearance of the results pane changes, based on the task you are performing. For example, the
results pane may display a list of files, as on the Files tab, or an active display of real-time processes and
statistics, as on the Server - Monitoring tab.

Tools pane
The tools pane provides additional functions associated with a selected tab. For example, from the Files
tab you can check disk space and perform tasks associated with files.

Window tabs
Use window tabs to switch from one open window to another in the Domino Administrator. Every time
you open a database or a document, a new window tab appears beneath the main menu bar.

Domains
You can access the servers in each domain that you administer. Click a domain to open the server pane.

Bookmark bar
The Bookmark bar organizes bookmarks. Each icon on the Bookmark bar (running down the left edge of
the Domino Administrator window) opens a bookmark or a list of bookmarks, which can include Web
browser bookmarks.

Selecting a server to administer in the Domino Administrator

To administer a server, you select the server from a server list. You can have multiple server lists, each of
which is represented by a button. After you select a server, information about that server appears in all
the tabs.

Button Description
Favorites Lists your ″favorite″ servers -- that is, those you administer most frequently. To add a
server to Favorites, choose Administration - Add Server to Favorites, and then specify the
name of the server to add.
Domain Lists all servers in a domain. You can also view servers by hierarchy or by network.

For more information on adding domains, see the topic ″Setting Basics Preferences,″ later in this chapter.

460 Lotus Domino Administrator 7 Help

To update a server list
The first time you start the Domino Administrator, the system automatically creates a server list, based on
the domains listed in Administration Preferences. If you add new servers to the list, choose
Administration - Refresh Server List.

Setting Domino Administration preferences

To customize the Domino Administrator work environment, set any of these administration preferences.

Preference Description
Basics v Select domains to administer
v Add, edit, or delete domains
v Set domain location setting
v Select domain directory server
v Specify Domino Administrator startup settings
v Show Administrator Welcome Page
v Refresh Server Bookmarks on Startup
Files v Customize which columns appear on the Files tab
v Change the order in which columns appear
v Limit the types of files that the Domino Administrator retrieves
Monitoring v Configure global settings used to monitor the server
v Enable server health statistics and reports
Registration v Select global settings to use to register users, servers, and certifiers
Statistics v Select global settings for statistic reporting and charting
v Enable statistic alarms while monitoring statistics

Setting Basics preferences

To manage Domino domains, set Basics preferences.
1. From the Domino Administrator, choose File - Preferences - Administration Preferences.
2. In the Basics section, under ″Manage these Domino Domains″ do one:
v Click New to add a domain, and then continue with Step 3.
v Click Edit to edit an existing domain, and then continue with Step 3.
v Click Delete to delete an existing domain
3. Complete these fields:

Field Action
Domain name Enter the name of the domain to add, or edit an existing
name.
Domino directory servers for this domain Enter one or more directory servers, separated by
commas, or edit the list. For example:

Mail-E/East/Acme Mail-W/West/Acme
What location settings do you want to use for this Choose one:
domain? v Do not change location
v Change to this location. Specify the location from
which you want to manage this domain.

Chapter 18. Setting Up and Using Domino Administration Tools 461

4. Under Domino Administrator Startup Settings, complete these fields:

Field Action
On startup Do one:
v Choose ″Don’t connect to any server″
v Choose ″Connect to last used server″
v Choose ″Connect to specific server″ and then specify
the startup domain and startup server.
Show Administrator Welcome Page Do one:
v Check this box to see the Welcome page each time you
start the Domino Administrator.
v Uncheck this box if you do not want to see the
Welcome page.
Refresh Server Bookmarks on Startup Do one:
v Check this box to update the server’s bookmarks each
time you start the Domino Administrator. If you are
using Domino and DB2, you check this box because
server bookmarks must be up-to-date to allow all of the
Domino and DB2 features to work correctly.
v Uncheck this box if you do not want to refresh the
server’s bookmarks each time you start the Domino
Administrator.

5. Click OK, or click Files to continue setting Administration Preferences.

Setting Files preferences

Setting Files preferences, you can customize which columns appear on the Files tab, change the order in
which columns display, and limit the types files the Domino Administrator retrieves.

By default, the Files tab displays columns in this order:

v Title
v File Name
v Physical Path
v Files Format
v Size
v Max Size
v Quota
v Warning
v Created
v Last Fixup
v Is Logged
v Template

To set Files preferences:

1. From the Domino Administrator, choose File - Preferences - Administration Preferences.
2. Click the Files section.
3. Do one:
v To add a column, select a column from the Available Columns list and click the right arrow to add
it to the ″Use these Columns″ list.
v To remove a column, select a column from the ″Use these Columns″ list and click the left arrow to
remove it from the list.
462 Lotus Domino Administrator 7 Help
4. Click the up or down arrows to change the order of the columns in the ″Use these Columns″ list.
5. Check ″Retrieve only (NSF, NTF, BOX) Domino file types (faster)″ to limit the types of files retrieved.
Uncheck this box to retrieve all file types.
6. Click OK or click Monitoring to continue setting Administration Preferences.
For more information on setting Files preferences in the Web Administrator, see the topic ″Setting
Files Preferences for the Web Administrator″ later in this chapter.

Setting Monitoring preferences

You can use the default Monitoring preferences or customize them.
1. Choose File - Preferences - Administration Preferences.
2. Click Monitoring, and then complete the Global settings for Monitoring:

Field
Do not keep more than <n> MB of monitoring data in
memory (4 - 99MB)
Not responding status displayed after <n> minutes of
inactivity
Generate server health statistics and reporting
Action
Enter the maximum amount of virtual memory, in MB,
used to store monitoring data. Default is 4.
Enter the amount of time after which the ″not
responding″ status displays. The default is 10 minutes.
Select this option to include health statistics in charts and
reports.
Note: You must enable this option to use the Server
Health Monitor.

3. In the Location section, complete these fields:

Field Action
When using this location Choose the Location document.
Monitor servers Do one:
v Choose ″From this computer″ to monitor servers from
the local Domino administration client.
v Choose ″From server″ and then click Collection Server.
Select the Domino server running the Collector task
for the servers being monitored by the location you
selected.
Poll server every <n> minutes (1-60 minutes) Enter the server’s polling interval, in minutes.
v If ″From this computer″ is selected, the default is 1
minute.
v If ″From server″ is selected, the default is 5 minutes.
Automatically monitor servers at startup Select this option to start the Domino Server Monitor
when you start the Domino Administrator.

Setting Registration preferences

Within the Domino Administrator, you can set default registration preferences that apply whenever you
register new certifiers, servers, and users.
1. From the Domino Administrator, choose File - Preferences - Administration Preferences.
2. Click Registration.
3. Complete any of these fields:

Field Action
Registration Domain Select a domain from the list. The registration domain is the domain into which users
and servers are registered.

Chapter 18. Setting Up and Using Domino Administration Tools 463

Field Action
Create Notes IDs for new Click to create a Notes ID for each new user during the registration process.
users
Certifier name list Choose a certifier ID to use when creating the user name during user registration when
a Notes user ID is not being created for the user.

This field appears if the check box ″Create a Notes ID for this person″ is not selected.

If you are working in a hosted environment and are registering a user to a hosted
organization, be sure to register that user with a certifier created for that hosted
organization.
Certifier ID Do one:
v Choose ″Certifier ID″ to use the certifier ID and password. Then click Certifier ID,
select the certifier ID file, and click OK to select the certifier ID used to register new
certifiers, servers, and users.
v Choose ″Use CA Process″ to use the Domino server-based certification authority.
Registration Server Click Registration Server to change the registration server, which is the server that
initially stores the Person document until the Domino Directory replicates. Select the
server that registers all new users, and then click OK. If you do not explicitly define a
registration server, it is, by default:
v The local server if it contains a Domino Directory
v The server specified in NewUserServer setting in the NOTES.INI file
v The administration server
Explicit policy If you already created explicit policies, select the policy from the list. If you have not
created explicit policies, this field displays ″None Available.″
User Setup Profile Select a profile. The default is none. You can assign either a policy or a user setup
profile, but you cannot assign both to the same users.
Mail Options Click Mail Options to display the Mail Registration Options dialog box.

Choose one of the following and complete any required associated fields:
v Lotus Notes (default) -- The Internet address is automatically generated.
v Other Internet -- The Internet password is set by default during registration. Enter a
forwarding e-mail address.
v POP -- The Internet address is automatically generated during registration, and the
Internet password is set by default during registration.
v IMAP -- The Internet address is automatically generated during registration, and the
Internet password is set by default during registration.
v Other -- Enter a forwarding e-mail address.
v None
Note: If you select Other or Other Internet, you will need to enter a forwarding address
for the user during user registration. The forwarding address is the e-mail address to
which the user wants their mail sent.
User ID/Password Click User ID/Password Options Settings to open the Person ID File Settings dialog
Options box. Do any of these:
v Person ID folder -- Choose a folder or enter a directory path in which to store the ID
files generated for this user during registration.
v Person password quality -- Set a new password quality for the ID files that are
generated for this user during registration. The default for a user ID is 8.

464 Lotus Domino Administrator 7 Help

Field Action
Advanced Options Click Advanced Options to open the Advanced Person Registration Options dialog box
on which you can specify the following:
v Whether to keep registered users in the registration queue
v Whether to attempt to register users with an error status from a previous registration
attempt
v Whether to prompt for duplicate files
v Whether to search all directories for duplicate names
v Other registration settings
Server/Certifier Click to open the Server Certifier ID File Settings dialog box on which you can define
Registration the directories in which to store certifier IDs and server IDs and specify the default
password quality setting for each.

4. Click OK.
For more information on explicit policies, see the chapter ″Using Policies.″ For more information on
Advanced Options, see Domino Administrator 7 Help.

Setting Statistics preferences

You set statistics preferences to enable statistics reporting and statistics charting. The Statistics section in
Administration preferences is also where you specify the polling and reporting time interval used for
gathering and reporting statistics.

You also enable statistic alarms for use with statistic event generators. If you create statistics event
generators to report alarms, you must enable statistics alarms.

To set statistics preferences:

1. From the Domino Administrator, choose File - Preferences - Administration Preferences.
2. Click Statistics.
3. Complete these fields:

Field Action
Generate statistic reports while monitoring or charting Do one:
statistics v Enable the field and then specify, in minutes, how
often to create statistics reports in the Monitoring
Results database (STATREP.NSF). Default is 45
minutes. The value must be greater than the
monitoring poll interval specified in the Monitoring
preferences.
v Disable the field if you do not want to create statistics
reports or charts.
Check statistic alarms while monitoring or charting Do one:
statistics v Enable the field to report an alarm when a statistic
exceeds a threshold. You must enable this field to
generate a statistic events. Alarms are reported to the
Monitoring Results database (STATREP.NSF).
v Disable the field if you do not want to generate
alarms.

Chapter 18. Setting Up and Using Domino Administration Tools 465

Field
Chart statistic using same poll interval as monitoring
Action
Do one:
v Enable the field to use the poll interval specified in the
Monitoring preferences.
v Disable the field to set a charting interval that is
different than the poll interval. Then specify a time
interval in which to chart statistics. The default is 20
seconds.

4. Click OK.

Tools and preferences for debugging in the Domino Administrator

The Domino Administrator client offers several tools and one set of preferences for debugging errors.

From the Domino Administrator, choose Files - Tools and then choose one of these:
v Debug LotusScript -- Enables LotusScript debugging. When a check mark appears to the left of the
Debug LotusScript option, LotusScript debugging is enabled. For more information about LotusScript
debugging, see the Domino Designer documentation, topic Using the LotusScript Debugger.
v Remote LotusScript Debugger -- Opens the Domino Debugger. The remote debugger allows debugging
of LotusScript agents running on remote servers. For more information about remote debugging, see
the Domino Designer documentation, topic Using the Remote Debugger.
v Show Java Debug Console -- Opens the Java Debug Console window. For information about the Java
Debug Console, see the Domino Designer documentation, topics Writing Java in an agent, Running a
Java program, and other related topics.
v Java Debugging Preferences -- Opens the Java Debugging Preferences dialog box. For information, see
the topic Enabling Java Debugging.

Enabling Java Debugging

The Domino Administrator supports Java debugging in the following contexts. Each context has its own
JVM. Only one user can debug at a time in each context.
v Foreground -- Java code that runs in the Domino Administrator client interactively, for example, an
agent triggered from the Actions menu.
v Background -- Java code that runs in the Domino Administrator client under control of the task loader,
for example, a locally scheduled agent.
v Web preview -- Java code being previewed in a browser through Domino Designer, for example, an
applet on a form.

Java code from a script library runs in the context of the calling code.

To enable and disable Java debugging on the Domino Administrator

Java debugging is disabled by default.
1. From the Domino Administrator, choose Files - Tools - Java Debugging Preferences. The Java
Debugging Preferences dialog box appears.
2. Do one or more of these:
v To enable foreground debugging, click Client Agents/Applets, and then specify a port number to
connect the Notes and debugger computers. Deselect to disable.
v To enable background debugging, click Locally Scheduled Agents, and then specify a port number
to connect the Notes and debugger computers. Deselect to disable.
v To enable Web preview debugging, click HTTP Preview, and then specify a port number to connect
the Domino Administrator client and debugger computers. Deselect to disable.

Note: Specifying a port number may require several attempts before you locate a free port.

466 Lotus Domino Administrator 7 Help

If you change the foreground or background preference, the Domino Administrator must be restarted. If
you change the Web preview preference, the preview must be restarted.

Domino Administrator tabs

General administration tasks are organized by the tabs described in the following table. Click a tab to
display its contents, or use the Administration menu to navigate among the tabs. For example, to move
from the Files tab to the Replication tab, choose Administration - Replication.

Tab Use to administer

People & Groups People-related Domino Directory items -- such as, Person documents, groups, mail-in
databases, and policies
Files Databases, templates, database links, and all other files in the server’s data directory
The Server tabs Current server activity and tasks. This tab has five sub-tabs: Status, Analysis,
Monitoring, Statistics, and Performance.
Messaging Mail-related information. This tab has two sub-tabs: Mail and Tracking Center.
Replication Replication schedule, topology, and events
Configuration All server configuration documents -- such as, the Server, Messaging Settings,
Configuration Settings, and Server Connections documents.

People and Groups tab in the Domino Administrator

From the People and Groups tab, you perform these tasks to manage the Domino Directory:
v Register new users and groups
v Manage existing users, groups, mail-in databases, and other resources
v Assign policies to users and groups
v Assign roaming options and Internet settings to users

Files tab in the Domino Administrator

From the Files tab, you perform these tasks to manage database folders and links:
v Access a folder and one or more files inside the folder
v Select the type of files to display -- for example, display only databases or only templates
v Move or copy a database by dragging it onto a Domino server on the bookmark bar
v Manage databases -- for example, compact databases and manage ACLs
v View disk size and free space on the C drive

Server tabs in the Domino Administrator

There are five Server tabs: Status, Analysis, Monitoring, Statistics, and Performance.

Status: From the Status tab, you can:

v See which server tasks are running, stop or restart them, or start new tasks
v See who is connected to the server, including Notes users, browser and e-mail clients
v See which Notes databases are currently in use
v Access the live remote console of the server
v Monitor the schedule of programs, agents, mail routing and replication

Analysis: From the Analysis tab, you can:

v View, search, and analyze the log file (LOG.NSF)
v Access the database catalog on the server
v Access the Monitoring Results database (STATREP.NSF)
v Manage Administration Process requests

Chapter 18. Setting Up and Using Domino Administration Tools 467

Monitoring: From the Monitoring tab, you can:
v Check the status of Domino servers
v Check server availability and sort servers by state or timeline
v View the current status of tasks running on each server and view selected statistics
v Monitor server health status and access server health reports

Statistics: From the Statistics tab, you can see the real-time statistics for the current status of the Domino
system.

Performance: From the Performance tab, you can:

v View statistic charts for server performance in real time
v Chart historical server performance over a selected period of time
v Manage server activity trends
v Perform resource load-balancing among servers

Messaging tabs in the Domino Administrator

There are two messaging tabs.

Mail: From the Mail tab, you can:

v Manage the mailboxes on the server
v Check mail
v Manage shared mail
v Monitor the log file for routing-related events
v Run reports on messaging use

Tracking Center: From the Tracking Center tab, you can issue tracking requests to track messages. You
must enable the Tracking Center tab in the Web Administrator.

For more information on enabling the Tracking Center for the Web Administration, see the topic
″Message-tracking in the Web Administrator″ later in this chapter.

Replication tab in the Domino Administrator

From the Replication tab, you can:
v View the server replication schedule
v Check the log file for replication events
v View replication topology maps related to the server

Configuration tab in the Domino Administrator

From the Configuration tab, you can configure all server options, settings, and configurations for various
subsystem including:
v Security
v Monitoring
v Messaging
v Policies
v Replication
v Directory services
v Off-line services

468 Lotus Domino Administrator 7 Help

Domino Administrator tools
Most tabs on the Domino Administrator include a set of tools that change based on the selected tab. For
example, the People and Groups tab includes two tools: one for managing people and one for managing
groups.

To hide or show the Tools panel, click the triangle. To choose a specific tool, click the triangle to expand
or collapse the tools options. Hiding tools on one tab does not hide tools on other tabs.

You can also access tools using:

v Right click -- Select an object that has an associated tool and right click. For example, on the People &
Groups tab, right-click a Person document to access the People tools.
v Menus -- For each tab that has tools, the appropriate tools menu appears in the menu bar. For example,
when you click the Files tab, the Files menu appears.

The following table describes the tools that are on each tab.

Tab Tools
People & Groups v People
v Groups
Files v Disk Space
v Folder
v Database
Server - Status v Task
v User
v Ports
v Server
Server - Analysis v Analyze
Messaging v Messaging
Configuration v Certification
v Registration
v Policies
v Hosted Org
v Server
v Miscellaneous

Web Administrator
If you have a browser and want to manage and view settings for a Domino server, you can use the Web
Administrator to perform most of the tasks that are available through the Domino Administrator. This
section includes the following information about the Domino Web Administrator:
v Setting up the Web Administrator
v Setting up access to the Web Administrator database (WEBADMIN.NSF)
v Giving additional administrators access to the Web Administrator and assigning roles
v Starting the Web Administrator
v Using the Web Administrator

Chapter 18. Setting Up and Using Domino Administration Tools 469

Setting up the Web Administrator
The Web Administrator uses the Web Administrator database (WEBADMIN.NSF). The first time the
HTTP task starts on a Web server, Domino automatically creates this database in the Domino data
directory. However, you need to make sure that the Web browser and server meet these requirements for
the Web Administrator to run.

Web browser requirement

You must use one of these browsers with the Web Administrator:
v Microsoft Explorer 6.0 on Windows 2000 or Windows XP
v Mozilla Browser 1.7.6 on Microsoft Windows XP Professional, Microsoft Windows 2000, IBM AIX,
Solaris, Linux REL 3.0 and Novell Linux Desktop 9
v Mozilla Browser on Windows 2000, or on Linux 7.x

For the most current information about supported browsers, see the Release Notes.

Domino server tasks required

You must have the following Domino server tasks running:
v The Administration Process (AdminP) server task must be running on the Web Administrator server.
v The Certificate Authority (CA) process must be running on the Domino 7 server that has the Issued
Certificate List database on it to register users or servers.
v The HTTP task must be running on the Web server so that you can use a browser to access it.

To set up the Web Administrator

1. Make sure that the server you want to administer is set up as a Domino Web server and that it is
running the HTTP task. The Domino Web server does not have to be a dedicated server, you can use
it for other server tasks, such as mail routing and directory services. You can administer only the
servers you set up as Domino Web servers.
2. Set up administrator access to the Web Administrator database (WEBADMIN.NSF).
For more information on setting up the Domino Web server, see the chapter ″Setting Up the Domino
Web Server.″

Setting up access to the Web Administrator database

Domino automatically sets up default database security when the Web Administrator database
(WEBADMIN.NSF) is created for the first time. At that time, all names listed in either the Full Access
Administrators or Administrators fields of the Server document are given Manager access with all roles
to the Web Administrator database. In addition, the HTTP server task periodically (about every 20
minutes) updates the Web Administrator database ACL with names that have been added to the Server
document in either the Full Access Administrators or Administrators fields, but only if the names are not
already on the ACL list.

For more information on how the HTTP server task synchronizes names in the Server document with
those on the Web Administrator database ACL, see ″Giving additional administrators access to the Web
Administrator,″ later in this chapter.

Default database security: The default ACL settings for the Web Administrator database are listed
below. You do not need to change these settings if the administrator’s name appears in the
Administrators field of the Server document.

470 Lotus Domino Administrator 7 Help

Access control list:

Default name Access level

User and group names listed in either of these fields on the Server Manager with all roles
document:
v Full Access Administrators
v Administrators
The name of the server Manager
-Default- No access
Anonymous No access
OtherDomainServers No access

Authenticating administrators: You can use either an Internet password or an SSL client certificate to
access the Web Administrator. The Web Administrator uses either name-and-password or SSL
authentication to verify your identity. The method the Web Administrator uses depends on whether you
set up the server or the Domino Web Administrator database (WEBADMIN.NSF), or both to require
name-and-password or SSL authentication.

To access the Web Administrator database, you must have name-and-password authentication or SSL
client authentication set up on the server. Name-and-password authentication is enabled for the HTTP
protocol by default.

To use name-and-password authentication, you must have an Internet password in your Person
document. To use SSL client authentication, you must have a client certificate, and SSL must be set up on
the server.

For more information, see the chapters ″Setting up Name-and-Password and Anonymous Access to
Domino Servers,″ ″Setting up Clients for S/MIME and SSL,″ and ″Setting up SSL on a Domino Server.″

Giving additional administrators access to the Web Administrator

You can use the Server document as a convenient way to give additional administrators access to the
Web Administrator. To add an administrator to the Web Administrator database (WEBADMIN.NSF) ACL,
simply add the name to either the ″Full Access Administrators″ or ″Administrators″ field of the Server
document. The HTTP server task routinely synchronizes the names listed in those fields of the Web
Server document with those listed on the Web Administration database ACL. Names that are not already
listed in the ACL are added with Manager access and all roles. Names that are already listed in the ACL,
keep the access granted to them in the ACL. This preserves custom ACL settings, such as limiting the
ACL roles of a particular administrator, from being overwritten. It also allows you to restrict
administrators from using the Web Administrator, even though they are listed as administrator in the
server document. If you delete an administrator’s name from the Server document, the name is also
deleted from the Web Administrator database ACL automatically at the next synchronization.

You can also give administrators access to the Web Administrator manually by adding them directly to
the Domino Web Administrator database ACL. You can give an administrator full or partial access by
restricting the roles assigned. The role assigned to an administrator determines which commands are
available to the administrator, and which tabs appear in the Web Administrator client. You cannot restrict
roles when you add administrator access to the Web Administrator using the Server document. If you
add a name using the server document, you must manually restrict access to the web Administrator
through the Domino Web Administrator database ACL. To prevent an administrator from access, assign
No access in the ACL.

For more information on Web Administrator roles, see the topic ″Administrator Roles in the Web
Administrator″ later in this chapter.

Chapter 18. Setting Up and Using Domino Administration Tools 471

To update access to the Web Administrator database automatically:
1. From the Domino Administrator, click the Configuration tab.
2. Select the Server view, and open the Current Server Document for the Web Administration server.
3. Select the Security tab.
4. In one of these fields, enter the name of the administrator to whom you want to give access to the
Web Administrator:
v Full Access Administrators
v Administrators
5. Click Save & Close

To update the Web Administrator database ACL list manually: You can manually add an administrator
to the Web Administrator database ACL list.
1. From the browser using the Web Administrator, click the Files tab.
2. Select the Web Administrator database (WEBADMIN.NSF).
3. From the Tools menu, select Database - Manage ACL.
4. Click Add and add the administrator or group name to the ACL of the Web Administrator database.
5. In the Access field, select Manager.
6. Assign the roles. Assigned roles determine which commands and tabs appear in the Web
Administrator.

Tip: To select more than one role, hold down the Shift or Control key while selecting roles. Selected
roles appear highlighted.
7. Do one of the following:
v If the server requires name-and-password authentication, edit each administrator’s Person
document and enter an Internet password.
v If the server requires SSL client authentication, set up the browser for SSL.
For more information on Managing ACL roles, see the chapter ″Controlling User Access to Domino
Databases.″ For more information on SSL authentication, see the chapter ″Setting Up Clients for
S/MIME and SSL.

Administrator roles in the Web Administrator

By default, the ACL gives Manager access and all roles to users named in the Administrators and Full
Access Administrators fields on the Server document. However, you can restrict a Web administrator’s
access to parts of the Domino Administrator by limiting the assigned roles. Each role has a corresponding
tab and associated commands. When you restrict access, you also restrict which tabs appear in the Web
Administrator.

For example, if you assign only the People&Groups role to a Web Administrator, the People & Groups
tab is the only tab that appears when that administrator uses the Web Administrator. The following table
shows the roles that have been predefined for the Domino Web Administrator.

Role Tab
Files Files
People&Groups People & Groups
Replication Replication
Configuration Configuration
Mail Messaging - Mail
MsgTracking Messaging - Tracking Center
ServerStatus Server - Status

472 Lotus Domino Administrator 7 Help

Role Tab
ServerAnalysis Server - Analysis
ServerStatistic Server - Statistic

To restrict a Web administrator’s access, use the Manage ACL tool on the Files tab. For more information
on managing ACL roles, see the chapter ″Controlling User Access to Domino Databases.″

Starting the Web Administrator

When you start the Web Administrator, it displays the server’s administration homepage (information
about the server and the administrator using the server). It does not automatically open to a tab, you
must choose a tab to begin using the Web Administrator. To return to the server administration
homepage at any time, click the top left server icon in the Web Administrator bookmark bar.

To start the Web Administrator

1. Start the HTTP task on the server if it is not already running.
2. From the browser, enter the URL for the Web Administrator database on the server you want to
administer. For example, enter:
http://yourserver.domain.com/webadmin.nsf
Or for SSL, enter:
https://yourserver.domain.com/webadmin.nsf
3. Enter your hierarchical, common name, or short name and your Internet password.
4. Click one of the tabs to being using the Web Administrator.

Using the Web Administrator

The Web Administrator is almost identical to the Domino Administrator with very few exceptions. The
user interface looks the same, and most menu options, dialog and information boxes are identical,
although the Web Administrator may occasionally display additional information. For example, the Mail
tab in the Web Administrator offers additional mail specific statistics -- for example, Mail Routing
Schedule, Mail Routing Statistics, and Mail Retrieval Statistics. This information is available in the
Domino Administrator; however, it is not displayed the same way.

In addition, there is a new Task tool on the Replication and Mail - Messaging tabs. You can use this tool
to issue Tell commands, and to stop, start, and restart replication, router, and messaging tasks.

The Web Administrator includes most of the Domino Administrator functionality. However, the Domino
Server Monitor and performance charting are not available in the Web Administrator. And you can
restrict further which commands and tabs are available by restricting the roles assigned to an
administrator. Information on the availability of specific Web Administrator features and minor changes
to how you access a feature are documented throughout the Domino Administrator help documentation.

For the most recent information on using the new Domino Web Administrator, see the Release Notes that
shipped with this product or download the Domino Administrator online help from the Lotus Domino
Administrator Release 7 download page on the Lotus Developer Domain at http://www.lotus.com/ldd.

Accessing online help

To access online documentation, use the Help button.

Additional buttons
The Domino Web Administrator includes these buttons that appear at to the right of the tabs. These do
not appear in the Domino Administrator:
v Sign out -- Use this to log out when you cannot or do not want to close the browser.

Chapter 18. Setting Up and Using Domino Administration Tools 473

v Preferences -- Use this to set Administration preferences.
v Help -- Use this to access on-line help documents for the Domino Administrator.

The mail bookmark displays in the bookmark area only if you have browsed to your home mail server.

Setting Files preferences for the Web Administrator

You can use the Web Administrator to set Files preferences.

Files preferences: By default, the Files tab in the Domino Administrator displays information about
database files in the following order; however, you can customize which columns display in the Web
Administrator. The fewer columns you display, the faster the Files panel performs.
v Title
v File Name
v Physical Path
v File Format
v Size
v Space Used
v Max Size
v Quota
v Warning
v Created
v Last Fixup
v Is Logged
v Template Name
v Inherit From
v Type
v Replica ID

To set Files preferences: By default, the Web Administrator displays all columns. You can add or delete
columns from the display. Select a column name from the ″Use these Columns″ list and then click Add or
Remove.

Registering users and servers with the Web Administrator

To use the Web Administrator to register new Notes users, you must use the Domino server-based
certification authority. Any request or task that requires a certifier ID file -- for example, migrate or
modify ID -- is not available.

To use the Web Administrator to register users or servers, you must have Registration Authority (RA)
access in the server-based certification authority (CA). The server that is running the Web Administrator
should also be listed as an RA but that role is not required for the server. If, however, the server is not
listed as an RA, the administrator that is an RA must open the Administration Requests database and
approve the administration request to register the user. You must assign the RA role in the Domino
Administrator, not in the Web Administrator. To assign the RA role, use the Modify Certifier tool on the
Configuration panel.

You cannot set registration preferences in the Web Administrator. You must use the registration settings in
the CA and in the Registration policy settings document.

In the Web Administrator, you cannot configure a server for SSL during the server registration process.

For more information about modifying certifiers, see the chapter ″Setting up a Domino Server-Based
Certification Authority.″ For more information about user registration in the Web Administrator, and

474 Lotus Domino Administrator 7 Help

about creating and modifying groups, see the chapter ″Setting Up and Managing Notes Users.″ For more
information about registering a server, see the chapter ″Installing and Setting Up Domino Servers.″

Managing policies with the Web Administrator

The Policy tools on the Configuration and People & Groups tabs in the Domino Administrator are not
available in the Web Administrator. Therefore, from the Web Administrator, you cannot use the Policy
Assign tool or the Policy Synopsis tool.

If you create policies before you register users, you can assign them to users and groups during user
registration. You can also edit a Notes user’s Person document and manually assign an explicit policy by
specifying the name of the policy.

Working with policy documents: From the Web Administrator, you can use the Policies view in either
the People & Groups or the Configuration tab to add, edit, or delete policy documents. To add or delete
policy documents, use the buttons that display in the Results pane. In this view, the names of policy
documents are links. To edit one of these documents, click the link for the document you want to edit.

Using the Web Administrator to delete policy documents is not recommended because doing so does not
initiate the Administration Process requests required to remove all references to the deleted document
from other policy documents.

If you use the Web Administrator to create Setup or Desktop policy settings documents, you cannot add
the database links used to set up bookmarks or custom Welcome pages.

For more information about managing policies and policy documents, see the chapter ″Using Policies.″

Using the Web Administrator consoles

The Web Administrator includes two consoles, the Quick Console and the Live Console, which you access
from the Server - Status tab. These consoles mirror the server console on the Server Status tab of the
Domino Administrator.

Use the Live Console to send commands to a Web server running under a Server Controller. You can
send Controller and shell commands, as well as Domino server commands. To use the Live Console, you
must install Java Plug-in 1.4 or higher and enable it in your Web browser.

Use the Quick Console to send commands to a Web server that does not run under a Server Controller.
Or use it if you are unable to install or use the Java Plug-in in your browser.

For more information on using the console in the Web Administrator to send commands, see the topic
″The Server Controller and the Domino Console,″ later in this chapter and the appendix ″Server
Commands.″

Using the Web Administrator with service providers

Service providers may allow administrators at hosted organizations to manage users and groups by
allowing remote access through the Web Administrator, with restricted roles. In some cases, the
administrator at the service provider site will assume all responsibilities for managing users and groups.

For more information on service providers, see the chapter ″Managing a Hosted Environment.″

Message tracking in the Web Administrator

To use the Web Administrator to trace messages, you must first enable message tracking.

To enable message tracking:

1. From the Web Administrator, click the Configuration tab.
2. Open the Messaging view, and select Settings.
3. Click Edit Message Settings.

Chapter 18. Setting Up and Using Domino Administration Tools 475

4. Select the Message Tracking tab.
5. Under Basics, in the Message tracking field, select Enabled. The default is Disabled.
6. Under Access Settings, complete these fields:

Field Action
Allowed to track messages Select both of these:
v Your name
v LocalDomainServers
Allowed to track subjects Select your name from the list

7. Click Save & Close.

Editing the NOTES.INI file and cleanup script in the Web Administrator
You must be a Full Access Administrator to edit the NOTES.INI file. You must have Administrator access
or higher to view the NOTES.INI file, or to edit or view the cleanup script.

For more information on editing the NOTES.INI file, see the appendix ″NOTES.INI File.″

Signing out of the Web Administrator

When you finish using the Web Administrator, close the browser to end the session or click Sign out to
end the session and clear your user name and password credentials so that unauthorized users cannot
access the browser while the Web Administrator is still running.

The Server Controller and the Domino Console

The Server Controller is a Java® based program that controls a Domino server. Starting the Server
Controller starts the Domino server it controls. When a server runs under a Server Controller, you can
send operating system commands (shell commands), Controller commands, and Domino server
commands to the Server Controller. For example, from a remote console, you can use Controller
commands to kill Domino processes on a server that is hung or to start a Domino server that is down.

You can use the Domino Console, a Java-based console, to communicate with a Server Controller. You can
run the Domino Console on any platform except Apple Macintosh. Using the Domino Console, you can
send commands to multiple servers. The Domino Console doesn’t require a Notes ID, only a Domino
Internet name and password, so you can connect to servers certified by different certifiers without having
multiple Notes IDs or cross-certificates. You can customize output to the Domino Console -- for example,
use local event filters to specify the types of events the Console displays. You can also log server output
to log files and customize the appearance of the Console.

The Domino Console functions strictly as a server console. Consequently, the Domino Console doesn’t
include the full set of Domino administration features that are available through the Domino
Administrator and the Web Administrator, and you can’t use it to open and manage Notes databases.

The files needed to run the Server Controller and to run the Domino Console are provided with Domino
and Notes.

You can also use remote consoles in the Domino Administrator and Web Administrator to communicate
with a Server Controller.

For information on the available Controller commands and on using the Domino Administrator or Web
Administrator to communicate with a Controller, see the appendix ″Server Commands.″

476 Lotus Domino Administrator 7 Help

Starting and stopping the Server Controller
Do the following to start the Server Controller, the Domino server, and the Domino Console:
1. Shut down the Domino server, if it is running.
2. Start the Server Controller using the same command you normally use to start the Domino server but
append the argument -jc. For example, if you run a server on Windows XP from the directory
c:\lotus\domino using a shortcut icon on the Desktop, use the following target for the shortcut:
c:\lotus\domin\nserver.exe -jc

The Server Controller runs in its own window. You can minimize a Server Controller window, but do not
close or kill the window to stop the Server Controller. Instead, use the Controller Quit command from a
console to stop a Server Controller and the server it controls.

When you run a Server Controller, you no longer have access to the traditional console at the server. You
can communicate only through the Domino Console or a console in the Domino Administrator or Web
Administrator.

Optional arguments to use when running the Server Controller

Starting the Server Controller using only the argument -jc starts the Domino Server and the Domino
Console along with the Server Controller. There are two optional arguments you can specify to change
this default behavior: -c and -s.

Use -c to prevent the Domino Console from running when you start the Server Controller. You might
prevent the Console from running on a slow machine or a machine that is low on memory. If you use
this argument and the Domino server ID requires a password, the Domino server starts without running
its server tasks. To run the server tasks, you must connect to the Server Controller from a console and
specify the server password when prompted.

Use -s to prevent the server from running when you start the Server Controller. Use this argument along
with -c so that someone who is directly at the server can start only the Server Controller, and then a
remote administrator can start the server and specify a required server password remotely from a
console.

Example Result
nserver -jc Runs the Server Controller, the server, and the Domino Console
nserver -jc -c Runs the Server Controller and the server
nserver -jc -s Runs the Server Controller and the Domino Console
nserver -jc -c -s Runs only the Server Controller

Starting and stopping the Domino Console

You can run the Domino Console from any machine on which a Domino server or the Domino
Administrator is installed. To use the Domino Console to communicate with a Domino server, the server
must be running under a Server Controller.

To start the Domino Console

1. Make sure that the Domino server or the Domino Administrator is installed on the machine.
2. Run the following command directly from the program directory, or from a directory path that points
to the program directory:
jconsole

Note: The Domino Console also starts by default when you start a Server Controller.

Chapter 18. Setting Up and Using Domino Administration Tools 477

For information on using the Domino Console, choose Help - Help Topics from the Domino Console
menu.

To stop the Domino Console

1. From the Domino Console, choose File - Exit.
2. If the Console is currently connected to a Server Controller, when you see the prompt ″Exiting the
Console by disconnecting all active connections. Do you want to continue?″ do the following:
a. (Optional) To also stop a Domino server and Domino Server Controller running locally, select the
option ″Also, bring down Domino (if running) and quit the local Server Controller - local server
name.
b. Click Yes.

478 Lotus Domino Administrator 7 Help

Chapter 19. Using Domino with Windows Synchronization
Tools
This chapter explains how to synchronize user and group information in the Windows 2000 Active
Directory(R) and in Notes.

Setting up Domino Active Directory synchronization

When the Domino server is installed on a Windows 2000 server, as an administrator, you typically need
to maintain two separate directories for the same set of people and groups. Maintaining user and group
information involves adding entries to both directories, deleting entries, ensuring that passwords are the
same when users use Notes Single Logon, coordinating group membership in both directories, and
ensuring that user or group settings, such as e-mail addresses and telephone numbers, are identical.

Lotus Domino includes a set of tools to make synchronization between Domino and Active Directory(R)
simple and easy. The Active Directory Domino Upgrade Service (AD DUS) is a tool that you can use with
Active Directory synchronization (ADSync) when you have data in your Active Directory and you have
just installed Domino. AD DUS can optionally be used to migrate all or a set of your Active Directory
users. After you’ve done that, you can start using ADSync to maintain those users in Active Directory
and in Domino.

User options are available to register Notes users in Active Directory. In the Domino Administrator’s user
registration interface, there is a ″Windows User Options″ button on the Other panel of the Register
Person - New Entry dialog box. You can select options to register a user in Active Directory at the same
time that the user is registered in Domino. This is essentially the opposite of what ADSync does.
Regardless of the tool with which you register a new user in both directories, you can use ADSync to
synchronize and delete users from both directories. You can also use ADSync to rename users in both
directories.

For more information on the user options available when registering Notes users, see the chapter ″Setting
Up and Managing Notes Users.″

You can synchronize Person and Group documents in the Domino Directory, and user and group
accounts in Active Directory. When you register or delete a Notes user or delete a Notes group, you can
automatically update the Active Directory. Use the Notes synchronization options to enable the
synchronization of all operations.

Conversely, special menu options and dialog boxes added to the Users and Computers snap-in of the
Microsoft Management Console (MMC) enable you to specify that additions, deletions, and name changes
made to Active Directory user or group accounts be reflected in the Domino Directory. You can also add
existing Active Directory user or group accounts to the Domino Directory, and synchronize Active
Directory and Domino Directory entries.

These directory synchronization features let you keep both the Domino Directory and Active Directory
current without having to update both when either changes. Also, you can manage user and group
information in the Domino Directory and the Active Directory through a single interface of your choice,
either Domino or Windows 2000.

You must have a properly certified Notes ID and appropriate access to make any changes to a Domino
Directory from Notes or Windows 2000, and have the appropriate rights if you are going to use the
Domino server-defined certification authority (CA) to certify users on Domino. Use a Lotus Notes 6 or
more recent client, and Lotus Domino 6 or more recent server as your registration server. You must create

479
policies that contain registration settings documents, either implicit or explicit, for all Domino certifiers
with which you are going to certify new users. Also, you must have appropriate rights in the Active
Directory allowing you to add user accounts and synchronize passwords.

To set up Domino Active Directory synchronization

Install the Active Directory domain controller, the Domino server, and the Domino Administrator on
separate machines to improve performance and enhance security. However, if necessary you may install
any two or all three of these on the same machine.
1. From a Windows 2000 Professional workstation, log into the Windows domain using a user account
with administrative rights.
2. From the Windows 2000 Server CD, install the Windows 2000 Administration Tools Package. From
the CD, run \i386\adminpak.msi.

Note: This file is not on the Windows 2000 Professional workstation CD. You must install the file
from the Windows 2000 Server CD. Microsoft licensing permits you to install this administrative
package on Windows 2000 Professional workstations.
3. From the Start menu, click Programs - Administrative Tools - Active Directory Users and Computers,
and verify that the workstation has connected to the domain controller.
4. Install, but do not run, the Domino Administrator.
5. Open a command prompt. From your Notes install directory, type:
regsvr32 nadsync.dll
A message box appears indicating that registration is complete. This can take up to one minute.
6. Run the Domino Administrator and complete the configuration process.
7. From the Domino Administrator, create an organizational policy or an explicit policy and a
Registration policy settings document. You must have at least one policy to use with ADSync.
For more information on policies, see the chapter ″Using Policies.″
8. From the Start menu, click Programs - Administrative Tools - Active Directory Users and Computers.
Click the Lotus Domino Options folder.
9. Right-click Domino Directory synchronization and then choose Options.
10. Enter your Notes password.
11. Click the Notes Settings tab.
12. Click the Notes Server for Registration button and specify a registration server. This is typically the
administration server of the Domino Directory.
13. Click OK.
14. Close and restart Active Directory Users and Computers to allow these changes to take effect.

Enabling the Notes synchronization options

Use the Notes Synchronization Options tab on the Lotus ADSync Options dialog box to enable or disable
Notes/Windows synchronization features in the Microsoft Management Console (MMC).
1. From the MMC, choose Domino Directory Synchronization.
2. Click Notes Synchronization Options.
3. Complete these fields:

Field
Enable all synchronization operations
Select synchronization operations to enable
Action
Click to enable all Notes synchronization operations. All
Windows 2000 and Domino Notes operations will be
synchronized.
Click to activate all the fields on this dialog box. When this
check box is not selected, all of the other options on this
dialog box are not enabled.

480 Lotus Domino Administrator 7 Help

Field Action
User/group registration Click this check box to register new or existing Windows
users and groups in Notes. When you click this check box
the ″Synchronize if new user/group already exists in Notes″
field becomes active.
Synchronize if new user/group already exists in Click this check box to prevent the synchronization options
Notes from creating duplicate users or groups in Notes. This field
is active only if you select the ″User/group registration″
check box.
User/group deletion Click this check box to synchronize user and group
deletions. User and groups that are selected for deletion are
then deleted from the Windows 2000 Active Directory as
well as from the Domino Directory.
User/group synchronization Click this check box to copy the values from Active
Directory objects fields to Domino Directory fields,
according to the field mapping specified in the Field
Mapping tab. Member lists in groups are synchronized
when you enable this option.

Synchronization occurs when you select a Synchronize menu

item, or click a toolbar button, or after an Active Directory
object is modified.

When you click this check box, these fields are activated:
v Recertify users on rename
v Set common password on user synchronization
Recertify users on rename Click to use the Domino Administration Process to rename a
Notes user if the corresponding Windows 2000 user is
renamed.

This field is active only if the ″User/group synchronization″

Set common password on user synchronization
check box is selected.
Click to set a new password when you synchronize users.
The password will be used as the Windows and Notes
Internet password. The Notes User ID password does not
change.

This field is active only if the ″User/group synchronization″

check box is selected.
Prompt to confirm/cancel synchronization operations Click to use one of the options for confirming or canceling
synchronization operations. Choose one:
v Prompt for all operations - prompt prior to initiating all
synchronization operations.
v Prompt only for user/group deletions - prompts only
when deleting users or groups.
v Do not prompt for any operations - no prompts are issued
prior to performing any synchronization options.

4. Click Apply and OK.

For more information on the Domino CA, see the chapter ″Setting Up a Domino Server-Based
Certification Authority.″

Specifying Notes settings

Use the Notes Settings tab on the Lotus ADSync Options dialog box to enable or disable Notes and
Windows registration features in the Microsoft Management Console (MMC).

Chapter 19. Using Domino with Windows Synchronization Tools 481

1. From the MMC, choose Domino Directory Synchronization.
2. Click Notes Settings.
3. Complete these fields:

Field Action
Administrator’s ID Click to open the Choose Notes Administrator ID dialog box
in which you can specify another Notes User ID as the
administrator ID. The initial user ID file name is taken from
current Notes client settings.
Registration Server Click to open the Choose Server dialog box from which you
can select a Registration server. The registration server must
be a Domino 6 or more recent server.
Use Registration server for all operations Click to use the server that you designated as the
Registration server for all synchronization operations and for
deletions.

When you deselect this option, these fields are enabled:

v Notes server for synchronization
v Notes server for deletion
Synchronization server Click to open the Choose Server dialog box from which you
can select a Synchronization server. All synchronization
operations are done on this server.

This check box is enabled only if the ″Use Registration

server for all operations″ check box is not selected.
Deletion server Click to open the Choose Server dialog box from which you
can select a deletion server. All deletions are performed on
this server.

This check box is enabled only if the ″Use Registration

server for all operations″ check box is not selected.
Delete entries from Domino Directory immediately Click to immediately remove the selected entries from the
Domino Directory instead of using the Administration
Process to perform the deletion.
Mail file deletion To specify options for mail file deletion when the user is
deleted. Choose one:
v Don’t delete mail file -- To delete the Person document
but leave the user’s mail files intact.
v Delete just the mail file specified in the Person record --
To delete only the mail file specified in the Person
document. No replicas of the mail file are deleted.
v Delete mail file specified in the Person document and all
replicas -- Deletes all mail database replicas on other
servers in addition to the mail file specified in the user’s
Person document.
Default certifier Click to specify a certifier that will be used during user
registration. ADSync uses this certifier if mapping was not
set for a particular Active Directory container on the
Container Mappings tab.
Use Certificate Authority for user certification Click this check box to use the Domino server-based
certification authority (CA) when registering new users.
Default explicit policy Click to specify the explicit policy (and its related settings)
to be applied to users during user registration.

482 Lotus Domino Administrator 7 Help

Field Action
Registration Options Choose one or both:
v Search all directories for duplicate names -- Domino
checks all directories to ensure that the user name is
unique. An error is generated if the name if found to be
a duplicate.
v Enforce short name uniqueness -- Forces all short names
to be unique.
Action on duplicate mail file Choose one:
v Skip the person registration -- Registration for this user
is skipped; other user registrations are performed.
v Generate a unique mail file name -- If a duplicate mail
file is found, a new unique mail file is created by
appending a number beginning with 1, then 2, etc., to
the non-unique mail file name until a unique name is
found.
v Replace the existing mail file -- This option does not
apply when the mail file is being created in the
background via the Administration Process, or if the
current ID does not have delete access to the mail file
that is being replaced.
Action on duplicate roaming folder Choose one:
v Skip the person registration -- Does not register the user
with the duplicate roaming folder name. Proceeds to
the next user registration.
v Generate a unique roaming directory name -- Generates
a unique roaming directory name by appending a
number beginning with 1, then 2, etc., to a non-unique
roaming file name until a unique name is found.

4. Click Apply and OK.

Mapping Active Directory fields and groups with Domino Directory

fields and groups
Use the Field Mappings tab and the Group Mappings tab on the Lotus ADSync Options dialog box to
map specific Active Directory fields and groups to Domino’s Person and Group document fields. Person
and Group documents are stored in the Domino Directory. Mapping is different for the two Field
Mapping object classes, ″User″ and ″Group.″

You can modify any of the initial mappings, create mappings, or create Notes field names. When an
Active Directory object is created or is synchronized with Notes, all field values in the mapped Active
Directory object are copied to corresponding fields in the Person or Group document in the Domino
Directory. If necessary, fields are created in the Person or Group document and existing field values are
overwritten. This is one-way synchronization. No changes are made to the Active Directory object.

Field Mappings in ADSync, unlike other settings, are different for each Active Directory domain.

To create group mappings

1. From the MMC, choose Domino Directory Synchronization.
2. Click Group Mappings.

Chapter 19. Using Domino with Windows Synchronization Tools 483

3. Complete these mappings as necessary, and then click Apply and OK.

In Active Directory In Domino Directory

Security Click to assign a group type when registering security
groups in Notes. Choose one:
v Multi-purpose -- Use for a group that has multiple
purposes, for example, mail and ACLs.
v Mail only -- Use for mailing list groups.
v Access Control List only -- Use for server and
database access authentication only.
v Deny List only -- Use to control access to servers.
Deny List only is typically used to prevent terminated
employees from accessing servers, but this type of
group can be used to prevent any user from accessing
particular servers. The Administration Process cannot
delete any member from this group.
Distribution Click to assign a group type when registering
distribution groups in Notes. Choose one:
v Multi-purpose -- Use for a group that has multiple
purposes -- for example, mail and ACLs.
v Mail only -- Use for mailing list groups.
v Access Control List only -- Use for server and
database access authentication only.
v Deny List only -- Use to control access to servers.
Deny List only is typically used to prevent terminated
employees from accessing servers, but this type of
group can be used to prevent any user from accessing
particular servers. The Administration Process cannot
delete any member from this group.

To create field mappings

1. From the MMC, choose Domino Directory Synchronization.
2. To create field mappings, click Field Mappings.
3. Choose either User or Group in the ″Field mappings for Object class″ field.
4. Scroll through the In Active Directory list until you locate the Active Directory field that you are
mapping to a Domino Directory field.
5. Right-click the corresponding In Domino Directory field (it may appear blank). An editable field
appears. Enter the field name or select one from the list.
6. Continue this process until you have mapped as many fields as needed.
7. Click Apply and OK.

To allow the new fields to display in the dialog box, close and then restart the Microsoft Management
Console. The new fields appear.

Mapping Active Directory containers to Notes certifiers and policies

Use the Container Mappings tab on the Lotus ADSync Options dialog box to define the mapping
between Active Directory containers and Notes certifiers and Notes policies. Container mappings are
used to register new users and translate group member names into the correct Notes format during
synchronization. The group members must belong to an organizational unit that is mapped to a specific
Notes certifier.

When initializing, ADSync reads all Active Directory containers, Domino certifiers, and explicit policies
from the Domino Directory on the registration server. Because Active Directory allows you to create a

484 Lotus Domino Administrator 7 Help

hierarchy of organizational units and containers, it makes sense to preserve that hierarchy in Domino by
using different certifiers and policies to register people from different Active Directory containers. Plan
and then specify mappings between two hierarchies before starting to use ADSync, especially if any of
those hierarchies are extensive. If you do not specify mappings, the default certifier name and
organizational policy are used. You can map multiple containers to one policy and/or to one certifier.

When you create or delete Active Directory containers or Notes certifiers and policies, they can be
mapped using the Container Mappings table by closing and reopening the Microsoft Management
Console.

Container Mappings in ADSync differ for each Active Directory domain.

To map containers
1. From the MMC, choose Domino Directory Synchronization.
2. Click Container Mappings.
3. Scroll through the AD Container list until you locate the Active Directory containers to which you are
mapping a particular Notes certifier and/or a Notes Policy. If you are mapping more than one
container to one policy or certifier, select multiple containers before choosing a policy or certifier.
4. Right-click the corresponding Notes Certifier field (it may appear blank). An editable field appears.
Enter the certifier name or select one from the list.
5. Right-click the corresponding Notes Policy field (it may appear blank). An editable field appears.
Enter the policy name or select one from the list.
6. Continue this process until you have mapped as many containers, certifiers, and policies as needed.
7. Click Apply and OK.

To allow the new policies and certifiers to display in the dialog box, close and then restart the Microsoft
Management Console. The new policies and certifiers appear.

Synchronizing users and groups

Active Directory user and group accounts can be synchronized with the corresponding Person and Group
documents in the Domino Directory. Synchronizing users facilitates other user synchronization
operations, such as user registration and deletion, which can be initiated through the Microsoft
Management Console (MMC) or Domino. Synchronization also enables users to have a common
password for Windows and for Domino Web Server access, copies all mapped field values from user or
group objects in Active Directory to corresponding documents stored in the Domino Directory, and it
copies member lists of the groups. The synchronization server specified in Notes Settings is used for all
synchronization operations.

Note: When you synchronize an Active Directory with the Domino Directory, ADSync copies the primary
names from the Active Directory to the Domino Directory. Primary names are copied exactly as they have
been entered in the Active Directory. Japanese (double-byte) characters are not supported in the Domino
Directory, but in some cases, they are supported in Active Directory. If you have registered any primary
names with Japanese characters in the Active Directory, before synchronizing the directories, rename
those primary names using single-byte characters that are supported by the Domino Directory.

For more information on Notes Settings, see the topic ″Specifying Notes Settings″ in this chapter.

Synchronization is initiated at these times:

v After the user or group is registered in Domino from the MMC using ADSync.
v When one or more users or groups are selected on the results pane of the MMC and the Synchronize
with Domino option is selected from the context menu or the toolbar.
v When you change any of the properties of the user or group object and confirm your changes by
clicking the OK or Apply buttons.

Chapter 19. Using Domino with Windows Synchronization Tools 485

During synchronization, ADSync attempts to match the Active Directory object with an entry in the
Domino Directory. If more than one match is found, ADSync prompts you to specify the match from
those that have been located.

The field mappings that are set in the Field Mappings table designate which fields are synchronized
during synchronization. System fields that cannot be safely synchronized in two directories are excluded
from the Field Mappings table.

For more information on Field Mappings, see the topic ″Mapping Active Directory fields with Domino
Directory fields″ in this chapter.

If the ″Set common password″ check box is checked on the Synchronization Options tab on the Lotus
ADSync Options dialog box, you are prompted to enter a new password during synchronization. This
changes the Windows password as well as the Notes Internet password for that user.

For more information on synchronization options, see the topic ″Enabling the Notes synchronization
options″ topic earlier in this chapter.

Note: Consult your Windows 2000 documentation for information about running and working with the
MMC and the Users and Computers snap-in.

Registering new users in Active Directory and in Domino Directory

simultaneously
Before starting any operation in ADSync, review all of the ADSync settings, especially Notes Settings and
Container Mappings.

You can register new users in Notes at the same time that you register them in the Active Directory, or
you can register existing Active Directory users in Notes. If any of the users or groups being registered
already exist in Notes, and the ″Synchronize if new user/group already exists in Notes″ option on the
Notes Synchronization Options tab is checked, a duplicate user or group is not created. Instead,
synchronization is performed.

Registration uses certifier IDs or the Domino server-based certification authority (CA). Only certifiers
listed in the registration server’s Domino Directory are used. If you are using certifier IDs, you are
prompted for the path and password, once per certifier per MMC session.

If you create users and groups without additional prompts, all defaults are used, and the entire
registration queue is processed. When users are created, random passwords are generated and placed in
the database, NTSYNC45.NSF, located in the root directory of the local Notes data directory.

For information on the fields that display while registering users, consult your Microsoft documentation.

To register new Windows 2000 users in Domino

1. From the MMC, right-click Users - New - User.
2. Complete the Active Directory registration fields on the first two New Object - User windows that
display.
3. Complete these Notes registration fields on the third New Object - User field that displays:

Fields Action
Register in Domino Directory Click this check box to register this user in the Windows Active Directory and
in the Domino Directory. Other fields on this dialog box are enabled when you
click this check box.

486 Lotus Domino Administrator 7 Help

Fields Action
First name, Middle name, Last Enter the user’s first name and last name, and optionally, enter a middle name.
name Note: The user’s Short name and Internet address are automatically generated.
To change the Short name or Internet address, click the appropriate space and
enter the new text.
Org unit (Optional) Enter an organizational unit if your enterprise uses them. For
example, if user John Smith is part of engineering, the organizational unit may
be Eng. The user name would be John Smith/Eng.

Certifier context
Organizational Policy
Explicit Policy
Use common password
Organizational units are useful for differentiating between users of the same
name. For example, John Smith/Eng/Acme and John Smith/Doc/Acme, where
one employee is a member of Engineering and the other is a member of
Documentation. Each is assigned a different organizational unit name.
Choose the certifier to use to certify this user.
Non-modifiable. Displays the name of the organizational policy that is
assigned if there is one. If there are no organizational policies, this field
displays None.
Choose an explicit policy from the list. If you do not specify an explicit policy,
registration will not complete and you are prompted to specify one.
Click this check box if you want to use one password for Windows, Notes, and
Notes Internet. The existing Windows password is then replaced by the
password you enter here.

To preserve the existing Windows 2000 password, enter that password as the
common password.

If the Use common password check box is selected, the Notes password for the
user name field and the Confirm password field are enabled.
Password Enter the new password.
Confirm password Enter the same password again to confirm it.
Internet address The default Internet address as derived from the Windows user login name,
for example, KCarter@domain.com. When the user is registered in Notes, the
domain name from the user’s registration policy settings document is
appended.
Short name in Notes The short name by which the user will be known in Notes. By default, the
short name consists of the user’s first initial and last name.

4. Click Next.

Note: If you do not complete all required fields, a message indicates which fields need to be completed.
You must go back and complete the required fields.
5. Review the settings you specified for the user you are registering and click Finish.

Reviewing ADSync operations in the Application Log

You can examine the Windows 2000 event viewer for more information about any errors that may occur.
Look for ″NUMEEvent″ messages in the Application Log. All ADSync operations are recorded in the
Application Log.

Registering existing Active Directory users and groups in Notes

There are two procedures available for registering existing Active Directory users and groups in Notes.

When you are registering user and groups, all groups are registered first.

Registering existing users or groups quickly without prompts: Use this method to register many
existing users or groups at one time. Users and groups are registered using the existing information in

Chapter 19. Using Domino with Windows Synchronization Tools 487

the registration queue so that you are not prompted to enter user-specific or group-specific information
on multiple dialog boxes for every user or group that you are registering. This is the recommended
method for registering multiple users and groups at one time, but this method can be used to quickly
register an individual user or group.
1. From the MMC, click Users.
2. On the Results pane, right-click the users and/or groups you are registering and then click Register in
Domino. You can choose multiple users and/or groups and then click Register in Domino once for all
of your selections.
3. Choose ″Register users and groups at once without additional prompts; use defaults.″ This button
registers users and groups without prompts.
4. Choose one of these options:

Field
If error happens during registration of
some users and/or groups, try to
register them later
If registration is canceled for some
users and/or groups, try to register
them later
Action
Click this check box to register any users or groups whose registrations fail
on the first try. If not selected, users and groups are not registered if the
first attempt fails.
Click this check box to allow to attempt to register any users or groups
whose registrations are canceled on the first try. If not selected, users and
groups will not be registered if the first attempt is canceled.

This option is active only if ″Prompt for the name and password of each
user, and for the name and members of each group″ button is selected.

5. Click Register Now.

Note: You have the option of choosing one of the following if you decide not to register now:
v Click Register later to store the users or groups in the registration queue. You can then register
them later.
v Click Do not register to cancel user registration.

After successful registration in Notes, users and groups are synchronized with the Active Directory. A
progress bar displays during the registration process.

Registering existing users or groups individually with prompts: Use this method to register users and
groups individually. You are prompted to enter multiple fields of information on multiple dialog boxes
for each user and for each group that you register. This method is recommended when registering very
small numbers of users or groups, or when you need to modify information for users and groups during
the registration process. This option provides administrators with control over Notes registration
information for each user or group. When used to register numerous users or groups, this method is
time-consuming.

During group registration, for each group you can specify the members that are to be registered in Notes
by clicking the Members button on the dialog box on which it appears. You are also able to specify a new
group name, description, and group type if you want to modify any of those.

For more information on Active Directory, see the Microsoft Active Directory documentation or use the
Microsoft Active Directory online help for fields.
1. From the MMC, click Users.
2. On the Results pane, right-click the user or group you are registering and then click Register in
Domino.
3. Choose ″Prompt for the name and password of each user, and for the name and members of each
group.″ When this option is chosen, the ″If registration is canceled for some users and/or groups, try
to register them later″ check box is also active.

488 Lotus Domino Administrator 7 Help

4. Choose one of these options:

Field
If error happens during registration of
some users and/or groups, try to
register them later
If registration is canceled for some
users and/or groups, try to register
them later
Action
Click this check box to attempt to register at a later time, any users or
groups whose registrations fail on the first try. If not selected, users and
groups are not registered if the first attempt fails.
Click this check box to attempt to register at a later time, any users or
groups whose registrations are canceled on the first try. If not selected,
users and groups will not be registered if the first attempt is canceled.

This option is active only if ″Prompt for the name and password of each
user, and for the name and members of each group″ button is selected.

5. Click Register Now.

Note: You have the option of choosing one of these if you decide not to register now:
v Click Register later to store the users or groups in the registration queue. You can then register
them later.
v Click Do not register to cancel user registration.
6. Complete the fields on all dialog boxes that display for each user or group.
7. Click Finish when you are done.
For more information on the Notes Registration dialog box that displays for users, see the topic
″Registering new users in Active Directory and in Domino Directory simultaneously″ in this chapter.
For more information on the Notes Registration dialog box that displays for groups, see the topic
″Registering new groups simultaneously in Active Directory and in Domino Directory″ later in this
chapter.

Registering new groups in Active Directory and in Domino Directory

simultaneously
Before registering new groups, review all of the ADSync settings, especially the Notes Settings and
Container Mappings.

You can register new groups in Notes at the same time you register them in the Active Directory.

For information on the fields that display while registering groups, consult your Microsoft
documentation.

Complete this procedure to simultaneously register a group in Notes and in Active Directory:
1. From the MMC, right-click Users - New - Groups.
2. Complete the Active Directory group fields on the first window that displays, and then click Next.
3. Complete these Notes registration fields on the second window that displays:

Fields Action
Register in Domino Directory Click this check box to create a Notes group to
correspond to the Windows group. Deselect to create the
group only in the Active Directory. When this option is
selected, all other fields on this dialog box are active.
Group name Enter a group name.

This field is active only if you select the ″Register in

Domino Directory″ check box.

Chapter 19. Using Domino with Windows Synchronization Tools 489

Fields Action
Group type Specifies the purpose of the group and determines the
views in the Domino Directory where the group name
appears:
v Multi-purpose -- Use for a group that has multiple
purposes -- for example, mail and ACLs. This is the
default.
v Access Control List only -- Use for server and database
access authentication only.
v Mail only -- Use for mailing list groups.
v Deny List only -- Use to control access to servers.
Deny List only is typically used to prevent terminated
employees from accessing servers, but this type of
group can be used to prevent any user from accessing
particular servers. The Administration Process cannot
delete any member of this type of group.

This field is active only if you select the ″Register in

Domino Directory″ check box.
Description (optional) Enter a description of the group.

4. Click Next.
5. Review the information that displays and click Finish. Click OK.

Adding members to a group:

1. From the MMC, select the name of the group to which you are adding members.
2. Complete the fields on the Newgroup Properties dialog box. For more information on completing
these fields, refer to the Microsoft help documentation.
3. Click Apply and OK.

Renaming Active Directory and Notes users and groups

When you rename a user or group in the Active Directory, and there is a corresponding user in the
Domino Directory that was previously synchronized with its Active Directory counterpart, ADSync
renames or recertifies that user or group accordingly. The server that is used for synchronizing the
Domino Directory with the Active Directory is the synchronization server that you specify on the Notes
Synchronization Options tab.

When you rename a Notes user or group, all occurrences of that user name are updated in the Domino
Directory and other databases by the Domino Administration Process on the Domino server.

To rename a user or group in Active Directory and in Domino Notes

1. From the MMC, right-click the name of the user or group you are renaming, and click Rename.
2. Enter the user’s or group’s new name.
3. Complete the fields in the Rename User/Group wizard. Be sure to enter the new name in any fields
in which you want the name change to take effect.
4. On the Verification to Rename dialog box, verify that the check box ″Corresponding user or group in
Domino Directory″ is selected to change the name in the Domino Directory.
5. Click Yes.

Deleting Active Directory and Notes users and groups

When you delete a user or group from the Active Directory and there is a corresponding user or group in
the Domino Directory that was synchronized with it, ADSync removes the Person document or Group

490 Lotus Domino Administrator 7 Help

document for that Domino Directory entry using the Administration Process on the deletion server. You
can designate a deletion server and change user mail file deletion settings in the Notes Settings tab of the
Lotus ADSync Options dialog box.

When you delete a Notes user or group, all references to it are removed from the Domino Directory by
the Domino Administration Process running on a Domino server. After initiating the deletion, you must
approve the request in the Administration Requests (ADMIN4.NSF) database on the Domino server.

For more information on deleting users in Domino, see the chapter ″Setting Up and Managing Notes
Users.″

For more information on administration requests, see the appendix ″Administration Process Requests.″

Note: To use a Notes administrator ID other than the one most recently used, go to the Notes Settings
tab of the Lotus ADSync Options dialog box and specify another administrator’s ID.

How to delete users from Active Directory and Domino

1. From the MMC, right-click the name of the user you are deleting, and then click Delete.
2. Click Yes at the verification message.

Disabling Active Directory synchronization prior to uninstalling the

Domino Administrator
If you have set up and registered Active Directory synchronization, prior to uninstalling the Domino
Administrator, you must unregister Active Directory synchronization.
1. Close the Administrator Client and the Active Directory MMC.
2. From the system prompt, unregister the nadsync.dll library by entering one of these commands:
regsvr32 /u <notes program path>nadsync.dll
OR by entering
cd <notes program path>
regsvr32 /u nadsync.dll
3. Uninstall the Administrator Client.
4. Delete any remaining Notes folders on the file system.
5. Launch regedit and search for all adsync entries. Delete any adsync entries that are found.

Chapter 19. Using Domino with Windows Synchronization Tools 491

492 Lotus Domino Administrator 7 Help
Chapter 20. Planning Directory Services
This chapter describes the Domino directory services features and some of the planning issues to consider
before using them.

Overview of Domino directory services

Domino provides a range of directory service features that are useful for both small and enterprise
companies including:
v The option to use dedicated directory servers and to use a central directory architecture
v Lightweight Directory Access Protocol (LDAP) features
v Flexible directory access control, including the ability to use an extended ACL to set access at the form
and field level
v Tools for creating and managing entries in the directory
v Directory features for Notes clients
v Features for multiple-directory environments
v Internationalization features
v Directory customization features

Using directory servers in a Domino domain

A Domino domain is a network of clients and servers whose users, servers, connections, and access
control information is described in a single database called the Domino Directory. When you set up the
first server in an organization, Domino creates a Domino domain and a Domino Directory for the
domain. When you add servers to the domain they pull replicas of the Domino Directory. To create an
additional domain and Domino Directory, you perform a first server setup.

Each Domino domain has at least one administration server for the Domino Directory. The administration
server is responsible for carrying out Administration Process requests that automate changes to the
Domino Directory. By default, the first server set up in a domain is the administration server for the
Domino Directory.

You can use directory servers in a Domino domain to dedicate specific servers to providing directory
services. Clients and specialized servers such as mail and application servers use the directory servers to
look up user, group and similar information.

A directory server might:

v In a central directory architecture, store a primary Domino Directory that servers with Configuration
Directories access remotely
v Run the LDAP service
v Run the Dircat task to build and store directory catalogs
v Store replicas of directories that are aggregated into the directory catalog
v Store replicas of secondary Domino Directories that servers in the domain access through directory
assistance

You can set up Notes clients to use directory servers, rather than their mail servers, to look up names and
addresses.

For information on setting up Notes clients to use directory servers, see the chapter ″Setting Up the
Domino Directory.″

493
Using a central directory architecture in a Domino domain
Prior to this release, companies always used a distributed directory architecture in which every server in
a Domino domain had a full replica of the domain’s primary Domino Directory. A primary directory
contains all types of documents: documents used to provide directory services such as Person and Group
documents as well as documents used to configure Domino servers.

In this release, companies can implement a central directory architecture. In a central directory
architecture, a few directory servers in a domain have a replica of a the primary Domino Directory that
contains the entire contents of the Domino Directory. The other servers in the domain have a
Configuration Directory, a small, selective replica of the Domino Directory that contains only documents
used for Domino configuration. A server with a Configuration Directory uses a primary Domino
Directory on another server -- referred to as a remote primary Domino Directory -- to look up
information in Person, Group, Mail-In Database, and Resource documents, and in any new types of
custom documents a company has added to the directory.

Enterprise companies that use centralized architectures can benefit from this feature. A central directory
architecture allows for tighter administrative control over directory management because only a few
directory replicas contain user and group information. In addition, application and mail servers can run
on less powerful machines then the directory servers require, since the application and mail servers don’t
have to store a primary Domino Directory, which can be the largest database in a company. If the user
and group information in a directory changes frequently, the servers with Configuration Directories have
immediate access to the changes that critical business applications and processes require, because they
don’t have to wait for the changes to replicate locally.

To use a central directory architecture you must have adequate network bandwidth to support the remote
primary directory lookups. For failover, it is also important that at least two servers in a domain are
configured as a remote primary Domino Directory.

For additional information on implementing a central directory architecture, see the chapter ″Setting Up
the Domino Directory.″

Planning LDAP features

Lightweight Directory Access Protocol (LDAP) is a standard Internet protocol for searching and managing
entries in a directory. Domino and Notes provides these LDAP features
v The LDAP service enables a Domino server to function as an LDAP directory server and process LDAP
requests.
v LDAP accounts on Notes clients enable Notes users to do LDAP-style searches for an addresses in
LDAP directories.
v The ldapsearch utility enables you to use LDAP search syntax to search an LDAP directory.
v Directory assistance can enable a Domino server to use a remote LDAP directory for client
authentication and/or to look up the members of groups during database authorization.

Planning the LDAP service

A Domino server that runs the LDAP task functions as an LDAP directory server, ready to process
requests from LDAP clients. Such requests can come from any of the popular Web browser clients that
have built-in LDAP support to retrieve directory information, or from custom LDAP applications
designed to search for and manage directory information.

Some of the questions to ask when planning for the LDAP service are:
v What levels of LDAP client authentication do you want to use? Anonymous access, enabled by default,
allows LDAP clients to connect without providing names and authentication credentials, such as
password or certificates. Typically you allow LDAP clients connecting anonymously only read access to
the directory.

494 Lotus Domino Administrator 7 Help

v Should you use an extended ACL to control LDAP access to the directory? An extended ACL provides
more granular directory access control than the database ACL alone supports. If you use an extended
ACL, the database ACL and extended ACL control Anonymous LDAP search access as well as
anonymous access for the other supported client protocols. If you do not use an extended ACL, a
Configuration Settings document controls Anonymous LDAP search access.
v Should you create a full-text index for the Domino Directory? If your LDAP clients typically use search
filters that search for names or mail addresses, then it’s not necessary to full-text index the directory. If
LDAP clients user other types of search filters, creating a full-text index for the directory is
recommended so the LDAP service can process these kinds of requests more quickly by searching a
full-text index.
v Do you need to extend the schema to add support for new object classes or attributes? You may need
to extend the schema if your company has LDAP applications that search for application-specific
information. You can use the Domino LDAP Schema database (SCHEMA.NSF) to extend the schema,
or add forms and fields to the directory. Using the Schema database is recommended.
For additional information, see the chapters ″Setting Up the LDAP Service″ and ″Managing the LDAP
Schema.″

Planning directory assistance for the LDAP service: You can set up directory assistance on a server that
runs the LDAP service so the LDAP service can extend client LDAP requests to a secondary Domino
Directory or to a remote LDAP directory.

Some of the issues to consider with respect to setting up the LDAP service to use directory assistance for
a secondary Domino Directory include:
v What access do I want LDAP clients to have to the secondary Domino Directory? You control LDAP
access separately for each Domino Directory or Extended Directory Catalog the LDAP service serves.
v If you use a custom LDAP application to administer the directory, the LDAP service allows the
application to modify the directory only if the directory is stored locally on the server running the
LDAP service. If the secondary Domino Directory is stored on a remote server, the LDAP service can
return a referral to that server instead or processing the LDAP operations itself.

Some of the issues to consider with respect to setting up the LDAP service to use directory assistance to
refer LDAP clients to a remote LDAP directory include:
v The LDAP service can never process an LDAP search, add, or modify request in a remote LDAP
directory. It can only refer LDAP clients to a remote LDAP directory.
v By default the LDAP service can return a given LDAP client a referral to only one remote LDAP
directory. If you want to enable the LDAP service to return an LDAP client more than one referral so
that an LDAP client can follow up with alternate referral if the directory server specified in the first
referral is unavailable, you must increase the ″Maximum number of referrals setting″ for the LDAP
service.
v You can specify alternate LDAP directories for referral in one Directory Assistance document for a
remote LDAP directory.

Note: The LDAP service, like any Domino Internet protocol server, can use directory assistance to
authenticate its clients using credentials in a secondary directory, and to use groups in a secondary
directory for database authorization.

For more information, see the topic ″Planning directory assistance″ later in this chapter.

Planning LDAP accounts on Notes clients

Notes clients can use LDAP accounts set up in the Personal Address Book to connect directly to a remote
LDAP directory server. Using an LDAP account, a Notes user can browse the remote LDAP directory and
can search for addresses in the remote LDAP directory when sending mail.

Some of the issues to consider before setting up LDAP accounts on Notes clients are:

Chapter 20. Planning Directory Services 495

v Would you rather set up directory assistance on Notes clients’ mail servers or directory servers to
provide Notes users with access to a remote LDAP directory rather than use LDAP accounts? If the
Notes clients run Notes Release 4, you must use directory assistance because Notes Release 4 clients
don’t support the use of LDAP accounts. You might also use directory assistance to avoid having to
update client LDAP accounts if the remote LDAP directory configuration changes; if you use directory
assistance, you change only the Directory Assistance document for the remote LDAP directory if the
directory server configuration changes.
v What settings do you want to use in an LDAP account? For example, if an LDAP directory server
requires a search base, you should specify a search base in the account. Should you use a simple search
filter that searches only for a cn attribute to locate user entries, or a more complex search filter that also
searches for a mail, uid, sn, or givenname attribute? If searches of the cn attribute only are adequate for
your needs, using the simple search filter improves the speed of searches.
v Should you use Setup policy settings and/or Desktop policy settings documents to set up and modify
the LDAP accounts? This approach automates the process of creating and updating the accounts.

LDAP accounts for the Bigfoot and VeriSign directories are set up by default.

The ldapsearch utility

LDAPSEARCH.EXE is a utility that you run from the operating system prompt that searches any LDAP
directory. ldapsearch connects to a directory server that you specify and returns results according to
specified search criteria. ldapsearch is provided with the Domino server and the Notes client. This tool
uses standard LDAP search syntax so you can also use it to learn about using LDAP to search an LDAP
directory.

For additional information, see the chapter ″Using the ldapsearch Utility.″

Domino does not provide a comparable tool for modifying an LDAP directory.

Planning directory access control

Use the database ACL to control the general access that users and servers have to the Domino Directory.
Optionally, use an extended ACL to refine the general database ACL and further restrict access to specific
portions of the directory. An extended ACL is available for only a Domino Directory and an Extended
Directory Catalog.

Some of the questions to ask when planning directory access control include:
v Do you want to assign administrators to specific administration roles in the Domino Directory? If
administrators in your company have specialized administrative duties, consider assigning the
administrators only to the administration roles in the ACL that correspond to their duties. If your
company administrators do all administrative tasks, assign them to all of the roles.
v Do you want to use an extended ACL? One of the reasons to use an extended ACL is to limit
cross-organizational access to a directory that contains information for multiple organizations or
organizational units.
v Do you want to allow Anonymous access to the directory? By default, you use the domain
Configuration Settings document in the Domino Directory to control anonymous LDAP search access.
By default, anonymous LDAP users have Read access to a specific list of attributes.
The Anonymous entry in the directory database ACL by default is set to No Access and controls
anonymous access for all users other than LDAP users. If you use an extended ACL, then the
Anonymous entry in database ACL, and the extended ACL, then also control anonymous LDAP access.
Typically you give the Anonymous entry no more than Reader access.
For additional information, see the chapters ″Setting Up the Domino Directory″ and ″Setting Up
Extended ACLs.″

496 Lotus Domino Administrator 7 Help

Planning new entries in the Domino Directory
The tools you can use to add entries to the Domino Directory are the Notes user registration program,
migration tools that are integrated with the Notes user registration program, Domino directory
synchronization tools, and third-party LDAP applications. You can also add an entry manually, for
example you typically add a group entry manually. You might also develop a custom Notes application
to add entries.

Note: In general an entry’s distinguished name is determined by the first value listed in the FullName
field. Domino Group and Server entries are the exceptions. The ListName field controls the distinguished
name of a Domino Group and the ServerName field controls the distinguished name of a Domino server.
If you add more than one value to a FullName, ListName, or ServerName field, keep the distinguished
name as the first value.

Notes user registration program

The Notes user registration program, available through the Domino Administrator and Web
Administrator clients, is the traditional method for adding user entries to the Domino Directory. The
registration program registers users with hierarchical names -- names with multiple, distinguishing
components -- provided by a certifier. The registration program can register users with Notes IDs, X.509
certificates, or passwords, and can register users to use Notes mail, an Internet mail protocol, or no mail.

Before you register Notes users you should decide on a naming scheme for the users and create certifiers
that reflect that scheme. You should also use the Policies feature with a Registration policy settings
document to simplify the process of registration by filling in many of the registration settings
automatically.

For more information, see the chapters ″Setting Up Notes Users″ and ″Using Policies.″

Directory synchronization tools

If you create a new user or group account in Active Directory, Domino provides tools you can use to
simultaneously register the user or group in the Domino Directory.

For more information, see the chapter ″Using Domino with Windows Synchronization Tools.″

Migration tools
The Notes user registration program provides migration tools that convert third-party mail system users
or third-party LDAP directory users to Notes users. Be aware that if you migrate users from an LDAP
directory the migration tools convert the entries from the LDAP directory into Notes entries with new
names based on a certifier specified in the Notes user registration program.

For more information on migration tools, see the Upgrade Guide.

Third-party LDAP applications

If you use the LDAP service, you can use an LDAP application to add entries to the Domino Directory.
Because Domino does not provide such an LDAP application, your company must develop or obtain one
to add entries to the directory in this way. These are some of the issues to keep in mind if you use an
LDAP application to add entries to a Domino Directory:
v You must set up the directory to allow LDAP write access.
v Enabling schema checking for the LDAP service is recommended so the directory contents conform to
the schema and are consistent.
v The distinguished names of entries must be 256 characters or less.
For additional information on using LDAP to add entries, see the chapter ″Setting Up the LDAP
Service.″

Chapter 20. Planning Directory Services 497

Planning the management of entries in the Domino Directory
You can use the Domino Administrator, the Web Administrator, directory synchronization tools, and
third-party LDAP applications to manage entries in the Domino Directory.

Domino Administrator and Web Administrator

The People & Groups tab of the Domino Administrator and Web Administrator clients provide several
tools for managing Domino user and group entries in the Domino Directory, including tools that:
v Rename and recertify users
v Edit user and group entries
v Find user and group entries
v Set policies for user and group entries

Many of these tools invoke the Administration Process to automate these tasks.

For additional information, see the chapters ″Setting Up the Administration Process″ and ″Setting Up and
Using Domino Administration Tools.″

Directory synchronization tools

If you modify or delete a Domino user or group, Domino provides tools you can use to simultaneously
carry out the modification or deletion to a corresponding user or group in Active Directory.

For more information, see the chapter ″Using Domino with Windows Synchronization Tools.″

Third-party LDAP applications

The LDAP service allows third-party LDAP applications to modify directory entries. By default the LDAP
service does not allow LDAP write operations to a directory, so you must set up the directory to allow
them.

Planning directory services for Notes clients

There are a variety of directory services features available to Notes clients. If there are Notes clients client
settings that apply to groups of Notes users, use policies with Setup or Desktop settings documents to set
up the desired settings on Notes clients automatically.

Personal Address Book

The Personal Address Book is a directory on the Notes client that stores Contacts created by users --
documents containing information about people with whom the users come in contact and/or send mail
-- and that stores mailing lists created by users for sending mail to groups of people. The Personal
Address Book also stores a variety of documents related to configuration of the Notes client.

For more information, see Lotus Notes Help.

Condensed Directory Catalog

A condensed Directory Catalog, sometimes referred to as a Mobile Directory Catalog when used on a
Notes client, is an optional directory that aggregates user and group entries from one or more Domino
Directories. A condensed Directory Catalog provides Notes users with a small, local, organization-wide
directory that they can use either off-line or when connected to the local area network.

For more information, see the chapter ″Setting Up Directory Catalogs.″

Type-ahead addressing
Using type-ahead addressing a Notes user enters a few letters in a mail addressing field and Notes tries
too match those letters to a name in a directory. If Notes finds a match, it enters the completed name in
the addressing field automatically. If a Notes user has a local condensed Directory Catalog configured,

498 Lotus Domino Administrator 7 Help

type-ahead addressing does not search a directory on a server. However pressing F9 to resolve a name
will search for the name in both local and server directories.

Administrators can use a setting in a Configuration Settings document to disable type-ahead addressing
on a server to reduce network traffic and improve server performance.

For more information on disabling type-ahead addressing on a server, see the chapter ″Customizing the
Domino Mail System.″

Easy location of user and group entries

Notes users can use an addressing tool or a generic search tool to find easily user and group entries in a
directory. When searching a Personal Address Book or a Domino Directory, these tools provide a
type-ahead-style mechanism to match letters entered by a user to a name in a directory. Users can choose
to view entries in a directory by name, by Notes name hierarchy, by corporate hierarchy, and by alternate
names (if used).

To search all local Address Books or an LDAP directory accessed using an LDAP Account document,
users can use an LDAP-style search query to locate entries. For example, users can search for all entries
with the last name ″Brown.″

For additional information, see Lotus Notes Help.

Access to server directories

The Notes client has automatic access to the Domino Directory in its domain. If an administrator sets up
directory assistance for a secondary directory, or sets up a server-based directory catalog, Notes clients
can easily address mail to users and groups in those directories.

In addition, a Notes client can set up LDAP accounts to connect directly to a remote LDAP directory.

For more information on LDAP account, see the earlier topic ″Planning LDAP accounts on Notes clients.″

Directory servers
Using the ″Domino directory server″ field on the Servers tab of a Location document in the Personal
Address Book, Notes clients can use directory servers, rather than mail servers, for directory lookups.

For more information, see the chapter ″Setting Up the Domino Directory.″

Planning directory services in a multiple-directory environment

Domino provides directory catalogs and directory assistance to help companies operate in environments
with secondary directories. A secondary directory is any server-based directory that is not a server’s
primary Domino Directory. A secondary directory can be a Domino Directory for a different Domino
domain, a Domino Directory that you create manually from the PUBNAMES.NTF template that is
unaffiliated with a Domino domain, an Extended Directory Catalog, or a remote LDAP directory.

Planning directory catalogs

A directory catalog is an optional directory database that can aggregate entries from multiple Domino
Directories into a single database. A directory catalog provides enterprise-wide directory access via a
single database.

Directory catalogs are either client-based or server-based. Using a client-based condensed Directory
Catalog, often referred to as a Mobile Directory Catalog, Notes users can access directory information for
an enterprise off-line, when not connected to the network. Servers use server-based directory catalogs,
either a condensed Directory Catalog or an Extended Directory Catalog, to look up information
originating from a secondary Domino Directory.

Some of the questions to ask when planning directory catalogs are:

Chapter 20. Planning Directory Services 499

v Which documents and fields should be aggregated into a directory catalog? Which information you
aggregate depends on the type and purpose of the of directory catalog.
v If your company uses multiple Domino Directories, should you set up servers to use a directory
catalog? The more Domino Directories a company uses, the more benefit there is to aggregating the
directories in a directory catalog used by servers. An Extended Directory Catalog, rather than a
condensed Directory Catalog, is recommended for servers.
v Do you want to use a server-based directory catalog for client authentication? If so, how you enable
the use of the directory catalog for this purpose depends on the type of server-based directory catalog
you use.
v If you plan to use a condensed Directory Catalog, how should the entries be sorted? You should sort a
Mobile Directory Catalog according to how users typically enter names when addressing mail so that
type-ahead addressing can find the names.
For additional information on planning directory catalogs, see the chapter ″Setting Up Directory
Catalogs.″

Planning directory assistance

Servers use directory assistance to look up information in a secondary directory -- a secondary Domino
Directory, an Extended Directory Catalog, or a remote LDAP directory. Directory assistance provides
these services:
v Client authentication using credentials in a secondary directory
v ACL group lookups for database authorization using one secondary directory
v Notes mail addressing using a secondary directory
v LDAP service searches of a secondary Domino Directory or Extended Directory Catalog
v LDAP service referrals to a remote LDAP directory

Some of the questions to ask when planning directory assistance include:

v Which services do you want to enable for each secondary directory?
v If you use a server-based directory catalog, how does it relate to directory assistance? The answer
depends on the type of directory catalog you use. An Extended Directory Catalog has its own
Directory Assistance document and the source directories that are aggregated in the directory catalog
should not also have separate Directory Assistance documents. However it’s beneficial to create
Directory Assistance documents for the directories aggregated in a condensed Directory Catalog.
v Do you plan to use a secondary directory, Domino or LDAP, for client authentication? If so, you must
specify in the Directory Assistance document for the directory the user names in the directory that are
allowed to be authenticated (trusted for authentication). If clients use name-and-password security,
configure in the Server document of the server to which the clients connect the types of name formats
that clients can provide for authentication.
v Do you plan to use a secondary directory to look up groups listed in database ACLs to verify database
access? You can enable one secondary directory only -- Domino or LDAP -- for this purpose.
v How many directory assistance databases should you use? You can create more than one and set of
groups of servers to use specific ones.

In addition, if you are setting up directory assistance for a remote LDAP directory:
v Does the directory server require a search base? If so, enter the search base in the Directory Assistance
document.
v Do you plan to use the LDAP directory for client authentication or for ACL group authorization? If so,
for tighter security, in the Directory Assistance document, enable SSL and require the remote directory
server to present X.509 certificate.
v Is the remote LDAP directory Active Directory? If so, in the Directory Assistance document for the
directory select LDAP search filters that work specifically with Active Directory.
For additional information on planning directory assistance, see the chapter ″Setting Up Directory
Assistance.″
500 Lotus Domino Administrator 7 Help
Comparison of directory catalogs and directory assistance
The following table compares the features that directory catalogs and directory assistance support.

Directory assistance
for secondary Domino Directory assistance
Mobile Directory Condensed Directory Directory or Extended for remote LDAP
Feature Catalog Catalog on server Directory Catalog directory
Notes client mail Yes Yes Yes Yes
addressing
Notes client Yes Yes Yes No
LDAP-style
searches
Notes client Yes Yes Yes No
directory browsing
Notes client Yes Yes (if no Mobile Yes (if no Mobile No
type-ahead Directory Catalog) Directory Catalog)
addressing
Notes client F9 Yes Yes Yes No
address resolution
LDAP client search No Yes (search) Yes No
and write
operations No (write)
LDAP client No No No Yes
referrals
Internet client No Yes Yes Yes
authentication
Group No No Yes Yes
authorization
(enabled for one
secondary directory
only)

Directory search order

There are a variety of ways to configure directories in a multiple directory environment. The order in
which Notes and Domino search directories depends on the nature of the search and the configuration of
the directory.
v Directory search order for Internet client authentication
v Directory search order for group names in database ACLs
v Directory search order for LDAP searches
v Directory search order for a name in a Notes address field

Directory search order for Internet client authentication: To authenticate an Internet client connecting
to a Domino server, the server searches directories for the user name and credentials in the following
order:
1. The server’s primary Domino Directory.
2. A condensed Directory Catalog on the server.
3. All directories defined in the server’s directory assistance database that:
v Have a naming rule that is trusted for authentication and that matches the logon name of the
Internet user
v Have the directory assistance option ″Make this domain available to: Notes clients and Internet
Authentication/Authorization″ enabled.

Chapter 20. Planning Directory Services 501

 If there more than one directory with a trusted naming rule that matches the user name, the server
searches the directory with the most specific matching rule first. If directories have identical trusted
naming rules that match the Internet user name, search orders assigned to the directories determine
the order in which the server searches them.

Directory search order for group names in database ACLs: When a Internet or Notes user attempts to
access a database on a server and the database ACL includes a group name, the server searches
directories in this order to locate the group to determine if the user is a member of it:
1. The server’s primary Domino Directory.
2. One directory -- LDAP or Notes -- configured in the server’s directory assistance database with the
″Group Authorization″ option selected.

Directory search order for LDAP searches: A server running the LDAP service searches directories in
the following order to process LDAP search requests:
1. A server’s primary Domino Directory, unless the primary Domino Directory is configured in a
directory assistance database used by the server and has the option ″Make this domain available to:
LDAP clients″ deselected.
2. A condensed Directory Catalog on the server.
3. A Domino Directory or Extended Directory Catalog that is configured in a server’s directory
assistance with the option ″Make this domain available to: LDAP clients″ selected.
If an LDAP user doesn’t specify a search base, which is a distinguished name used to indicate the
directory location at which to begin a search, the LDAP service searches the Domino Directories
and/or Extended Directory Catalog according to the search orders assigned to the directories. The
LDAP service searches directories with no assigned search orders alphabetically according to their
specified domain names.
If an LDAP user specifies a search base, only directories assigned naming rules that correspond to the
search base are searched. If there is more than one directory assigned a naming rule that matches, the
directory with the most specific matching rule is searched first. For example, if a user specifies the
search base ″ou=Sales,o=Acme,″ the server first searches a directory with the rule /Sales/Acme,
before searching a directory with the rule */Acme. If directories have identical naming rules that
match the search base specified by the user, search orders assigned to these directories determine the
order in which the directories are searched.
4. If the search is not successful in any Domino Directory or Extended Directory Catalog, the LDAP
service refers clients to an LDAP directory enabled for LDAP clients in the directory assistance
database.
If an LDAP user doesn’t specify a search base, the LDAP service does not return a referral.
If an LDAP user specifies a search base, the server picks an LDAP directory enabled for LDAP users
with a naming rule that matches the specified search base. If there is no such directory, the server
doesn’t return a referral. If there is more than one such directory, the server picks the one with the
most specific matching rule before picking one with a less-specific rule. If directories have identical
naming rules that match the search base specified by the user, search orders assigned to these
directories determine the order in which the LDAP service picks them for referrals.

Directory search order for a name in a Notes address field: When a Notes user enters a user or group
name in an address field of a Notes memo, the Notes client and mail server search directories in the
following order to retrieve the address for the name. If a name is found during any step, searches
continue only if the ″Recipient name lookup″ field in the Notes user’s current Location document is set to
″Exhaustively check all address books.″
1. The user’s Personal Address Book.
2. Any local Mobile Directory Catalogs on the client.
For searching to continue to a server, the ″Mail file location″ field in the active Location document
must be set to ″On server.″ Type-ahead searches never continue to a server if there is a local Mobile
Directory Catalog.

502 Lotus Domino Administrator 7 Help

3. The primary Domino Directory on the user’s mail server or directory server.
4. A condensed Directory Catalog on the server.
5. Directories defined in the server’s directory assistance database that have the option ″Make this
domain available to: Notes clients and Internet Authentication/Authorization″ enabled.
If the user enters a common name rather than a hierarchical one, the server searches all directories
according to the search order specified for the directories.
If the user enters a hierarchical name, only directories assigned naming rules that correspond to the
hierarchical name the user entered are searched. If there is more than one directory assigned a naming
rule that matches, the directory with the most specific matching rule is searched first. For example, if
a user enters the name Phyllis Spera/Sales/Acme, the server first searches a directory with the rule
/Sales/Acme, before searching a directory with the rule */Acme. If directories have identical naming
rules that match the name entered by the user, search orders assigned to the directories determine the
order in which the directories are searched.

Distinguished Name syntax in multiple-directory environments

For a multiple directory environment that include entries that reside in both Domino and LDAP
directories, it’s important to understand in what contexts to use a Notes DN and in what contexts to use
an LDAP DN (defined in RFC 2253). Generally, you use a Notes DN in a Domino database field (e.g.
Fullname field or any other names field) or ACL, and use an LDAP DN in an LDAP directory attribute.

Additionally, name conversions between Notes and LDAP DN syntaxes may be necessary in multiple
directory environments. For instance, when entering the DN of an entry that resides in an LDAP
directory in the ACL of a Domino database (or an additional value of Fullname), you need to convert it
to its Notes DN equivalent. Or, when using the Notes DN mapping feature in Directory Assistance, you
should convert the Notes DN to its LDAP equivalent and use that value in the specified attribute of the
LDAP directory.

Note: Do not add an LDAP DN as the second value in a Domino Fullname field, as this value is the
Notes ″Common name″ value.

The table below is a helpful reference for how to do these conversions.

Real character in name

component LDAP DN representation Notes DN representation
rr

, <comma> \, <backslash + comma> , <comma>

+ <plus> \+ <backslash + plus> + <plus>
\ <backslash> \\ <backslash + backslash> \ <backslash>
> <greaterthan> \> <backslash + backslash> > <greaterthan>
< <lessthan> \< <backslash + lessthan> < <lessthan>
; <semicolon> \; <backslash + semicolon> ; <semicolon>
″ <doublequote> \″ <backslash + doublequote> ″″″
= <equals> \= <backslash + equals> =
# <numbersign> \# <backslah + numbersign> #
@ <atsign> @ <atsign> ″@″
/ <slash> / <slash> ″/″

Planning internationalized directory services

Domino and Notes provide the following features to support directory services in non-English-speaking
environments:
v Alternate names

Chapter 20. Planning Directory Services 503

v Corporate hierarchies
v LDAP Alternate Language Information documents

Alternate names
The alternate naming feature assigns a Notes user an alternate name recognizable in the user’s native
language, in addition to a primary name that is internationally recognizable. Users use alternate names to
use their native languages when displaying and working with names in the Domino Directory.

For additional information, see the chapter ″Setting Up Notes Users.″

Corporate hierarchies
Companies can create corporate hierarchies to customize the way the Domino Directory categorizes user
entries. For example, companies might create a corporate hierarchy that categorizes by management level.
You can assign one user to a maximum of four corporate hierarchies. When Notes users address mail or
use the search tool to find people, they can choose to display the entries according to their corporate
hierarchy assignments, rather than simply by name or by Notes name hierarchy.

For additional information, see the chapter ″Setting Up the Domino Directory.″

LDAP Alternate Language Information documents

If you use the LDAP service, optionally assign language subattributes to an attribute to define an
alternate language value for the attribute.

For additional information, see the chapter ″Setting Up the LDAP Service.″

Planning directory customization

You can add forms and views to the Domino Directory to accommodate specific needs of your company.
If you use the LDAP service, you can also use the Domino LDAP Schema database (SCHEMA.NSF) to
define new object classes and attributes to be added to the directory.

Some of the questions to ask when planning directory customization are:

v To define a new type of entry in the directory, should you use the Schema database or create a form in
the Domino Directory instead? If you don’t use the LDAP service, you must create a form. If you use
the LDAP service you can use the Schema database to define object classes and attributes with some
LDAP-specific characteristics that are not available when you create Domino Directory forms. However
only LDAP clients, not Notes and Web clients, can access entries defined only in the Schema database.
v If you use the LDAP service, are there attributes and object classes already defined in the Domino
LDAP schema that serve your company’s needs? The schema -- the types of directory entries that are
defined for the LDAP service -- by default defines many object classes and attributes which you may
be able to use rather than adding new ones.
v If your company doesn’t use the LDAP service, should you create a form in such a way that it can
represent an LDAP object class? It’s good practice to create a form that can represent an LDAP object
class, so that if in the future your company uses the LDAP service, the design requirements are in
place.
For additional information, see the chapter ″Managing the LDAP Schema″ and the appendix
″Customizing the Domino Directory.

Directory services terms

Central directory architecture
Directory architecture in a Domino domain in which some servers store Configuration Directories and
use primary Domino Directories on remote servers for lookups.

504 Lotus Domino Administrator 7 Help

Condensed Directory Catalog
A directory catalog created from the DIRCAT5.NTF template that is optimized for small size and used
primarily on Notes clients.

Configuration Directory
A directory in a central directory architecture that contains only documents related to Domino
configuration.
D

Directory server
A server whose purpose is providing directory services.

Directory assistance
A feature used by servers to extend client authentication, name lookups, and LDAP operations to
secondary directories.D

Directory assistance database

A database created from the DA50.NTF template and used to configure directory assistance. D

Directory catalog
An optional directory database that can aggregate entries from multiple Domino Directories into a single
database. There are two kinds of directory catalogs: condensed Directory Catalogs and Extended
Directory Catalogs.

Directory Assistance document

Document created in a directory assistance database that describes a secondary directory. D

Distributed directory architecture

Directory architecture in a Domino domain in which all servers use a local primary Domino Directory.

Domino Directory
A directory created automatically from the PUBNAMES.NTF template during first server setup that
describes the users, servers, connections, and access control information for a Domino domain, or a
directory created manually from the PUBNAMES.NTF.

Domino domain
A network of clients and servers whose users, servers, connections, and access control information is
described in a Domino Directory.

Extended Directory Catalog

A directory catalog used by servers that, to facilitate quick name lookups, retains the individual
documents and the multiple, sorted views available in the Domino Directory. You create an Extended
Directory Catalog from the PUBNAMES.NTF template. Servers use directory assistance to locate an
Extended Directory Catalog.

Extended ACL
An optional directory access control feature available for a Domino Directory and Extended Directory
Catalog used to apply restrictions to users’ overall directory access.

LDAP schema
A set of rules that defines what can be stored as entries in an LDAP directory. The Domino LDAP
Schema database (SCHEMA.NSF), which is created from the SCHEMA.NTF template, publishes the
schema for a domain.

LDAP service
The LDAP server task running on a server to process LDAP client requests.

Chapter 20. Planning Directory Services 505

Lightweight Directory Access Protocol (LDAP)
A standard Internet protocol for accessing and managing directory information. LDAP is a simpler
version of the X.500 protocol that supports TCP/IP.

Mobile Directory Catalog

Name for a condensed Directory Catalog set up on a Notes client.

Personal Address Book

A directory database on a Notes client created from the PERNMAMES.NTF template that contains the
names and addresses of users and groups added by Notes users.

Primary Domino Directory

The Domino Directory that a server searches first and that describes the Domino domain of the server.

Remote LDAP directory

A directory on a remote LDAP server accessed via directory assistance. R

Remote primary Domino Directory

In a central directory architecture, a primary Domino Directory that a server with a Configuration
Directory uses remotely.

Secondary directory
Any directory a server uses that is not its primary Domino Directory. S

Secondary Domino Directory

Any Domino Directory a server uses that is not its primary Domino Directory.

506 Lotus Domino Administrator 7 Help

Chapter 21. Setting Up the Domino Directory
This chapter describes the Domino Directory and explains how to set up the Domino Directory for a
Domino domain.

The Domino Directory

The Domino Directory, which some previous releases referred to as the Public Address Book or Name
and Address Book, is a database that Domino creates automatically on every server. The Domino
Directory is a directory of information about users, servers, and groups, as well as custom entries you
may add. Registering users and servers in a domain automatically creates corresponding Person
documents and Server documents in the Domino Directory for the domain. These documents contain
detailed information about each user and server.

The Domino Directory is also a tool that administrators use to manage the Domino system. For example,
administrators create documents in the Domino Directory to connect servers for replication or mail
routing, to schedule server tasks, and so on.

When a server runs the LDAP service, the Domino Directory is accessible through the Lightweight
Directory Access Protocol (LDAP).

Typically, a Domino Directory is associated with a Domino domain. When you set up the first server in a
Domino domain, Domino automatically creates the Domino Directory database and gives it the file name
NAMES.NSF. When you add a new server to the domain, Domino automatically creates a replica of the
Domino Directory on the new server.

You can also create a Domino Directory manually from the PUBNAMES.NTF template and use it as a
secondary directory to store, for example, entries for your Internet users.

To optimize its performance, the Domino Directory has these database properties enabled by default:
v ″Document table bitmap optimization″ to improve the performance of small view updates -- for
example, updates of the Connections view.
v ″Don’t maintain unread marks″ to improve database performance and reduce the size of the database.
For more information on database performance properties, see the chapter ″Improving Database
Performance.″

Setting up the Domino Directory for a domain

After you install and set up servers in a Domino domain, perform these procedures to set up the Domino
Directory for the domain.
1. (Optional) Set up a central directory architecture in the domain.
2. Control access to the Domino Directory.
3. (Optional) Categorize users in the domain by corporate hierarchy.
4. (Optional) Set up Notes clients to use a directory server in the domain.
5. (Optional) Customize the Directory Profile.
6. Schedule replication for the Domino Directory.

507
Using a central directory architecture in a Domino domain
A central directory architecture is an optional directory architecture you can implement in a Domino
domain. This architecture differs from the traditional distributed directory architecture in which every
server in a domain has a full replica of the primary Domino Directory.

With a central directory architecture, some servers in the domain have selective replicas of a primary
Domino Directory. These replicas, which are known as Configuration Directories, contain only those
documents that are used to configure servers in a Domino domain, such as Server, Connection, and
Configuration Settings documents. A server with a Configuration Directory uses a remote primary
Domino Directory on another server to look up information about users and groups and other
information related to traditional directory services.

A central directory architecture:

v Provides servers with Configuration Directories quick access to new information because the servers
aren’t required to wait for the information to replicate to them.
v Enables servers that store Configuration Directories to run on less powerful machines because they
don’t have to store and maintain the primary Domino Directory.
v Provides tighter administrative control over directory management because only a few directory
replicas contain user and group information.

A server with a Configuration Directory connects to a remote server with a primary Domino Directory to
look up information in the following documents that it doesn’t store locally:
v Person
v Group
v Mail-in Database
v Resource
v Any custom documents you add

For example, to authenticate a user, a server with a Configuration Directory looks for the user credentials
in a Person document in a remote primary Domino Directory on another server in the domain.

508 Lotus Domino Administrator 7 Help

You can set up a Domino Directory as a Configuration Directory when you set up an additional server in
the domain. If a server is already set up, you can use replication settings for the directory to change a
primary Domino Directory to a Configuration Directory or change a Configuration Directory to a primary
Domino Directory.

Planning a central directory architecture for a domain

The central directory architecture is most useful for an enterprise organization that has a domain with a
large Domino Directory. Using a central directory architecture requires network speeds that make remote
directory lookups feasible. In addition, servers that store primary Domino Directories that function as
remote primaries must have the capacity to handle the additional workload generated by the remote
lookups.

Only an application that does a NAMELookup or similar directory call can use a Configuration Directory
to do a lookup in a remote primary Domino Directory.

Deciding which servers should use primary Domino Directories: The administration server for the
Domino Directory must store a primary Domino Directory. For failover, at least one other server in the
domain should store a primary Domino Directory. There may be additional servers that require primary
Domino Directories as well, depending on network bandwidth and stability, server usage patterns and
locations, and so forth. You may want servers that use primary Domino Directories that function as
remote primaries to be within a cluster to provide failover and workload balancing.

If there is a network congestion point in the domain, at least one server on each side of the congestion
point should have a primary Domino Directory that functions as a remote primary.

Using a combined central and distributed directory architecture: You can use a hybrid directory
architecture within one domain. For example, suppose at a company’s headquarters there are multiple
servers connected via fast network connections. There are also smaller remote offices that have limited
network bandwidth but are within the same domain. Servers at corporate headquarters can use the
central directory model that includes a combination of primary Domino Directories and Configuration
Directories, while the remote satellite offices can continue to use the distributed directory architecture in
which each server stores a primary Domino Directory.

Note: Do not mix servers with Configuration Directories and servers with primary Domino Directories in
the same cluster. This can cause users to encounter server authentication and database authorization
problems. All servers in a cluster should be configured to use the same type of directory.

Using a combined primary Domino Directory and Extended Directory Catalog: Although not a typical
configuration, you can integrate an Extended Directory Catalog with a primary Domino Directory to
collect users and groups from the primary domain and secondary domains into one directory database. A
server that stores a Configuration Directory can use this combination directory on a remote server as a
remote primary Domino Directory.

When you use this combination directory, all the users from the aggregated secondary directories are
automatically trusted for authentication, and all the groups can be used in database ACLs for database
authorization.

For more information on integrating an Extended Directory Catalog with a primary Domino Directory,
see the chapter ″Setting Up Directory Catalogs.″

Managing Domino Directories in i a central directory architecture

To manage a central directory architecture, in which there are a combination of Configuration Directories
and primary Domino Directories in a domain, you can:
v Change the directory type of a Domino Directory
v Control how a server finds a remote primary Domino Directory to use
v Prevent the use of a Domino Directory replica as a remote primary

Chapter 21. Setting Up the Domino Directory 509

v Show the primary Domino Directories that servers with Configuration Directories can use

Changing the directory type of a Domino Directory: The first server set up in a domain is always set
up with a primary Domino Directory. When you set up an additional server in the domain, you choose
whether to set up the replica of the Domino Directory on the server as a Configuration Directory or as a
primary Domino Directory. The default selection is a primary Domino Directory.

After server setup, you can change the directory type. After you change directory type, the
Administration Process generates a ″Store Directory Type in Server Record″ request to change the value
of the Directory Type field on the Basics tab of the Server document.

Changing a primary Domino Directory to a Configuration Directory:

Note: Do not change the primary Domino Directory on the administration server to a Configuration
Directory.
1. From the Domino Administrator, connect to the server that stores the replica of the Domino Directory
you want to change.
2. Click the Files tab.
3. Select the Domino Directory, and then double-click.
4. Choose File - Replication - Settings, and change the replication settings for the directory as follows:
a. Click Space Savers in the Replication Settings dialog box.
b. Next to Include, select ″Configuration Documents only.″
c. Click OK.
5. Use the server command Replicate to replicate the Domino Directory that has the changed settings
with a primary Domino Directory on another server. Do a push-pull replication.
6. Restart the server that stores the Domino Directory replica you changed.

Changing a Configuration Directory to a primary Domino Directory:

1. From the Domino Administrator, connect to the server that stores the replica of the Domino Directory
you want to change.
2. Click the Files tab.
3. Select the Domino Directory, and then double-click.
4. Choose File - Replication - Settings, and change the replication settings for the directory as follows:
a. Select Space Savers in the Replication Settings dialog box.
b. Next to Include, select All Fields.
c. Deselect ″Documents that meet a selection formula.″
d. Click Yes when you see the following prompt:
″Switching to Folders will clear the current selection formula. Are you sure you want to do this?″
e. Click OK.
5. Use the server command Replicate to replicate the Domino Directory that has the changed settings
with a primary Domino Directory on another server. Do a push-pull replication.
6. Restart the server that stores the Domino Directory replica you changed.

Controlling how a server finds a remote primary Domino Directory to use: To locate a remote primary
Domino Directory, a server with a Configuration Directory can use a default logic or can use a directory
replica specified through directory assistance.

The default logic to locate a remote primary Domino Directory: The Directory Servers view in a Domino
Directory list the replicas of the primary Domino Directories in the domain that are available for use as
remote primary directories by servers with Configuration Directories. The views sort these replicas
alphabetically by their server names.

510 Lotus Domino Administrator 7 Help

A server that stores a Configuration Directory uses the following logic to build a list in memory of the
five best remote primary Domino Directory replicas to use. If the first replica in the list is unavailable, the
server uses the next replica in the list, and so on.
1. Look in the replication history and find the remote primary directory replica with which the server
most recently replicated. Then look for the replica with which it replicated prior to that, and so on.
2. If the list in memory does not yet include five replicas of a remote primary directory, look for a
primary directory replica in the same Notes named network. If there is more than one such replica,
order them alphabetically by their server names.
3. If the server has not yet located five replicas, refer to the Directory Servers view to order the
remaining remote primary directory replicas alphabetically by their server names, until there are five
primary directories in the list or until all the primary directories are listed.

Setting up directory assistance to locate a primary Domino Directory: You can use directory assistance rather
than the default logic to control which remote primary Domino Directory replicas in a domain servers
with Configuration Directories use. For example, if servers with primary Domino Directories are in a
cluster, you can use directory assistance to use cluster failover to locate the primary Domino Directory
replicas.

To create a Directory Assistance document in a directory assistance database that servers with
Configuration Directories use:
1. Make sure you have set up a directory assistance database on servers with configuration Domino
Directories.
2. From the Domino Administrator, connect to a server that is set up to use the directory assistance
database.
3. Click the Configuration tab.
4. Expand Directory and select Directory Assistance.
5. Click ″Add Directory Assistance.″
6. On the Basics tab, do the following:
a. Next to Domain Type, select Notes.
b. Next to Domain Name, enter the domain of the servers that store the remote primary Domino
Directories. This domain should be the same domain as that of the servers with configuration
Domino Directories.
c. Next to Search Order, select 1.
d. Next to Group Authorization, select No. A server can always use groups in a primary Domino
Directory replica to authorize database access, regardless of what you select for this option. Select
No to reserve the use of the Group Authorization option for a secondary directory.
7. On the Replicas tab do one of the following:
v If the servers that store the primary Domino Directories are clustered, to user cluster failover
specify one replica within the cluster. If that replica is unavailable, cluster failover takes effect
automatically. To use cluster failover, specify only one replica in the cluster.
v If the servers that store primary Domino Directories are not clustered, for failover specify at least
two replicas of the primary Domino Directories to use.

Note: A server always trusts the primary Domino Directory for client authentication, so it is not
necessary to enable a trusted rule in the Directory Assistance document.

For more information on directory assistance, see the chapter ″Setting Up Directory Assistance.″

Preventing the use of a Domino Directory replica as a remote primary: Do the following to prevent
servers with Configuration Directories from using a specific replica of the Domino Directory as a remote
primary. You can prevent a replica from being used only when servers with Configuration Directories use

Chapter 21. Setting Up the Domino Directory 511

the default logic, and not directory assistance, to locate a remote primary Domino Directory. You might
prevent the use of a specific replica to avoid the use of a server that has limited connectivity or CPU
capacity.
1. From the Domino Administrator, select the server that stores the primary Domino Directory.
2. Select the Configuration tab, and select Server - Current Server Document.
3. Click Edit Server.
4. On the Basics tab, in the Directory Information section, below the Directory Type field, deselect
″Allow this directory to be used as a remote primary directory for other servers.″
5. Click Save & Close.

Showing the Domino Directory replicas that can function as remote primaries: The Directory Servers
view in the Domino Directory lists the primary Domino Directories that are in the domain and that have
the option ″Allow this directory to be used as a remote primary directory for other servers″ selected on
the Basics tab of their Server documents. The Central Directories view sorts the primary Domino
Directory replicas by server name.
1. From the Domino Administrator, in the server pane on the left, select any server in the domain. If you
don’t see the server pane, click the servers icon.
2. Click the Files tab and open the Domino Directory.
3. Select the view Servers - Directory Servers.

Tip: Use the Show Xdir command on a server that uses a Configuration Directory to show the remote
primary Domino Directory replica the server last used.

Controlling access to the Domino Directory

Do the following to control access to the Domino Directory:
v Set the Domino Directory ACL to control overall access.
v Assign administrators to the roles in the Domino Directory ACL that correspond to their administrative
tasks.
v (Optional) Use the Administrators field to control access to individual documents.
v (Optional) Use the extended ACL to set access at the form and field level.
For information on setting up an extended ACL, see the chapter ″Setting Up Extended ACLs.″

Setting overall access levels in the Domino Directory ACL

The Domino Directory, like all Notes databases, has an access control list (ACL) that controls the overall
access that users and servers have. The following table shows the default name entries in the Domino
Directory ACL and the default access settings for each entry.

Default name entry Access level User type

-Default- Author access without the ″Create documents″ Unspecified
privilege or administration roles
Anonymous No access Unspecified
LocalDomainAdmins Manager access with no administration roles Person group
LocalDomainServers Manager access with all administration roles except Server group
PolicyCreator and PolicyModifier
OtherDomainServers Reader access Server group
Server in the domain on which the Manager access with all administration roles Server
directory was created.
Administrator specified during server Manager access with all administration roles Person
setup

512 Lotus Domino Administrator 7 Help

You might want to customize the database ACL. For example, to have stricter control over database
access, you might change the access for the -Default- entry to No Access and explicitly add the names of
groups of users to the ACL that you want to allow access.

Note: The default access for the -Default- entry allows users only to change some of the fields in their
Person documents.

Using administration roles in the Domino Directory ACL

i

The Domino Directory ACL includes Creator and Modifier roles that you assign to administrators so they
have the authority to create and edit specific types of documents. By assigning one or more roles along
with general access levels, you can limit an administrator’s access to some types of documents but allow
greater access to other types of documents.

Roles are useful when groups of administrators have specialized responsibilities. If all of the
administrators in your organization have identical administrative responsibilities, assign them to all roles.

The access defined in the ACL by a role never exceeds a general access level. For example, even if you
give the UserCreator role to an administrator who has Reader access in the ACL, the administrator
cannot use the Create menu to create Person documents.

For more general information on roles in an ACL, see the chapter ″Controlling User Access to Domino
Databases.″

Creator roles: Assign creator roles to control who can create documents in the Domino Directory. To
create documents in the Domino Directory, administrators must have:
v The ″Create documents″ privilege
v The Creator role that corresponds to the type of document being created

The following table describes the available Creator roles.

Role Allows
GroupCreator Administrators to create Group documents
NetCreator Administrators to create all documents except Person, Group, Policy, and
Server documents
PolicyCreator Administrators to create Policy documents
ServerCreator Administrators to create Server documents
UserCreator Administrators to create Person documents

CAUTION:
Assigning Creator roles does not provide true security because Domino sometimes ignores Creator
roles when administrators add documents to the directory programmatically.

Modifier roles: Rather than assigning Editor access which allows administrators to modify all
documents, assign administrators Author access along with one or more Modifier roles to control the
types of documents they can edit. For example, assign the UserModifier role to administrators who are
responsible for managing users. Unlike Creator roles, Modifier roles are a true security feature.

The following table describes the available Modifier roles.

Role Allows
GroupModifier Administrators to edit Group documents
NetModifier Administrators to edit all documents except Person, Group, Policy, and
Server documents

Chapter 21. Setting Up the Domino Directory 513

Role Allows
PolicyModifier Administrators to edit Policy documents
ServerModifier Administrators to edit Server documents
UserModifier Administrators to edit Person documents

When using Modifier roles, keep in mind the following points:

v An administrator with Author access and a Modifier role cannot edit fields assigned the security
property ″Must have at least Editor access to use.″
v To delete a document, an administrator must have Author access, the ″Delete documents″ privilege,
and the appropriate Modifier role.
v Modifier roles apply only to administrators who have Author access. Administrators who have Editor
access or higher automatically can modify all documents.

Using the Administrators field to control access to individual documents in the i

Domino Directory
Most types of documents in the Domino Directory contain an Administration tab with an Administrators
field on it. To allow an administrator who has Author access to the directory to modify a single
document, enter the administrator’s name in the Administrators field.
1. From the Domino Administrator open the server that stores the Domino Directory you want to
change.
2. Click the Files tab and open the Domino Directory.
3. Open any document and click Edit.
4. Click the Administration tab.
5. In the Administrators field, enter the names of individual administrators or the name of a group of
administrators who can edit this document.

Note: The designated administrator(s) cannot modify the Owner or Administrator fields even though
they have access to edit the document. For a group document, the designated administrators can edit
only the Group Members field.
6. Click Save & Close.

Corporate hierarchies
You can categorize a Person document in the Domino Directory by a corporate hierarchy. When a Notes
user clicks the Address button to select the name in the Person document from a Domino Directory, or
uses the Find People search tool to find the name, the user can view the name by the assigned Corporate
Hierarchy.

You can categorize user names in any way you want in a corporate hierarchy. For example, you might
categorize users by company division:

Marketing

Kaplan, Judy

Spera, Phyllis

Research and development

Burke, Kathy

Murphy, Bob

514 Lotus Domino Administrator 7 Help

You can assign a user to up to six subcategories below a top-level category. For example, the following
corporate hierarchy sorts each user by one subcategory below a top-level company division category.

Marketing

Design

Spera, Phyllis

Planning

Kaplan, Judy

Research and development

Hardware

Burke, Kathy

Software

Murphy, Bob

You can assign a user to up to four corporate hierarchies. For example, in addition to categorizing a user
by company division, you could also categorize the user by geographic location:

Boston

Spera, Phyllis

Marketing

Design

Spera, Phyllis

Categorizing a user by corporate hierarchy

1. From the Domino Administrator, select the server that stores the Domino Directory to modify.
2. Click the People & Groups tab.
3. Select People, select the user’s Person document, and click Edit Person.
4. Click the Work/Home tab.
5. Click the Corporate Hierarchy Information tab.
6. (Optional) If you want the user’s name to appear in a specific order relative to other names
categorized in the same way, in the Personal ranking field, enter a number to indicate the order in
which the user’s name should appear. A user name given a ranking of 1 is listed before a name with a
ranking of 2, and so on. Leave the Personal ranking field blank to sort the user’s name alphabetically
by last name among other names without a ranking.
7. Below Hierarchy 1, enter categories in the ″Level″ fields by which to sort the user’s name. Repeat this
step to assign the user to up to three additional hierarchies.
8. Click Save & Close.

For example, to categorize the user Judy Kaplan this way, with no personal ranking:

Marketing

Chapter 21. Setting Up the Domino Directory 515

Planning

Kaplan, Judy

Philadelphia

Kaplan, Judy

fill out the Corporate Hierarchy Information tab in her Person document like this:

Setting up Notes clients to use a directory server

You can set up Notes clients to use a different server than their mail servers for mail addressing.
Type-ahead addressing searches a directory server only when Notes users don’t use Mobile Directory
Catalogs. Directory servers aren’t used for LDAP directory searches initiated by Notes users.

To use Desktop settings, Setup settings, or a User Setup Profile to automate the setup:
1. Create a Desktop settings, Setup settings, or User Setup Profile document in the Domino Directory.
For information, see the chapter ″Using Policies.″
2. Enter the name of the directory server in the Directory server field in the Basics tab of the document.
3. Click Save & Close.

Alternatively, a user can add the name of a directory server manually in the ″Domino directory server″
field which is on the Servers tab of a Location document in the Personal Address Book.

For more information on Location documents, see Lotus Notes Help.

Customizing the Directory Profile

Use the Directory Profile to specify miscellaneous settings for the Domino Directory:
1. From the Domino Administrator, in the server pane on the left, select the server that stores the replica
of the Domino Directory you want to modify. If you don’t see the server pane, click the servers icon.
2. Click the Files tab.
3. Select the Domino Directory, and then double-click.
4. Choose Actions - Edit Directory Profile.

516 Lotus Domino Administrator 7 Help

5. Complete any of these fields, and then click Save & Close.

Field
Domain defined by this Domino
Directory
Condensed server directory catalog The file name for a condensed Directory Catalog used by servers in the
for domain
Sort all new groups by default
Use more secure Internet
Passwords
Allow the creation of Alternate
Language Information documents
List of administrators who are
allowed to create Cross Domain
Configuration documents in the
Administration Process Requests
database
Enter
The name of the Domino domain for this directory. Domino completes this
field automatically as part of first server setup.
domain. As an alternative to using this field, you can specify the file names for
individual condensed Directory Catalogs in the ″Directory catalog database
name on this server″ field in the Basics section of Server documents. Setting up
a directory catalog is optional.
Choose one:
v Yes to display the members of a new group in alphabetical order.
v No (default) to display members of a group in the order in which you add
them. If you select No, you can still override this option and alphabetize
members of a specific group.
Choose one:
v Yes (default) to use strong encryption for Internet passwords.
v No to use less secure encryption available with previous releases of Domino.
Choose one:
v Yes (default) to allow you to create Alternate Language Information
documents that enable LDAP clients to search for user information in an
alternate language.
v No to prevent the creation of Alternate Language Information documents.
Enter the names of users who can create Cross Domain Configuration
documents to allow the Administration Process to submit requests between
Domino domains.

Scheduling replication of the Domino Directory

Create Connection documents to schedule replication of the Domino Directory on all servers in the
Domino domain. Since the Domino Directory is central to a Domino system, it’s important to replicate it
frequently. Although the replication schedule you select ultimately depends on the configuration of the
servers in the domain, in general, replicate the Domino Directory at least every 30 minutes or, if the
directory is large and changes frequently, every 10 to 15 minutes.

Schedule the Administration Requests database (ADMIN4.NSF) to replicate as frequently as you replicate
the Domino Directory. The Administration Process, which simplifies some administration tasks, uses the
Administration Requests database and the Domino Directory to do its work. If the Domino Directory is
large, create a Connection document to schedule replication of only the Domino Directory and the
Administration Requests database.

For information on scheduling replication between servers, see the chapter ″Creating Replicas and
Scheduling Replication.″ For information on the Administration Process, see the chapter ″Setting Up the
Administration Process.″

Chapter 21. Setting Up the Domino Directory 517

518 Lotus Domino Administrator 7 Help
Chapter 22. Setting Up the LDAP Service
This chapter describes how to set up a Domino server to use the Lightweight Directory Access Protocol
(LDAP) service.

The LDAP Service

LDAP, Lightweight Directory Access Protocol, is a standard Internet protocol for searching and managing
entries in a directory, where an entry has one or more attributes associated with a distinguished name. A
distinguished name -- for example, cn=Phyllis Spera,ou=Sales,ou=East,o=Acme -- is a name that identifies
an entry within a directory tree. A directory can contain many types of entries -- for example, entries for
users, groups, devices, and application data. Commercial Internet clients such as Microsoft Internet
Explorer and Notes clients with LDAP accounts use LDAP to look up directory information, for example
during mail addressing. You can also develop LDAP applications to search and manage directory
contents. Read about the ldapsearch utility provided with Domino and Notes to learn about LDAP search
syntax.

For more information on the ldapsearch utility, see the chapter ″Using the ldapsearch Utility.″

Running the LDAP task on a server enables the LDAP service to process LDAP client requests.

LDAP service features

The LDAP service supports these features:
v Support for LDAP v3 and v2 clients
v Anonymous access, name-and-password authentication, secure sockets layer (SSL) connections and
X.509 certificate authentication, Simple Authentication and Security Layer (SASL) protocol.
v LDAP operations extended beyond the primary Domino Directory to secondary Domino Directories
and to directory catalogs
v LDAP referrals to remote LDAP directories
v Support for LDAP search, add, modify, modifyDN, compare, and delete operations
v Two methods for schema extension, and support for schema publishing and schema checking
v LDAP language tags to support LDAP searches in alternate languages
v Use of a third-party, LDAP-compliant server to authenticate users that have passwords or X.509
certificates stored in the Domino Directory on a Domino server running the LDAP service. For
information on setting up a third-party server to use the Domino Directory for client authentication,
see the documentation for the server.
v LDAP searches of document text in databases configured in a Domain Catalog

In addition to the LDAP service, Domino and Notes offer these LDAP features:
v Notes client support for LDAP. For more information, see Notes 7 Help.
7

v Command-line utility, ldapsearch, for searching LDAP directories

v Migration tools that use LDAP to import entries from another LDAP directory and register the entries
in Domino
v LDAP C API Toolkit

How the LDAP service works

When the LDAP task is running on a server, the server can listen for and process LDAP client requests.
By default, the LDAP task runs automatically on the administration server for the Domino Directory. The

519
schema daemon spawned by the LDAP task on the administration server uses the Domino LDAP Schema
database to propagate schema changes to any other servers in the domain that run the LDAP service. The
LDAP task on the administration server for the LDAP service domain Domino Directory also verifies the
directory tree to ensure the LDAP service complies with the standard LDAP requirement that each part of
a distinguished name has an entry in the directory that represents the name part as an object class.

For information on the schema daemon, see the chapter ″Managing the LDAP Schema.″ For more
information on directory tree verification, see the next topic.

In addition to using its primary Domino Directory for processing LDAP requests, the LDAP service can
extend LDAP request processing to directory catalogs and secondary Domino Directories, and can refer
LDAP clients to remote LDAP directories, if processing is unsuccessful in any Domino Directory or
directory catalog.

By default the LDAP task listens for LDAP client requests over TCP/IP port 389, and accepts both
anonymous connections, and connections that bind using name-and-password security. The LDAP service
can also listen for requests over an SSL port, usually port 636. The LDAP service can accept requests over
the SSL port from anonymous LDAP clients, and from LDAP clients authenticated using
name-and-password security and/or X.509 certificates.

To search for an entry specified in an LDAP request, the LDAP service does either a view lookup or a
full-text search, depending on the search filter specified in the request. Views lookups are typically faster
than full-text index searches.

Note: The LDAP service always does a full-text search to locate information in a condensed Directory
Catalog set up on the server.

When an LDAP search filter specifies a name or mail attribute, the LDAP service uses views to quickly
locate entries. The PUBNAMES.NTF template design property for these hidden views has ″Universal″
with ″Unicode standard sorting″ selected for the sort order. Unicode provides a unique definition for
every character an LDAP client can specify regardless of the language configured on the client. Using
Unicode sorting, the LDAP service can accurately process LDAP requests specified in different languages
when using these views.

If an LDAP search filter searches for an attribute other than a name or mail attribute, the LDAP service
searches the full-text index, if one exists. If no full-text index exists, the LDAP service uses a view, but the
search will take longer than the full-text index search.

Note: The first value in the FullName field defines the distinguished name for any entry in the Domino
Directory except a Domino Group or Domino Server; the first value in the ListName field defines the
distinguished name for a Domino Group, and the first value in the ServerName field defines the
distinguished name for a Domino Server.

The LDAP service and directory tree verification

When the LDAP service starts on the server that is the administration server for the primary Domino
Directory, it displays these messages at the server console:
LDAP server: "Started verifying Directory Tree on filename"
LDAP server: "Finished verifying Directory Tree on filename"

These messages indicate that the LDAP service is verifying that each part of a Notes-style distinguished
name in a document in the directory has a separate document to define the name part. If the LDAP
service detects that a part of a name is missing such a corresponding document, it creates one in a
hidden view. Creating an additional document in this way ensures that LDAP clients can always use
subtree searches to find the original document.

520 Lotus Domino Administrator 7 Help

For example, if the distinguished name in a Person document is Phyllis Spera/Boston/Acme, and there is
no Domino Certifier document registered for the organizational unit Boston, the LDAP service creates an
organizationalUnit document for Boston. Then, an LDAP user can use a search filter that specifies a
search base of ″ou=Boston,o=Acme″ with the subtree scope to find the entry cn=Phyllis
Spera,ou=Boston,o=Acme.

If the server running the LDAP service is the administration server for a Domino Directory or Extended
Directory Catalog, the LDAP service can verify the directory tree. The LDAP service does not verify the
directory tree for a Configuration Directory or for a condensed Directory Catalog.

The LDAP service can create three types of documents, depending on which part of a Notes
distinguished name is missing one: country, organizationalUnit, and organization documents. The LDAP
service adds such a document when:
v A Notes user name is registered with a unique organizational unit that is not controlled by a certifier.
In this case, the LDAP service creates an organizationalUnit document.
v A Notes user name is registered with a country part. In this case, the LDAP service creates a country
document.
v An administrator creates a document manually that contains a Notes-style distinguished name with an
organizational unit or organization that doesn’t correspond to a Notes certifier document. In this case,
the LDAP service creates an organizationalUnit or an organization document.

Directory tree verification applies only to the distinguished names of documents are added and visible
through Notes, since entries added through the LDAP protocol always have an object class defined for
each distinguished name part.

Running directory tree verification manually: You can run directory tree verification manually, for
example if you’ve added documents to a directory since you last started the LDAP service. To run
directory tree verification manually, enter this command from the Domino Directory administration
server:
Tell Ldap VerifyDIT

Finding the documents that directory tree verification creates: To find the documents created by
directory tree verification, use an LDAP client and specify the following search filter:
"creatorsname=servername"

where servername is the name of the name of the Domino that created the documents. Specify the name in
LDAP format, for example:

″creatorsname=cn=westserver,o=acme″

How the LDAP service forms a value for the mail attribute
To return to value for the mail attribute for a Person, Group, Mail-In Database, or Resource document, the
LDAP service searches for the following:
1. A fully formed Internet address in one of these fields, in the order indicated:
a. Internet Address (InternetAddress)
b. Short Name (ShortName) -- If the ″Internet Address Lookup″ field on Conversions tab of a Global
Domain document is disabled, the LDAP service doesn’t look for a short name.
c. Forwarding address (MailAddress) -- ″Forwarding address″ is the label for this field for Notes mail
users, but the label is different if another mail system is specified for a user.
2. Rules specified below the ″Internet address lookup″ field in the SMTP Address Conversion section on
the Conversions tab of a Global Domain document. If your organization uses more than one Global
Domain document, you must select ″Yes″ in the ″Use as default Global Domain″ field of the Global
Domain document you want to use.

Chapter 22. Setting Up the LDAP Service 521

3. A DNS domain name retrieved from the operating system of the machine on which the LDAP service
runs. The syntax is:
user’s hierarchical name%notesdomain@hostname
For example, Randi Bowker/Marketing/East/Acme%Acme@acme.com

Note: If an extended ACL denies an LDAP access to the LDAP mail attribute or the corresponding
Domino InternetAdress field, the LDAP service does not follow the above steps to derive an address for
the entry to return to the LDAP user.

The LDAP service and secondary directories

You can set up directory assistance on a server that runs the LDAP service to:
v Process LDAP search requests using secondary Domino Directories and Extended Directory Catalogs.
These directories can be either local or remote to the server running the LDAP service.
v Process LDAP write requests to secondary Domino Directories and Extended Directory Catalogs
v Refer LDAP clients to remote LDAP directories when searches are unsuccessful in any Domino
Directory or directory catalog.
v Use secondary Domino Directories, Extended Directory Catalogs, and/or remote LDAP directories to
look up the authentication credentials of LDAP clients connecting to the LDAP service.
v Look up the members of groups used in the access control lists (ACLs) of the directories served by the
LDAP service in one of the following directories, in addition to the primary Domino Directory:
secondary Domino Directory, Extended Directory Catalog, or remote LDAP directory.
v Prevent the LDAP service from carrying out LDAP operations in the primary Domino Directory.
If a server that runs the LDAP service is set up to use a condensed Directory Catalog, the LDAP
service searches the directory catalog automatically after searching the primary Domino Directory. Note
that an Extended Directory Catalog, rather than a condensed Directory Catalog, is recommended for
use on servers.
For more information, see the chapters ″Setting Up Directory Assistance″ and ″Setting Up Directory
Catalogs.″

Setting up the LDAP service

Before you set up the LDAP service, make sure you understand TCP/IP concepts, including DNS host
names and IP addressing.

Follow these steps to set up a server to run the LDAP service:

1. The LDAP task runs automatically on the administration server for the primary Domino Directory. On
other servers in the domain, run the LDAP task manually.
2. If your organization uses more than one Global Domain document, specify the one that the LDAP
service uses to return Internet addresses to LDAP clients. Open the Global Domain document. In the
″Use as default Global Domain″ field, choose Yes.
3. (Optional) Customize the default LDAP service configuration. In many cases, the LDAP service
default settings are adequate.
4. To check whether you set up the LDAP service correctly, use an LDAP search utility such as
ldapsearch provided with Notes and Domino, to issue a query to the LDAP service.
5. Set up LDAP clients to connect to the LDAP service.
If clients wish to connect to the LDAP service over the Internet, connect the server that runs the
LDAP service to an Internet service provider (ISP), and register the server’s DNS name and IP address
with the ISP.
For information on troubleshooting problems with the LDAP service, see the chapter
″Troubleshooting.″

522 Lotus Domino Administrator 7 Help

Note: A server that runs the LDAP service on the Windows platform should not use the system’s name
as the Domino server name.

For more information, see the chapter ″Setting Up the Domino Network.″

Starting and stopping the LDAP service

The following table describes the ways to start and stop the LDAP service.

To do this Perform this task

Start the LDAP service automatically when you
start Domino
Start the LDAP service manually
Stop and restart the LDAP service
Stop the LDAP service
Edit the ServerTasks setting in the NOTES.INI file to include
the LDAP task. Domino adds the LDAP task to the
ServerTasks setting automatically on the administration server
for a domain Domino Directory, or if you select the option
″Directory services (LDAP services)″ during server setup.
Enter Load LDAP at the console.
Enter Restart Task LDAP at the console.
Enter Tell LDAP Quit at the console.

For information on the NOTES.INI file and on server commands, see the appendices.

Preventing the LDAP service on the administration server for the Domino
Directory from processing LDAP client requests
You can prevent the administration server for the Domino Directory from processing LDAP requests, and
leave this processing to another server or servers in the domain that run the LDAP service. Prevent the
administration server from LDAP request processing, for example, if the LDAP ports on the
administration server conflict with the operating system. When you disable the LDAP ports on the
Domino Directory administration server, the LDAP service on the server continues to run the schema
daemon and verify the directory tree for the domain, but does not accept LDAP client requests.

To disable the LDAP ports:

1. Open the Server document of the Domino Directory administration server.
2. Click Edit Server.
3. Click the Ports - Internet Ports - Directory tab.
4. In the ″SSL port status″ and ″TCP/IP port status″ fields, choose Disabled.
5. Click Save & Close.
6. If necessary, wait for the change to replicate to the Domino Directory administration server for the
domain, then enter this command on the Domino Directory administration server to put the changes
into effect:
Restart Task LDAP

The server console displays the message:

"LDAP Server: No ports enabled, listener not started but control task running to maintain schema."

Disabling the LDAP service in i a domain

If you do not want to run the LDAP service on any server in a domain, you can stop the LDAP service
from running on the administration server for the Domino Directory. Do the following on the
administration server:
1. Add the NOTES.INI setting DisableLDAPOnAdmin=1.
2. Remove LDAP from the ServerTasks NOTES.INI setting.

Chapter 22. Setting Up the LDAP Service 523

Customizing the LDAP service configuration
The default LDAP service configuration works without modification, but you can customize it to suit
your needs. The following table describes the LDAP service configuration settings. In addition to the
settings in the table, there are NOTES.INI settings you can use to configure the LDAP service.

For more information, see the topic ″NOTES.INI settings for the LDAP service″ later in the chapter.

Except where noted in the table, restarting the LDAP task or the Domino server is unnecessary after
changing a setting because the task checks for setting changes automatically, by default at three-minute
intervals. You can use the NOTES.INI setting LDAPConfigUpdateInterval to change the interval at which
the LDAP service checks for changes to its settings.

Setting Description For more information

Port and port security Controls the ports LDAP clients can use to See the topic ″Changing the LDAP
settings1 connect to the LDAP service, and the service port and port security
authentication methods enabled for each port configuration.″

Default: TCP/IP port 389 enabled for

name-and-password authentication and for
anonymous access

Changing requires restarting the LDAP task

″Automatically Full Text Controls whether the LDAP service creates and See the topic ″Full-text indexing
Index Domino updates full-text indexes on the Domino directories served by the LDAP service.″
Directory?″ 4 Directories it serves

Default: does not create full-text indexes

″Choose fields that If the port settings allow anonymous access, See the topic ″Configuring anonymous
anonymous users can controls which attributes anonymous LDAP LDAP search access to a directory.″
query via LDAP″ 2, 3, users can search

Changing requires restarting the server

″Allow LDAP users Controls whether LDAP users can modify a See the topic ″Using LDAP to modify a
write access″ 3 directory directory served by the LDAP service.″

Default: LDAP modifications not allowed

Changing requires restarting the server

″Rules to follow when Controls how the LDAP service responds when See the topic ″Configuring how the
this directory...″ 4 it encounters more than one entry or naming LDAP service responds to multiple
rule that applies to an LDAP add, modify, or name matches when processing write
compare operation and compare operations.″

Default: don’t carry out the operation

″Timeout″ 4
Controls the maximum time allowed to process See the topic ″Customizing search
an LDAP search processing to improve LDAP service
performance.″
Default: no limit
″Maximum number of Controls the maximum number of entries that See the topic ″Customizing search
entries returned″ 4 the LDAP service can return in response to an processing to improve LDAP service
LDAP search performance.″

Default: no limit

524 Lotus Domino Administrator 7 Help

Setting Description For more information
″Minimum characters for Controls the minimum number of characters See the topic ″Customizing search
wildcard search″ 4 users must place before the first wildcard in a processing to improve LDAP service
substring search filter performance.″

Default: 1
″Allow Alternate Controls whether LDAP users can do alternate See the topic ″Enabling LDAP alternate
Language Information language searches language searches.″
processing: 4
Default: not allowed
″Enforce schema?″ 4
Controls whether directory modifications See the topic ″Enabling or disabling
through LDAP must conform to the schema schema-checking.″

Default: schema enforced

″DN Required on Bind?″ Controls whether the LDAP service requires See the topic ″Requiring distinguished
4
clients to log on with distinguished names for logon names for LDAP
name-and-password authentication name-and-password security.″

Default: distinguished logon names not

required
″Encode results in UTF8 Controls whether the LDAP service returns See the topic ″Configuring character
for LDAP-v2 clients?″ 4 results in OUTFIT to LDAP v2 clients. encoding for LDAP V2 clients.″

Default: Returns results in OUTFIT to v2

clients
″Maximum number of Controls the maximum number of directory See the topic ″Configuring the number
referrals″ 4 server referrals the LDAP service can return to of referrals the LDAP service can
a client return.″

Default: 1
″Activity Logging Controls the size of the information Activity See the topic ″Limiting the amount of
truncation size″ 4 Logging can log for an LDAP Add or Modify attribute information logged for LDAP
operation Add and LDAP Modify activity.″

Default: 4096 bytes

″Allow dereferencing of Enables limited alias dereferencing for LDAP See the topic ″Configuring alias
aliases on search search requests dereferencing for search requests.″
requests?″
Default: Not enabled

1
Set in the Server document of each server that runs the LDAP service. To configure authentication
options for the ports enabled in a Server document, you can instead use a Directory Site document. Using
the site document to configure authentication options is required in a hosted organization environment.
2
Alternatively, use the database ACL/extended ACL to specify anonymous LDAP search access.
3
Set in the domain Configuration Settings document of each Domino Directory and Extended Directory
Catalog the LDAP service serves. Each directory can have different settings.
4
Set in the domain Configuration Settings document of the primary Domino Directory of the servers that
run the LDAP service in a domain. Setting applies to the LDAP service running on any server in the
domain.

For information on the ″Activity Logging truncation size″ setting, see the chapter ″Setting Up Activity
Logging.″ For information on the ″Enforce schema?″ setting, see the chapter ″Managing the LDAP
Schema.″

Chapter 22. Setting Up the LDAP Service 525

Changing the LDAP service port and port security configuration
By default, LDAP clients can connect to the LDAP service over TCP/IP port 389, anonymously or using
name-and-password authentication. By default, LDAP clients cannot connect using SSL.

Note: To authenticate using name-and-password security some LDAP clients -- for example Microsoft
Internet Explorer and Notes clients with LDAP accounts -- first do an anonymous search to retrieve the
distinguished names used for the authentication, so that users don’t have to specify the distinguished
names themselves. To enable such clients to authenticate using names and passwords, you must enable
anonymous access, as well as name and password authentication, for the LDAP service port the clients
use to connect. You must also allow anonymous read access to the attribute(s) the clients use to search
the directory anonymously to retrieve the distinguished names. Attributes typically searched for are cn,
uid, sn, givenname, or mail.

Follow these steps to change the LDAP service port and port security configuration on a specific server
that runs the LDAP service:
1. From the Domino Administrator, click the Configuration tab.
2. In the left pane, expand Server and open the Server document for the server that runs the LDAP
service.
3. Click Edit Server.
4. Click the Ports - Internet Ports - Directory tab.

Note: If you are administering a hosted organization environment, an asterisk (*) in the following
tables indicates options you must specify instead in a Internet Site document. In a non-hosted
organization environment, you can use the Internet Site document, but you aren’t required to.
For information on using Internet Site documents, see the chapter ″Installing and Setting Up Domino
Servers.″
5. To change the TCP/IP port configuration for the LDAP service, complete these fields:

Field Enter
TCP/IP port number Choose 389 (default) to use the industry standard port for LDAP connections
over TCP/IP. You can specify a different port, but 389 works in most situations.
TCP/IP port status Choose one:
v ″Enabled″ (default) to allow LDAP clients to connect to the server without
using SSL.
v ″Redirect to SSL″ to direct LDAP clients connecting without using SSL to use
SSL instead. The LDAP service returns a message to LDAP clients indicating
that they must connect over SSL.
v ″Disabled″ to prevent LDAP clients from connecting using the TCP/IP port.
Enforce server access settings Choose one:
v Yes to apply the ″Access server″ and ″Not access server″ settings set in the
Server Access section on the Security tab of this Server document to
authenticated LDAP clients connecting to the LDAP service over the TCP/IP
port.
v No (default) to specify that the LDAP service ignore the Server Access
settings.
Authentication options: Name & If the ″TCP/IP port status″ field is set to Enabled, choose one:
Password* v Yes (default) to allow LDAP clients to use name-and-password authentication
when connecting using the TCP/IP port.
v No to prevent LDAP clients from using name-and-password authentication
when connecting using the TCP/IP port.

526 Lotus Domino Administrator 7 Help

Field Enter
Authentication options: If the ″TCP/IP port status″ field is set to Enabled, choose one:
Anonymous* v Yes (default) to allow LDAP clients to connect anonymously using the
TCP/IP port.
v No to prevent LDAP clients from connecting anonymously using the TCP/IP
port.

For more information on server access settings, see the chapter ″Controlling Access to Domino
Servers.″ For more information on the authentication options, see the chapter ″Setting Up
Name-and-Password and Anonymous Access to Domino Servers.″
6. To change the SSL port configuration for the LDAP service, complete these fields:

Field Enter
SSL port number Choose 636 (default) to use the industry standard port for LDAP connections
over SSL. You can specify a different port, but 636 works in most situations.
SSL port status Choose one:
v ″Enabled″ to allow LDAP clients to connect to the LDAP service over SSL.
v ″Disabled″ (default) to prevent LDAP client connections over SSL.
Authentication options: Client If ″SSL port status″ is set to Enabled, choose one:
certificate* v Yes to allow LDAP clients to use client certificate authentication when
connecting.
v No (default) to prevent the LDAP service from using client certificate
authentication.
Authentication options: Name & If the ″SSL port status″ field is set to Enabled, choose one:
password* v Yes to allow LDAP clients to use name-and-password authentication when
connecting to the LDAP service over SSL.
v No (default) to prevent LDAP clients from using name-and-password
authentication over SSL.
Authentication options: If the ″SSL port status″ field is set to Enabled, choose one:
Anonymous* v Yes (default) to allow LDAP clients to connect to the LDAP service
anonymously over SSL.
v No to prevent anonymous SSL connections.

For more information on the authentication options, see the chapters ″Setting Up Clients for S/MIME
and SSL″ and ″Setting Up Name-and-Password and Anonymous Access to Domino Servers.″
7. Click Save & Close.
8. If you made the changes on a different server than the one for which you are configuring the LDAP
service, replicate the changes to the server that runs the LDAP service.
9. Enter the following command on the server that runs the LDAP service to put the changes into effect:
Restart Task LDAP

Full-text indexing directories served by the LDAP service

The LDAP services uses hidden views in a Domino Directory or Extended Directory Catalog to search for
entries when LDAP users specify names or mail addresses in a search filters. When LDAP users specify
other attributes as search criteria, the LDAP service searches the full-text index, if one is created. If your
LDAP users search on attributes other than names or mail addresses, create a full-text index for the
directories the LDAP service serves to improve the speed of these types of searches.

Note: The LDAP service always searches the full-text index to find information in a condensed Directory
Catalog set up on the server.

Chapter 22. Setting Up the LDAP Service 527

You can configure the LDAP service so that the Indexer creates full-text indexes automatically on the
Domino Directories the LDAP service servers. To enable or disable automatic creation of a full-text
indexes on the Domino Directories and Extended Directory Catalogs the LDAP service serves:
1. From the Domino Administrator, open the server that runs the LDAP service, or a server in the same
domain as the one that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would you
like to create one now?″ click Yes, then click the LDAP tab on the document.
If you do not see the prompt, click ″Edit LDAP Settings.″
5. Next to ″Automatically Full Text Index Domino Directory?″ choose one:
v Yes to enable the LDAP service to create and update full-text indexes automatically
v No (default) to prevent the LDAP service from creating and updating full-text indexes
automatically.
6. Click Save & Close.
7. If you selected No to disable this feature, you must delete manually any full text index(s) you want to
remove.

Configuring anonymous LDAP search access to a directory

If the TCP/IP and/or SSL port configuration for the LDAP service allows anonymous LDAP access, use
one of these tools to specify which information anonymous LDAP users can search in a Domino
Directory or an Extended Directory Catalog served by the LDAP service:
v Domain Configuration Settings document
v Database ACL/extended ACL

You specify anonymous search access separately for each directory the LDAP service serves.

Note: Always use the directory database ACL, optionally with an extended ACL, to control directory
access for authenticated LDAP users, and to prevent anonymous LDAP users from modifying the
directory.

Domain Configuration Settings document: The ″Choose fields that anonymous users can query via
LDAP″ setting on the LDAP tab of a domain Configuration Settings document in a Domino Directory or
Extended Directory Catalog is the default method used to determine search access for anonymous LDAP
users. The LDAP service uses the default settings in this document as the default anonymous search
access, even if you do not create the document.

You can modify the ″Choose fields that anonymous users can query via LDAP″ setting to customize
search access for anonymous LDAP users.

Database ACL/Extended ACL: You can use the database ACL along with an extended ACL to define
anonymous LDAP search access to a directory, rather than use the domain Configuration Settings
document.

For information on extended ACLs, see the chapter ″Setting Up Extended ACLs.″

Choosing which method to use: The database ACL/extended ACL is a more flexible method of
controlling anonymous LDAP search access than the domain Configuration Settings document. For
example, when you use the domain Configuration Settings document to allow or deny access to an
attribute, the access applies to all entries that contain the attribute. However, when you use the database
ACL/extended ACL, you can deny access to an attribute contained in entries at a particular branch of the

528 Lotus Domino Administrator 7 Help

directory tree, but allow access to the same attribute contained in entries located at other branches. Or
you can deny access to the attribute in a particular type of entry throughout the directory, but allow
access to it in another type of directory entry.

However, there are implications to using extended access that don’t apply to the use of the domain
Configuration Settings document. For example, after you enable extended access, you can make directory
changes only on a directory replica located on a Lotus Domino 6 or later server. You cannot make such
changes on releases earlier than Domino 6. ACL method also causes database security to be enforced for
Notes namelookups, such as type-ahead lookups. If the domain Configuration Settings document method
is adequate for your needs, it may make sense to use it instead.

Anonymous LDAP search access and upgrades from previous releases: If you upgrade a server from a
pre-Domino 6 release to Domino 6 or later, the LDAP service uses the LDAP anonymous access
configuration from the previous release. If you create or edit the domain Configuration Settings
document after updating the directory with the Lotus Domino 6 PUBNAMES.NTF design, the list of
attributes allowed for anonymous access include the following attributes not listed in previous releases:

Attribute Attribute Attribute Attribute

altServer ditContentRules namingContexts subschemasubentry
attributeTypes extendedAttributeInfo o supportedControl
c extendedClassInfo objectClass supportedExtension
cn l objectClasses supportedLDAPVersion
createTimestamp ldapSyntaxes ou supportedSASLMechanisms
creatorsName modifiersName st vendorname
dc modifyTimestamp street vendorversion

These attributes were not listed in previous releases because you could not prevent anonymous LDAP
access to them -- in previous releases anonymous LDAP users always had search access to these
attributes. Starting with Lotus Domino 6, you can deny anonymous LDAP search access to the attributes
above, although they are allowed for anonymous search access by default to be consistent with the
anonymous search behavior of previous releases.

Using the domain Configuration Settings document to customize anonymous LDAP search access to a
directory: To use the domain Configuration Settings document to customize anonymous LDAP search
access to a specific Domino Directory or Extended Directory Catalog served by the LDAP service, first
open the document, then configure anonymous search access.

Step 1: Open the domain Configuration Settings document in the directory: To open the domain Configuration
Settings document for the primary Domino Directory:
1. From the Domino Administrator, open a server within the domain that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would you
like to create one now?″ click Yes, then click the LDAP tab on the document.
If you do not see the prompt, click ″Edit LDAP Settings.″

To open the domain Configuration Settings document for a secondary Domino Directory or an Extended Directory
Catalog:: To open the domain Configuration Settings document in a Domino Directory that is not the
directory for a domain, or to open the document in an Extended Directory Catalog:
1. From the Domino Administrator, open the directory.

Chapter 22. Setting Up the LDAP Service 529

2. Select the Servers - Configurations view.
3. If you do not see a domain Configuration Settings document in the view, a document named * - [All
Servers], skip to step 4. If you do see this document, do the following:
a. Open the document
b. Click the LDAP tab.
c. Click Edit Server Configuration.
4. If you do not see a domain Configuration Settings document in the view, create one by doing the
following:
a. Click Add Configuration.
b. On the Basics tab select Yes next to ″Use these settings as the default settings for all servers.″
c. Click the LDAP tab.

Step 2: Customize anonymous LDAP search access to the directory: After you have opened the domain
Configuration Settings document for the directory, follow these steps to customize anonymous LDAP
search access:
1. Next to ″Choose fields that anonymous users can query via LDAP″ select ″Select Attribute Types″ to
open the LDAP Attribute Type Selection dialog box.
The ″Queriable Attribute Types″ box at the right of the dialog box shows the attributes anonymous
LDAP users can access.
2. To add an attribute to the ″Queriable Attribute Types″ box to allow anonymous LDAP users to access
the attribute:
a. In the Object Classes box, select an object class that contains the attribute.
b. Click ″Display Attributes″ to display in the ″Selectable Attribute Types″ box all the attributes
defined for the selected object class(es).
c. Select the attribute in the ″Selectable Attribute Types″ box that you want to allow anonymous
LDAP users to access, and click Add to add the attribute to the ″Queriable Attribute Types″ box.
You can select more than one attribute.
Or, to add all the attributes listed in the ″Selectable Attribute Types″ box, click Add All.
When you allow anonymous access to an attribute, the access applies to all object classes for which
that attribute is defined.
3. To remove an attribute from the ″Queriable Attribute Types″ box to prevent anonymous LDAP users
from accessing the attribute, select the attribute and click Remove. Or, to remove all attributes, click
Remove All.

Tip: To revert the ″Queriable Attribute Types″ box to the attributes the LDAP service allows for
anonymous LDAP access by default, click ″Use Default Values.″
4. Click OK to close the LDAP Attribute Type Selection dialog box.
5. Click Save & Close to save the changes in the Configuration Settings document.
6. Do the following for each server in the domain that runs the LDAP service:
a. If you made the changes to a Domino Directory replica on a different server, replicate the changes
to the server.
b. Enter the following command on the server to put the changes into effect:
Restart Server

Converting the default anonymous access settings to database ACL and extended ACL settings: As
soon as you select the advanced ACL option ″Enable Extended Access″ for a directory served by the
LDAP service, the ″Choose fields that anonymous users can query via LDAP″ setting stops controlling
anonymous LDAP search access and is no longer visible in the domain Configuration Settings document.

530 Lotus Domino Administrator 7 Help

To convert the default anonymous search access settings set in the domain Configuration Settings
document to database ACL and extended ACL settings for a Domino Directory or Extended Directory
Catalog, do the following:
1. Make sure you have read thoroughly the documentation on Extended ACLs.
For more information, see the chapter ″Setting Up Extended ACLs.″
2. Open the directory and select ″Enable Extended Access″ in the Advanced tab of the database ACL.
3. On the Basics tab of the ACL, give the Anonymous entry Reader access.
4. Click Extended Access and set the access as follows:
5. Select / (root) as the target.
6. Add Anonymous as a subject at / (root).
7. Leave ″This container and all descendants″ selected as the scope.
8. For the default privileges, click Allow Browse and click Deny Create, Delete, Read, and Write.
9. Click Form and Field Access.
10. Next to Schema, select Domino.
11. In the Forms box, select Person.
12. With the Person form still selected, select each of the following fields in the Fields box, and for each
field click Allow Read:
AltFullName
Certificate
FirstName
InternetAddress
LastName
Location
MailAddress
MailDomain
O
OfficeCity
OfficeCountry
OfficeState
OU
PublicKey
ShortName
Street
Type
UserCertificate
13. In the Forms box, select Group.
14. With the Group form still selected, select each of the following fields in the Fields box, and for each
field click Allow Read:
InternetAddress
MailDomain
Members
Type
15. Next to Schema, select LDAP.
16. In the Object Classes box, select dominoPerson.
17. With the dominoPerson object class still selected, in the Attributes box select cn and click Allow
Read.

Chapter 22. Setting Up the LDAP Service 531

18. Click OK twice, and when you see the prompt ″Save changes before exiting?″ click Yes.

Note: If you disable ″Enable Extended Access″ in a directory ACL, the default settings in the ″Choose
fields that anonymous users can query via LDAP″ setting in the domain Configuration Settings document
resume control of anonymous LDAP search access for the directory.

Using LDAP to modify a directory served by the LDAP service

By default, the LDAP service does not allow LDAP clients to modify the directories the LDAP service
serves. However, you can enable LDAP write access for any of the following directories to allow LDAP
users with the required database access to modify the directories:
v Primary Domino Directory of the LDAP service
v Secondary Domino Directory or Extended Directory Catalog the LDAP services serves

You control LDAP write access separately for each directory. For example, you could enable write access
for the primary Domino Directory, and leave write access disabled for an Extended Directory Catalog.

Note: You cannot enable LDAP write access to a condensed Directory Catalog served by the LDAP
service.

Keep the following points in mind if you enable LDAP write access for a directory:
1. Domino does not provide a tool for doing LDAP write operations, you must develop or obtain one.
2. If you allow LDAP write access, use the directory database ACL, and optionally, extended ACL, to
control the directory changes that LDAP users can make.
3. Enable schema checking for the LDAP service to require that directory changes made via LDAP
conform to the directory schema. By default schema checking is disabled, if you allow LDAP write
operations, enabling it is recommended to maintain consistent directory contents.
4. The Administration Process server task doesn’t respond to LDAP write operations. For example, if an
LDAP user deletes a Person document, the Administration Process can’t delete the associated user
name from database ACLs.
5. The LDAP service can carry out an LDAP write operation in a secondary Domino Directory or
Extended Directory Catalog only if that directory is stored locally on the server that runs the LDAP
service. If the LDAP service receives a write operation request for a Domino Directory on a remote
server, it sends an LDAP referral to the client. The LDAP service refers the client to the administration
server for the directory. If there is no administration server specified, it refers the client to the remote
server that stores the directory. The client must then follow the referral itself.

Note: If you enable LDAP write access to a secondary Domino Directory, do not use a condensed
Directory Catalog that aggregates that directory on a server that runs the LDAP service.
6. The distinguished names of directory entries are limited to 256 characters. Distinguished names do
not have to conform to the standard Notes naming model of organizational unit (ou), organization (o),
and country (c). For example, distinguished names such as these are acceptable:
v dn: cn=Jay Walker + uid=123456,u=Sales,o=Widget Inc.,c=GB
v dn: foo=Bar, o=Acme
v dn: cn=L. Eagle,o=Sue\, Grabbit and Runn,c=GB
Names such as these are recommended primarily for entries that are accessed through LDAP only,
since Notes users may find them confusing.
7. Prior to doing batch adds of 100 or more directory entries, you can use the NOTES.INI setting
LDAPBatchAdds to process the additions more quickly. Disable the setting when the batch adds are
complete.
8. You can’t modify the value of an entry’s structural object class attribute.

Enabling or disabling LDAP write access to a directory served by the LDAP service: By default, the
LDAP service does not allow LDAP clients to modify the directories the LDAP service serves. If you

532 Lotus Domino Administrator 7 Help

enable directory changes to be made via LDAP, the directory database ACL and, optionally, an extended
ACL, control the extent to which authenticated and anonymous LDAP users can modify directory entries.
For example, an LDAP user with Editor database ACL access can modify all entries, whereas an LDAP
user with only Author database ACL access and the UserModifier role can modify only Person entries
and not other entries.

To enable or disable LDAP write access to the primary Domino Directory of the LDAP service, or to a
secondary Domino Directory or Extended Directory Catalog the LDAP service serves:
1. From the Domino Administrator, open the directory for which you want to enable write access.
2. Select the Servers - Configurations view.
3. If you do not see a domain Configuration Settings document in the view, a document named * - [All
Servers], skip to step 4. If you see this document, do the following:
a. Open the document
b. Click the LDAP tab.
c. Click Edit Server Configuration.
4. If you do not see a domain Configuration Settings document in the view, create one by doing the
following:
a. Click Add Configuration.
b. On the Basics tab select Yes next to ″Use these settings as the default settings for all servers.″
c. Click the LDAP tab.

Tip: If you are enabling write access for the primary Domino Directory in the domain, a shortcut for
steps 2-4 is: from the Domino Administrator open the server that stores the directory; click the
Configuration tab; in the left pane expand Directory, then LDAP, and then select Settings; click Edit
LDAP Settings.
1. Next to ″Allow LDAP users write access″ choose one:
v Yes to allow directory changes via LDAP.
v No (default) to prevent directory changes via LDAP.
2. Click Save & Close.
3. For each server in the domain that runs the LDAP service, do the following:
a. If you made the changes to a Domino Directory replica on a different server, replicate the changes
to the server.
b. Enter the following command on the server to put the changes into effect:
Restart Server
4. If you enabled LDAP write access, set up the database ACL, and optionally extended ACL, to specify
the directory contents that LDAP users can modify.
For more information, see the chapters ″Setting Up the Domino Directory″ and ″Setting Up Extended
ACLs.″

Note: If you want to allow users to modify documents in the directory, you must have the
″Maximum Internet name-and-password access″ setting, found in the Advanced pane of the database
Access Control dialog box, set to Editor access or higher.
For more information on this ACL setting, see the chapter ″Controlling User Access to Domino
Databases.″
5. Configure how the LDAP service responds when it finds more than one occurrence of a name
specified in an LDAP write operation.

Chapter 22. Setting Up the LDAP Service 533

Configuring how the LDAP service responds to multiple name matches when
processing write and compare operations
The LDAP service uses its ″Rules to follow when this directory is the primary directory and there are
multiple matches on the distinguished name being compared/modified″ setting to determine how to
responds in either of these situations:
v It receives an LDAP modify, modify DN, delete, or compare request and finds more than one entry,
within one directory or across directories, with a distinguished name that matches the one specified in
the request.
v It receives an LDAP add request and finds more than one Domino Directory enabled for LDAP clients
in its directory assistance database with a directory assistance naming rule that most specifically
matches the distinguished name specified in the request.
Note that if there is no Domino Directory enabled for LDAP clients in directory assistance with a rule
that matches the distinguished name specified in an add operation, the LDAP service adds the entry to
its primary Domino Directory. If there is only one Domino Directory enabled for LDAP clients in
directory assistance with a rule that matches the distinguished name specified in an add operation, the
LDAP service adds the entry to that directory.
For more information on the LDAP service and directory assistance, see the chapter ″Setting Up
Directory Assistance.″

To specify the ″Rules to follow when this directory is the primary directory and there are multiple
matches on the distinguished name being compared/modified″ for all servers in the domain that run the
LDAP service:
1. From the Domino Administrator, open the server that runs the LDAP service, or a server in the same
domain as the one that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would you
like to create one now?″ click Yes, then click the LDAP tab on the document.
If you do not see the prompt, click ″Edit LDAP Settings.″
5. In the ″Rules to follow when this directory is the primary directory and there are multiple matches on
the distinguished name being compared/modified″ field, choose one to specify how the LDAP service
responds in the two situations described above:

″Rules to follow...″ setting Results

″Don’t modify any″ (default)
″Modify first match″
″Modify all matches″
Prevents the operation from occurring. The LDAP service returns an error, and
you can investigate the duplicate names/naming rules.
v Carries out the LDAP modify, delete, or compare operation on the first entry
encountered in a directory enabled for LDAP write operations that matches
the distinguished name specified in the operation.
v Carries out the LDAP add operation in the Domino Directory configured in
directory assistance database that is enabled for LDAP write operations and
has the most specific matching rule and the lowest search order
v Carries out the LDAP modify, delete, or compare operation on all the entries
encountered that match the distinguished name specified in the operation.
v Carries out the LDAP add operation in all the Domino Directories configured
in the directory assistance database with a matching rule that most
specifically matches the distinguished name specified in the add operation,
and that are enabled for LDAP write operations.

6. Click Save & Close.

534 Lotus Domino Administrator 7 Help

Examples of the ″Rules to follow...″ setting and LDAP add operations: Assume the LDAP service uses
directory assistance to serve secondary Domino Directories in Domains B, C, and D, in addition to its
primary Domino Directory. These secondary directories are stored locally on the server running the
LDAP service and are configured in the directory assistance database as follows:

Domain Naming rule Search order

Domain B */*/*/*/*/* 1
Domain C */*/*/*/*/* 2
Domain D */*/*/DomainD/Acme* 3

Note: If a directory is stored on a remote server, the LDAP service can send an LDAP referral to the
client but cannot process the add operation remotely itself.

For more information, see the chapter ″Setting Up Directory Assistance.″

The following table provides examples of how the LDAP service processes add operations as a result of
the above directory assistance configuration and different selections for the ″Rules to follow when this
directory is the primary directory and there are multiple matches on the distinguished name being
compared/modified″ LDAP service setting.

Name of entry being added
cn=Kate
Power,ou=DomainD,o=Acme
cn=John
Ashby,ou=DomainC,o=Acme
cn=John
Ashby,ou=DomainC,o=Acme
cn=John
Ashby,ou=DomainC,o=Acme
Directory or
directories to
″Rules to follow...″ which entry
setting added Explanation
N/A Domain D Domain D directory is the only
directory with a rule that most
specifically matches a name added
Modify first match Domain B Rules for Domain B and C both
match the name being added;
entry added to Domain B because
it has lower search order than
Domain C.
Modify all matches Domains B & C Rules for Domain B and C both
match the name being added;
entry added to both directories.
Don’t modify any None Rules for Domain B and C both
match the name being added;
entry not added.

Customizing search processing to improve LDAP service performance

To improve the performance of the LDAP service, you can choose options to customize how the service
processes searches. These settings apply to all servers in a domain that run the LDAP service.

″Timeout″ and ″Maximum number of entries returned″: By default, LDAP service takes as long as
necessary to process searches, and returns all entries it finds that match the search criteria. If LDAP
service performance is slow, consider using the ″Timeout″ and ″Maximum number of entries returned″
fields on the LDAP tab of a domain Configuration Settings document to set limits on the length of
searches and the number of entries returned. If the LDAP client that sends a request also specifies limits,
whichever setting is lower takes precedence.

″Minimum characters for wildcard search″: Specify the minimum number of characters that users must
place before the first wildcard in a search filter when the wildcard is combined with a substring. The
default is 1 character. If you increase this value, users must provide more specific substring search filters,

Chapter 22. Setting Up the LDAP Service 535

and as a result, the LDAP service searches fewer entries and processes the searches more quickly. If
LDAP service performance is slow, consider increasing the minimum characters required for wildcard
searches to 2.

If a filter begins with a wildcard followed by a substring, the LDAP service removes the initial wildcard
(unless ″Minimum characters for wildcard search″ is set to 0), then uses what remains as the search filter.
For example, if the option is set to 2 and a user specifies the filter sn=*br*, the LDAP service uses the
filter br* to process the search. However, if a user specifies the filter *b*, the LDAP service rejects the
search request because after the first wildcard is removed, b*, which is the remaining search filter,
contains only one character before the (now) first wildcard.

Note: The ″Minimum characters for wildcard search″ option doesn’t apply to search filters that use only
a wildcard as a value, for example, a search filter such as sn=* is always allowed. Because this kind of
filter searches only for the presence of an attribute, not for an attribute value, it does not have the search
performance implications associated with wildcards in substring searches. To control the number of
entries returned as the result of a presence search filter, use the ″Maximum number of entries returned″
option to set a maximum number of entries that the LDAP service can return.

Specifying settings to improve LDAP service search performance::

1. From the Domino Administrator, open a server that runs the LDAP service, or a open a server in the
same domain as one that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would you
like to create one now?″ click Yes, then click the LDAP tab on the document.
If you do not see the prompt, click ″Edit LDAP Settings.″
5. Change settings in any of these fields:

Field Enter
Timeout The maximum time, in seconds, allowed for LDAP client searches;
default is 0. For example, specify 60.
Maximum number of entries returned The maximum number of directory entries the LDAP service
returns to LDAP clients as search results; default is 0, meaning that
there is no limit. For example, specify 100.
Minimum characters for wildcard search The minimum number of characters that must precede the first
wildcard in a search filter when the wildcard is combined with a
substring; default is 1.

6. Click Save & Close.

Enabling LDAP alternate language searches

RFC 2596 defines language tags that you can append to an attribute to define an alternate language value
for the attribute. For example,″givenName;lang-fr=Etienne″ defines Etienne as a French value for the
givenName attribute. The LDAP service supports language tags.

Many LDAP clients do not support language tags in search queries. Such LDAP clients can specify, for
example, ″givenName=Etienne″ to find an entry with ″givenName;lang-fr=Etienne″ defined.

To enable LDAP alternate language searches, configure the LDAP service to allow them, and add the
language tags to entries. Use an Alternative Language Information document in the Domino Directory to
add language tags to a Person document. Use LDAP add and modify operations to add language tags to
any other type of entry.

536 Lotus Domino Administrator 7 Help

Configuring the LDAP service to allow LDAP alternate language searches: Follow these steps to allow
all servers in a domain that run the LDAP service to process LDAP alternate language searches:
1. In the Directory Profile, enable support for LDAP alternate language searches:
a. From the Domino Administrator, open the primary Domino Directory of the server that runs the
LDAP service:
b. Choose Actions - Edit Directory Profile.
c. In the ″Allow the creation of Alternate Language Information documents″ field, choose Yes.
d. Click Save & Close.
2. In the domain Configuration Settings document, enable support for LDAP alternate language
searches:
a. From the Domino Administrator, open the server that runs the LDAP service, or a open a server in
the same domain as the one that runs the LDAP service.
b. Click the Configuration tab.
c. In the left pane, expand Directory, then LDAP, and then select Settings.
d. Do one of the following:
If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would
you like to create one now?″ click Yes, then click the LDAP tab on the document.
If you do not see the prompt, click ″Edit LDAP Settings.″
e. In the ″Allow Alternate Language Information processing″ field, choose Yes.
f. Click Save & Close.

Using an Alternative Language Information document to define language subattributes for a Person
document: To add LDAP language tags for a specific language to a Person document (dominoPerson
entry), create an Alternative Language Information document that is associated with the Person
document. The Alternative Language Information document contains a subset of the fields in the Person
document, for which you assign values in the alternate language. You can create multiple Alternative
Language Information documents for one Person document. You can create Alternative Language
Information documents in any Domino Directory that the LDAP service serves.

To add LDAP language tags for a specific language to a Domino Person document:
1. From the Domino Administrator, open the Domino Directory that contains the Person document.
2. Click the People & Groups tab.
3. Select People, and open the Person document to which you want to add the language tags.
4. Choose Actions - Add Alternate Language Information.
5. Click the Basics tab, and do the following:
a. In the Language field, select the language to use.
b. Enter values in the selected language for any of the other fields in the Basic tab.

Note: The User name (FullName) field is inherited from the Person document. LDAP uses this as
the distinguished name that identifies the person, and you can’t create an alternate language
version of it.
6. Click the Work/Home tab, and enter values in the selected language for any of the fields in the Work,
Home, and Corporate Hierarchy tabs.
For information on Corporate Hierarchies, see the chapter ″Setting Up the Domino Directory.″
7. Click Save & Close.

Viewing Alternative Language Information documents: To view the Alternative Language Information
documents associated with Person documents:
1. From the Domino Administrator, click the Files tab, and open the Domino Directory.
2. Expand the People view, and select the Alternate Languages view.

Chapter 22. Setting Up the LDAP Service 537

Requiring distinguished logon names for LDAP name-and-password security
To conform to RFCs 2251 through 2254, you can use the LDAP service option ″DN Required on Bind?″ to
require that an LDAP client that binds using name-and-password security to any LDAP service running
in the domain use their fully qualified LDAP distinguished name as their LDAP client logon name. In a
Person document in the Domino Directory, the distinguished name is the first value in the FullName
field, labeled User Name. By default, the LDAP service doesn’t require an LDAP client to use the
distinguished name as a logon name.

If you don’t require distinguished names as logon names for name-and-password security, the ″Internet
authentication″ field on the Security tab of a Server document for a server that runs the LDAP service
controls which client logon names are allowed for name-and-password security.

For more information on name-and-password security, see the chapter ″Setting Up Name-and-Password
and Anonymous Access to Domino Servers.″

To enable or disable the requirement that LDAP users use their distinguished names as log on names
when using name-and-password security when binding to the LDAP service:
1. From the Domino Administrator, open a server that runs the LDAP service, or a server in the same
domain as a server that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
v If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would
you like to create one now?″ click Yes, then click the LDAP tab on the document that is created.
v If you do not see this prompt, click ″Edit LDAP Settings.″
5. Next to ″DN Required on Bind?″ choose one:
v Yes to require distinguished names as LDAP client logon names for name-and-password security.
v No (default) to not require distinguished names for client logon names.
6. Click Save & Close.

Configuring character encoding for LDAP V2 clients

By default, the LDAP service uses UTF-8 character encoding when returning results with international
characters to LDAP V2 clients. Although the LDAP V2 RFC does not support the use of UTF-8, the
default behavior ensures that LDAP V2 clients such as EudoraPro 4.1, which uses UTF-8, can work well
with the LDAP service.

To support LDAP V2 clients that don’t use UTF-8, you can change the default encoding to prevent the
LDAP service from using UTF-8 character encoding for V2 clients. If you prevent the use of UTF-8
character encoding for LDAP V2 clients, then the LDAP service may sometimes be unable to return
results containing international characters to V2 clients that use UTF-8.

Note: The LDAP service always uses UTF-8 character encoding when returning results with international
characters to LDAP V3 clients, for example, Microsoft Outlook Express clients and Notes clients.

To enable or disable the use of UTF-8 character encoding for LDAP V2 clients for the LDAP service
running on any server in a domain:
1. From the Domino Administrator, open the server that runs the LDAP service, or a server in the same
domain as the one that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:

538 Lotus Domino Administrator 7 Help

 v If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would
you like to create one now?″ click Yes, then click the LDAP tab on the document that is created.
v If you do not see this prompt, click ″Edit LDAP Settings.″
5. Choose one:
v Yes (default) to use UTF-8 character encoding for LDAP V2 clients.
v No to prevent the use of UTF-8 character encoding for LDAP V2 clients.
6. Click Save & Close.

Configuring the number of referrals the LDAP service can return

When the LDAP service can’t find information for which an LDAP client is searching, it can return a
referral to the client, which is a URL to another directory server that might hold the information the
client is requesting. The LDAP service uses directory assistance to return referrals.

For more information on LDAP service referrals, see the chapter ″Setting Up Directory Assistance.″

By default, the LDAP service can return one referral to a client. To configure the number of referrals the
LDAP service running on any server in a domain can return to LDAP clients:
1. From the Domino Administrator, open the server that runs the LDAP service, or a server in the same
domain as the one that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
v If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would
you like to create one now?″ click Yes, then click the LDAP tab on the document that is created.
v If you do not see this prompt, click ″Edit LDAP Settings.″
5. Next to ″Maximum number of referrals″ specify the maximum number of referrals the LDAP service
can return to a client.
6. Click Save & Close.

Setting up clients to use the LDAP service

You can set up both non-Notes clients and Notes clients to use the LDAP service running on a specific
server.

Setting up non-Notes clients to use the LDAP service

To set up Internet clients to connect to the LDAP service, specify the following on the clients:
v Host name of a Domino server running the LDAP service -- for example, ldap.acme.com
v Port to use for the connection, for example 389 for TCP/IP, or 636 for SSL.
v (Optional) Client authentication: SSL or name-and-password security
v Search base -- applies only to any secondary Domino Directories the LDAP service serves using
directory assistance

For more information, see the documentation provided with the client.

Setting up Notes clients to use the LDAP service

To set up Notes clients to connect to the LDAP service running on a particular Domino server, create
LDAP accounts for the LDAP service in the Notes clients’ Personal Address Books. Use Setup policy
settings and/or Desktop policy settings documents to automate setup of the LDAP accounts. If you do
not automate setup of the accounts, you or the users must create the accounts manually.

For more information on accounts, see Notes 7 Help.

Chapter 22. Setting Up the LDAP Service 539

Note: User Setup Profiles used in Lotus Domino Release 5 for automated LDAP account setup continue
to work in all post-Release 5 versions of IBM Lotus Domino.

To use a Setup policy settings document and/or Desktop policy settings document to automate setup of
LDAP accounts for the LDAP service on Notes clients:
1. Make sure you understand policies and how to set them up.
For information, see the chapter ″Using Policies.″
2. If you haven’t already done so, create a Desktop policy settings document or a Setup policy settings
document to use to automate setup of the LDAP accounts.
3. Open the Desktop policy settings document or Setup policy settings document you want to use to
automate setup of the LDAP account.
4. Click the Accounts tab, then complete the following fields:

Field Enter
Inherit Default Accounts Settings from Parent Select to inherit default account settings from parent.
Enforce Default Accounts Settings in Children Select to enforce default account settings in children.
Account Names A descriptive name for the LDAP service account; users see this
name in the list of directories the client can search. If you specify
more than one account -- for example, an account for another
Internet service -- separate account names with commas (,).
Server Addresses The host name of the server running the LDAP service -- for
example, ldap.acme.com.
Protocols LDAP
Use SSL Connection Yes to use SSL; otherwise, No.

5. Click Save & Close.

LDAP client authentication

To authenticate LDAP clients, the LDAP service can look up the clients’ distinguished names and
passwords/certificates in any of the following directories:
v Primary Domino Directory
v Extended Directory Catalog
v Condensed Directory Catalog on server (passwords only recommended)
v Secondary Domino Directory
v Remote LDAP directory

The primary Domino Directory of the server running the LDAP service is trusted for client authentication
automatically. You must explicitly trust other directories for client authentication.

For additional information, see the chapters ″Setting Up Directory Catalogs,″ ″Setting Up Directory
Assistance,″ ″Setting Up Name-and-Password and Anonymous Access to Domino Servers,″ and ″Setting
Up Clients for S/MIME and SSL.″

Using LDAP to search a Domain Index

If the LDAP service is running on a server that stores a Domain Index, you can develop an LDAP
application to search the Domain Index for all documents that contain a specific text string and then
return specific attributes of these documents. Use this search query format:
"(&(ObjectClass=Document)(Object=*xxx*))" attributes

where:

540 Lotus Domino Administrator 7 Help

xxx represents the text string to search for

attributes are any of these attributes to retrieve:

v cn
v url
v doctitle
v docauthor
v docsummary
v dbheading
v dbcategories
v dbtitle

For example, the following query searches for all documents that contain the text ″HR policies″ and then
returns the cn, url, doctitle, docauthor, and dbtitle values for those documents:
"(&(ObjectClass=Document)(Object=*HR policies*))" cn url doctitle docauthor dbtitle

You can use operators with the Object attribute search filter. For example, to find all documents that
contain both the text ″HR policies″ and the text ″1999″ and then return the same set of attributes as the
example above, use this query:
"(&(ObjectClass=Document)(&(Object=*HR policies*)(Object=*1999*)))" cn url doctitle docauthor dbtitle

To search the text of a database, you must have at least Reader access in the ACL of the source database.

Monitoring the LDAP service

Use these methods to monitor the LDAP service:
v Show the current LDAP service configuration settings
v Show statistics related to LDAP service port activity

Showing the current LDAP service configuration settings

To show the current status of:
v The settings for the LDAP service that are controlled through the domain Configuration Settings
document.
v The LDAP service port settings in the Internet Ports section of the Server document.
v LDAP Activity Logging

enter this server command on a server that runs the LDAP service:
Tell Ldap Showconfig

To show the status of the above settings as well as the status of the LDAP service settings controlled
through the NOTES.INI file, enter this server command:
Tell Ldap showconfig debug

Showing statistics related to LDAP service port activity

You can see statistics about LDAP service port activity related specifically to LDAP operations, and also
network statistics related to general network activity over the LDAP service ports. You can use the Show
Stat command to see statistics.

Note: Each statistic listed in the following tables begins with the prefix LDAP. but the tables omit the
prefix. For example, the statistic LDAP.Total LDAP Connections is shown as Total LDAP Connections.

Statistics related to LDAP operations: The following statistics relate to connections made using LDAP.
Statistics calculation begins at LDAP service startup.

Chapter 22. Setting Up the LDAP Service 541

Statistic
Total LDAP Connections
Simple LDAP Connections
Anonymous LDAP Connections
Strong Authentication Connections
Failed LDAP Connections
Total LDAP Searches
Longest LDAP Search time
Average LDAP Search time
Longest LDAP Search request
Total LDAP Modifies
Total LDAP Compares
Total LDAP Adds
Total LDAP Deletes
Total LDAP ModifyDNs
Total LDAP Extended Operations
Total LDAP Abandons
Total LDAP Searches for Subschema
Total LDAP Searches for Root DSE
Total LDAP Referrals returned
Total LDAP Searches on Domain Catalog
Total LDAP Search Entries Returned
Total LDAP Search time
Server.Running
Statistics for network activity on the LDAP service ports: The following statistics relate to network
activity over the LDAP service ports since Domino server startup. These statistics can reflect network
activity that does not involve the LDAP protocol, for example activity resulting from telnet requests.
Statistic
Sessions.Inbound.Accept.Queue
Sessions.Inbound.Active
Sessions.Inbound.Active.SSL
Sessions.Inbound.BytesReceived
Sessions.Inbound.BytesSent
Sessions.Inbound.Peak
542 Lotus Domino Administrator 7 Help
Description
Number of LDAP connections
Number of LDAP connections using name-and-password
authentication
Number of anonymous LDAP connections
Number of LDAP connections using X.509 client certificate
authentication
Number of LDAP connections that failed
Number of LDAP search requests processed
Longest amount of time taken to successfully complete an LDAP
search request that has been received so far. This statistic does not
include LDAP searches that fail with any error.
Average amount of time taken to process LDAP search requests
received so far. The value includes time taken to process search
requests that fail, and so on occasion it may exceed the Longest LDAP
Search time value.
Longest amount of time to receive an LDAP search request
Number of LDAP modify requests processed
Number of LDAP compare requests processed
Number of LDAP add requests processed
Number of LDAP delete requests processed
Number of modifyDN requests processed
Number of requests to extend the schema processed
Number of abandon requests processed
Number of requests to search the subschema processed
Number of requests to search the root DSE processed
Number of referrals to remote LDAP directories returned
Number of requests to search the Domain Catalog processed
Number of entries returned from search requests
Total time spent processing LDAP searches
Shows whether the LDAP service is running
Description
Number of new connections waiting to be serviced by
threadpool
Number of currently running inbound TCP/SSL connections
Number of currently running inbound SSL connections
Number of bytes received by all inbound TCP/SSL
connections
Number of bytes sent by all inbound TCP/SSL connections
Maximum number of concurrent inbound TCP/SSL
connections
Statistic Description
Sessions.Inbound.Peak.SSL Peak number of concurrent inbound SSL connections
Sessions.Inbound.Total Number of all TCP/SSL inbound connections since server
started
Sessions.Inbound.Total.SSL Number of all SSL inbound connections since server started
Sessions.Inbound.Total.SSL.Bad_Handshake Total number of failed inbound SSL handshakes since server
started
Sessions.Outbound.Active Number of currently running outbound TCP/SSL
connections
Sessions.Outbound.Active.SSL Number of currently running outbound SSL connections
Sessions.Outbound.BytesReceived Number of bytes received by all outbound TCP/SSL
connections
Sessions.Outbound.BytesSent Number of bytes sent by all outbound TCP/SSL connections
Sessions.Outbound.Peak Maximum number of concurrent outbound TCP/SSL
connections
Sessions.Outbound.Peak.SSL Maximum number of concurrent outbound SSL connections
Sessions.Outbound.Total Number of all TCP outbound connections since server
started
Sessions.Outbound.Total.SSL Number of all SSL outbound connections since server started
Sessions.Outbound.Total.SSL.Bad_Handshake Total number of failed outbound SSL handshakes since
server started
Sessions.Threads.Busy Total number of running threads servicing network IO
requests
Sessions.Threads.Idle Total number of idle threads waiting to service network IO
requests
Sessions.Threads.InThreadPool Current number of threads in threadpool
Sessions.Threads.Peak Peak number of threads in threadpool

RFCs supported by the LDAP service

The Domino LDAP service supports the RFCs described in the following table.

RFC Description
2079 Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource
Identifiers
2222 Simple Authentication & Security Layer (SASL)
2251 Lightweight Directory Access Protocol (v3)
2252 Lightweight Directory Access Protocol (v3) Attribute Syntax Definitions
2253 Lightweight Directory Access Protocol (v3) UTF-8 String Representation of Distinguished
Names
2254 The String Representation of LDAP Search Filters
2255 The LDAP URL Format
2256 A Summary of the X.500 (96) User Schema for use with LDAPv3
2596 Use of Language Codes in LDAP
2798 Definition of the inetOrgPerson LDAP Object Class

Chapter 22. Setting Up the LDAP Service 543

544 Lotus Domino Administrator 7 Help
Chapter 23. Managing the LDAP Schema
This chapter defines the term LDAP schema and provides information about the Domino LDAP schema
and how to extend it.

LDAP Schema
A directory entry contains information about a particular entity, for example, a person or a group, and is
associated with a distinguished name. An LDAP schema is a set of rules that define what can be stored
as entries in an LDAP directory. Each LDAP directory has a default schema, which organizations can
customize, or ″extend,″ by adding elements to it. The elements of a schema are attributes, syntaxes, and
object classes. LDAP directory servers provide the ability to enforce the schema to ensure that directory
changes made using LDAP operations conform to it.

Attributes
An attribute defines a piece of information that directory entries contain. For example, some common
attributes for entries related to people are cn (common name), telephoneNumber, and userPassword.

An attribute is either mandatory or optional for a particular type of entry. When an attribute is
mandatory and directory administrators use schema-checking to enforce the schema, administrators must
provide a value for the attribute when they add or modify the entries using LDAP operations. An
attribute can be defined to allow multiple values.

Multiple types of directory entries can use the same attribute.

Object classes
An object class defines a set of attributes for a type of directory entry. Two or more object classes in an
object class hierarchy define the attributes for a type of entry. An object class inherits attributes from all
object classes above it in the hierarchy and then adds attributes of its own; for example:

Object class 1: adds attribute A

Object class 2: inherits A; adds B, C, D

Object class 3: inherits A, B, C, D; adds E, F

There are three types of object classes: abstract, structural, and auxiliary.

Abstract object classes

An abstract object class defines an attribute or set of attributes that all object classes in an object class
structure inherit. Every object class structure must have an abstract object class as the top-level object
class. A default LDAP schema typically uses the abstract object class top. top includes only one attribute,
objectClass, which defines an object class for each entry in the directory.

Structural object classes

A structural object class defines a type of entry in an LDAP directory. Examples of standard LDAP
structural object classes are person, organizationalPerson, and inetOrgPerson. An object class structure must
include at least one structural object class.

545
Auxiliary object classes
An auxiliary object class adds attributes to another object class, usually a structural object class. An
auxiliary object class is useful for defining a set of attributes used by multiple object classes. An auxiliary
object class usually inherits from the abstract object class top. Object classes can’t inherit attributes from
an auxiliary object class. Instead, you must add an auxiliary object class to each object class that uses it.

Syntaxes
A syntax defines the data format in which an attribute value is stored. Directory String, Integer, and JPEG
are examples of standard LDAP syntaxes.

The Domino LDAP schema

The default Domino LDAP schema includes:
v Domino-specific schema elements defined by the default forms in the Domino Directory
v All LDAP-standard schema elements defined in RFCs 2252, 2256, 2798, 2247, and 2739. The LDAP
service uses the file LSCHEMA.LDIF to build these elements in the default schema.

You can extend the schema to add custom schema elements that your organization needs.

To see detailed information about the Domino LDAP schema, open the Domino LDAP Schema database
(SCHEMA.NSF) on any server that runs the LDAP service.

For information relating to upgrading the LDAP schema, see the Upgrade Guide.

How an LDAP object class relates to a Domino form

An LDAP object class is similar to a form in the Domino Directory, in that each defines a set of
information for a directory entry. A Domino-specific object class -- whose name usually begins with
domino -- always maps to a form in the Domino Directory. For example, the object class dominoPerson
maps to the form Person, and the object class dominoGroup maps to the form Group.

An object class that is not specific to Domino, for example a standard LDAP object class defined in the
LSCHEMA.LDIF file, maps to a form only if you create such a form. For example, the object class
residentialPerson is part of the default Domino LDAP schema, but it has no corresponding form in the
Domino Directory. Therefore by default you can use only LDAP operations to add, search, and modify,
residentialPerson entries. To give Notes and Web users access to these entries, you must you create a
corresponding form following a specific procedure. If you create a corresponding form, residentialPerson
entries are created as documents that are visible to Notes and Web users.

For instructions on creating a form in the Domino Directory that corresponds to an object class, see the
appendix ″Customizing the Domino Directory.″

Domino forms that are not defined as object classes in the default Domino LDAP
schema
The following forms in the Domino Directory are not defined as object classes in the schema because
their designs do not include a field that defines a distinguished name:
v CrossCertificate
v Location
v Server\Configuration Settings
v Server\Connection
v Server\Holiday
v Server\Domain
v Server\User Setup Profile

546 Lotus Domino Administrator 7 Help

How an LDAP attribute relates to a Domino field
An LDAP attribute is similar to a field in the Domino Directory in that each define a piece of information
about a directory entry. An LDAP attribute defined for a Domino-specific object class always maps to a
field in a form in the Domino Directory. The name of the attribute and the name of the field may not be
identical. This difference occurs when a preexisting field in Domino has a purpose similar to an
LDAP-standard attribute. For example, the LDAP attribute uid maps to the Domino field ShortName.

By default, an attribute that is not Domino-specific does not map to a visible field in the Domino
Directory.

LDAP-standard attributes on Domino forms

If a Domino object class inherits from an LDAP-standard object class, the fields that represent the
inherited attributes may be hidden in the Domino Directory document. For example, the dominoPerson
object class inherits the attribute employeeNumber from the LDAP-standard object class inetOrgPerson.
However, the field employee number is only apparent when you select a Person document, choose Edit -
Properties, and select the second tab in the Document properties box to see a listing of all the fields. You
can add the field to the $PersonInheritableSchema subform to make the field visible.

How an LDAP syntax relates to a field type

There are some syntaxes in the default Domino LDAP schema that map to Domino field types. For
example, the LDAP syntax Integer maps to the field type Number. To see whether a syntax maps to a
Domino field, find the document for the syntax in the Schema database (SCHEMA.NSF), and compare
the LDAP name field to the Notes mapping field.

Object class hierarchy for dominoPerson object class

The dominoPerson object class, which maps to the Person form in the Domino Directory, is part of this
object class hierarchy:

top

person

organizationalPerson

inetOrgPerson

dominoPerson

Object class hierarchy for dominoGroup object class

The dominoGroup object class, which maps to the Group form in the Domino Directory, is part of this
object class hierarchy:

top

groupOfNames

dominoGroup

dominoUNID operational attribute

The Domino 7 LDAP Service supports Universal Notes IDs (UNID) through 32-character values of the
dominoUNID operational attribute. Designed for use with advanced LDAP applications, such as IBM
Workplace, it allows them to uniquely identify documents in the Domino Directory even when the
directory object’s FullName/ListName (LDAP DN), ShortName (LDAP uid), or other normally
identifying field values change.

Chapter 23. Managing the LDAP Schema 547

If you are using IBM Workplace with Domino, you can use the dominoUNID attribute for mapping
Workplace member entries in Websphere Member Manager (via its extId attribute) to LDAP person
records.

While this attribute is fully available to customers deploying a new Domino 7 Domino Directory, those
using existing Domino Directories will need to do the following to make dominoUNID fully available:
1. Reload the LDAP schema by using the tell ldap reloadschema command.
2. In the domain Configuration Settings document of the primary Domino Directory, click ″Select
Attribute Types″ next to the setting ″Choose fields that anonymous users can query via LDAP″. The
LDAP Attribute Type Selection dialog box appears. From here, you can either:
v add the dominoUNID attribute automatically by clicking Use Default Values. All default attributes
for Anonymous users will be selected.
or
v manually add dominoUNID by choosing the wildcard class (*) in the Object Classes drop-down list.
This option is recommended if you have customized your attribute list for Anonymous.
For information on the tell ldap reloadschema command, see the chapter ″Server Commands.″
For more information on customizing anonymous LDAP search access information, see the chapter
″Setting up the LDAP Service.″

The schema daemon

When the LDAP service runs on a server, it spawns a schema daemon that runs at regular intervals. The
schema daemon running on the administration server for the Domino Directory implements schema
changes and propagates the changes to other (subordinate) servers in the domain that run the LDAP
service. The schema daemon running on each subordinate server updates its LDAP service with the
schema changes propagated from the administration server. The Domino LDAP Schema database
(SCHEMA.NSF) is the vehicle for propagating the schema changes.

The schema daemon ensures that each LDAP service running in the domain uses a schema that is
up-to-date and consistent across servers. The schema daemon runs when the LDAP service first starts,
and then after that at 15-minute intervals by default.

For information on NOTES.INI settings that are available to control the schema daemon, see the topic
″NOTES.INI settings related to the schema daemon″ later in this chapter.

The LDAP service runs by default on the administration server for the Domino Directory. The schema
daemon spawned by the LDAP service on the administration server does the following to maintain the
schema for the domain:
1. Creates the Domino LDAP Schema database (SCHEMA.NSF) from the SCHEMA.NTF template (the
first time the schema daemon runs in this release, and subsequently if the Schema database is ever
deleted).

Note: Be sure the administration server for the Domino Directory is the first server in the domain you
upgrade to Lotus Domino 6 so that it is the server that first creates the Schema database.
2. Builds the schema for the domain into memory by loading information from the following files:
v LDAP-standard schema elements from the local LSCHEMA.LDIF file -- these elements do not
change.
v Forms and fields from the primary Domino Directory, which supply the Domino-specific schema
elements, and optionally, extended schema elements added as forms and fields. For performance
reasons, this step is done only once every 24 hours by default. You can use the NOTES.INI setting
Schema_Daemon_Reloadtime to change the default interval.
v Schema elements from the Extended Documents view of its local Domino LDAP Schema database.

548 Lotus Domino Administrator 7 Help

 Note: If the schema daemon finds the same schema element defined in more than one of these
files, it uses this order of precedence to determine which definition to use: 1) LSCHEMA.LDIF, 2)
Domino Directory, 3) Schema database.
3. The first time it runs, publishes the schema in memory to disk in the All Schema Documents view of
the Schema database. Subsequently, it compares its in-memory schema to the on-disk schema
published in the Schema database, and if the two schemas are different, the daemon updates the All
Schema Documents view of the Schema database with the more recent in-memory schema. For
performance reasons, this step is done only once every 24 hours by default. You can use the
NOTES.INI setting Schema_Daemon_Resynctime to change the default interval.
4. Replicates its local Schema database with replicas on subordinate servers that run the LDAP service if
the contents of the two replicas are different. This replication occurs without the use of Connection
documents immediately after step 3 is complete. If a subordinate server does not yet have a local
replica of the Schema database, the schema daemon on the administration server creates one on the
subordinate server.

The schema daemon on each subordinate server in the domain that run the LDAP service does the
following:
1. Replicates information from the replica of the Schema database on the administration server for the
Domino Directory to its local Schema database if the two replicas are different.
If the subordinate server doesn’t yet have a local replica of the Schema database and the
administration server is running, it pulls a replica from the administration server. If the administration
server is unavailable, the subordinate server uses a local LSCHEMA.LDIF file and Domino Directory
forms to determine the schema until the administration server is available.
2. The first time it runs, loads the schema published on disk in the All Schema Documents view of its
local Schema database into memory. Subsequently, it compares its in-memory schema to the on-disk
schema published in its local Schema database. If the two are different, updates its in-memory schema
with the more recent schema published in the local Schema database.

Tip: Use the server command Tell LDAP ReloadSchema to manually initiate the steps described above.

Domino LDAP Schema database

The schema daemon spawned by the LDAP service running on the administration server for the Domino
Directory creates the Domino LDAP Schema database (SCHEMA.NSF). Subordinate servers within the

Chapter 23. Managing the LDAP Schema 549

domain that run the LDAP service automatically get a replica of this database. The Schema database is
the vehicle used to propagate schema changes to all the servers in the domain that run the LDAP service.

Administrators use the Schema database to learn about the schema and to extend the schema.
Administrators can access the Schema database from a Lotus Notes 7, Lotus Notes 6, or Web browser
client, and can use the Schema database to extend the schema from a Lotus Notes 6 or Web browser
client.

For more upgrade information, see the Upgrade Guide.

Views in the Schema database

The Domino LDAP Schema database (SCHEMA.NSF) includes these views:
v All Schema Documents
v Extended Documents
v Pending Documents
v Draft Documents

Each of these views included sub-views for object classes, attributes, and syntaxes.

All Schema Documents view: The All Schema Documents view contains a document for each element
defined in the schema. It also contains documents for draft schema elements awaiting administrator
approval and pending schema elements awaiting processing by the schema daemon on the
administration server for the Domino Directory.

Extended Documents view: The Extended Documents view shows a document for each extended object
class, attribute, and syntax added using the Schema database and incorporated into the schema by the
schema daemon running on the administration server for the Domino Directory.

The Extended Documents view does not show schema extensions made by adding forms and fields to the
Domino Directory. Only the All Schema Documents view shows new schema elements defined by new
Domino Directory forms and fields.

Pending Documents view: The Pending Documents view shows a document for each object class,
attribute, and syntax that an administrator has added using the Schema database and approved that is
awaiting processing by the schema daemon on the administration server for the Domino Directory.

In the All Schema Documents view, a green check mark icon indicates a pending schema element.

Draft Documents view: The Draft Documents view shows a document for each new object class,
attribute, and syntax that an administrator has added using the Schema database, but has not yet
approved.

In the All Schema Documents view, an hourglass icon indicates a draft schema element.

Using the Schema database to view the schema

The Domino LDAP Schema database (SCHEMA.NSF) contains information about each attribute, syntax,
and object class defined in the schema. You can also retrieve the entire schema by doing an LDAP search
of the schema entry; however the Schema database provides schema information in a easy-to-read format.

Viewing information about an attribute defined in the schema:

1. Open the Schema database (SCHEMA.NSF) on any server in the domain that runs the LDAP service.
2. Select the All Schema Documents - LDAP Attribute Types view.
3. Open a document to view information about a specific attribute. Any document without an icon next
to it in the view is an attribute defined in the schema.

550 Lotus Domino Administrator 7 Help

 For information about the fields in Attribute documents, see the topic ″Using the Schema database to
add an attribute to the schema″ later in this chapter.

Viewing information about an object class defined in the schema:

1. Open the Schema database (SCHEMA.NSF) on any server in the domain that runs the LDAP service.
2. Select the All Schema Documents - LDAP Object Classes view.
3. Open a document to view information about a specific object class. Any document without an icon
next to it in the view is an object class defined in the schema.

Tip: To determine which object classes use a particular attribute, do a full text search for the attribute
from the All Schema Documents - LDAP Object Classes view.

For information about the fields in Object Class documents, see the topic ″Using the Schema database to
add an object class to the schema″ later in this chapter.

Viewing information about a syntax defined in the schema:

1. Open the Schema database (SCHEMA.NSF) on any server in the domain that runs the LDAP service.
2. Select the All Schema Documents - LDAP Syntaxes view.
3. Open a document to view information about a specific syntax. Any document without an icon next to
it in the view is a syntax defined in the schema.
For information about the fields in Syntax documents, see the topic ″Using the Schema database to
add a syntax to the schema″ later in this chapter.

Methods for extending the schema

Extending the schema refers to adding elements to the schema, usually object classes and attributes. The
default schema comes with many object classes and attributes that are ready to be used for entries. Before
you extend the schema, see if there are existing elements in the default schema that you might use
instead of extending the schema. For example, if you need an additional attribute for the dominoPerson
object class, evaluate if you can use an attribute already defined for dominoPerson.

If the default schema does not contain the attributes you need, add custom elements.

There are two methods available for extending the schema: using the Domino LDAP Schema database
(SCHEMA.NSF) or using the Domino Directory to add forms and fields.

Note: Modifying the file LSCHEMA.LDIF that is provided with Domino is not supported as a method
for extending the schema. This file is used to define the LDAP-standard object classes in the default
Domino LDAP schema.

Schema database
You can use the Domino LDAP Schema database (SCHEMA.NSF) to extend the schema. The Schema
database:
v Provides an easy-to-use interface for extending the schema
v Has built-in error checking that ensures valid schema elements
v Supports the creation of draft schema elements, which you can consider and modify before approving
them as part of the schema
v Simplifies the creation of object class hierarchies
v Allows you to assign object identifiers (OIDs) associated with your organization to the elements you
add
v Allows you to define LDAP characteristics for attributes, such as matching rules, and to define any
standard LDAP syntax for an attribute.

Chapter 23. Managing the LDAP Schema 551

An object class that you add to the schema using the Schema database does not map to a form in the
Domino Directory. Therefore, to add entries defined by these schema elements to the directory,
administrators must use LDAP operations, and the entries are accessible only via LDAP, and are not
visible to Notes and Web users.

Domino Directory
You can extend the schema by adding forms, subforms, and fields to the Domino Directory. This method
allows Notes and Web users to create and view entries that use the new schema elements as documents,
while also enabling LDAP user access to the entries. This method is more time consuming than using the
Schema database, and must be done carefully to avoid mistakes in schema definition.

For information on using the Domino Directory to extend the schema, see the appendix ″Customizing the
Domino Directory.″

Guidelines for extending the schema

Regardless of the method you use to extend the schema, follow these guidelines:
1. See if there is an object class, attribute, or syntax defined in the default schema you can use rather
than adding a new one.
2. Don’t define multiple attributes to store the same type of information. Instead add one attribute, and
define the attribute in an auxiliary object class that multiple structural object classes use.
3. Don’t edit existing schema elements. For example, don’t remove attributes from, or add attributes to,
an existing object class. You can delete a custom object class that is no longer needed as long as you
are sure no one is using it.
4. When possible, create object classes that define attributes as optional rather than mandatory, so the
schema is flexible.
5. After you extend the schema, configure LDAP access to the new schema elements. For example, if
you want anonymous LDAP users to access a new attribute, make sure you enable the attribute for
anonymous access.
For more information on controlling LDAP access, see the chapter ″Setting Up the LDAP Service.″

Extending an existing object class

How you add attributes to an object class in the default schema depends on whether or not the attributes
should apply to another object class as well. If the attributes apply to only one object class, add the
attributes to a new structural object class and have the new object class inherit from the object class you
want to extend. For example, to extend object class A which is part of the default schema, add attributes
to a new structural object class, B, and define object class B to inherit from A.

If the attributes will apply to more than one structural object class, add them to a new auxiliary object
class and then add the auxiliary object class to each structural object class that will use the attributes.

For example, suppose you want to add the same attributes to object classes A and B, both part of the
default schema. Add the attributes to a new auxiliary object class C, then add C to A and B.

Note: To add a new type of entry to the directory, typically you create a new structural object class that
inherits from top.

Registering an object identifier (OID) for your organization

When you use the Domino LDAP Schema database to add a new element to the schema, you must
specify an OID for the element. To do this, your organization should have a registered OID prefix which
is used as the root of all the OIDs you assign to your schema elements. An OID is a unique series of
numbers assigned to a schema element. For example, in the Domino schema, the dominoPerson object
class has the following OID assignment:

2.16.840.1.113678.2.2.2.1.1.

552 Lotus Domino Administrator 7 Help

A registered OID prefix begins with one of the following numbers:
v 0 if assigned by the International Telecommunication Union (ITU)
v 1 if assigned by the International Organization for Standardization (ISO)
v 2 if assigned jointly by the ITU and ISO.

This number is then followed by a series of numbers that uniquely identify an organization.

When you create a schema element, assign it the OID prefix registered for your organization, followed by
an additional number that uniquely identifies the element within the schema.

For more information on OID’s or to request a prefix for your organization, go to the IANA (Internet
Assigned Numbers Authority) Web site: http://www.iana.org.

Extending the schema using the Schema database

You can use the Domino LDAP Schema database to extend the schema by:
v Adding attributes to the schema
v Adding object classes to the schema
v Adding syntaxes to the schema

When you use the Schema database to create a new schema element, you first create a draft document for
the element. You approve the draft document when you are ready, and the document then moves from
the Draft Documents view to the Pending Documents view, where it awaits processing by the Schema
daemon on the administration server for the Domino Directory. The Schema daemon on the
administration server incorporate the changes into the schema and publishes them in the Schema
database. The Schema database then replicates to subordinate servers in the domain that run the LDAP
service.

To use the Schema database to extend the schema, you must use one of the following clients:
v Lotus Notes 7
v Lotus Domino Adminstrator 7
v Netscape Navigator with Java applets and Java scripts enabled
v Microsoft Internet Explorer with Java applets and Java scripts enabled

Using the Schema database to add an attribute to the schema

You can use the Domino LDAP Schema database (SCHEMA.NSF) to add an attribute to the schema:
1. Make sure you have Manager access to the Schema database.
2. Open the Schema database (SCHEMA.NSF) on any server in the domain that runs the LDAP service.
3. Select the All Schema Documents view, then click New Document - Add Attribute Type.
4. Complete these fields on the Basics tab:
For more information, see RFCs 2252 and 2256.

Field Action
LDAP name Enter a name for the attribute. The name can contain only ASCII characters and
hyphens. Do not include a space in the name.
OID Enter the object identifier.
Syntax name Select a syntax defined in the schema for the new attribute, then click OK. The
Syntax type field automatically displays the OID for the selected syntax.
Description (Optional) Enter a description for the attribute.
Equality match (Optional) Select a matching rule to apply when the equality operator is used to
search for this attribute.

Chapter 23. Managing the LDAP Schema 553

Field Action
Ordering match (Optional) Select a matching rule to apply when an ordering operator is used to
search for this attribute.
Substrings match (Optional) Select a matching rule to apply when a substring operator is used to
search for this attribute.
Single valued Choose one:
v Yes to allow more than one value for the attribute (default)
v No to allow only one value
Collective Choose one:
v Yes to allow the values for this attribute to be shared
v No to prevent values from being shared (default)
No user modification Choose one:
v Yes to prevent users from modifying the values
v No to allow users to modify values (default)

5. Click Save & Close. A draft document for the new attribute appears in the Draft Documents - Draft
Attribute Types view.
6. Complete the procedure ″Approving draft schema documents in the Schema database.″

Using the Schema database to add an object class to the schema

You can use the Domino LDAP Schema database (SCHEMA.NSF) to add an object class to the schema.
1. Make sure you have Manager access to the Schema database.
2. Open the Schema database on any server in the domain that runs the LDAP service.
3. Select the All Schema Documents view, then click New Document - Add Object Class.
4. Complete these fields on the Basics tab:

Field Action
LDAP name Enter a name for the object class.
OID Enter the object identifier.
Object Class Type Select the type of object class.
Superior Object Class (Optional) Select the object class that is immediately superior to this one in the
object class structure.
Auxiliary Object Classes (Optional) If this is a structural object class, select each auxiliary object class to use
with this object class.
Description (Optional) Enter a description for the object class.
Mandatory attributes Select the attributes that are required to have values.

You can’t remove mandatory attributes displayed that are inherited from a
superior object class.
Optional Attributes Select any attributes that may, but are not required to, have values.

You can’t remove optional attributes displayed that are inherited from a superior
object class.

5. Click Save & Close. A draft document for the new object class appears in the Draft Documents - Draft
Object Classes view.
6. Compete the procedure ″Approving draft schema documents in the Schema database.″

554 Lotus Domino Administrator 7 Help

Using the Schema database to add a syntax to the schema
You can use the Domino LDAP Schema database (SCHEMA.NSF) to add a syntax to the schema:
1. Make sure you have Manager access to the Schema database.
2. Open the Schema database on any server in the domain that runs the LDAP service.
3. Select the All Schema Documents view, then click New Document - Add Syntax.
4. Complete these fields on the Basics tab:
For more information on syntaxes, see RFC 2252.

Field Action
LDAP name Enter a name for the syntax type.
OID Enter the object identifier.

5. Click Save & Close:

6. Complete the procedure ″Approving draft schema documents in the Schema database.″

Approving draft schema elements in the Schema database

When you use the Domino LDAP Schema database (SCHEMA.NSF) to add a schema element, the Draft
Documents and All Schema Documents views display a draft document for the element. Follow these
steps to approve draft schema elements to move them to the Pending Documents view, so the schema
daemon on the administration server for the Domino Directory can incorporate them into the schema:
1. Make sure you have Manager access to the Schema database.
2. Open the Schema database on any server in the domain that runs the LDAP service.
3. Look at the Draft Documents views to see a draft document for each schema element added but not
yet approved.
4. Review the draft documents, and make any final changes.
5. When you are ready to approve the changes, do one of the following:
v To approve only selected draft documents, select a specific Draft Documents view, select the draft
documents you are ready to approve, and click Approve - Approve Selected Drafts.
v To approve all draft documents, select any Draft Documents view, and click Approve - Approve All
Drafts.

The documents you approve move to the Pending Documents views. If you used a replica of the Schema
database on a subordinate server to approve the schema documents, the documents in the Pending
Documents views must replicate to the administration server for the Domino Directory. When the schema
daemon next runs on the administration server it verifies the elements in the Pending Documents views
and then publishes them in the Schema database. The updated Schema database then replicates to
subordinate servers in the domain that run the LDAP service.

Checking the status of approved schema elements in the Schema database

Every 15 minutes (by default) the schema daemon on the administration server for the Domino Directory
looks for approved schema changes in the Pending Documents views of the Domino LDAP Schema
database. To check the status of pending schema changes in the Schema database:
1. Open the Schema database (SCHEMA.NSF) on the administration server for the Domino Directory.
2. Open the Extended Documents view -- any documents here represent schema elements that have been
incorporated into the schema.
3. Open the Pending Documents view -- any documents here represent schema elements the schema
daemon has not yet incorporated into the schema.

Tip: Use the Tell LDAP Reloadschema server command on the administration server for the Domino
Directory to manually initiate processing of the schema changes in the Pending Documents view rather
than wait for the schema daemon to run on schedule.

Chapter 23. Managing the LDAP Schema 555

Deleting schema elements from the Schema database
If you use the Domino LDAP Schema database (SCHEMA.NSF) to add an element to the schema, you
can delete that element if it is no longer needed. After you delete an element, entries already in the
directory with values for the deleted element remain, but LDAP add and modify operations can no
longer specify the deleted element if schema-checking is enabled.

Note that deleting an object class does not delete the attributes defined for the object class. If you want to
delete the attributes, you must do so separately.

To delete an attribute, object class, or syntax shown in the Extended Documents, Draft Documents, or
Pending Documents view of the Schema database:
1. Make sure you have Manager access in the database ACL with the ″Delete documents″ privilege.
2. Open the Schema database on the administration server for the Domino Directory.
3. Open the Extended Documents, Draft Documents, or Pending Documents view that contains the
schema element to be deleted.
4. Delete the schema element.
5. If you deleted a document from the Extended Documents view, on the administration server for the
Domino Directory restart the LDAP task, so the schema daemon loads the schema changes into
memory:
Restart Task LDAP
6. If you deleted a document from the Extended Documents view and the LDAP service also runs on a
subordinate server in the domain, after the Schema database changes replicate to the subordinate
server, restart the LDAP task on the subordinate server:
Restart Task LDAP

Schema-checking
When schema-checking is enabled the LDAP service carries out LDAP and and modify operations only if
the operations conform to the schema. Schema checking is enabled by default and it’s best to keep this
default behavior if you allow write access to a directory so you have better control over the contents of a
directory. When schema-checking is enabled the LDAP service does the following to check that LDAP
add and modify operations comply with the schema:
v Verifies that each object class specified in an LDAP add operation is defined in the schema.
v Verifies that attributes specified in LDAP add and modify operations are associated with valid object
classes for the entry.
v Verifies that during an LDAP add operation all mandatory attribute(s) required by the object classes for
the entry are provided.

If any of these checks fail, the LDAP service aborts the operation and returns the message, ″Object Class
Violation.″

Schema-checking is done only for LDAP add and modify operations and not when Notes and Web users
add and change documents in a Domino Directory.

Note: Whether or not you enforce schema-checking, the LDAP service requires that each directory tree
component specified in a distinguished name during an add or modify DN operation corresponds to an
entry in the directory. For example, to add an entry with the distinguished name ″uid=JDoe, o=Acme,″
there must be an entry in the directory for o=Acme.

Schema-checking and directory assistance

The schema defined for the domain of the server running the LDAP service is the basis for
schema-checking. If the LDAP service uses directory assistance to serve a secondary Domino directory or

556 Lotus Domino Administrator 7 Help

Extended Directory Catalog for which LDAP write operations are enabled, the LDAP service uses the
schema defined for its own domain to determine whether or not to allow write operations in the
directory served through directory assistance.

Enabling or disabling schema-checking

To disable or enable schema-checking for all the servers in the domain that run the LDAP service:
1. From the Domino Administrator, open a server that runs the LDAP service, or a server in the same
domain as one that runs the LDAP service.
2. Click the Configuration tab.
3. In the left pane, expand Directory, then LDAP, and then select Settings.
4. Do one of the following:
If you see the prompt ″Unable to locate a Server Configuration document for this domain. Would you
like to create one now?″ click Yes, then click the LDAP tab on the document.
If you do not see the prompt, click ″Edit LDAP Settings.″
5. In the ″Enforce schema?″ field, choose one:
v Yes, to enable schema-checking (default)
v No, to prevent schema-checking
6. Click Save & Close.

Searching the root DSE and schema entry

The LDAP service supports schema-publishing, which means the directory includes a schema entry that
you can use to retrieve the directory schema. Use the ldapsearch utility provided with Notes and Domino
or use another LDAP V3-compliant LDAP search tool to search the root directory server entry (DSE) to
determine the name of this schema entry and to retrieve other information about the Domino LDAP
directory -- for example, to retrieve the LDAP versions, extensions, and controls supported.

For information on using the ldapsearch utility to search an LDAP directory, see the chapter ″Using the
ldapsearch Utility.″

When you search the root DSE or the schema entry you can specify whether to return values for
operational attributes. An operational attribute is an attribute that is used for directory administration.

Searching the root DSE

To search the root DSE, use one of the following ldapsearch commands:

To return the values of all attributes, specify one of the following:

ldapsearch -h hostname -b "" -s base "(objectclass=*)"
ldapsearch -h hostname -b "" -s base "(objectclass=*)" * +

To return only the values of non-operational attributes, specify:

ldapsearch -h hostname -b "" -s base "(objectclass=*)" *

To return only the values of operational attributes, specify:

ldapsearch -h hostname -b "" -s base "(objectclass=*)" +

Searching the schema entry

To search the schema entry to retrieve the directory schema, use one of the following ldapsearch
commands.

To return only the values of non-operational attributes, specify:

ldapsearch -h hostname -b "cn=schema" -s base "(objectclass=subschema)" *

Chapter 23. Managing the LDAP Schema 557

To return only the values of operational attributes, specify:
ldapsearch -h hostname -b "cn=schema" -s base "(objectclass=subschema)" +

To return the values of all attributes, specify:

ldapsearch -h hostname -b "cn=schema" -s base "(objectclass=subschema)" * +

The easiest way to see the schema is to open the All Schema Documents views in the Domino LDAP
Schema database (SCHEMA.NSF).

558 Lotus Domino Administrator 7 Help

Chapter 24. Using the ldapsearch Utility
This chapter describes how to use the ldapsearch utility to search an LDAP directory.

ldapsearch Utility
Domino and Notes provide a command-line search utility, LDAPSEARCH.EXE, that you use to search
entries in any LDAP directory. ldapsearch connects to a directory server and returns results that match
search criteria you specify.

ldapsearch is available on Domino server and Notes client platforms.

Note: To use this tool, the NOTES.INI file must be included in your system’s path statement.

To use ldapsearch, enter the following command from the Domino or Notes program directory:
ldapsearch parameters searchfilter attributes

Where:
v parameters are case-sensitive command-line parameters.
v searchfilter is a required search filter that specifies the attributes for which to search.
v attributes are the attributes to return. Separate attributes with spaces. If you don’t specify one or more
attributes to return, ldapsearch returns all attributes from entries that match the search filter.

You do not have to use ldapsearch from a machine that runs the Domino LDAP service.

Note: If you have a local condensed Directory Catalog that is encrypted, to run ldapsearch from the
Notes program directory, you must specify the password associated with the Notes ID used to do the
encryption.

Table of ldapsearch parameters

The following table describes the case-sensitive parameters you can use with ldapsearch.

Parameter Use to
-? Print help on using ldapsearch.
-a deref Specify alias de-referencing. Enter never, always, search, or find. Never is the default if
you don’t use this parameter.
-A Retrieve only attribute names, not the values for the attributes.
-b base dn Specify a distinguished name to use as the starting point for beginning the search. Use
quotation marks to specify the value -- for example: ″ou=West,o=Acme,c=US″

You must use this parameter if the server you’re searching requires you to specify a search
base. Otherwise, it is optional.

Optionally use -s along with -b to determine the scope of the search. Without -s, -b
searches the entry specified as the starting point and all descendants of the entry.
-B Allow printing of non-ASCII values

559
Parameter Use to
-D bind dn Specify a distinguished name that the server uses to authenticate you. The name must
correspond to an entry in the directory and must have the necessary access to search the
directory.

Specify the name in quotation marks -- for example: ″cn=Directory

Manager,o=Acme,c=US″

If you don’t use this parameter, the connection to the server occurs anonymously. You
must use -D if the server doesn’t allow anonymous connections.

Along with -D, you must use the -w parameter to specify a password associated with the
distinguished name.
-f file Specify a file that contains search filters to use -- for example, -f filters. Place each search
filter on a separate line. ldapsearch performs one search for each line. Optionally specify a
filter pattern. For example, specify -f filters ″cn=%s″ and enter a common name value on
each line in the file.
-F sep Print sep rather than equal sign (=) between attribute names and values. Use this
parameter, for example, if a tool that reads the ldapsearch output expects a different
separator.
-h host name Specify the host name of the server to which you’re connecting -- for example, -h
server.acme.com.
-l timelimit Specify a time limit (in seconds) for the search to complete. If you do not specify this
parameter or if you specify a limit of 0, searches can take an unlimited amount of time.
ldapsearch never waits longer than a search time limit set on the server, however.
-L Specify that the output is in LDIF format. LDIF format uses a colon (:) as the attribute
delineator rather than an equal sign (=). LDIF is useful for adding or modifying many
directory entries at once. For example, you can import the contents of the output into an
LDAP-compliant directory.
-M Manage referral objects as normal entries so that ldapsearch returns attributes for the
referral entries themselves, rather than for the entries referred to.
-n Show how a search would be performed, but do not actually perform the search.
-p port Specify the port that the server uses. If you don’t use this parameter, ldapsearch uses port
389.
-R Do not automatically follow search references returned by the server.
-s scope Specify the scope of the search when you use the -b parameter:
v base -- to search only the entry specified with the -b parameter
v onelevel -- to search only the immediate children of the entry specified with the -b
parameter but not the entry itself
v subtree -- to search the entry specified with the -b parameter and all of its descendants.
This is the default behavior when you use -b without -s.

The order in which you specify -b and -s is unimportant.

-S attribute Sort the results by a specified attribute.
-z sizelimit Specify the maximum number of entries to return. If you don’t specify this parameter or if
you specify a limit of 0, an unlimited number of entries are returned. ldapsearch never
returns more entries than the server allows, however.
-u Specify that ldapsearch return distinguished names in a user-friendly format.
-v Specify that ldapsearch run in verbose mode.
-w password Specify the password associated with a distinguished name used with the -D parameter.
-x Use with -S to specify that that LDAP server sorts the results before returning them. If you
use -S without -x, ldapsearch sorts the results.

560 Lotus Domino Administrator 7 Help

Using search filters with ldapsearch
You must use a search filter to specify the attributes for which to search. The syntax for a search filter is:
"<attribute> <operator> <value>"

For example, this search filter finds all entries containing Smith as the value for the sn (surname)
attribute:
"sn=Smith"

You can specify any attribute stored in a directory in a search filter. The following are common attributes
used to search for entries about people:
v cn -- a person’s common name
v sn -- a person’s last name
v telephonenumber -- a person’s telephone number
v l -- a person’s geographic location

You can specify search filters on the ldapsearch command line, or you can specify them in a file and use
the ldapsearch parameter -f to refer to the file. If you use a file, specify each search filter on a separate
line.

Note you can include language tags in a search filter if the LDAP directory, such as the Domino
Directory, supports them. For example:
"givenName;lang-fr=Etienne"

Multiple search filters with Boolean operators

You can use multiple search filters and Boolean operators. Use this syntax:
"(operator(filter)(filter))"

For example, use this search filter to find entries with the surname Browning and the location Dallas.
"(&(sn=Browning)(l=Dallas))"

You can nest Boolean operators. For example, use this search filter to find entries with the surname
caneel or givenname alfred in the mail domain MDN:
"(&(maildomain=MDN)(|(sn=caneel)(givenname=alfred)))"

Table of operators used in ldapsearch search filters

The following table describes the operators you can use in a search filter.

Operator Use to Example

= Find entries that contain an attribute with a value ″cn=John Browning″
equal to a specified value
= <string>*<string> Find entries that contain an attribute with a value ″cn=John*″
equal to a specified substring
″cn=J*Brown″
>= Find entries that contain an attribute with a value ″cn>=D″
that is numerically or alphabetically greater than
or equal to a specified value
<= Find entries that contain an attribute with a value ″roomNumber<=300″
that is numerically or alphabetically less than or
equal to a specified value
=* Find entries that contain a value for a specified ″sn=*″
attribute, regardless of the attribute value.

Chapter 24. Using the ldapsearch Utility 561

Operator Use to
~= Find entries that contain an attribute with a value
approximately equal to a specified value.
& Find entries that meet the criteria specified in all
search filters
| Find entries that meet the criteria specified in at
least one specified search filter
! Find entries that do not meet the criteria specified
in any search filter
Example
″sn~=Brning″ could return
sn=Browning
″(&(cn=John Browning)(l=Dallas))″
″(|(cn=John Browning)(l=Dallas))″
″(!(cn=John Browning)(l=Dallas))″

Using ldapsearch to return operational attributes

You can use the plus sign (+) with ldapsearch to return all the operational attributes for entries.
Operational attributes are attributes used for directory administration, and a directory server only returns
them if you request them.

For example, to return all operational attributes for entries with the common name John Brown specify:
ldapsearch -h host "cn=John Brown" +

You can use the + syntax only with the directory servers that support the syntax, such as the Domino
LDAP service.

To return a specific operational attribute only, specify the attribute.

Examples of using ldapsearch

The following table provides examples of using the ldapsearch utility.

Search Command
All entries on host ldap.acme.com using port 389, and ldapsearch -h ldap.acme.com ″objectClass=*″
return all attributes and values
Same as above, but return only attribute names ldapsearch -A -h ldap.acme.com″ objectClass=*″
All entries on host ldap.acme.com using port 389, return ldapsearch -a always -h ldap.acme.com ″objectClass=*″
all attributes, and de-reference any aliases found
All entries on host ldap.acme.com using port 389, and ldapsearch -h ldap.acme.com ″objectClass=*″ mail cn sn
return attributes=mail, cn, sn, givenname givenname
(cn=Mike*) under base ″ou=West,o=Acme, c=US″ on ldapsearch -b ″ou=West,o=Acme,c=US″ -h ldap.acme.com
host ldap.acme.com using port 389, and return all ″(cn=Mike*)″
attributes and values
One level on host ldap.acme.com using port 389, and ldapsearch -s onelevel -h ldap.acme.com ″objectClass=*″
return all attributes and values
Same as above, but limit scope to base ldapsearch -s base -h ldap.acme.com ″objectClass=*″
All entries on host ldap.acme.com using port 389; return ldapsearch -l 5 -h ldap.acme.com ″objectClass=*″
all attributes and values; do not exceed the time limit of
five seconds
All entries on host ldap.acme.com using port 389; return ldapsearch -z 5 -h ldap.acme.com ″objectClass=*″
all attributes and values; do not exceed the size limit of
five
All entries on host ldap.acme.com using port 389, ldapsearch -h ldap.acme.com -D ″cn=john doe,o=acme″ -w
binding as user ″cn=John Doe,o=Acme″ with a password -L ″objectClass=*″
password of ″password″, and return all attributes and
values in LDIF format

562 Lotus Domino Administrator 7 Help

Search Command
Search the host ldap.acme.com using port 389. All ldapsearch -h ldap.acme.com″ -s base -b ″cn=john
attributes that anonymous are allowed to see are doe,o=acme″ objectClass=*″
returned for the entry ″cn=John Doe,o=Acme″
All entries on a different host, bluepages.ibm.com, ldapsearch -h bluepages.ibm.com -p 391 ″objectClass=*″
which is configured to listen for LDAP requests on port
391
Search bluepages.ibm.com on port 391. Doing a subtree ldapsearch -h bluepages.ibm.com -p 391 -b ″o=ibm″ -l 300
search (default) starting in the organization ″o=ibm″ for -z 1000 ″(&(objectclass=Person)(|(cn=mary
any object type of Person who also has an attribute that smith*)(givenname=mary smith*)(sn=mary
matches any one of the attributes found in the OR filter. smith*)(mail=mary smith*)))″ cn
There is a timeout value of 300 seconds and the
maximum number of entries to return is set to 1000.
And only the DN (default) and CN will be returned.
(This is a common filter for Web applications).
Search bluepages.ibm.com on port 391 starting at the ldapsearch -h bluepages.ibm.com -p 391 -b ″cn=HR
base entry ″cn=HR Group,ou=Asia,o=IBM″ with a time Group,ou=Asia,o=IBM″ -s base -l 300 ″(objectclass=*)″
limit of 300 seconds and asking for all the members of member
this entry. (Another common filter in Web applications
to determine group membership).

Chapter 24. Using the ldapsearch Utility 563

564 Lotus Domino Administrator 7 Help
Chapter 25. Setting Up Directory Assistance
This chapter describes directory assistance and how to set up and monitor directory assistance in your
organization.

Directory Assistance
Directory assistance is a feature a server can use to look up information in a directory other than a local
primary Domino Directory (NAMES.NSF). You can configure directory assistance to use a particular
directory for any of these services:
v Client authentication
v Group lookups for database authorization
v Notes mail addressing
v LDAP service searches or referrals

You can set up directory assistance for a remote LDAP directory or a Domino directory. A remote LDAP
directory can be any remote LDAP-compliant directory, either one on a foreign LDAP directory server or
one on a Domino server that runs the LDAP service.

A Domino directory is a directory created from the PUBNAMES.NTF template and accessed via
NAMELookup calls. Servers can use directory assistance to do lookups in either local or remote replicas
of a Domino directory. A Domino directory configured for directory assistance can be a secondary
Domino Directory, an Extended Directory Catalog, or a primary Domino Directory.

A secondary Domino Directory is any Domino Directory that is not a server’s primary Domino Directory.
A secondary Domino Directory can be a directory associated with another Domino domain. A secondary
Domino Directory can also be a Domino Directory created manually from the PUBNAMES.NTF template
that is not associated with a Domino Domain, used, for example, to store and track Web user
information.

An Extended Directory Catalog contains documents aggregated from multiple secondary Domino
Directories. A server must use directory assistance to look up information in an Extended Directory
Catalog, unless you integrate the Extended Directory Catalog directly into the primary Domino Directory.

For more information, see the topic ″Directory assistance for an Extended Directory Catalog″ later in this
chapter.

The primary Domino Directory is the directory a server searches first that describes the Domino domain
of the server. You can set up directory assistance for a primary Domino Directory, usually to specify
which replicas of primary Domino Directories that servers with Configuration Directories can use.

For more information, see the topic ″Directory assistance for the primary Domino Directory″ later in this
chapter.

How directory assistance works

To configure directory assistance, you create a directory assistance database from the template DA50.NTF,
and replicate it to the servers that will use it. A server must have a local replica of a directory assistance
database to use directory assistance. Then you add the database file name to the ″Directory Assistance
database name″ field in the Domino Directory Server documents of these servers.

565
Note: Directory assistance is not supported in a hosted environment. When working in a hosted
environment, the Directory assistance database name field on the xSP Server document should be blank.

You create a Directory Assistance document in the directory assistance database to describe a particular
directory and how it will be used, and to define how to connect to the directory and to find alternate
replicas for failover. To set up directory assistance for a Domino Directory or an Extended Directory
Catalog , you select ″Notes″ in the ″Domain type″ field in the Directory Assistance document. To set up
directory assistance for a remote LDAP directory, you select ″LDAP″ in the ″Domain type″ field. You use
one Directory Assistance document to configure all the services for a directory and its replicas.

Each server process that provides directory services and detects a local directory assistance database
configuration loads directory information configured in the directory assistance database into an internal
memory table. During server startup and thereafter at five-minute intervals each server process checks for
changes to the directory assistance database configuration and if found, each process reloads its internal
memory table to reflect the changes.

To look up names in a Domino Directory or an Extended Directory Catalog, a server uses NAMELookup
calls. To look up names in a remote LDAP directory, a server uses a gateway feature that translates
NAMELookup calls to LDAP operations, and then translates LDAP operations back to NAMELookup
calls -- a Domino server doesn’t have to run the LDAP service to use a remote LDAP directory for
directory services.

Directory assistance services

Before you set up directory assistance, read about the services directory assistance can provide:
v Client authentication
v Group lookups for database authorization
v Notes mail addressing
v LDAP service searches and referrals

Directory assistance and client authentication

To authenticate a user who is accessing a database on a Domino server via any of the supported Internet
protocols -- Web (HTTP), IMAP, POP3, or LDAP -- a server can look up the users’ credentials in a
directory that is configured in its directory assistance database. Servers can use X.509 certificate security
or name-and-password security for the authentication.

To allow a server to use a directory for Internet client authentication that is configured in a directory
assistance database, do the following in the Directory Assistance document for the directory:
v On the Basics tab, next to ″Make this domain available to,″ select ″Notes clients and Internet
Authentication/Authorization.″
v On the ″Naming Contexts (Rules)″ tab, enable at least one rule that corresponds to the distinguished
names of the users in the directory to be authenticated, and next to ″Trusted for Credentials,″ select
Yes.

For example, if your organization registers Web users in a foreign LDAP directory, when a Web user
attempts to access a database on a Domino Web server, the server can connect to the remote foreign
LDAP directory server to look up the user name and password to do the authentication.

566 Lotus Domino Administrator 7 Help

Note: A server’s primary Domino Directory is always enabled for client authentication. This is true even
if you create a Directory Assistance document for the primary Domino Directory and do not select ″Make
this domain available to: Notes clients and Internet Authentication/Authorization.″ A server’s primary
Domino Directory is always enabled for client authentication. This is true even if you create a Directory
Assistance document for the primary Domino Directory and do not select ″Make this domain available to:
Notes clients and Internet Authentication/Authorization.″

For more information on creating rules that are trusted for credentials, see the topic ″Trusted naming
rules″ later in the chapter.

For information on specifying a domain name for a directory in a Directory Assistance document, see the
topic ″Directory assistance and domain names″ later in the chapter.

Note: You use an Internet Site document or the Ports - Internet Ports tab of the Server document to
control the types of client authentication an Internet protocol server allows.

Names accepted for name-and-password authentication: If a server uses name-and-password security

to authenticate Internet clients, you select the types of names that the server can accept from clients. On
the Security - Internet Access tab of the Server document in the primary Domino Directory, select ″More
name variations with lower security″ or ″Fewer name variations with higher security″ (the default). The
selection applies to name and password authentication using any directory, including the primary
Domino Directory.

Though a server can accept a name other than a distinguished name from a client to search for a user’s
entry in a directory, it is always the user’s distinguished name in the directory entry that the server
compares to trusted rules in the Directory Assistance document to determine whether to authenticate the
client. For example, suppose a user is registered in a directory with the distinguished name cn=alice
browning,o=Acme, but the user configures the name alice browning on the client. During authentication,
the server searches for an entry that contains the name alice browning. When it finds the entry, it can
only authenticate the client if ″cn=alice browning,o=acme″ matches a trusted naming rule for the
directory.

A user’s distinguished name is also used as the basis for access control in Domino, so you should use
users’ distinguished names in database ACLs, in groups used in database ACLs, in access lists in Server
documents, and in Web server File Protection documents.

For more information on name-and-password security, see the chapter ″Setting Up Name-and-Password
and Anonymous Access to Domino Servers.″

Encountering duplicate names during client authentication: If a server finds more than one directory
entry containing the name presented by the client that corresponds to a valid distinguished name for
Chapter 25. Setting Up Directory Assistance 567
authentication, within one directory or across directories, the server authenticates the client using the
entry with the valid password or X.509 certificate. If more than one such entry has a valid password or
X.509 certificate and the same distinguished name, the server authenticates the user using the first
password or X.509 certificate it finds.

Consistent client names and passwords across protocols: If Domino servers authenticate a client over
more than one Internet protocol, for ease of directory administration, create one directory entry for the
client with one name and password that applies to all the protocols. Then set up the client to use the
same name and password for all protocols.

For example, if a client connects to Domino over HTTP for Web browsing and over LDAP for directory
services, create one directory entry for the cllient with a name and password, and set up the client to use
the name and password for both types of connections.

Features available for client authentication using a remote LDAP directory: The following features are
available specifically for client authentication using a remote LDAP directory:
v Configurable search filters to control the search filter used to look up names in the remote LDAP
directory
v LDAP-to-Domino name mapping to enable users to authenticate using Notes distinguished names
rather than LDAP distinguished names.
For more information, see the topics ″Configuring search filters in a Directory Assistance document for
a remote LDAP directory″ and ″Using Notes distinguished names in a remote LDAP directory″ later in
the chapter.

Notes client authentication: By default, when a server authenticates a Notes client it does not use
information in Domino Directory Person documents. However, if you enable the option ″Compare Notes
public keys against those stored in Directory″ on the Basics tab of the server’s Server document, the
server authenticates a Notes user only if the public key presented by the Notes client matches the public
key in the user’s Person document.

If a Notes user who connects to a server to authenticate is registered in a secondary Domino Directory
rather than the server’s primary Domino Directory, and the ″Compare Notes public keys against those
stored in Directory″ option is enabled for the server to which the user connects, you must select the
option ″Make this domain available to: Notes clients and Internet Authentication/Authorization″ on a
Directory Assistance document to allow a server to do the public key comparison. This Directory
Assistance document can be for:
v The secondary Domino Directory in which the Notes user is registered
v An Extended Directory Catalog that aggregates the secondary Domino Directory in which the Notes
user is registered.

Directory assistance and group lookups for database authorization

When a database access control list (ACL) includes a group located in a server’s primary Domino
Directory, the server automatically can look up the members of that group when authorizing a user’s
database access. You can store groups used for database authorization in one directory in addition to the
primary Domino Directory. This one additional directory can be a secondary Domino Directory, an
Extended Directory Catalog, or a remote LDAP directory. Note that if the primary Domino Directory and
the one additional directory both contain a group used for database authorization with the same name, a
server uses the group in the primary Domino Directory.

To use one additional directory for group authorization, do the following in the Directory Assistance
document for the directory:
v On the Basics tab, next to ″Make this domain available to,″ select ″Notes clients and Internet
Authentication/Authorization.″
v On the Basics tab, next to ″Group Authorization,″ choose Yes.

568 Lotus Domino Administrator 7 Help

The following figure illustrates looking up groups used for database authorization in a remote secondary
Domino Directory.

Tip: Enable ″Group Authorization″ for an Extended Directory Catalog effectively enables you to store
groups used for database authorization in multiple secondary Domino Directories, as long as you
aggregate the directories into the directory catalog.

A server verifies a client’s access to a database after the client authentication process is complete. You can
use different directories for client authentication and group authorization. For example, you can use a
remote LDAP directory for client authentication, and an Extended Directory Catalog to look up groups
during database authorization.

Note: When you enable Group Authorization for a remote LDAP directory, you can select a custom
search filter for servers to use for searching the groups.

For more information, see the topic ″Configuring search filters in a Directory Assistance document for a
remote LDAP directory″ later in the chapter.

Nesting groups used for database authorization: When authorizing database access, a server can search
a group that is nested in a group listed in a database ACL, and search a group nested in the nested
group, and so on, as long as all of the groups are located in the same directory.

If you enable ″Group Authorization″ for a secondary Domino Directory or an Extended Directory
Catalog, a server always searches nested groups in the directory. If you enable ″Group Authorization″ for
a remote LDAP directory, use the ″Nested group expansion″ option to control whether a server searches
nested groups. Choose Yes (the default) to search nested groups, or No to prevent nested group searches.
If there are many nested groups, selecting No can improve search performance.

Note that Domino does not apply directory assistance name rules for searches of nested groups.
Sometimes the DN of a group will match the name rules established for a secondary directory, but the dn
of a member of that group - either a user or a nested group - does not. By not applying directory
assistance name rules, this circumvents the problem and enables the search to return a complete nameslist
for any search request.

The restrictions on the location for groups used for database authorization do not apply to groups used
for other purposes. For example, the Router can search groups in any directory configured for directory
assistance, and can search nested groups even when the nested groups are located in different directories
than their parents.

Chapter 25. Setting Up Directory Assistance 569

Directory assistance and Notes mail addressing
You can set up directory assistance on Notes users’ mail servers or directory servers to enable the users
to address mail easily to users in a directory that is not the Domino Directory for their Domino domain.
To enable a directory to be used for Notes mail addressing, on the Basic tab of the Directory Assistance
document for the directory, next to ″Make this domain available to,″ select ″Notes clients and Internet
Authentication/Authorization.

Notes mail addressing using a Domino Directory or Extended Directory Catalog: To enable Notes
users to address mail easily to Notes users registered in a secondary Domino Directory or to users that
have entries aggregated into an Extended Directory Catalog, you can set up directory assistance for the
directory on the users’ mail servers or directory servers. Then, a Notes user can:
v Use the ″Select Addresses″ dialog to browse and select names from the directory, if the ″Mail file
location″ field in the active Location document is set to ″On server.″
v Enter a name of a user or group from the directory and have type-ahead use directory assistance to
find a matching name if the ″Recipient name type-ahead″ field in the user’s active Location document
is set to ″Local then server.″
v Press F9 to resolve the address of a user name from the directory; if the Notes user doesn’t resolve the
address, either the Notes client uses directory assistance to resolve the address when the user sends the
mail or, if the client doesn’t resolve the address, the Router uses directory assistance to resolve the
address.

The Router also uses directory assistance when routing mail.

For more information on Location documents, see Notes 7 Help.

Note that if a Notes user uses a local Mobile Directory Catalog that aggregates secondary Domino
Directories, name and address lookups of users in a secondary Domino Directory can occur locally on the
client without the use of directory assistance. Note that type-ahead addressing never extends to a server
on a Notes client set up to use a Mobile Directory Catalog.

Note: A server can always use a Domino directory in the directory assistance database for Notes mail
addressing if the domain specified for the directory is the same domain as the primary domain for the
server; this is true regardless if you select ″Make this domain available to: Notes clients and Internet
Authentication/Authorization.″

Notes mail addressing using a remote LDAP directory: To enable Notes users to address mail easily to
users registered in a remote LDAP directory, you can set up directory assistance for the directory on the
users’ mail servers or directory servers. Then, a Notes user can press F9 to resolve an address for a name
from the LDAP directory entered in an addressing field of a Notes message. If the user doesn’t resolve
the address, either the Notes client uses directory assistance to resolve the address when the user sends
the mail or, if the client doesn’t resolve the address, the Router uses directory assistance to resolve the
address. A Notes client doesn’t use type-ahead addressing to find names in a remote LDAP directory, and
Notes users can’t use the ″Select Addresses″ dialog box to browse and select names from a remote LDAP
directory.

LDAP accounts compared to directory assistance for Notes mail addressing using a remote LDAP
directory: A Notes client can use an LDAP account in the Personal Address Book to connect directly to a
remote LDAP directory server, without using directory assistance. Using an LDAP account, a Notes user
can search for addresses in a remote LDAP directory using LDAP-style search queries.

Configure directory assistance to use a remote LDAP directory for Notes mail addressing, rather than use
LDAP accounts if there are users with Notes Release 4 clients, since these clients don’t support LDAP
Accounts. You might also use directory assistance rather than LDAP Accounts to avoid having to
maintain the LDAP Accounts, for example, if the remote LDAP directory configuration changes in some
way.

570 Lotus Domino Administrator 7 Help

For more information on creating accounts in the Personal Address Book, see Notes 7 Help.

Choosing a preferred mail format for Notes mail addressing using a remote LDAP directory: If you
set up directory assistance so that Notes users can address mail to users in a remote LDAP directory, use
the ″Preferred mail format″ option on the LDAP tab of the Directory Assistance document for the LDAP
directory to select the format of the mail address for Notes clients to use:
v Keep the default selection, ″Internet Mail Address,″ to use the Internet mail format, for example,
jdoe@acme.com, which is the format used in previous Notes/Domino releases.
v Select ″Notes Mail Address″ to use Notes-style addressing, for example, John Doe/Acme@Acme.

If you select ″Notes Mail Address″ user entries in the remote LDAP directory must have values for the
mailDomain attribute. Typically the ″Notes Mail Address″ option is used only in some cases if the remote
LDAP directory is a Domino Directory.

Directory assistance for the LDAP service

If a Domino server runs the LDAP service, you can:
v Set up directory assistance for a Domino Directory or Extended Directory Catalog so that the LDAP
service uses the directory to process LDAP client operations.
v Set up directory assistance for a remote LDAP directory so that the LDAP service can refer LDAP
clients to the directory when a search is unsuccessful in any Domino Directory or Extended Directory
Catalog.

Processing LDAP operations using a secondary Domino Directory or Extended Directory Catalog: The
LDAP service can use a secondary Domino Directory or an Extended Directory Catalog to process LDAP
client requests if there is a Directory Assistance document for the directory in a directory assistance
database that the LDAP service uses, and ″LDAP Clients″ is selected in the ″Make this domain available
to″ field on the Basics tab of the document. To prevent the LDAP service from using a Domino Directory
or Extended Directory Catalog when processing LDAP client requests, do not select ″LDAP Clients″ in
the Directory Assistance document for the directory. Naming rules configured for the directories affect
which of the directories the LDAP service uses.

You control LDAP client access separately for each directory that the LDAP services uses. For example,
you can allow anonymous LDAP users to access specific attributes in one directory, but not in another.

If the Domino Directory or Extended Directory Catalog is remote, the remote server does not have to run
the LDAP service. To process an LDAP search request using a remote directory, the directory ACL on the
remote server must give the server running the LDAP service Reader access through a ″Server group″ or
″Server″ user type entry if either of the following is true:
v The search request comes from an authenticated LDAP client
v Extended access is enabled on the directory.

Servers typically have this required access through the LocalDomainServers and OtherDomainServers
groups default access in the directory ACL.

The LDAP service does not process write operations to a remote Domino Directory or Extended Directory
Catalog. Instead, it returns the client an LDAP referral to the administration server for the directory, or if
there is no administration server, the server that stores the remote replica specified in the directory
assistance database. This referral occurs regardless if the remote server runs the LDAP service.

For more information on how naming rules for Domino Directories and Extended Directory Catalogs
configured in the directory assistance database affect the LDAP service, see the topic ″Naming rules and
the LDAP service″ later in the chapter. For information on controlling LDAP access to a directory, see the
chapter ″Setting Up the LDAP Service.″

Chapter 25. Setting Up Directory Assistance 571

Note: You can also use directory assistance to prevent the LDAP service from searching its primary
Domino Directory.

For more information, see the topic ″Using directory assistance to prevent the LDAP service from
searching the primary Domino Directory″ later in the chapter.

LDAP service referrals to a remote LDAP directory: If the LDAP service can’t find information for
which an LDAP client is searching in the primary Domino Directory, a condensed Directory Catalog, or a
Domino Directory or Extended Directory Catalog configured in a directory assistance database, it can
refer the client to a remote LDAP directory. In the Directory Assistance document for the remote LDAP
directory on the Basics tab, next to ″Make this domain available to,″ select ″LDAP Clients″. To prevent the
LDAP service from referring clients to the directory, do not select ″LDAP Clients″.

To return a referral, the Domino LDAP service uses information in the Directory Assistance document for
the remote LDAP directory. The referral is compliant with LDAP v3 and includes:
v The URL hostname for the LDAP directory server
v The base distinguished name configured for the directory in the Directory Assistance document.
v The port the LDAP directory server uses

Note that when returning a referral, the Domino server running the LDAP service never connects to the
remote LDAP directory server.

Some LDAP clients can accept more than one referral so that if the host name specified in one referral is
unavailable, the client can attempt to use another. By default, for a given search, the LDAP service can
refer an LDAP client to only one remote LDAP directory host name. If there are LDAP clients that use the
LDAP service that can accept more than one referral, you can use the LDAP service configuration setting
″Maximum number of referrals″ to increase the number of referrals that the LDAP service can return.

For information on how naming rules affect which host names the LDAP service refers to clients, see the
topic ″Naming rules and the LDAP service″ later in the chapter.

Directory assistance concepts

Before you set up directory assistance, read about these directory assistance concepts:
v Naming contexts (rules)
v Domain names
v Directory failover
v Directory assistance for an Extended Directory Catalog
v Directory assistance in conjunction with a condensed Directory Catalog
v Directory assistance for the primary Domino Directory
v Number of directory assistance databases

Directory assistance and naming rules

When you configure directory assistance for a directory, you define at least one naming rule that
corresponds to the names of users in the directory. Naming rules are based on the X.500 distinguished
name model. This model uses a directory tree name hierarchy of country (c), organization (o), and
organizational unit (ou) to divide names into parts that together represent unique locations in the
directory tree. This is also the naming model Domino and Notes have traditionally used.

Each directory assistance naming rule includes six parts, with each part containing one of the following:
v The name of a specific directory tree branch, for example, the organization Acme or the organizational
unit Sales.
v An asterisk (*) to represent all branches at a specific level in the directory tree name hierarchy

572 Lotus Domino Administrator 7 Help

v A null character (nothing or a single space) to exclude all branches at a specific level in the directory
tree name hierarchy

It’s common to assign an all-asterisk rule to a directory (*/ */ */ */ */ */ *) to represent all names in a
directory. However if directories configured in directory assistance use discrete name hierarchies, then it’s
useful to define rules for the directories that corresond to the hierarchies, so servers can target a specific
directory when searching for specific names.

For example, assume Directory A and Directory B are both configured in a directory assistance database.
Names in Directory A fall under o=acme, c=us so you specify the rule, */ */ */ */ acme/us for it, and
the names in Directory B fall under o=acme,c=fr so you specify the rule */ */ */ */ acme/fr for it. To
find the name cn=jack brown,o=acme,c=fr, a server searches only Directory B, and not Directory A, and to
find the name cn=joan brown,o=acme,c=us, a server searches only Directory A and not Directory B.

This type of targeted directory search can occur when:

v A server looks for a hierarchical name in a Notes message address field to resolve the address
v A server running the LDAP service processes an LDAP client search operation that specifies a search
base.
v A server running the LDAP service processes an LDAP client add, delete, modify, or compare
operation.
v A server looks for a hierarchical logon name an Internet client passes when logging on to the server to
initiate authentication.
For more information on how naming rules affect the LDAP service, see the topic ″Naming rules and
the LDAP service″ later in the chapter.

To find a flat name, a name without distinguishing parts, or to process an LDAP search request that
doesn’t specify a search base, a server ignores naming rules and searches directories according to search
orders specified for the directories in the Directory Assistance documents.

Note: Some LDAP directories do not use the country (c), organization (o), and organizational unit (ou)
naming model. If you set up directory assistance for an LDAP directory such as this, use an all-asterisk
naming rule for the directory.

Trusted naming rules: When an Internet client passes a logon name to a server to initiate authentication,
the server looks for the name in a directory configured in the directory assistance database only if the
directory has at least one configured naming rule that is ″Trusted for Credentials″ -- known as a trusted
rule. If the client logon name is hierarchical, the server looks for the name only in directories with a
trusted rule that matches the client logon name, in addition to the primary Domino Directory. If the client
logon name is flat, for example John Smith, then the server looks for the name in all directories with a
trusted rule.

When a server finds the client logon name in a user entry in a directory, the server compares the
distinguished name assigned to the user entry to the trusted rule(s) defined for the directory. The server
only authenticates the client if the distinguished name matches a trusted rule. If you use a remote LDAP
directory for client authentication and add Notes distinguished names to the directory, the Notes
distinguished names, not the original LDAP distinguished names, must match a trusted rule for the
directory.

For more information on using Notes names in a remote LDAP directory, see the topic ″Using Notes
distinguished names in a remote LDAP directory″ later in the chapter.

Examples of naming rules: The following table provides examples of naming rules, illustrating how
each rule includes or excludes names such as:
v Marilyn Jenkins/Omega

Chapter 25. Setting Up Directory Assistance 573

v Alan Jones/Sales/East/Acme/US
v Randi Bowker/Marketing/East/Acme/US
v Cheryl Lordan/IS/West/Acme/US
v Derek Malone/Accounting/West/Acme/US
v Deborah Jones/West/Acme/US
v Karen Lessing/West/Acme/DE

Rule Includes Excludes

*/*/*/*/*/* All names in the directory No names
/ / */ */Acme/* Alan Jones/Sales/East/Acme/US Marilyn Jenkins/Omega

Randi Bowker/Marketing/East/Acme/US

Cheryl Lordan/IS/West/Acme/US

Derek Malone/Accounting/West/Acme/US

Deborah Jones/West/Acme/US

Karen Lessing/West/Acme/DE
/ / */West/Acme/* Cheryl Lordan/IS/West/Acme/US Marilyn Jenkins/Omega

Derek Malone/Accounting/West/Acme/US Alan Jones/Sales/East/Acme/US

Deborah Jones/West/Acme/US Randi Bowker/Marketing/East/Acme/US

Karen Lessing/West/Acme/DE
/ / /West/Acme/* Deborah Jones/West/Acme/US Marilyn Jenkins/Omega

Karen Lessing/West/Acme/DE Alan Jones/Sales/East/Acme/US

Randi Bowker/Marketing/East/Acme/US

Cheryl Lordan/IS/West/Acme/US

Derek Malone/Accounting/West/Acme/US
// Karen Lessing/West/Acme/DE Marilyn Jenkins/Omega
*/West/Acme/DE
Alan Jones/Sales/East/Acme/US

Randi Bowker/Marketing/East/Acme/US

Cheryl Lordan/IS/West/Acme/US

Derek Malone/Accounting/West/Acme/US

Deborah Jones/West/Acme/US
/ /IS/West/Acme/* Cheryl Lordan/IS/West/Acme/US Marilyn Jenkins/Omega

Alan Jones/Sales/East/Acme/US

Randi Bowker/Marketing/East/Acme/US

Derek Malone/Accounting/West/Acme/US

Deborah Jones/West/Acme/US

Karen Lessing/West/Acme/DE

574 Lotus Domino Administrator 7 Help

How naming rules relate to directory search orders: To look up a name that corresponds to a naming
rule defined in more than one Directory Assistance document, or to look up a flat name that doesn’t have
distinguishing parts, directory assistance uses the configured search orders for the directories to decide
which directory to use, or which directory to use first.

For example, if the Directory Assistance documents for directory A and directory B are assigned search
orders of 2 and 1, respectively, and both documents contain only an all-asterisk rule, then directory
assistance searches directory B before directory A.

The Directory Assistance view in the directory assistance database sorts Directory Assistance documents
by their specified search order.

If you don’t specify a search order, or if you assign the same search order to two directories, directory
assistance searches the directories in alphabetical order, according to the value specified in the ″Domain
name″ field of the Directory Assistance document.

For more information on how Notes and Domino search multiple directories, see the chapter ″Planning
Directory Services.″

Naming rules and the LDAP service: Naming rules affect how the LDAP service processes LDAP
search operations and LDAP write and compare operations. Naming rules also define naming contexts
for the LDAP service.

For information on directory assistance and the processing of LDAP service write and compare
operations, see the chapter ″Setting Up the LDAP Service.″ For more information on how the LDAP
service uses directory assistance, see the topic ″Directory assistance for the LDAP service″ earlier in the
chapter.

How naming rules affect LDAP search operations: An LDAP client can specify a search base when searching
a directory. A search base limits the scope of a search by specifying a point in the directory tree at which
to begin. You use naming rules to define a search base for a directory. If an LDAP client specifies a search
base, the LDAP service searches a Domino Directory or Extended Directory Catalog configured in
directory assistance only if the directory has a naming rule that matches the search base. For example, if
an LDAP client specifies the search base ou=sales,o=acme, the LDAP service searches only Notes
directories that have rules such as:

*/ */ */ */ */ *

*/ */ */ */ acme/ *

*/ */ */ sales/ acme/ *

but not Notes directories with rules such as:

*/ */ */ mktg/ acme/ *

*/ */ */ */ org2/ *

*/ */ */ */ acme/ us

Note: You can’t define a search base for the primary Domino Directory.

If the LDAP service can’t find the information for which an LDAP client is searching in its primary
Domino Directory, a condensed Directory Catalog, or a Domino Directory or Extended Directory Catalog
configured in a directory assistance database, it can refer the client to a remote LDAP directory.

Chapter 25. Setting Up Directory Assistance 575

By default, the LDAP service can refer a client to one LDAP directory only. If the client specifies a search
base, the LDAP service refers the client only to an LDAP directory that is enabled for LDAP clients and
has a naming rule that matches the search base. If there is more than one such directory, the LDAP
service refers the client to the one with the lowest search order.

If the client doesn’t specify a search base, the LDAP service refers the client to an LDAP directory that is
enabled for LDAP clients, and if there is more than one, it refers the client to the one assigned the lowest
search order.

If there is more than one host name specified in the Directory Assistance document for the LDAP
directory that the LDAP service picks for a referral, the LDAP service refers the client to the first host
name listed.

If you increase the number of referrals the LDAP service can return to a client, the LDAP service follows
the logic described above to pick the first directory referral. If there is more than one host name specified
in the Directory Assistance document for this directory, the LDAP service uses the additional host
name(s) as the additional referral(s), up to the maximum number of referrals the LDAP service
configuration allows. If there is no additional host name specified for the first directory picked for
referrals, then LDAP service can refer the client to an LDAP directory with a different Directory
Assistance document.

Naming rules as LDAP naming contexts: Some LDAP client applications, for example the IBM WebSphere®
Application Server, can discover naming contexts configured for an LDAP directory server by searching
the directory server’s root directory server entry (DSE). When an LDAP user doesn’t specify a search
base, these applications can use the naming contexts configured on the server to contruct one to apply to
the LDAP client searches.

The LDAP service uses naming rules configured in the directory assistance database to define naming
contexts in its root DSE.

Directory assistance and domain names

When you configure directory assistance for a directory you must configure a domain name for the
directory that is unique within the directory assistance database. You use the ″Domain name″ field on the
Basics tab of a Directory Assistance document to configure a directory’s domain name.

If the directory is a remote LDAP directory, make up a unique domain name for the directory that is not
the name of any Domino domain.

If the directory is the Domino Directory for a Domino domain -- Domino server setup created it -- specify
the name of the directory’s Domino domain.

If you created the directory manually from the PUBNAMES.NTF template, and so it is not associated
with a Domino domain -- for example the directory is an Extended Directory Catalog, or a Domino
Directory used to track Web user information -- do one of the following to specify a domain name for the
directory:
v If you want servers with Configuration directories to use the directory as their remote primary Domino
Directory, specify the Domino domain of the servers with the Configuration directories.
v If servers won’t use the directory as a remote primary Domino Directory, make up a unique domain
name for the directory.

Note: If the domain name you specify for a Domino Directory or Extended Directory Catalog is the same
as the domain of the servers that use the directory assistance database, the servers can use the directory
automatically for client authentication, group lookups for database authorization, and Notes mail
addressing, regardless if you select ″Make this domain available to: Notes clients and Internet
Authentication/Authorization.″ In addition, servers search a directory in the same domain first,
regardless of the search order specified for the directory.

576 Lotus Domino Administrator 7 Help

Directory assistance and failover for a directory
When you set up directory assistance for a directory, you can configure failover for the directory.
v Failover for a Domino Directory or Extended Directory Catalog
v Failover for a remote LDAP directory

Directory assistance and failover for a Domino Directory or Extended Directory Catalog: When you
set up directory assistance for a Domino Directory or Extended Directory Catalog, on the Replicas tab of
the Directory Assistance document you specify the replicas of the directory for directory assistance to use.
When you specify replicas in a Directory Assistance document for a Domino Directory or Extended
Directory Catalog:
v Configure directory failover, so that if one replica is unavailable, directory assistance has at least one
alternate replica it can try to use. Directory assistance can use one of two methods to fail over to an
alternate replica of a Domino Directory or Extended Directory Catalog: directory assistance failover, the
failover method also available in previous releases, or cluster failover.
v Make sure servers that use the directory assistance database have fast network access to the directory
replicas you specify. Fast network access to replicas is particularly important if servers use a directory
to look up groups for database authorization.
v Make sure servers that do remote lookups to a replica have access to the server that stores the replica,
and have at least Reader access in the directory access control list (ACL).
v If a directory is used for Notes mail addressing, make sure the Notes users that use the feature have at
least Reader access in the directory ACL, so they can browse the directory. If Extended Access is
enabled for a directory, then the users must also have at least Reader access to use typeahead or F9
address resolution.

The directory assistance failover method: Servers can use the directory assistance failover method, rather
than cluster failover method, to find an available replica of a Domino Directory or Extended Directory
Catalog. To use the directory assistance failover method, on the Replicas tab of the Directory Assistance
document for the directory, specify up to five replicas of the directory that are potentially available for
use.

When a server starts up, directory assistance searches for an available replica among the replicas you
have specified. If directory assistance cannot find an available replica during server startup, in five
minutes it attempts to locate an available replica again, continuing this attempt at five-minute intervals
until successful.

Once directory assistance finds an available replica at server startup, it continues to use the replica unless
the replica becomes unavailable, at which point failover occurs and directory assistance looks for an
alternate replica. When a replica is unavailable for any reason, directory assistance continues to use the
alternate replica, even after the previously unavailable replica becomes available.

Directory assistance finds that a replica is unavailable if it attempts to access the replica during server
startup, or during normal server operation when it processes a client lookup request. A directory replica
is unavailable to directory assistance if:
v The server that stores the replica is unavailable, for example, the server is down or there is a network
connectivity problem.
v A view in the replica required for directory lookups is locked because the server that stores the replica
is rebuilding the view.
v A replica no longer exists because it has been deleted.

Note: Directory assistance run on servers running Domino Release 5.0.9 or earlier do not fail over when
locked out of a view. To have this failover capability in a mixed Lotus Domino 6 or higher/Lotus
Domino Release 5 environment, upgrade Domino Release 5 servers to at least Lotus Domino Release
5.0.10.

Chapter 25. Setting Up Directory Assistance 577

At server startup and during failover, directory assistance looks for an available replica from the list of
replicas specified in the Directory Assistance document as follows:
1. Looks for a local replica.
2. Looks for a replica within the same Notes named network; if there is more than one, looks in the
order in which the Directory Assistance document lists them.
3. Looks for a replica within the same Domino Domain; if there is more than one, looks in the order in
which the Directory Assistance document lists them.
4. Looks for a replica it hasn’t looked for yet.

The cluster failover method for directory assistance: If replicas of a Domino Directory or Extended Directory
Catalog configured in the directory assistance database are on servers that are members of a cluster, you
can set up directory assistance to use cluster failover and workload balancing instead of the directory
assistance failover method. To use cluster failover and workload balancing, in the Replicas tab of the
Directory Assistance document for the directory specify only one of the directory replicas that is within
the cluster. Be sure to specify only one replica; if you specify more than one, directory assistance ignores
cluster failover, and instead uses the directory assistance failover method described above to find an
available replica.

Cluster failover is particularly useful in environments with centralized directory services. For example,
you can configure cluster failover in a Directory Assistance document for a remote primary Domino
Directory, so that servers with Configuration Directories use cluster failover to find an available replica of
the remote primary directory.

Directory assistance and failover for a remote LDAP directory: To provide failover in the event that a
remote LDAP directory configured in directory assistance is unavailable, on the LDAP tab of the
Directory Assistance document for the remote LDAP directory, enter more than one host name in the
Hostname field. Separate hostnames with commas. If the first LDAP directory server specified is
unavailable, a Domino server attempts to use the next one listed, and so on.

The configuration selections made in the Directory Assistance document apply to each host name
specified in the Hostname field except for the value specified in the Port field. You can specify a port for
a hostname that is different than the port specified in the Port field by adding a colon (:) followed by a
port number after the hostname. For example, you can enter the following in the Hostname field:

ldap1.acme.com:390, ldap2.acme.com:391

Directory assistance for an Extended Directory Catalog

Unless you integrate an Extended Directory Catalog directly into a server’s primary Domino Directory, a
server uses directory assistance look up information in an Extended Directory Catalog.

When you create a Directory Assistance document for an Extended Directory Catalog, the following
selections are the important ones to consider:
1. On the Basics tab, next to Domain type, select Notes.
2. On the Basics tab, next to Domain name, make up a unique domain name. Or, if the Extended
Directory Catalog functions as a remote primary Domino Directory used by servers with
Configuration Directories, specify the domain of the servers with the Configuration Directories.
3. If there are other Directory Assistance documents in the database, on the Basics tab, next to Search
order, typically you should specify a search order of 1.
4. On the Basics tab, next to ″Group Authorization,″ select Yes if you want servers to use groups
aggregated in the Extended Directory Catalog for authorizing database access. You can choose this
option for only one directory in the directory assistance database. Choose the option for an Extended
Directory Catalog if you want serves to be able to use groups from any of the aggregated directories
for database authorization.

578 Lotus Domino Administrator 7 Help

5. To trust all the directories aggregated in the Extended Directory Catalog for Internet client
authentication, on the ″Naming contexts (Rules)″ tab, include a rule that is ″Trusted for Credentials.″
If you want to trust some Domino Directories for client authentication, but not others, you can create
one Extended Directory Catalog that aggregates the trusted directories and a second that aggregates
untrusted directories. Then create a separate Directory Assistance document for each Extended
Directory Catalog, and enable ″Trusted for Credentials″ only in the document for the directory catalog
you want servers to trust for authentication.
6. In the replicas tab, be sure to configure failover for the Extended Directory Catalog.
For information on all the fields in a Directory Assistance document for a Domino Directory or
Extended Directory Catalog, see the topic ″Creating a Directory Assistance document for a Domino
Directory or Extended Directory Catalog″ later in the chapter.

Note: When servers use an Extended Directory Catalog, to optimize lookup performance, remove any
Directory Assistance documents that exist for the directories aggregated in the directory catalog. For
example, if you aggregate Directory A into an Extended Directory Catalog, if there is a Directory
Assistance document for Directory A, remove the document.

For more information on Extended Directory Catalogs, see the chapter ″Setting Up Directory Catalogs.″

Directory assistance in conjunction with a condensed Directory Catalog

Condensed Directory Catalogs are optimized for small size and client use. Although a server can use a
condensed Directory Catalog, under most circumstances it’s best for a server instead to use an Extended
Directory Catalog.

For information on the advantages to servers’ using an Extended Directory Catalog rather than a
condensed Directory Catalog, see the chapter ″Setting Up Directory Catalogs.″

If you do set up servers to use a condensed Directory Catalog, you may also want to set up directory
assistance for the individual Domino Directories aggregated into the directory catalog, so that:
v A server can use directory assistance to look up information not aggregated in the condensed Directory
Catalog.
v A server can trust a particular aggregated directory, but not all aggregated directories, for client
authentication.

Note: Do not create a Directory Assistance document for a condensed Directory Catalog itself, only for
the directories aggregated into the directory catalog.

Using directory assistance to look up information not aggregated into a condensed Directory Catalog:
While you always aggregate fields containing mail addressing information into a condensed Directory
Catalog to support the common task of looking up users’ mail addresses, typically you would not
aggregate fields containing information such as the following, because this would make the directory
catalog too large:
v X.509 certificates used for client authentication
v Information LDAP clients only occasionally search for
v Notes users’ public keys used to send encrypted mail

Instead, set up directory assistance for a Domino Directory aggregated into the directory catalog, so
servers can use directory assistance to look up the missing information directly in the Domino Directory.
Each entry in a condensed Directory Catalog includes the replica ID of the Domino Directory from which
the entry was derived and the UNID for the entry, a unique ID associated with a replicated document. In
the cases where the condensed Directory Catalog doesn’t aggregate a field being searched for, a server
uses this directory catalog information and information available through directory assistance to access

Chapter 25. Setting Up Directory Assistance 579

quickly the complete entry in the Domino Directory. Searching a Domino Directory by keying off entries
in a condensed Directory Catalog is faster than using directory assistance alone to locate and search the
Domino Directory.

If you aggregate a Domino Directory into a condensed Directory Catalog, and you don’t also set up
directory assistance for the directory itself, a server can’t use the directory to look up information omitted
from the Directory Catalog.

If you set up directory assistance for a Domino Directory but do not aggregate the directory into a
condensed Directory Catalog, a server can use directory assistance to search the Domino Directory after
searching the directory catalog.

Note: If a Domino Directory is aggregated into a condensed Directory Catalog, but particular entry from
the directory is not aggregated, for example a selection formula excludes the entry, servers cannot use
directory assistance to look up the missing entry directly in the Domino Directory.

Using directory assistance trust for client authentication one or some directories aggregated into a
condensed Directory Catalog: To indicate that a server should trust for client authentication all
directories aggregated into a condensed Directory Catalog, select the option ″Trust the server based
condensed directory catalog for authentication with internet protocols″ on the Basics tab of the server’s
Server document in the Domino Directory. In this case, directory assistance is not required to indicate
trust.

However to tell a server to trust for client authentication only one or some directories aggregated in a
condensed Directory Catalog, create a Directory Assistance document in a directory assistance database
for each of the aggregated Domino Directories to be trusted. In the Directory Assistance document for
each such directory, do the following:
v On the Basics tab, next to ″Make this domain available to,″ select ″Notes clients and Internet
Authentication/Authorization.″
v On the ″Naming Contexts (Rules)″ tab enable at least one rule that corresponds to the names to be
authenticated, and select ″Trusted for Credentials″ for the rule.
v On the ″Replicas″ tab include the replica of the Domino Directory that the Dircat task uses to aggregate
the directory into the condensed Directory Catalog. Note that you do not include the replica of the
directory catalog.

Note: You are not required to store user passwords, and you shouldn’t store X.509 certificates, in a
condensed Directory Catalog. Instead you can set up directory assistance for the secondary Domino
Directories that are aggregated to enable servers to find the passwords/X.509 certificates.

Directory assistance for the primary Domino Directory

A server with a local replica of its primary Domino Directory searches the directory automatically
without the use of directory assistance. You can configure directory assistance for the primary Domino
Directory of servers that use a directory assistance database to:
v Tell servers with Configuration Directories that use the directory assistance database how to locate a
remote replica of the primary Domino Directory.
v Prevent the LDAP service from searching the primary Domino Directory.

If multiple domains use replicas of one directory assistance database, you might also create a Directory
Assistance document for the primary Domino Directory so that servers in other domains that use the
directory assistance database can do lookups in the directory.

Note: You cannot prevent a server from using its primary Domino Directory for Notes mail addressing,
client authentication, or group lookups for database authorization. A server can always use a primary
Domino Directory for these purposes, regardless of the options you select for the directory in the
Directory Assistance document.

580 Lotus Domino Administrator 7 Help

Using directory assistance to control which remote replicas of a primary Domino Directory servers
with Configuration Directories can use: A Configuration Directory is a small, selective replica of a
domain Domino Directory that contains only Domino configuration information. A server with a
Configuration Directory looks up information related to directory services, such as information in user
and group documents, in a full replica of the domain primary Domino Directory on a remote server. You
can create a Directory Assistance document for the primary Domino Directory in a directory assistance
database used by servers with Configuration Directories. Do this to specify which replicas of a remote
primary Domino Directory the servers potentially can use. This step isn’t required -- if you do not use
directory assistance, a server with a Configuration Directory uses a default, built-in logic, to find a remote
replica of a primary Domino Directory to use.

For more information on Configuration Directories and on the default logic used to find a remote
primary Domino Directory, see the chapter ″Setting Up the Domino Directory.″

If you set up directory assistance to control which remote replicas of the primary Domino Directory
servers with Configuration Directories can use, the key options to select in the Directory Assistance
document are the following ones.

On the Basics tab:

v Next to ″Domain Type″ select Notes.
v Next to ″Domain Name″ enter the domain of the servers with the Configuration Directories.
v Next to ″Group Authorization″ select No. A server can use groups located in a primary Domino
Directory replica to authorize database access even when you select No because a primary Domino
Directory is always trusted for this purpose. Since you can select Yes for only one directory in the
directory assistance database, select No to reserve the use of ″Group Authorization″ for another
directory in the directory assistance database.
For more information on the ″Group Authorization″ feature, see the topic ″Directory assistance and
group lookups for database authorization″ earlier in this chapter.

On the Replicas tab, make sure to configure failover for the directory.

For more information, see the topic ″Directory assistance and failover for a Domino Directory or
Extended Directory Catalog″ later in this chapter.

For complete information on all the configuration fields in a Directory Assistance document for a Domino
Directory or Extended Directory Catalog, see the topic ″Creating a Directory Assistance document for a
Domino Directory or Extended Directory Catalog″ later in this chapter.

Using directory assistance to prevent the LDAP service from searching the primary Domino
Directory: You can set up directory assistance for the primary Domino Directory to prevent a server that
runs the LDAP service from using the primary Domino Directory when processing LDAP requests. For
example, you might want the LDAP service to use a secondary Domino Directory, but not the primary
Domino Directory.

The primary Domino Directory from which you exclude LDAP searches can be local, or can be remote if
the server running the LDAP service has a Configuration Directory.

If you set up directory assistance to prevent LDAP searches of the primary Domino Directory, the key
options to select in the Directory Assistance document are the following ones.

For complete information on all the configuration fields in a Directory Assistance document for a Domino
Directory, see the topic ″Creating a Directory Assistance document for a Domino Directory or Extended
Directory Catalog″ later in the chapter.

On the Basics tab:

Chapter 25. Setting Up Directory Assistance 581

1. Next to ″Domain Type″ select Notes.
2. Next to ″Domain Name″ enter the domain of the servers that run the LDAP service.
3. Next to ″Make this domain available to″ deselect ″LDAP Clients.″
4. Next to ″Group Authorization″ select No to reserve the use of ″Group Authorization″ for another
directory in the directory assistance database.
For more information on the ″Group Authorization″ feature, see the topic ″Directory assistance and
group lookups for database authorization″ earlier in this chapter.

On the Replicas tab, do one of the following:

v If all the servers that use the directory assistance database are within one domain and use a local
primary Domino Directory, you have to specify only one replica. Directory assistance requires the
replica specification to load properly, but the servers always do lookups in their local primary Domino
Directory replicas, regardless of the replica you specify. An easy method is specifying an asterisk in the
(*) in the Server Name field, and a file name in the Domino Directory File Name field, for example,
NAMES.NSF
v If the server running the LDAP service has a Configuration Directory, complete the Replicas tab to
indicate which replicas of the remote primary Domino Directories to use.
For more information on specifying replicas, see the topic ″Directory assistance and failover for a
Domino Directory or Extended Directory Catalog″ earlier in the chapter.

Number of directory assistance databases

Before you set up directory assistance, plan how many directory assistance databases to use. You can
create and configure one directory assistance database that all or most servers use. Or you can create
more than one directory assistance database, with groups of servers -- for example servers within a
domain -- each using specific ones. All the servers that use a particular directory assistance database must
use a directory configured in the database for the same services. If groups of servers require the use of
different directories or services, create a separate directory assistance database for each group of servers
to use.

For example, suppose all servers use an Extended Directory Catalog, but one group of servers only use,
in addition, a remote LDAP directory for client authentication. You would set up a separate directory
assistance for that group of servers that contains Directory Assistance documents for both the directory
catalog and the LDAP directory. For the other servers, create a directory assistance database configured
for the directory catalog only.

Setting up directory assistance

To set up directory assistance in a Domino domain, complete these procedures.
1. Create and replicate a directory assistance database.
2. Set up servers to use the directory assistance database.
3. Create a Directory Assistance document for each Domino Directory or Extended Directory Catalog for
which you want to provide directory assistance.
4. Create a Directory Assistance document for each remote LDAP directory for which you want to
provide directory assistance.
For information on troubleshooting problems with directory assistance, see the chapter
″Troubleshooting.″

Creating and replicating a directory assistance database

Create a directory assistance database on one server, and then create a replica of the database on each
server in the domain that will use it for directory assistance. A server can use one directory assistance
database only.
1. From the Domino Administrator, create the database:
a. Choose File - Database - New to open the ″New Database″ dialog box.

582 Lotus Domino Administrator 7 Help

 b. Enter the name of the server on which to create the database.
c. Enter a title for the database -- for example, Directory Assistance. You can enter any title.
d. Enter a file name for the database -- for example, DA.NSF. You can enter any file name with the
extension .NSF.
e. Click ″Show advanced templates.″
f. Click Template Server and select a server that stores the Directory Assistance template (DA50.NTF).
g. Select the Directory Assistance template (DA50.NTF) from the list of templates.
h. Keep ″Inherit future design changes″ selected.
i. Click OK.
2. Create a replica of the directory assistance database on each server that will use it.

Tip: Using the same file name and path for the replicas on each server makes it easy to use the
Administration Process to add the file name and path to Server documents.
For more information on replication, see the chapter ″Creating Replicas and Scheduling Replication.″
3. Create Connection documents to schedule replication of the database to all the servers that will use it.
4. Continue to the procedure ″Setting up servers to use a directory assistance database.″

Setting up servers to use a directory assistance database

After you create a directory assistance database and replicate it to servers, set up the servers to use the
database. To set up a server to use a directory assistance database, add the file name of the server’s
replica of the database to the ″Directory assistance database name″ field of the server’s Server document
in the primary Domino Directory.

Use the Administration Process to automate adding a directory assistance database file name to multiple
Server documents -- the Administration Process creates a ″Set Directory Assistance Field″ request to add
the file name. Or enter the file name of the directory assistance database to Server documents manually.

Using the Administration Process to add the directory assistance database file name to multiple Server
documents: To use the Administration Process to add a directory assistance database file name to
multiple Server documents:
1. Make sure that you:
v Created and replicated the directory assistance database
v Have either Author access and the ServerModifier role, or Editor access in the ACL of the Domino
Directory to which you will add the file names.
v Have set up the Administration Process
2. From the Domino Administrator, click the Configuration tab.
3. Next to ″Use Directory on,″ select the administration server for the Domino Directory.
4. In the left pane, expand Server - All Server Documents.
5. Select the Server documents for all servers that use the same file name for the directory assistance
database. A check mark appears next to each document.
6. Choose Actions - Set Directory Assistance Information.
7. Enter the file name that you gave to the directory assistance database on these servers -- for
example, DA.NSF. If the directory assistance database is in a subdirectory under the data directory,
include the path relative to the data directory -- for example, DIRECTORIES\DA.NSF.
8. Click OK.
9. When you see the dialog box stating ″Request has been submitted,″ click OK again.
10. Use the command ″tell adminp process interval″ to force processing of the ″Set Directory Assistance
Field″ request, or wait until the Administration Process processes the request when it next processes
interval requests.
For more information, see the appendix ″Server Commands.″

Chapter 25. Setting Up Directory Assistance 583

11. Replicate the modifed Domino Directory to the servers that will use the directory assistance
database.
12. Restart the servers so they detect the directory assistance database file names in their Server
documents.
13. Continue to one or both of these procedures:
v Creating a Directory Assistance document for a Domino directory
v Creating a Directory Assistance document for a remote LDAP directory

Entering the directory assistance database file name to a Server document manually:
1. Make sure that you:
v Created and replicated the directory assistance database
v Have either Author access and the ServerModifier role, or Editor access in the ACL of the Domino
Directory to which you will add the file names.
2. From the Domino Administrator, click the Configuration tab.
3. Next to ″Use Directory on,″ select the server whose Domino Directory you want to modify.
4. In the left pane, choose Server - All Server Document.
5. Select a specific Server document, and then click Edit Server.
6. In the ″Directory Assistance database name″ field in the ″Directory Info″ section on the Basics tab,
enter the file name that you gave to the replica of the directory assistance database on this server --
for example, DA.NSF. If the directory assistance database is in a subdirectory under the data
directory, include the path relative to the data directory -- for example, DIRECTORIES\DA.NSF.
7. Click Save & Close.
8. If the Domino Directory you changed is not the replica of the server whose directory assistance
database file name you specified, replicate the updated Domino Directory to the server.
9. Restart the server so it detects the directory assistance database file name now in its Server
document.
10. Continue to one or both of these procedures:
v Creating a Directory Assistance document for a Domino directory
v Creating a Directory Assistance document for a remote LDAP directory

Creating a Directory Assistance document for a Domino Directory or Extended

Directory Catalog
To set up directory assistance for a Domino Directory or an Extended Directory Catalog, create a
Directory Assistance document for the directory in the directory assistance database as follows:

Note: Do not create a Directory Assistance document for a condensed Directory Catalog.
1. Make sure you have read about directory assistance services and concepts.
2. Make sure that you have created and replicated a directory assistance database and have set up
servers to use it.
3. From the Domino Administrator, choose File - Open Server, and select a server that you have set up
to use the directory assistance database.
4. Click the Configuration tab.
5. In the left pane, expand Directory - Directory Assistance. If you see ″Server Error: File does not
exist,″ the server you selected in step 3 is not set up to use the directory assistance database.
6. Click Add Directory Assistance.
7. On the Basics tab, complete these fields:

Field Enter
Domain type Choose Notes.

584 Lotus Domino Administrator 7 Help

Field Enter
Domain name The name of the Domino domain associated with the directory. If the directory isn’t
associated with a Domino domain because you created it manually rather than through
server setup, make up a unique domain name for it. For more information, see the topic
″Directory assistance and domain names.″
Company name (Optional) The name of the company associated with this directory. Multiple Directory
Assistance documents can use the same company name.
Search order (Optional) A number affecting the order in which servers search this directory relative to
other directories configured in the directory assistance database. For more information,
see the topic ″How naming rules relate to directory searcher orders.″
Make this domain Choose one or both:
available to v ″Notes Clients and Internet Authentication/Authorization″
v ″LDAP Clients″

Choose ″Notes Clients and Internet Authentication/Authorization″ to use the directory

for Notes mail addressing, Internet client authentication (including LDAP client
authentication), or to look up the members of groups for database authorization. For
group authorization, you must also enable ″Group Authorization″ (see below). By
default, the option is enabled. To prevent servers from using the directory for these
services, do not choose this option.

If the domain specified in the ″Domain name″ field is the same Domino domain (the
primary domain) of the servers that use directory assistance, the servers use the
directory for these three services automatically, even if you do not choose this option. If
you are using a configuration directory server, you can then make this option equal to
the primary address book domain and have the secondary address book available
through directory assistance.

Choose ″LDAP Clients″ to enable the LDAP service running on servers to use the
directory for search and write operation when processing LDAP requests. To use the
directory for LDAP write operations, you must also enable the directory for write
operations in the ″All Servers″ Configuration Settings document. By default, the option
is enabled. To prevent the LDAP service from using the directory for search and write
operation, do not choose this option.

Fore more information, see the topics ″Directory assistance services″ and ″Directory
asssistance and domain names.″
Group Authorization Choose one:
v Yes to search the members of groups in the directory when authorizing database
access. You must also select ″Make this domain available to: Notes Clients and
Internet Authentication/Authorization.″
v No (default) to prevent searching the members of groups in the directory when
authorizing database access.

You do not have to enable a rule that is ″Trusted for Credentials.″

Enable this option in only one Directory Assistance document, Notes or LDAP, in the
directory assistance database.

If the domain specified in the ″Domain name″ field is the same Domino domain (the
primary domain) of the servers that use directory assistance, the servers use the
directory to look up groups for database authorization automatically, even if you choose
No for this option.

For more information, see the topic ″Directory assistance and group lookups for
database authorization.″

Chapter 25. Setting Up Directory Assistance 585

Field Enter
Enabled Choose Yes to enable directory assistance for this directory.
Note: You can enable or disable directory assistance from the main view of the
Directory Assistance database by selecting the directory assistance record for the
directory and, on the toolbar, click Enable/Disable.
Attribute to be used as The default option for this field is LTPA_UserNm.
name in an SSO token
For more information about name mapping in the LTPA token used for single sign-on,
see the topic ″Configuring user name mappings in the SSO LTPA token.″

8. Click the Naming Contexts (Rules) tab, and for each rule you want to define, complete the following
fields. By default, an all-asterisk rule is enabled with ″Trusted for Credentials″ set to No.

Field Enter
N.C. # A naming context (rule) that describes names in the directory. For more information, see
the topic ″Directory assistance and naming rules.″
Enabled Choose one:
v Yes to enable a rule
v No to disable a rule
Trusted for Credentials Choose one:
v Yes to allow servers to use credentials in this directory to authenticate Internet clients
whose distinguished names in the directory correspond to the rule.
v No (default) to prevent servers from using this directory to authenticate Internet
clients whose distinguished names correspond to the rule.

For more information, see the topic ″Trusted naming rules.″

If the domain specified in the ″Domain name″ field on the Basics tab is the same
Domino domain (the primary domain) of the servers that use directory assistance, the
servers trust all user names in the directory for client authentication, even if you do not
choose this option.

9. Click the Replicas tab. Use either the ″Database links″ field or the ″Replica#″ fields to specify replicas
of the directory for servers to use. If you make any entry in a Replica# field, then directory
assistance ignores all entries in the ″Database links″ field.
To set up directory assistance to use cluster failover to locate an available replica of the directory,
specify only one replica of the directory within the cluster.
For more information on failover, see the topic ″Directory assistance and failover for a Domino
Directory or Extended Directory Catalog.″

Field Enter
Database links For each replica you want to specify:
v Open the replica of the directory, and choose Edit - Copy As Link - Database Link.
v Select the ″Database links″ field, and choose Edit - Paste.

Using database links may delay server startup. When you restart a server that uses
directory assistance, server tasks retrieve database information from the remote servers
to which the links refer. Use database links only if the servers to which the links refer
are consistently available.

586 Lotus Domino Administrator 7 Help

Field Enter
Replica# The server name and file name of a replica of the directory -- for example:

Server Name: Mail1/West/Acme

Domino Directory File Name: EASTNAMES.NSF

Selected Enabled next to each replica you specify.

10. Click Save & Close.

Shortcut for specifying local replicas of a Domino Directory or Extended Directory Catalog in a
Directory Assistance document: You can enter an asterisk (*) in the Server Name field on the Replicas
tab of a Directory Assistance document for a Domino Directory or Extended Directory Catalog to indicate
that directory assistance should first look on its local server for a replica of the directory. This feature is
useful in an environment where multiple servers use directory assistance to search local replicas of a
directory with the same file name. Use an asterisk to represent all the servers that have local replicas of
the directory with the same file name, rather than specifying each server individually in its own Server
Name field.

For example, if servers A, B, C, and D each store local replicas of the directory ACMEWEST.NSF
configured for directory assistance, use an asterisk to specify only one Server Name/Directory Filename
entry in the Directory Assistance document for ACMEWEST.NSF:

Server Name Directory Filename

* ACMEWEST.NSF

If you do not enter an asterisk, you muse make these four Server Name/Directory Filename entries:

Server Name Directory Filename

Server A ACMEWEST.NSF
Server B ACMEWEST.NSF
Server C ACMEWEST.NSF
Server D ACMEWEST.NSF

If some servers use directory assistance but don’t have local replicas of the directory, add at least one
explicit Server Name/Directory Filename entry in the Directory Assistance document for these servers to
use. If you use the directory assistance failover method, specify at least one explicit Server
Name/Directory Filename entry for servers with local replicas to use as an alternate in the event the
replica is unavailable.

Note: Do not use * in the Server Name field in a Directory Assistance database that Lotus Domino
Release 4 servers use. Instead, create a separate Directory Assistance database that uses explicit server
names for Release 4 servers to use.

Creating a Directory Assistance document for a remote LDAP directory

To set up directory assistance for a remote LDAP directory, create a Directory Assistance document for
the directory in a directory assistance database as follows: Make sure you have read about directory
assistance services and concepts.
1. Make sure you have created and replicated a directory assistance database, and have set up servers
to use it.

Chapter 25. Setting Up Directory Assistance 587

 2. If you are using the remote LDAP directory for any purpose other than LDAP service referrals, use
the TCP/IP ping utility to test that the Domino servers that will use the LDAP directory can connect
to the remote LDAP directory server.
3. From the Domino Administrator, choose File - Open Server, select a server that you have set up to
use the directory assistance database, and click OK.
4. Click the Configuration tab.
5. In the left pane, expand Directory - Directory Assistance. If you see ″Server Error: File does not
exist,″ the server you selected in step 4 is not set up to use the directory assistance database.
6. Click Add Directory Assistance.
7. On the Basics tab, complete these fields:

Field Enter
Domain type Choose LDAP.
Domain name A domain name of your choice that is different from the domain name specified for any
other Directory Assistance document - Notes or LDAP - in the directory assistance
database. For more information, see the topic ″Directory assistance and domain names.″
Company name (Optional) The name of the company associated with this directory. Multiple Directory
Assistance documents can use the same company name.
Search order (Optional) A number affecting the order in which servers search or refer LDAP clients to
this directory relative to other directories configured in the directory assistance database.
For more information, see the topic ″How naming rules relate to directory search
orders.″
Make this domain Choose one or both:
available to v ″Notes clients and Internet Authentication/Authorization″ to use this LDAP directory
for Notes mail addressing, Internet client authentication (including LDAP client
authentication), or to look up the members of groups for database authorization. For
group authorization, you must also enable ″Group Authorization″ (see below).
v ″LDAP Clients″ to enable a server running the LDAP service to refer LDAP clients to
this LDAP directory when an LDAP search is not succesful in any Domino Directory.

For more information, see the topic ″Directory assistance services.″

Group Authorization Choose one:
v Yes to search the members of groups in this LDAP directory when authorizing
database access.
v No (default) to prevent searching the member of groups in the directory when
authorizing database access.

Choose Yes for only one directory, Notes or LDAP, configured in the directory assistance
database.

You do not have to enable a rule that is ″Trusted for Credentials.″

If you select Yes, in the ″Nested group expansion″ field that appears choose one:
v Yes (default) to search nested groups -- groups that are members of groups listed in
database ACLs.
v No to search only the members of groups listed in database ACLs, and not the
members of groups nested within those groups.

For more information on group authorization, see the topic ″Directory assistance and
group lookups for database authorization.″
Enabled Choose Yes to enable directory assistance for this LDAP directory.
Note: You can also enable and disable directory assistance for this directory from the
main view of the Directory Assistance database. Select the directory assistance record for
the directory and, on the toolbar, click Enable/Disable.

588 Lotus Domino Administrator 7 Help

Field Enter
Attribute to be used as Enter the name of the directory attribute that should be returned when the
name in an SSO token LTPA_UserNm field is requested. This value is used as the user name in any SSO token
(map to Notes generated by Domino.
LTPA_UserNm)
For more information about name mapping in the LTPA token used for single sign-on,
see the topic ″Configuring user name mappings in the SSO LTPA token.″

8. On the Naming Contexts (Rules) tab, for each rule you want to define for the directory, complete the
following fields. By default, an all-asterisk rule is enabled with ″Trusted for Credentials″ set to No.

Field Enter
N.C. # Enter a naming context (rule) that describes the user names in the LDAP directory. For
more information, see the topic ″Directory assistance and naming rules.″
Enabled Choose one:
v Yes to enable a rule
v No (default) to disable a rule
Trusted for Credentials Choose one:
v Yes to allow servers to use credentials in the LDAP directory to authenticate Internet
clients whose distinguished names in the directory correspond to the rule.
v No (default) to prevent servers from using this directory to authenticate Internet
clients whose distinguished names in the directory correspond to the rule.

For more information, see the topic ″Trusted naming rules.″

9. On the LDAP tab, complete these fields:

Field Enter
Hostname The host name for the remote LDAP directory server -- for example, ldap.acme.com. A
Domino server uses this host name to connect to the remote LDAP directory server, or
to refer LDAP clients to the LDAP directory.

Enter an additional host name or host names so that a Domino server can use an
alternate LDAP directory server if the directory server represented by the first host
name specified is unavailable. Separate host names with commas, semicolons, or by
entering each host name on a new line.

If you specify more than one directory server and each listens on a different port,
specify the ports after the host names. For example:
ldap1.acme.com:390, ldap2.acme.com:391

Port values entered in this field override those specified in the Port field. If no port is
specified in this field, then the value specified in the Port field will be used.
Note: IPv6 addresses are also supported for use in this field. However, it is important
to note that ifan IPv6 address is specified in this field, than the Directory Assistance
database should not be used by a pre-7.0 servers, as they do not support IPv6.

For more information, see the topic ″Directory assistance and failover for a remote
LDAP directory.″

Chapter 25. Setting Up Directory Assistance 589

Field Enter
Optional Authentication (Optional) Below ″Optional Authentication Credential″ enter a user name and a
Credential password for a Domino server to present when it connects to the remote LDAP
directory server. The LDAP directory server uses the name and password to
authenticate the Domino server. If you don’t specify a name and password, a Domino
server attempts to connect anonymously.

For more information, see the topic ″Specifying a name and password for Domino
servers in a Directory Assistance document for a remote LDAP directory.″

This setting may affect change detection for LDAP servers. For more information, see
the topic ″Special considerations for change detection.″
Base DN for search A search base, if the LDAP directory server requires one. For example:

o=Ace Industry

o=Ace Industry,c=US

This setting may affect change detection for LDAP servers. For more information, see
the topic ″Special considerations for change detection.″
Channel encryption Choose one:
v SSL (the default) to use SSL when a Domino server connects to the remote LDAP
directory server
v None to prevent SSL from being used.

Keep SSL selected in the ″Channel encryption″ field if you use the remote LDAP
directory for client authentication or to look up the members of groups for database
authorization.

If you choose SSL, make selections in these associated fields:

v ″Accept expired SSL certificates″
v ″SSL protocol version″
v ″Verify server name with remote server’s certificate″

For more information, see the next topic ″Configuring SSL in a Directory Assistance
document for a remote LDAP directory.″
Port The port number Domino servers use to connect to the remote LDAP directory server.
v If you choose SSL in the ″Channel encryption″ field, the default port is 636.
v If you choose None in the ″Channel encryption″ field, the default port is 389.

If the LDAP directory server doesn’t use one of these default ports, enter a different
port number manually.
Timeout The maximum number of seconds allowed for a search of the remote LDAP directory;
default is 60 seconds.

If the remote LDAP directory server also has a timeout setting, the lower setting takes
precedence.
Maximum number of The maximum number of entries the LDAP directory server can return for a name for
entries returned which a Domino server searches. If the LDAP directory server also has a maximum
setting, the lower setting takes precedence. If the LDAP directory server times out, it
returns the number of names found up to that point.

Default is 100.

590 Lotus Domino Administrator 7 Help

Field Enter
Dereference alias on Choose one to control the extent to which alias dereferencing occurs during searches of
search the remote LDAP directory:
v ″Never″
v ″Only for subordinate entries″
v ″Only for search base entries″
v ″Always″ (default)

If aliases aren’t used in the LDAP directory, selecting ″Never″ can improve search
performance.

For more information, see the topic ″Configuring alias dereferencing in a Directory
Assistance document for a remote LDAP directory.″
Preferred mail format If directory assistance is set up to allow Notes users to address mail to users in an
LDAP directory, use this option to specify the format of addresses from the directory to
be used in Notes mail. Choose one:
v ″Notes Mail Address″ - for example, John Doe/Acme@Acme. Typically, this option is
used only when the LDAP directory is a Domino Directory.
v ″Internet Mail Address″ (default) - for example, jdoe@acme.com.

For more information, see the earlier topic ″Notes mail addressing using a remote LDAP
directory.″
Attribute to be used as (Optional) If a Domino server uses the remote LDAP directory for client authentication
Notes Distinguished or for database authorization, optionally map users’ LDAP directory distinguished
Name names to corresponding Notes distinguished names. For information, see the topic
″Using Notes distinguished names in a remote LDAP directory.″
Type of search filter to Choose one to control which LDAP search filters are used to search the directory:
use v ″Standard LDAP″ (default)
v ″Active Directory″
v ″Custom″

″Standard LDAP″ works in most situations.

For more information, see the topic ″Configuring search filters in a Directory Assistance
document for a remote LDAP directory.″

10. Click Save & Close.

11. If you changed the Group Authorization field:
a. Wait for the change to replicate to all the servers that use the directory assistance database, or
force the replication.
b. Use the Restart Server console command to stop and restart each server that uses directory
assistance for group authorization, so each server detects the change.

Configuring SSL in a Directory Assistance document for a remote LDAP directory: If a Domino server
uses a remote LDAP directory to look up credentials during Internet client authentication, or to look up
the members of groups during database authorization, specify that the server use SSL to connect to the
LDAP directory server. Specify SSL so there are secure communications between the Domino server and
the LDAP server, and so that the Domino server can use an X.509 certificate to verify the remote LDAP
directory server’s identity.

To use SSL, select SSL in the ″Channel encryption″ field on the LDAP tab of the Directory Assistance
document for the remote LDAP directory. When you select SSL, you must also make selections for three
associated fields:
v ″Accept expired SSL certificates″

Chapter 25. Setting Up Directory Assistance 591

v ″SSL protocol version″
v ″Verify server name with remote server’s certificate″

″Accept expired SSL certificates″: In the ″Accept expired SSL certificates″ field choose one:
v Yes (the default) to accept a certificate from the LDAP directory server, even if the certificate has
expired.
v No, to reject an expired certificate, to provide tighter security.

″SSL protocol version″: In the ″SSL protocol version field,″ select the version number of the SSL protocol
to use, as follows:

SSL protocol version Description

V2.0 only Allows only SSL 2.0 connections.
V3.0 handshake Attempts an SSL 3.0 connection. If the connection fails and the requestor detects
SSL 2.0, attempts to use SSL 2.0 to connect.
V3.0 only Allows only SSL 3.0 connections.
V3.0 with V2.0 handshake Attempts an SSL 3.0 connection, but starts with an SSL 2.0 handshake, which
displays relevant error messages. Makes an SSL 3.0 connection if possible.
Choose ″V3.0 and V2.0 handshake″ to receive V2.0 error messages that may
occur during a connection attempt. These error messages can provide
information about compatibility problems found during the connection.
Negotiated Allows SSL to determine the protocol version and handshake.

″Verify server name with remote server’s certificate″: In the ″Verify server name with remote server’s
certificate″ field, choose one:
v Enabled (the default)
v Disabled

Choose Enabled to require that the subject line of the remote server’s certificate include the LDAP
directory server host name. For this option to work properly, the subject line in the remote server’s
certificate must include its DNS host name. Keep the option enabled if you are sure that the X.509
certificate of the remote LDAP directory server contains the remote server’s host name in the appropriate
format.

The Domino CA and some other CAs provide a dialog box into which users enter the subject line when
requesting a certificate. For example, the Domino CA prompts each user to enter the remote server’s
information -- such as, the common name, organizational unit name, organization name, state (or
province), and country name. The Domino CA places this information in the subject line and adds the
appropriate prefix (cn=, ou=, o=, and so on) to each field. If you used a Domino CA to create the remote
server’s certificate, enter the remote server’s host name in the common name field when using the ″Verify
server name with remote server’s certificate″ option. For example, the Domino CA allows users to enter
the following valid subject lines (mailserver.acme.com is the server’s DNS host name):

cn=mailserver.acme.com, ou=sales, ou=marketing, o=acme, st=mass, c=us

cn=mailserver, ou=sales - mailserver.acme.com o=acme, st=mass, c=us

To ensure that users enter the DNS host name properly, recommend that they enter it as the common
name (cn=) when they request a certificate from the Domino CA. Other CAs may have different dialog
boxes for entering the subject line; users must follow these dialog boxes to enter the remote server’s DNS
host name.

592 Lotus Domino Administrator 7 Help

Specifying a name and password for Domino servers in a Directory Assistance document for a remote
LDAP directory: In the ″Optional Authentication Credential″ section on the LDAP tab of a Directory
Assistance document for a remote LDAP directory you can enter a distinguished user name and a
password. If a Domino server connects to the remote LDAP directory server, it presents the name and
password so the remote LDAP directory server can authenticate the Domino server.

If you don’t specify a name and password, a Domino server attempts to connect to a remote LDAP
directory server anonymously. You must specify a name and password if the remote LDAP directory
server does not allow anonymous access.

Enter a distinguished name in the Username field, and a password in the Password field. The name and
password must correspond to a valid name and password in the remote LDAP directory. Enter the
distinguished name in LDAP format, for example cn=domino server,o=acme.

The Username and Password fields are encryptable fields. Do the following to encrypt the fields to limit
which Domino administrators and servers can read their contents:
1. Create a secret encryption key.
2. Use the secret encryption key to encrypt the Directory Assistance document.
3. Distribute and merge the encryption key only into the ID files of administrators and Domino servers
who should read the user name and password.

Only administrators and servers with the secret encryption key can read the user name and password.
Any Domino server that connects to the remote LDAP directory server or that replicates changes to the
directory assistance database requires the encryption key.

For information on creating and using secret encryption keys, see the book Application Development with
Domino Designer.

Configuring search filters in a Directory Assistance document for a remote LDAP directory: If servers
use directory assistance to search a remote LDAP directory, you can use the field ″Type of search filter to
use″ in the Directory Assistance document for the directory to control which LDAP search filters are used
to search the directory. The following choices are available.

Search filter option Description

Standard LDAP (Default)
Active Directory
Custom
Uses standard LDAP search filters that work with most LDAP directory servers,
including Domino, IBM Directory Server, Sun ONE Directory Server.
Uses predefined search filters that work with Active Directory servers. Select this
option if the remote LDAP directory is Active Directory.
Use to define your own search filters.

Note: The Active Directory search filter option replaces the Release 5 NOTES.INI setting
WebAuth_AD_Group, which allowed for searches of Active Directory groups.

Defining custom search filters: You might need to define custom search filters if searches are not returning
results or are returning results for the wrong entries. This situation can occur if the remote LDAP
directory server uses a non-standard schema. Typically, custom filters are targeted at a particular attribute
that can be used to produce unique, efficient matches - unique in that the attribute value is different for
each entry, efficient in that there is an index or some other fast mechanism to ensure quick searches.

Selecting ″Custom″ in the ″Type of search filter to use″ field displays the following three fields used to
define the custom search filters.

Chapter 25. Setting Up Directory Assistance 593

Custom search
filter field Description
Mail Filter If directory assistance is configured so that Notes users can look up mail addresses in the
directory, this search filter is used to look up the names in the directory. Leave the field blank
to use the following default search filter:
(|(cn=%*)(|(&(sn=%a)(givenname=%z))(&(sn=%z)(givenname=%a))))

If a user specified ″Pat Smith″ in a mail recipient field, the resulting filter used on the LDAP
search request would be:
(|(cn=Pat Smith)(|(&(sn=Pat)(givenname=Smith))(&(sn=Smith)(givenname=Pat))))

You may want to customize the mail filter if users always type in their UID attribute in a mail
recipient field. The custom filter would look similar to the following:
(uid=%*)

With this filter, if a user specified ″BAK12345″ in a mail recipient field the resulting filter used
on the LDAP search request would be:
(uid=BAK12345)

Authentication Filter If directory assistance is configured to trust a remote LDAP directory for client authentication,
this filter is used to look up a name in the directory. Leave the field blank to use the
following default search filter:

(|(cn=%*)(|(&(sn=%a)(givenname=%z))(&(sn=%z)(givenname=%a))))

If a user specified ″Maryanne Brown″ in the HTTP login prompt, the resulting filter used on
the LDAP search request would be:
(|(cn=Maryanne Brown)(|(&(sn=Maryanne)(givenname=Brown))(&(sn=Brown)
(givenname=Maryanne))))

You may want to customize the authentication filter if users typically specify their employee
ID or mail attribute at the login prompt. In this case, the custom filter would look similar to:
(|(employeeID=%*)(mail=%*))

So, if a user specified ″MB12345″ at the login prompt, the resulting filter used on the LDAP
search request would be:
(|(employeeID=AS12345)(mail=AS12345))
Authorization Filter Specify a search filter to use to look up the members of groups for Notes database
authorization. Leave the field blank to use the following default search filter:
(|(&(objectclass=groupOfUniqueNames)(UniqueMember=%*))
(&(objectclass=groupOfNames)(Member=%*)))

In this case, a membership lookup on ″cn=June Day,ou=Westford,o=Acme″ would result in

the following filter on the search request:
(|(&(objectclass=groupOfUniqueNames)(UniqueMember=
cn=June Day,ou=Sales,o=Acme))(&(objectclass=groupOfNames)
(Member=cn=June Day,ou=Sales,o=Acme)))

If the LDAP server that is enabled for ACL group expansion stores the groups with an
objectClass of aclGroup, then you may want to specify the following custom filter:
(&(objectclass=aclGroup)(Member=%*))

In this case a membership lookup on ″cn=June Day,ou=Sales,o=Acme″ would use the

following filter on the LDAP search request:
(&(objectclass=aclGroup)(Member=cn=June Day,ou=Sales,o=Acme))

594 Lotus Domino Administrator 7 Help

To define custom search filters, you should be familiar with valid search filter syntax described in RFCs
2251 and 2254.

Syntax for custom LDAP search filters: To define a custom search filter, insert parameters into standard
LDAP search filters to represent a part of the names being searched for.

Example of name Parameter to insert to

Name part Defined as part (in bold) represent name part
First name The set of characters from the Alex M Davidson %a
first character to the first space
or punctuation
Last name The set of characters from the Alex M Davidson %z
last space or punctuation to
the last character
Whole name The entire name Alex M Davidson %*
Local part Local part of an RFC 822 mail amd@acme.com %l
address
Domain part Domain part of an RFC 822 amd@acme.com %d
mail address
Any string value The string value of the For example, if a %s
attribute or object that is being search contains a filter
searched for. where ″uid=%s″, then
the name part
represented by %s in
this case is amd.

Examples of custom LDAP search filters:

Search filter formula in Directory

Name searched for Assistance document Search filter used to search for the name
Alex M Davidson (|(givenname=%a)(sn=%z) (|(givenname=Alex)(sn=Davidson) (cn=Alex M
(cn=%*)(mail=%l)) Davidson)(mail=″″))
amd (EmpID=%*) (EmpID=amd)
amd (EmpID=%z) (EmpID=″″)
amd (mail=%*@acme.com) (mail=amd@acme.com)
amd (mail=%*@*) (mail=amd@*)
amd@acme.com (mail=*@%d) (mail=*@acme.com)
amd@acme.com (mail=%*) (mail=amd@acme.com)
amd@acme.com (uid=%l) (uid=amd)
blue (color=%*) (color=blue)

Configuring alias dereferencing in a Directory Assistance document for a remote LDAP directory: An
alias entry in an LDAP directory is an entry that points to another entry. Searching the entry an alias
entry points to is known as dereferencing an alias. Dereferencing aliases can cause poor search
performance for some LDAP directories. Select one of the following options in the ″Dereference alias on
search″ field in a Directory Assistance document for an LDAP directory to control the extent to which
alias dereferencing occurs when searching the remote LDAP directory.

Chapter 25. Setting Up Directory Assistance 595

Option Description
Never Never dereference alias entries. If there are no alias entries in the LDAP
directory that require dereferencing, choose this option to improve search
performance.
Only for subordinate entries Dereference alias entries subordinate to a specified search base, but do not
dereference an alias search base entry.
Only for search base entries Deference an alias entry for a specified search base, but do not dereference
alias entries subordinate to the search base.
Always Always dereference aliases. This selection is the default, and the Release 5
behavior.

Example of alias dereferencing: Suppose an LDAP directory has these entries:

o=Acme1

o=Acme2 (alias entry that points to o=Acme1)

cn=John Doe, o=Acme1

cn=John Doe, o=Acme2 (alias entry that points to cn=John Doe, o=Acme1)

The following table describes which of these entries are returned for a subtree search of o=Acme 2
(o=Acme2 and subordinate entries) for each ″Dereference alias on search″ option.

Option Entries returned

Never o=Acme2

cn=John Doe, o=Acme2

Only for subordinate entries o=Acme2

cn=John Doe, o=Acme1

Only for search base entries o=Acme1

cn=John Doe, o=Acme2

Always o=Acme1

cn=John Doe, o=Acme1

Using Notes distinguished names in a remote LDAP directory: You can set up directory assistance for
a remote LDAP directory so that a Domino server:
v Uses a Notes distinguished name rather than an LDAP distinguished name for Internet client
authentication
v Accepts the Notes distinguished name in database ACLs, and in groups used in database ACLs, for
database access authorization.

This feature allows organizations that migrate users from a Domino Directory to a remote LDAP
directory to continue to use the original Notes distinguished names for users. This feature is also useful
as a way to hide complex LDAP distinguished names from users.

To set up this feature, you add an attribute for storing Notes name values to the user entries in the LDAP
directory, and then add the Notes distinguished names as values for the attributes. Then you specify the
attribute you use for the Notes names in a Directory Assistance document for the LDAP directory.

596 Lotus Domino Administrator 7 Help

Once you have set up this feature, clients can authenticate using either their Notes distinguished names
or their original LDAP distinguished names. Database ACLs, Server document access control fields,
access control groups, and Web server File Protection documents can use only the Notes distinguished
names.

To set up the use of Notes distinguished names:

1. To add the Notes distinguished names to the LDAP directory, In the remote LDAP directory, choose
an attribute for storing the values of the Notes names in the LDAP directory user entries. The syntax
for the attribute must be DN. You can create a new attribute, or use an existing one already defined in
the schema.
2. Add Notes names as values for the selected attribute to the remote LDAP directory user entries.
v Domino doesn’t provide a tool to add the names -- use a tool that is available to you.
v Use the LDAP format for the Notes name value. For example, use cn=John Doe,o=Acme and not
John Doe/Acme or cn=John Doe/o=Acme.
v You can use any distinguished name value, although a distinguished name with multiple parts is
recommended because it provides better security.
3. Set up directory assistance to use the Notes distinguished names:
a. If you haven’t created a Directory Assistance document for the LDAP directory, create one.
b. On the LDAP tab of the Directory Assistance document, in the ″Attribute to be used as Notes
distinguished name″ field, add the name of the attribute used in the LDAP directory to store the
Notes names.
c. On the ″Naming contexts (rules) tab″ of the Directory Assistance document, make sure there are
rules that are ″Trusted for Credentials″ that match the Notes distinguished names and the LDAP
distinguished names. If you do not use an all-asterisk trusted rule and the Notes and LDAP names
use different name hierarchies, configure a trusted rule to represent each hierarchy.
d. Save the Directory Assistance document.
4. Add the Notes distinguished names as necessary to database ACLs, Server document access control
fields, access control groups, and Web server File Protection documents. Use the Notes format for the
name, for example John Doe/Acme or cn=John Doe/o=Acme and not the LDAP format cn=John Doe,
o=Acme.

Note: If you enable this feature and some user entries in the LDAP directory do not have a value for the
Notes distinguished name attribute, then the users must specify their LDAP distinguished names to
authenticate, and Domino database ACLs and other access control lists must use the LDAP distinguished
names.

Example of using Notes distinguished names in a remote LDAP directory: Acme corporation uses the LDAP
distinguished name uid=675894,ou=boston,o=airius.com for a particular user in a remote LDAP directory.
For the same user Acme uses the name Jack Johnson/Boston/Acme in Notes database ACLs and in
groups used in database ACLs. The Domino server uses directory assistance to look up user credentials
for client authentication in the remote LDAP directory.

An Acme administrator does the following to configure the use of the Notes distinguished name for
client authentication and for database access control:
1. In the remote LDAP directory, the administrator adds an attribute called notesname to the user entry
for uid=675894, ou=boston, o=airius, and gives the attribute the value cn=Jack
Johnson, ou=Boston,o=Acme.
2. On the LDAP tab of the Directory Assistance document for the LDAP directory, the administrator
adds the attribute notesname to the field ″Attribute to be used as Notes distinguished name.″
3. On the ″Naming contexts (rules)″ tab of the Directory Assistance document, the administrator
specifies an all-asterisk trusted rule.

The user can then use any of the following names as the client logon name for authentication:
Chapter 25. Setting Up Directory Assistance 597
v cn=Jack Johnson/ou=Boston/o=Acme
v cn=Jack Johnson, ou=Boston,o=Acme
v Jack Johnson/Boston/Acme
v uid=675894, ou=boston, o=airius
v 675894

The Notes name Jack Johnson/Boston/Acme is used in database ACLs and groups.

Special considerations for change detection: Some subsystems in the Domino server perform searches
against LDAP servers. Directory Assistance, for instance, uses and retains LDAP search results for a
period of time, eliminating the need to obtain refreshed information from the LDAPservers. Domino 7
allows these subsystems to quickly detect if entries in certain LDAP directories have changed, allowing
Domino subsystems to flush stale search results and conduct another search for current LDAP
information.

Domino 7 takes advantage of LDAP servers that support the following change detection mechanisms.
While Domino automatically senses the LDAP server’s change detection mechanism, so configuration
user interfaces are not necessary to enable this feature, there may be requirements for the existing
Directory Assistance LDAP or (target) LDAP server settings.

Change Detection Mechanism Tested Products Settings Notes

Microsoft Active Directory Windows 2000 Server v The Directory Assistance LDAP
document should specify a user who is
a member of the Active Directory’s
″Administrators″ group.
v Cannot detect renames of Active
Directory objects
v Change detection is limited to the
Directory Assistance LDAP document’s
search base setting, hence this setting
must be specified.
Windows 2003 Server Same as above
LDAP Change Log IBM Tivoli Directory Server 5.1 v If the IBM Directory Server does not
have Change Log enabled, see the IBM
Directory Server Administration Guide
for more information about enabling it.
If change log is not enabled, the
default change detection mechanism
takes effect.
v The Directory Assistance LDAP
document should specify a user on the
LDAP server who has read access to its
″cn=changelog″ container.

598 Lotus Domino Administrator 7 Help

Change Detection Mechanism
Sun ONE Directory Server
Default (Domino 6)
Tested Products Settings Notes
v The Sun ONE Directory Server
supports change log through
its Retro Change Log Plug-in.
See the Sun ONE Directory
Server Administration Guide
for information on enabling the
plug-in. If change log is not
enabled, the default change
detection mechanism takes
effect.
v The Directory Assistance LDAP
document should specify a
user on the LDAP server who
has read access to the
″cn=changelog″ container.
* Reports hourly change of the LDAP
directory whether the directory has
changed or not. No interchange with the
LDAP server is performed at all. This is
the only ″change detection″ supplied in
Domino 6.

Directory assistance examples

v Example of directory assistance for one secondary Domino Directory
v Example of directory assistance for an Extended Directory Catalog
v Example of directory assistance for an Extended Directory Catalog and a remote LDAP directory

Example of directory assistance for one secondary Domino Directory

Company X uses two domains, Domain A and Domain B. Each domain creates its own directory
assistance database that has a Directory Assistance document for the other domain’s Domino Directory, so
that users from each domain can address mail easily to users in the other domain, and so servers in each
domain can search groups in the other domain’s directory when authorizing database access. If servers in
both domains instead used replicas of one directory assistance database that included documents for both
directories, they could enable only one of the domain directories for group authorization.

Network connections between domains are slow, so the company creates replicas of the Domain B
directory on two Domain A servers for servers in Domain A to use, and creates replicas of the Domain A
directory on two Domain B servers for servers in Domain B to use.

The following table shows the settings for the Domain B Directory Assistance document in the directory
assistance database that servers in Domain A use. Domain B uses a similar document for the Domain A
directory in its directory assistance database.

Basics tab Contents Comments

Domain type Notes --
Domain name Domain B --
Company name Company A --
Search order None --

Chapter 25. Setting Up Directory Assistance 599

Basics tab Contents Comments
Make this domain available Selected for: Enables Domain A servers to use the
to v Notes Clients Domain B directory for all directory
InternetAuthentication/Authorization assistance services.
v LDAP Clients
Group Authorization Yes Allows Domain A servers to to look up
groups in the Domain B directory when
authorizing database access.
Enabled Yes --
Naming contexts (rules) tab
N.C.1: */ */ */ */ */ * Enables Domain A servers to search all
names in the directory. ″Trusted for
Enabled - Yes Credentials″ selected to allow servers to
authenticate all Internet users registered
Trusted for Credentials - Yes in the directory.
Replicas tab
Replica1: Server Name: Server1/DomainA More than one replica of the Domain A
directory is specified, indicating that the
Directory Filename: DOMANAMES.NSF directory assistance method of failover is
used to find an available replica.
Replica2 Server Name: Server2/DomainA Same comments as above.

Directory Filename: DOMANAMES.NSF

Example of directory assistance for an Extended Directory Catalog

Company Y uses three domains, Domain A, Domain B, and Domain C. Rather than setting up directory
assistance to search each domain Domino Directory individually, the company builds an Extended
Directory Catalog that aggregates all three domain directories. Using this approach, Notes users can use
one directory to browse for names registered in any domain directory, servers can use one directory to
look up names from any domain, for example, when routing mail, and servers can look up the members
of groups aggregated from any of the three directories when authorizing database access.

The company creates replicas of the Extended Directory Catalog on two servers in Domain A that are
members of a cluster. Network connections between domains are fast, so servers in Domains B and C use
the replicas of the directory catalog on the Domain A servers.

Administrators from each domain want local control of the directory assistance database, so each domain
creates and uses its own directory assistance database.

The following table shows the settings for the Directory Assistance document for the Extended Directory
Catalog that is in each domain’s directory assistance database.

Basics tab Contents Comments

Domain type Notes --
Domain name EDC Made-up name that does not correspond to
an actual domain name.
Company name Company Y --
Search order None --
Make this domain available v Notes Clients & Internet Allows servers to use the Extended
to Authentication/Authorization Directory Catalog for all directory assistance
services.
v LDAP Clients

600 Lotus Domino Administrator 7 Help

Basics tab Contents Comments
Group Authorization Yes Allows servers to look up groups in the
Extended Directory Catalog when
authorizing database access.
Enabled Yes --
Naming contexts (rules) tab
N.C.1: */ */ */ */ */ * Allows servers to search all names in the
Extended Directory Catalog. ″Trusted for
Enabled - Yes Credentials″ selected to allow servers to
authenticate all Internet users with Person
Trusted for Credentials - Yes documents that are aggregated in the
directory catalog.
Replicas tab
Replica1: Server Name: Server1/DomainA Server1/DomainA is a member of a cluster.
Only one replica of the Extended Directory
Directory Filename: EDC.NSF Catalog in the cluster is specified so that
cluster failover is used to find an available
replica.

Example of directory assistance for an Extended Directory Catalog and a remote

LDAP directory
Company Z uses three domains, Domain A, Domain B, and Domain C. The company builds an Extended
Directory Catalog that aggregates all three domain Domino Directories. Network connections between
domains are slow, so Company Z replicates the Extended Directory Catalog to strategic servers in each
domain. In Domain A, the directory catalog is replicated to two servers that are members of a cluster.

Domino servers in Domain A register Internet users in a remote Active Directory server which they use
to authenticate the users. Domain A creates its own directory assistance database because only Domain A
servers use the remote Active Directory.

The following tables show the settings in the Directory Assistance documents for the Extended Directory
Catalog and for the remote Active Directory server in the directory assistance database that Domain A
servers use.

Directory Assistance document for the Extended Directory Catalog:

Basics tab Contents Comments

Domain type Notes --
Domain name EDC Made-up name that does not correspond to an
actual domain name in Domino.
Company name Company Z --
Search order 1 Causes Domain A servers to search the
Extended Directory Catalog before the remote
Active Directory.
Make this domain available v Notes Clients & Internet
to Authenticatoin/Authorization
v LDAP Clients
Group Authorization Yes Allows servers to use groups from any of the
directories aggregated into the directory catalog
for database authorization.
Enabled Yes --

Chapter 25. Setting Up Directory Assistance 601

Basics tab Contents Comments
Naming contexts (rules) tab
N.C.1: */ */ */ */ */ * Allows servers to search all entries in the
directory. ″Trusted for Credentials″ set to ″No″
Enabled - Yes to prevent the Extended Directory Catalog from
being used for Internet client authentication, and
Trusted for Credentials - No allow only the remote Active Directory to be
used for this purpose.
Replicas tab
Replica1: Server Name: Server1/DomainA Server1/DomainA is a member of a cluster.
Only one replica of the Extended Directory
Directory Filename: EDC.NSF Catalog in the cluster is specified so that cluster
failover is used to find an available replica.

Directory Assistance document for the remote LDAP Directory:

Basics tab Contents Comments

Domain type LDAP --
Domain name ActiveDir Made-up name that does not correspond to an
actual domain name in Domino.
Company name Company Z --
Search order 2 Causes Domain A servers to search the remote
Active Directory after the Extended Directory
Catalog.
Make this domain available to Notes Clients & Internet Domain A does not want its LDAP service to
Authentication/Authorization refer LDAP clients to the Active Directory, so it
does not select the ″LDAP Clients″ option.
Group Authorization No. Since Domain A servers look up groups used for
database authorization in the Extended Directory
Catalog, they cannot use the remote Active
Directory for this purpose too. All groups used
for database authorization are stored in the
Domain A primary Domino Directory and in the
domain directories that are aggregated into the
Extended Directory Catalog.
Enabled Yes. --
Naming contexts (rules) tab
N.C.1: */ */ */ */ */ * The distinguished names of the users registered
in the Active Directory do not correspond to the
Enabled - Yes Notes naming convention of organizational unit
(ou), organization (o), and country (c). So
Trusted for Credentials - Yes Company Z must use an all-asterisk rule to
represent the distinguished names of these users.

″Trusted for Credentials″ is enabled for the

naming context (rule) so that Domain A can use
the user entries in Active Directory for Internet
client authentication.
LDAP tab
Hostname ldap1.companyz.com, To provide failover, two Active Directory servers
ldap2.companyz.com are specified, each with replicas of the directory
and with the same LDAP configurations.

602 Lotus Domino Administrator 7 Help

Basics tab
Optional Authentication
Credential
Base DN for search
Channel encryption
Port
Accept expired SSL certificates
SSL protocol version
Verify server name with remote
server’s certificate
Timeout
Maximum number of entries
returned
Dereference alias on search
Preferred mail format
Attribute to be used as Notes
Distinguished Name
Type of search filter to use
Monitoring directory assistance
To monitor directory assistance:
v Use the Show Xdir command to display information about all the directories a server uses for directory
services.
v View these directory assistance statistics, which a server begins calculating at startup:
Statisic
Database.DAReloadCount
Database.DARefreshServerInfoCount
Database.DAFailoverCount
Contents Comments
Username: cn=john doe, --
cn=recipients, dc=east,
dc=acme, dc=com
Password: adminspass
cn=recipients, dc=east, --
dc=acme, dc=com
Yes Since DomainA servers use the Active Directory
for client authentication, Company Z selects the
″Channel Encryption″ so that Domino servers can
use a Secure Sockets Layer (SSL) certificate to
verify the Active Directory server’s identity.
636 Necessary for SSL connections.
Yes --
Negotiated --
Yes --
60 --
100 --
Never The Active Directory server does not use alias
dereferencing so Company Z selects Never to
improve search performance.
Internet Mail Address --
notesname Company Z uses Notes-style distinguished
names, rather than the original LDAP names of
the users in the Active Directory, for client
authentication and in Notes database ACLs. The
specified attribute, notesname, is defined in
Active Directory as the attribute to store the
Notes name. Company Z uses its own tool to add
Notes-style distinguished names as values for the
notesname attribute in user entries.
Active Directory Ensures that the Domain A servers use LDAP
search filters that are customized for Active
Directory searches.
Description
Number of times directory assistance reloaded because of changes to
the directory assistance database.
Number of times directory assistance refreshed because of changes
to Server documents in the Domino Directory.
Number of times directory assistance failed over to an available
replica.
Chapter 25. Setting Up Directory Assistance 603
604 Lotus Domino Administrator 7 Help
Chapter 26. Setting Up Directory Catalogs
This chapter describes how to set up and manage directory catalogs.

Directory Catalogs
A directory catalog is an optional directory database that typically contains information aggregated from
multiple Domino Directories. Clients and servers can use a directory catalog to look up mail addresses
and other information about the people, groups, mail-in databases, and resources throughout an
organization, regardless of the number of Domino domains and Domino Directories the organization
uses. A directory catalog includes the type of information that is important for directory services, and
excludes other types of information that are part of a Domino Directory, for example Domino
configuration information, such as information in Connection documents.

You use a directory catalog in conjunction with, rather than instead of, the primary Domino Directory
and the Personal Address Book. A server searches its primary Domino Directory, and a Notes client
searches its Personal Address Book, before searching a directory catalog.

There are two types of directory catalogs: condensed Directory Catalogs and Extended Directory
Catalogs. Condensed Directory Catalogs use a unique design based on the DIRCAT5.NTF template that
enables them to be extremely small. Condensed Directory Catalogs are designed for use on Notes clients.
A condensed Directory Catalog on a Notes client is also known as a Mobile Directory Catalog.

Extended Directory Catalogs use the same design as the Domino Directory, which is based on the
PUBNAMES.NTF. They are larger than condensed Directory Catalogs, but are the recommended directory
catalog for server use because they allow faster and more flexible directory lookups.

Servers can use a directory catalog for mail addressing, for processing LDAP service operations, to look
up client authentication credentials, and to look up the members of groups in database ACLs when
authorizing users’ database access.

Condensed Directory Catalogs

You create a condensed Directory Catalog from the Directory Catalog template (DIRCAT5.NTF).
Condensed Directory Catalogs are designed to be small enough to fit on Notes clients. For example,
several Domino directories that together contain more than 350,000 users and total 3GB in size, when
aggregated in a condensed Directory Catalog are likely to be only about 50MB. In general, each user and
group entry is slightly more than 100 bytes. Condensed directory catalog are designed primarily for use
on Notes clients.

To achieve its small size, a condensed Directory Catalog uses a unique design that combines multiple
documents from the Domino Directories into single documents in the directory catalog, and that limits
the number of sorted views available for lookups.

Aggregate documents
One reason a condensed Directory Catalog is small is it combines many entries from the source Domino
Directories into single aggregate documents. A single Directory Catalog aggregate document can contain
up to 250 source directory entries, although on average the maximum is about 200. This means that a
condensed Directory Catalog needs to use only about 1000 aggregate documents to store information
from 200,000 documents in the source Domino Directories.

605
Limited number of views
A condensed Directory Catalog is also small because it contains only a few, small views. By contrast a
Domino Directory and an Extended Directory Catalog have multiple, typically large views.

$Users view This is the one view used in a condensed Directory Catalog for name lookups. When you
configure the directory catalog you choose how to sort this view, either by distinguished name, by last
name, or by alternate name. To find names that don’t correspond to the selected sort order, a full-text
search is done of the directory catalog rather than a view lookup.

You shouldn’t open the aggregate documents in the $Users view manually; these documents are not
intended for viewing, and it can take a considerable amount of time to format them for that purpose.

$Unid view This view contains information needed by the Dircat task to replicate the source directory
entries into the directory catalog. The $Unid view isn’t created on replicas of the directory catalog, which
further reduces the directory catalog size.

$PeopleGroupsFlat view This view displays directory names when Notes users click the Address button
to browse directories.

Configuration view This view shows the Configuration document that contains the directory catalog
configuration settings.

Users view This is a view that users can open and programs can access to see the names included in the
directory catalog. This view is not stored on disk but is instead built as needed.

Design changes
In general, you should not change the database design of a condensed Directory Catalog. One exception
is changing the name of the Users view; you can change the name of this view, as long as you keep the
original view name, Users, as an alias.

Application access
Notes applications can use these methods to access a condensed Directory Catalog programmatically:
v NAMELookup calls to the $Users view
v NAMEGetAddressBooks calls, if you use the NOTES.INI setting Name_Include_Ed=1.
v NIFFindByKey, NIFReadEntries, and NIFOpenNote calls.* You can’t use NSFNoteOpen to open notes
passed back from NIFReadEntries; you must call NIFOpenNote instead.
v LotusScript methods*
v @NameLookup function

*Can access the Users view but not the $Users view.

In addition, LDAP applications can search a condensed Directory Catalog used by a server that runs the
LDAP service.

Benefits of condensed Directory Catalogs on clients (Mobile Directory Catalogs)

Condensed Directory Catalogs on Notes clients, also called Mobile Directory Catalogs, are useful to
organizations that use one or multiple Domino Directories. Although Notes users’ mail or directory
servers can do lookups in Domino Directories on behalf of Notes users, using condensed Directory
Catalogs on Notes clients instead offers these benefits:
v Notes users have access to one local, corporate-wide directory, even when their clients are disconnected
from the network.
v When they address mail, users can press F9 to verify quickly the address of anyone in the
organization.

606 Lotus Domino Administrator 7 Help

v Users can flag mail for encryption when using clients that are disconnected from the network. The
clients look up the public key and encrypt the mail when the users connect to the network and send
the mail.
v Groups are included in a directory catalog by default, so users can send mail to groups. However, to
minimize the size of the directory catalog, the members of the groups are not included by default, so
users’ mail servers or directory servers must be able to look up the members of the groups.
v Type-ahead name resolution is instantaneous because type-ahead searches the local directory catalog.
Type-ahead searches never extend to a server when there is a directory catalog configured locally on
the client.
v Users can use the detailed search feature available for Local Address Books to search the directory
catalog. For example, if a user wants to send mail to someone by the name of Robin at the Los Angeles
location but doesn’t remember Robin’s last name, the user can search for ″First name″ Robin and
″Location″ Los Angeles to retrieve the name from the directory catalog.
v Users can use the Mail Address dialog box to open and scroll through the names in the directory
catalog.
v Using Soundex, users can enter phonetic spellings to search for names they don’t know how to spell.
v Network traffic is reduced because name resolution occurs locally on the client, rather than on a server.

Directory catalogs on servers compared to directory assistance for

individual Domino Directories
A server can do lookups directly in a secondary Domino Directory using directory assistance, or can do
lookups in a directory catalog that aggregates information from the secondary Domino Directory. There
are several advantages to servers doing lookups in a directory catalog, rather than in individual Domino
Directories:
v A server can look up information more quickly by searching one directory database rather than
multiple databases -- the more secondary directories you aggregate in a directory catalog, the greater
this advantage.
v If there are multiple Person documents with the same name in one directory or across directories, you
can remove the duplicates from the directory catalog. The Dircat task then aggregates the first Person
document with the name that is encountered, which avoids name ambiguity problems, for example,
the Router failing to deliver mail because it finds more than one occurrence of a name.
v A directory catalog excludes most or all Domino administration information that is part of a Domino
Directory that is not of interest to users. You can also filter out other information in a Domino
Directory from a directory catalog. For example, an administrator can exclude specific fields, or use a
selection formula to exclude documents that don’t match specified criteria.
v Notes users without local condensed Directory Catalogs, can browse one directory, rather than
multiple, individual secondary Domino Directories.

The advantage to doing lookups in individual secondary Domino Directories is there is no need to build,
maintain, and replicate a directory catalog. Instead you create and replicate only a small directory
assistance database.

Setting up servers to use directory catalogs is useful for organizations that use multiple Domino
Directories, for example, organizations with multiple Domino domains.

Extended Directory Catalogs

You can set up servers to use an Extended Directory Catalog. You create an Extended Directory Catalog
from the PUBNAMES.NTF template, the same template used to create the Domino Directory. An
Extended Directory Catalog combines advantages of a Domino Directory and a condensed Directory
Catalog. It aggregates entries from multiple Domino directories into a single directory database as does
the condensed Directory Catalog, but it retains the individual documents and the multiple, sorted views
available in the Domino Directory to facilitate quick name lookups.

Chapter 26. Setting Up Directory Catalogs 607

Although you can set up servers to use a condensed Directory Catalog, there are several advantages to
using an Extended Directory Catalog instead.

Multiple views
The Extended Directory Catalog uses the same design as the Domino Directory, so it includes multiple
views that sort names in different ways. Regardless of the format of a name, there’s a view in the
Extended Directory Catalog that a server can use to quickly find the name. A condensed Directory
Catalog has one view used for lookups, which you choose how to sort when you configure it. To look up
a name in a condensed Directory Catalog that doesn’t correspond to the selected sort order, the server
uses the full-text index to search for the name, which takes longer than a view search.

Using an Extended Directory Catalog on servers that route mail is a particular advantage, because a mail
server can use views to quickly find an address regardless of the address format. When a mail server
uses a condensed Directory Catalog, mail routing can back up if the Router uses the full-text index to
look up addresses, for example, some Internet addresses, that don’t correspond to the selected sort order.

When a Notes user with a condensed Directory Catalog on the client sends mail to a group, if the client’s
directory catalog doesn’t contain the members of the group, there can be a delay while a server does a
full-text search of a condensed Directory Catalog to look up the members. Delays when sending mail to
groups are not an issue if mail servers use Extended Directory Catalogs.

Ease of application access

Applications can access information in an Extended Directory Catalog as easily as they can in a Domino
Directory. Application access to a condensed Directory Catalog however is restricted by the nature of the
aggregate documents and the number of views.

Multiple-view, enterprise directory

Users can open an Extended Directory Catalog and see an enterprise-wide directory with multiple views
that sort by entry type. In a condensed Directory Catalog, there is only one view to display the different
types of entries.

Groups for database authorization

Servers can use groups in only one directory configured in a directory assistance database, in addition to
the primary Domino Directory for authorizing database access. Using an Extended Directory Catalog for
this purpose, effectively allows servers to use groups in any secondary Domino Directory aggregated in
the directory catalog for database access control.

Remote lookups
Servers use Directory Assistance to locate an Extended Directory Catalog, so you need to replicate the
Extended Directory Catalog only to two or a few strategic servers to which the Directory Assistance
database then points. You can configure failover so that if one replica of the directory catalog is
unavailable, servers can use an alternate.

Each server that uses a condensed Directory Catalog requires a local replica of the directory catalog,
which makes its smaller size less of an advantage overall.

Administrator control over rebuilds

Rebuilding a directory catalog removes all of the existing aggregated information, and then re-aggregates
the information from the source Domino Directories. Since this process is time consuming, the Dircat task
only rebuilds an Extended Directory Catalog when an administrator indicates. Changing almost any field
in the configuration document for a condensed Directory Catalog, by contrast, triggers the Dircat task to
rebuild the directory catalog automatically.

Extended ACL and LDAP access control settings

You can use an extended ACL to refine the overall database access to an Extended Directory Catalog. For
example, you can deny access to sensitive fields, to entire documents associated with a particular part of

608 Lotus Domino Administrator 7 Help

a name hierarchy, and so forth. An extended ACL on an Extended Directory Catalog is independent of
any Extended ACLs set on the individual source Domino Directories.

You can also create a Configuration Settings document in an Extended Directory Catalog and use access
control settings on the LDAP tab of the document to control anonymous LDAP search access to the
directory catalog.

These access control features are not available for a condensed Directory Catalog.

Native documents
You can add documents manually to an Extended Directory Catalog, in addition to aggregating
documents through Dircat task processing. These ″native″ documents that originate in the database are
not affected by Dircat task processing. You cannot add native documents to a condensed Directory
Catalog.

Full-text index advantages

An Extended Directory Catalog has multiple, sorted views, so in general no full-text index is required for
lookups, which helps minimize disk space usage. A full-text index is required, however, if you want the
LDAP service to use an Extended Directory Catalog to process searches that use search filters based on
something other than names or mail addresses.

A full-text index is always required for a condensed Directory Catalog.

If you choose to create a full-text index on an Extended Directory Catalog, users can do full-text searches
of it from the Notes client. Users can’t do full-text searches of a condensed Directory Catalog from the
Notes client.

One server using more than one

A server can use more than one Extended Directory Catalog, for example one that aggregates directories
that are trusted for Internet client authentication, and another that aggregates directories that are not
trusted for client authentication.

A server can use one condensed Directory Catalog only.

Integration into a primary Domino Directory

Because an Extended Directory Catalog uses the same design as a Domino Directory, you can build an
Extended Directory Catalog directly into the primary Domino Directory for a domain, so that one
directory contains the information for an entire enterprise.

Server documents
You can aggregate Server documents into an Extended Directory Catalog, but not a condensed Directory
Catalog.

Overview of directory catalog setup

To set up a directory catalog, you first create a directory catalog database. You use the PUBNAMES.NTF
template to create an Extended Directory Catalog and the DIRCAT5.NTF template to create a condensed
Directory Catalog (CDC). In the directory catalog database you create a configuration document in which
you indicate which Domino Directories -- known as the source Domino Directories -- to aggregate, which
information from them to aggregate, and other options.

When the Dircat task combines multiple documents from source Domino directories into single
documents in a condensed Directory Catalog, the intra-document ordering must match the view’s default
sort ordering. You set the CDC’s view sort ordering through File - Database - Properties - Design ″Default
sort order″

Chapter 26. Setting Up Directory Catalogs 609

For information on creating and completing a directory catalog configuration document, see the next
topic ″Planning directory catalogs″ as well as the topics ″Setting up a condensed Directory Catalog″ and
″Setting up an Extended Directory Catalog″ later in the chapter.

After you complete the configuration document, you run the Directory Cataloger task (Dircat task) to
build the directory catalog. A server that runs the Dircat task is referred to as a Dircat server, and
typically there is one Dircat server dedicated to aggregating directory catalogs. The Dircat task replicates
information from the Domino Directories indicated in the configuration document, and then combines --
aggregates -- the entries into the directory catalog. After the directory catalog is built, you then continue
to run the Dircat task at regular intervals to keep the information in the directory catalog current with the
information in the source Domino Directories. The Dircat task can build and maintain multiple directory
catalogs.

After the Dircat task has built a directory catalog, you set up clients and/or servers to use the directory
catalog. You can automate setting up a condensed Directory Catalog on clients by using a Setup policy
settings document or a Desktop policy settings document. This process replicates the directory catalog to
the client, and adds the directory catalog file name to ″Local address books″ field in the User Preferences
dialog for mail.

To set up a server to use an Extended Directory Catalog, you set up the server to use a directory
assistance database, and then create a Directory Assistance document in the database for the Extended
Directory Catalog. To set up a server to use a condensed Directory Catalog, you specify the file name of
the directory catalog in either the servers’ Server document, or in the Domino Directory Profile.

Planning directory catalogs

When planning directory catalogs, consider the following issues:
v Directory catalogs and client authentication
v Directory catalogs and Notes mail encryption
v Picking the server(s) to run the Dircat task
v Specifying the Domino Directories for the Dircat task to aggregate
v Controlling which information is aggregated in a directory catalog
v Planning issues specific to Extended Directory Catalogs
v Planning issues specific to condensed Directory Catalogs
v Full-text indexing directory catalogs
v Multiple directory catalogs

Directory catalogs and client authentication

When an Internet client logs on to a server to authenticate, the server can look up the client name in the
directory catalog to find the client credentials for authentication.

Using an Extended Directory Catalog for client authentication

To allow a server to use an Extended Directory Catalog to look up client names for authentication, in the
Directory Assistance document for the Extended Directory Catalog, enable a rule that is trusted for
credentials.

In addition, if you don’t aggregate all fields from documents as recommended, you must make sure to
aggregate the fields required for the authentication. For example, to use name-and-password security,
aggregate the HTTPPassword field from Person documents. Or to use X.509 certificate security, aggregate
the userCertificate field.

If you want servers to use some secondary Domino Directories for Internet client authentication but not
others, you can create one Extended Directory Catalog that aggregates the Domino Directories to use for
authentication, and another that aggregates the other Domino Directories. Then create a Directory

610 Lotus Domino Administrator 7 Help

Assistance document for each Extended Directory Catalog, and enable a rule that is trusted for
credentials only in the one that aggregates the directories to be used for authentication.

Using a condensed Directory Catalog for client authentication

To enable a server to look up authentication credentials for any user name aggregated in a condensed
Directory Catalog, select the option ″Trust the server based condensed directory catalog for authentication
with internet protocols″ on the Basics tab of the server’s Server document in the Domino Directory.

To allow a server to look up credentials for user names from only one or some of the source Domino
Directories aggregated into a condensed Directory Catalog, do not select the above option. Instead, create
a directory assistance database on the server. In the database, create a Directory Assistance document for
each aggregated Domino Directory you want to use for authentication. In each Directory Assistance
document, enable a rule that is trusted for credentials.

If you use name-and-password security for Internet client authentication, you can store the passwords in
the condensed Directory Catalog. To do this, aggregate the HTTPPassword field from Person documents.
In this case, a server looks up the passwords in the directory catalog, and doesn’t require directory
assistance to look them up in the source Domino Directories.

If you use X.509 certificates for client authentication, storing the certificates in a condensed Directory
Catalog isn’t recommended due to their size. Instead, set up directory assistance to look up the
certificates directly in the source Domino Directories. Similarly, servers can use directory assistance to
look up passwords in the source Domino Directories, rather than aggregating the passwords into the
directory catalog, as a way to keep the condensed Directory Catalog small.

When you don’t store passwords and X.509 certificates in a directory catalog, using the directory catalog
and directory assistance in conjunction is quicker than using directory assistance alone, because only one
database, the directory catalog, needs to be used to find a name.

For more information on using directory assistance in conjunction with a directory catalog for client
authentication, see the chapter ″Setting Up Directory Assistance.″

Directory catalogs and Notes client authentication

By default, when a Notes client logs on to a server, the server does not look up information in Domino
Directory Person documents during the client authentication process. However, if the option ″Compare
Notes public keys against those stored in Directory″ is enabled in the server’s Server document, then the
server must be able to look up public key information in Person documents to authenticate Notes clients.
If there are Notes users who use a server with this option enabled who are not registered in the server’s
primary Domino Directory, servers can use a directory catalog that it trusts for credentials, to look up
names to do the public key comparison.

Scenarios for using directory catalogs for client authentication

The following table describes various ways to configure directory catalogs on servers to support client
authentication, depending on the type of directory catalog you are using and the extent to which you
want servers to trust the aggregated Domino Directories for authentication.

The scenarios assume the following:

v S1, S2, S3, and S4 are the names of the servers in a domain
v A, B, C, and D are the names of the Domino Directories for each of the organization’s four domains.
v Each name in A, B, C, and D is part of one of the following namespaces: west/acme, east/acme,
north/acme, south/acme. Namespaces overlap across A, B, C, and D.
v DA = Directory Assistance
v EDC = Extended Directory Catalog

Chapter 26. Setting Up Directory Catalogs 611

v CDC = Condensed Directory Catalog on server
Authentication goal
S1, S2, S3, S4 trust all names
in A, B, C, D for
authentication.
S1, S2, S3, S4 trust no names
in A, B, C, D for
authentication.
S1, S2, S3, S4 trust all names
in A and B for
authentication, but no names
in C and D.
S1, S2, S3, S4 trust only
names ending in west/acme
or east/acme, regardless of
which Domino Directory
contains the name.
S1 & S2 trust and use only
names in A and B.
S3 & S4 trust and use only
names in C and D.
612 Lotus Domino Administrator 7 Help
How to accomplish with Extended
Directory Catalog(s)
Aggregate A, B, C, and D into one EDC.
Create one DA database used by all
servers. Create one DA document for the
EDC with the */*/*/*/*/* naming rule
enabled and trusted for credentials.
Same as above except do no enable a
rule that is trusted for credentials in the
DA document for the EDC.
Aggregate A and B into EDC1, and
aggregate C and D into EDC2. Create
one DA database used by all servers.
Create a DA document for EDC1 with
the */*/*/*/*/* naming rule enabled
and trusted for credentials. Create a DA
document for EDC2 with the
*/*/*/*/*/* naming rule enabled but
not trusted for credentials.
Aggregate A, B, C, and D into one EDC.
Create one DA database used by all
servers and create one DA document for
the EDC. In the DA document, create
the rule */*/*/west/acme/* and the
rule */*/*/east/acme/* and enable
trusted for credentials for both rules. Do
not trust any other naming rule for
credentials.
Aggregate A and B into EDC1. Create a
DA database, DA1, and in it create a DA
document for EDC1 with the
*/*/*/*/*/* naming rule enabled and
trusted for credentials. Set up S1 and S2
to use DA1.
Aggregate C and D into EDC2. Create
another DA database, DA2, and in it
create a DA document for EDC2 with
the */*/*/*/*/* naming rule enabled
and trusted for credentials. Set up S3
and S4 to use DA2.
How to accomplish with condensed
Directory Catalog(s)
Aggregate A, B, C, and D into one CDC
used by all servers. In the Server
documents for each server, enable the
option ″Trust the server based condensed
directory catalog for authentication with
internet protocols.″
Same as above except do not enable ″Trust
the server based condensed directory
catalog for authentication with internet
protocols″ in the Server documents.
Aggregate A, B, C, and D into one CDC
used by all servers. Do not enable the
option ″Trust the server based condensed
directory catalog for authentication with
internet protocols″ in the Server
documents.
Create one DA database used by all the
servers. Create separate DA documents for
A, B, C, and D. In the DA documents for
A and B, enable the rule */*/*/*/*/* and
trust the rule for credentials. In the DA
documents for C and D, do not trust any
rule for credentials.
Aggregate A, B, C, and D into one CDC
used by all servers. Do not enable the
option ″Trust the server based condensed
directory catalog for authentication with
internet protocols″ in the Server
documents.
Create one DA database used by all the
servers. Create separate DA documents for
A, B, C, and D. In each DA document,
create the rule */*/*/west/acme/* and the
rule */*/*/east/acme/* and enable trusted
for credentials for both rules. Do not trust
any other naming rule in any of the DA
documents for credentials.
Aggregate A and B into CDC1 and set up
S1 and S2 to use CDC1. Enable the option
″Trust the server based condensed
directory catalog for authentication with
internet protocols″ in the S1 and S2 Server
documents.
Aggregate C and D into CDC2 and set up
S3 and S4 to use CDC2. Enable the option
″Trust the server based condensed
directory catalog for authentication with
internet protocols″ in the S3 and S4 Server
documents.
Directory catalogs and Notes mail encryption
When Notes users send encrypted mail to users registered in secondary Domino Directories, servers can
use an Extended Directory Catalog to look up the public keys of the recipients to encrypt the mail. Even
off-line Notes users with condensed Directory Catalogs can flag mail for encryption; then when they
reconnect to the network to send the mail, the clients look up the public keys in the Extended Directory
Catalog.

Storing public keys in a condensed Directory Catalog isn’t recommended because it greatly increases its
size. Instead, set up directory assistance for the aggregated Domino Directories so servers can look up the
public keys in them.

Servers do not have to trust a directory catalog or a Domino Directory for credentials to use the directory
to look up public keys for mail encryption.

Picking the server(s) to run the Dircat task

The Dircat task (Directory Cataloger) is the server task that initially aggregates information from source
Domino Directories into a directory catalog, and then continues to run at scheduled intervals to update
the directory catalog to reflect changes to the source Domino Directories, or to the directory catalog
configuration. The Dircat task aggregates both condensed Directory Catalogs and Extended Directory
Catalogs.

A server that runs the Dircat task (a Dircat server) should:

v Have enough disk space to store local replicas of the source Domino Directories that are aggregated, if
you choose to store the directories locally on the server, rather than have the server access them over
the network.
v Have enough disk space to store the resulting aggregated directory catalog(s) and full-text indexes.
Only condensed Directory Catalogs have full-text indexes by default.
v Be able to replicate the directory catalog(s) it aggregates to any servers and clients that will use them.

Typically it’s best to run the Dircat task to build and maintain a directory catalog on a server in one
domain, and then replicate the directory catalog to servers throughout an organization that need to use
the directory catalog. Using this approach, rather than having each domain build an maintain its own
version of the directory catalog, is beneficial because only one server then does the CPU-intensive Dircat
processing of the directory catalog. Aggregate the primary Domino Directory of the domain in which you
build the directory catalog so that servers in other domains can use the directory catalog to look up
information from the directory.

The Dircat task on one server can process more than one directory catalog. The Dircat task is
single-threaded so it processes directory catalogs sequentially rather than simultaneously. Because Dircat
is a CPU-intensive task, it’s often beneficial to dedicate one server solely to Dircat processing.

Allowing only one server to aggregate a directory catalog

You can run the Dircat task on more than one server, with each server aggregating separate directory
catalogs. Dircat tasks running on separate servers should never aggregate the same directory catalog,
however, because doing so causes replication conflicts in the directory catalog. When you configure a
directory catalog, choose the option ″Restrict aggregation to server″ in the configuration document for the
directory catalog to specify the name of the one server that can aggregate that directory catalog. If you
complete this field, when someone tries to run the Dircat task against a replica of the directory catalog on
a server not specified in the configuration document, the server aborts the Dircat task and returns the
message ″Aggregation of this catalog can only be done by servername.″

Chapter 26. Setting Up Directory Catalogs 613

Specifying the Domino Directories for the Dircat task to aggregate
The ″Directories to include″ field in a directory catalog configuration document is the field you use to
indicate which source Domino Directories the Dircat task aggregates. The Dircat task runs on the replicas
of the directories specified in the order in which you list them in the ″Directories to include″ field. Use
commas to separate source directory file names.

If you enable the option ″Remove duplicate users,″ if a user’s distinguished name is found in more than
one Person document, the Dircat task aggregates information from only the first Person document with
the name the Dircat task encounters, according to the order in which the source directories are listed in
the ″Directories to include″ field.

As the following table shows, you can store a source Domino Directory locally on a Dircat server, or on a
remote server that the Dircat server accesses over the network. It’s best to store the source directory
replicas locally for high availability and quick access. If you store replicas of the source directories locally,
make sure to keep them up-to-date by regularly replicating with the replicas on the remote servers.

If a Dircat server accesses the source Domino Directories over the network, it must have certifiers in
common with the servers that store the remote directories, or must be cross-certified with those servers.

Location of source Domino Directory Enter

Locally
Locally in a linked directory
Over the network on a mapped drive
Over the network through Domino
The file name -- for example, EASTNAMES.NSF
The file name, preceded by the linked directory -- for example,
DIRECTORIES\EASTNAMES.NSF
The file name and path -- for example, U:\DIRSERVER\NAMES.NSF
The file name in this syntax:

portname!!!servername!!filename

where:
v portname is the name you gave to the port
v servername is the hierarchical name of the server that stores the
directory
v filename is the file name for the directory on the server

For example:

TCPIP!!!dirserv/east/acme!!names.nsf

If you don’t care which port is used, omit the port, for example:

DIRSERV/EAST/ACME!!NAMES.NSF
Note: The server running the Dircat task must have a certifier in
common with the remote server, or be cross-certified with that server.

Controlling which information is aggregated into a directory catalog

Read these topics to learn about controlling which information the Dircat task aggregates into a directory
catalog:
v Types of documents the Dircat task can aggregate
v Removing duplicate user entries
v Choosing the types of groups to aggregate
v Using a selection formula
v Choosing the fields to aggregate

614 Lotus Domino Administrator 7 Help

Types of documents the Dircat task can aggregate
The Dircat task can aggregate information only from the following Domino Directory documents:

Option(s) in configuration document

Document type Aggregated by default? that affect aggregation of the document
Person Yes v ″Additional fields to include″
v ″Remove duplicate users″
v ″Selection Formula″
Group Yes (Mail and Multi-purpose types v ″Additional fields to include″
only, by default)
v ″Group types″
v ″Selection Formula″
Mail-in Database Yes v ″Additional fields to include″
v ″Include Mail-in Databases″
v ″Selection Formula″
Resource* Yes v ″Additional fields to include″
v ″Selection Formula″
Server (Extended Directory No v ″Additional fields to include″
Catalog only)
v ″Include Servers″
v ″Selection Formula″
Custom documents you’ve No v ″Additional fields to include″
added to a Domino Directory
v ″Selection Formula″

*Users can’t use a condensed Directory Catalog to reserve resources, only to view them.

Note: The Dircat task does not aggregate documents that contain Readers lists by default. Use the
NOTES.INI setting Dircat_Include_Readerslist_Notes to aggregate documents that contain Readers lists.

Removing duplicate user entries from a directory catalog

If there are multiple Person documents with the same distinguished name in the source Domino
Directories that are aggregated into a directory catalog, the ″Remove duplicate users″ field in a directory
catalog configuration document controls whether to aggregate information from all of the Person
documents, or just the first one the Dircat task encounters. Choose one:
v Yes (default) to aggregate information from only the first Person document encountered by the Dircat
task, according to the order in which you list the directories in the ″Directories to include″ field in the
directory catalog configuration document.
v No to aggregate information from multiple Person documents with the same name.

If there are occurrences of more than one Person document with the same distinguished name, and the
multiple documents really represent one user, keep ″Remove duplicate users″ selected so that:
v Notes users aren’t required to choose between duplicate entries in the ″Ambiguous Name″ dialog box
when they resolve the mail address for the name.
v The Router doesn’t encounter duplicates names that prevents it from delivering mail.

The ″Remove duplicate users″ field does not apply to Group documents. To distinguish between different
groups with the same name in multiple directories, the Dircat task uses the ″Domain defined by this
Domino Directory″ field in the Directory Profile of the source Domino Directories to append the domain
to all group names.

Chapter 26. Setting Up Directory Catalogs 615

Removing duplicate user entries from an Extended Directory Catalog to improve Dircat performance:
You can reduce the time it takes the Dircat task to run on an Extended Directory Catalog by selecting
″No″ to retain all entries with duplicate names. Doing so keeps the Dircat task from building a particular
view required for the removal of entries with duplicate names. Retaining entries with duplicate names
does not result in a similar performance gain for a condensed Directory Catalog.

Deleting Person documents from the source Domino Directories when ″Remove duplicate users″ is
selected: If you choose the ″Remove duplicate users″ option, and later remove a Person document from
a source Domino Directory that is the one aggregated into the directory catalog, the Dircat task removes
the corresponding user entry from the directory catalog the next time it runs, so the name is longer be
found in the directory catalog.

To cause the Dircat task to add the user entry back into the directory catalog, make a minor change to a
remaining Person document in one of the source Domino Directories for the user. The next time Dircat
runs, it then aggregates information from the remaining Person document into to the directory catalog.
You can also correct the problem by clicking the ″Clear History″ button in the directory catalog
configuration document, although this approach isn’t recommended because it causes a rebuild the entire
directory catalog.

For example, if Source Directory A and Source Directory B both contain a Person document with the
name Phyllis Spera/Acme, if ″Remove duplicate users″ is enabled and Directory A is listed first in the
″Directories to include″ field, when the Dircat tasks runs, it includes only the entry from Directory A. If
someone then removes the Person document from Directory A, the name Phyllis Spera/Acme is removed
from the directory catalog the next time Dircat runs. To add the name back, make a small change to the
remaining Person document in Directory B, so the Dircat task adds the name back to the directory catalog
the next time it runs.

Choosing the types of groups to aggregate in a directory catalog

The ″Group types″ directory catalog configuration option controls which types of groups the Dircat task
aggregates. Choose one of the following:
v ″Mail and Multi-purpose″ (default) to aggregate only these two types of groups from all of the
directories listed in the ″Directories to include″ field.
v ″Mail Only″ to aggregate only ″Mail only″ groups from all of the directories listed in the ″Directories to
include″ field.
v ″All″ to aggregate all types of groups from all the directories listed in the ″Directories to include″ field.
v ″All in first directory only″ to aggregate all types of groups, but only those from the first directory
listed in the ″Directories to include″ field.
v ″None″ to exclude all groups.

If your organization uses a Notes application to look up the members of ″Access Control List only,″
″Servers only,″ or ″Deny List Only″ groups in an Extended Directory Catalog or a condensed Directory
Catalog used by servers, choose ″All″ or ″All in first directory only″ to add these types of groups to the
directory catalog.

If the directory catalog you are configuring is an Extended Directory Catalog servers use to look up
groups to authorize users’ database access, and these groups in the source Domino Directories are
defined as ″ACL only″ groups, choose ″All″ or ″All in first directory only″ to ensure the groups are
aggregated.

LocalDomainServers and OtherDomainServers groups: The Dircat task doesn’t aggregate the
LocalDomainServers and OtherDomainServers groups into a directory catalog because the servers listed
in these groups can’t be used for mail addressing, and because excluding them improves performance of
the Dircat task.

616 Lotus Domino Administrator 7 Help

All groups aggregated as Multi-purpose groups, by default: By default, all groups aggregated into a
directory catalog are assigned the type ″Multi-purpose.″ For example, by default, a ″Mail only″ group in a
Domino Directory becomes a ″Multi-purpose″ group in the directory catalog. To keep the correct group
type definition for groups in a directory catalog, add the GroupType field to the directory catalog
configuration.

For more information, see ″Choosing which fields to aggregate in a directory catalog.″

Using a selection formula in a directory catalog configuration document

Use the ″Selection Formula″ field in a directory catalog configuration document to aggregate only
documents defined by a selection formula. For example, to aggregate only Person documents with a
value of ″Atlanta″ in the Location field, aggregate all Group documents, and exclude all other documents,
use the following selection formula:

SELECT (Form = ″Person″ & Location = ″Atlanta″) | (Form = ″Group″)

Or to aggregate only Person documents for people assigned to a specific mail server, use a selection
formula such as:

SELECT (Form = ″Person″ & MailServer = ″MailServer1″)

The ″Selection Formula″ field replaces the replication setting ″Receive only a subset of the documents″ -
″Documents that meet a selection formula″ used in other databases. Keep in mind that a selection
formula applies to all the aggregated directories, so the formula should be valid for all of them. Note that
you can’t use a selection formula to aggregate documents that are never aggregated into a directory
catalog. For example, you can’t use a selection formula to aggregate Server Configuration documents or
Server Connection documents.

For more information on selection formulas, see Domino Designer 7 Help.

How a selection formula interacts with the ″Group types″ option: The ″Group types″ field in a
directory catalog configuration document controls the types of groups that the Dircat task aggregates into
a directory catalog. If you use a selection formula and you want to aggregate groups, you must select the
groups as part of the selection formula as well as use the ″Group types″ field to indicate which types of
groups to aggregate. For example, to aggregate only Person documents with a Location of Atlanta, and
only Mail and Multipurpose groups:
v Use this selection formula: SELECT (Form = ″Person″ & Location = ″Atlanta″) | (Form = ″Group″)
v Select the ″Group Type″ option ″Mail and Multi-purpose.″

A selection formula can select only the types of groups indicated by the ″Group types″ option.

How a selection formula interacts with the ″Include Servers″ option: The ″Include Servers″ field in a
directory catalog configuration document for an Extended Directory Catalog controls whether the Dircat
task aggregate Server documents. If you use a selection formula that includes Server documents, you
must select the Server documents as part of the selection formula as well as select Yes in the ″Include
Servers″ field.

You cannot aggregate Server documents into a condensed Directory Catalog.

How a selection formula interacts with the ″Include Mail-In Databases″ option: The ″Include Mail-In
Databases″ option in a directory catalog configuration document controls whether to aggregate Mail-In
Database documents. If you use a selection formula that includes Mail-In Databases documents, you must
select the Mail-In Database documents as part of the selection formula, as well as select Yes for the
″Include Mail-In Databases″ option.

Chapter 26. Setting Up Directory Catalogs 617

Choosing which fields to aggregate in a directory catalog
By default, a directory catalog aggregates the following fields from the documents supported for
aggregation.

Field aggregated by default Documents that use the field

1
FullName Person, Mail-In Database, Resource
1
ListName Group
1
Type All
FirstName Person
MiddleInitial Person
LastName LastName
Location Person
MailAddress Person
Shortname Person
MailDomain Person, Group, Mail-In Database, Resource
InternetAddress Person, Group, Mail-In Database, Resource
MessageStorage Person, Mail-In Database
2
Members Group
2
AltFullName Person
2
AltFullNameLanguage Person

1
Required fields that ensure that each document aggregated in the directory catalog has a known name
and type
2
Aggregated by default only in an Extended Directory Catalog

Use the ″Additional fields to include″ field in a directory catalog configuration document to aggregate
additional fields into a directory catalog. To avoid making a mistake, use Domino Designer to copy and
paste the fields from forms in the Domino Directory template. Be sure to copy the field itself, not the
field label -- for example, copy the field OfficePhoneNumber, not the label Office phone.

If you use a directory catalog configuration option to exclude a particular type of document, that
document isn’t aggregated even if you specify a field from the document in the ″Additional fields to
include″ field. For example, if you choose ″None″ next to the ″Group types″ option, the Dircat task does
not aggregate group documents, even if the Members field is listed in the ″Additional fields to include″
field.

Guidelines for modifying the ″Additional fields to include″ field: Follow these general guidelines
when modifying the ″Additional fields to include″ configuration field:
v Do not remove the fields aggregated by default because these field selections are the optimum ones for
mail addressing.
v In an Extended Directory Catalog, aggregating all fields is recommended, since there is no way for
servers to use directory assistance to look up missing information directly in the full Domino
Directories themselves that are aggregated. To aggregate all fields from the aggregated documents,
including custom documents added to a Domino Directory, leave the ″Additional fields to include″
field blank. If you don’t aggregate all fields, then follow the guidelines described in the following table.

618 Lotus Domino Administrator 7 Help

v In a condensed Directory Catalog, aggregate as few fields as possible, to keep the directory catalog
small. When possible avoid aggregating fields that change frequently, since doing so requires Domino
frequently to update entries in the directory catalog and replicate the changes to other replicas of the
directory catalog.
v If the LDAP service searches an Extended Directory Catalog or condensed Directory Catalog on a
server, consider aggregating fields that are not part of the default configuration if LDAP clients
frequently search for these fields.
v If you use a subform to customize a Domino Directory template, you can add fields from the subform
to the ″Additional fields to include″ field. If you are adding custom fields to a condensed Directory
Catalog, you must first copy and paste the subform from the Domino Directory into the Directory
Catalog database that the Dircat task runs against.

In addition to the above general guidelines, follow these more specific guidelines:

Condensed Directory Condensed Directory Catalog

Field to add Catalog used by clients Extended Directory Catalog used by servers
Members field (from (Optional) Add only to (Required) Allows Notes (Required) Allows Notes
Group documents) allow Notes users who clients and servers to look up clients and servers to look up
are not connected to the the members of groups from the members of groups from
network to look up free secondary Domino Directories. secondary Domino
time schedules of other Directories.
users. Note that adding
the Members fields is not
generally recommended
because it increases the
directory catalog size and
requires more replication.
Use a server directory
catalog or directory
assistance to provide a
way for servers to look
up the members of
groups from a secondary
Domino Directory.
AltFullName, (Optional) Add if users (Recommended) Include this (Recommended) Include this
AltFullNameLanguage in the directory catalog field even if no certified field even if no certified
(from Person use alternate names in alternate names are used in alternate names are used in
documents) their certificates. your organization; then if your organization; then if
alternate certified names are alternate certified names are
put into use later, no directory put in use later, no directory
catalog rebuild is necessary. catalog rebuild is necessary.
HTTPPassword (from Not recommended (Optional) Add to enable (Optional) Add to enable
Person documents) servers to look up Internet servers to look up Internet
passwords in the directory passwords in the directory
catalog for Internet client catalog for Internet client
authentication. authentication.
UserCertificate (from Not recommended (Optional) Add to enable Not recommended
Person documents) servers to look up X.509
certificates in the directory
catalog for Internet client
authentication.

Full-text indexing directory catalogs

A condensed Directory Catalog should have a full-text index, but a full-text index on an Extended
Directory Catalog is optional.

Chapter 26. Setting Up Directory Catalogs 619

Full-text indexing condensed Directory Catalogs
Since a server uses full-text searches rather than view lookups to find any of the following information in
a condensed Directory Catalog, it’s important that the directory catalog has a full-text index:
v Names that don’t correspond to the selected sort order for the directory catalog
v Any information requested by an LDAP search when the LDAP service searches a condensed Directory
Catalog
v Soundex fields

When you replicate a condensed Directory Catalog, the replica you create is full-text indexed
automatically. However, if you use the file system to make a copy of a condensed Directory Catalog, the
copy is not full-text indexed. If you delete a full-text index from a condensed Directory Catalog, you
must re-create the index manually.

If only clients use a condensed Directory Catalog, conserve disk space by deleting full-text indexes on
any server replicas.

Users cannot directly full-text search condensed Directory Catalogs.

Full-text indexing Extended Directory Catalogs

It’s generally not necessary to full-text index Extended Directory Catalogs, because servers rely primarily
on view searches to look up information in them. An exception is if a server running the LDAP service
uses an Extended Directory Catalog; in this case, create a full-text index for the directory catalog if LDAP
users use something other than names in search filters, since these types of LDAP searches use the
full-text index.

Planning issues specific to Extended Directory Catalogs

Consider these issues when planning an Extended Directory Catalog:
v Extended Directory Catalog size
v Extended Directory Catalogs and directory assistance
v Extended Directory Catalogs and group lookups for database authorization
v Integrating an Extended Directory Catalog into a primary Domino Directory

Extended Directory Catalog size

Since the Extended Directory Catalog contains the views that are in a standard Domino Directory and
combines multiple Domino Directories into one database, it typically is very large. If you aggregate all
fields as recommended, an Extended Directory Catalog is about the size of all the aggregated Domino
Directories combined. Don’t replicate the database to Notes clients and use as few replicas on servers as
feasible.

Extended Directory Catalogs and directory assistance

Unless you integrate an Extended Directory Catalog into a server’s primary Domino Directory, a server
must use directory assistance to look up information in an Extended Directory Catalog, and to determine
whether to use an Extended Directory Catalog for client authentication and/or group lookups for
database authorization.

After you create a Directory Assistance document for an Extended Directory Catalog in a directory
assistance database, to optimize look up performance, remove any Directory Assistance documents for
the individual Domino Directories aggregated into the directory catalog.

Make sure to aggregate all the fields that need to be searched because once servers search an Extended
Directory Catalog they cannot use directory assistance to access the source Domino Directories directly to
retrieve field values that are not aggregated, as can occur with a condensed Directory Catalog.

620 Lotus Domino Administrator 7 Help

You can set up a server to use more than one Extended Directory Catalog by creating a Directory
Assistance document for each one.

For more information on setting up directory assistance for an Extended Directory Catalog, see the
chapter ″Setting Up Directory Assistance.″

Extended Directory Catalogs and group lookups for database authorization

You can use the groups in one directory configured in a Directory Assistance database, in addition to the
primary Domino Directory, to authorize database access for Internet and Notes clients. When group
authorization is enabled for a directory, if a server finds groups in a database ACL, it can look up the
members of the groups to verify a user’s access to a database. The one directory enabled for group
authorization can be an Extended Directory Catalog, which effectively allows servers to use groups from
any of the source Domino Directories for database access control.

Select the option ″Group authorization″ in the Directory Assistance document for the Extended Directory
Catalog to enable this feature. If you enable group authorization for an Extended Directory Catalog, you
cannot enable it for any other directory, Notes or LDAP, configured in the directory assistance database.

If you enable ″Group authorization″ for an Extended Directory Catalog, and groups used for database
access control in the directory catalog contain groups as members -- nested groups -- a server only looks
up names in the nested groups if the nested groups are located in the Extended Directory Catalog.

Note: A server cannot use groups aggregated in a condensed Directory Catalog for database
authorization.

Integrating an Extended Directory Catalog into a primary Domino Directory

You can build an Extended Directory Catalog into an existing primary Domino Directory so that servers
and users within the domain can use one, integrated corporate directory. Rather than create a new
database from the PUBNAMES.NTF template in which to add the directory catalog configuration
document and aggregate documents, instead create the configuration document in the primary Domino
Directory (NAMES.NSF). All the original documents in the NAMES.NSF are retained, and the Dircat task
adds documents aggregated from other Domino Directories into the database.

When you integrate an Extended Directory Catalog into a primary Domino Directory, a server within the
domain of the primary Domino Directory searches the aggregated information automatically as part of its
primary Domino Directory search, and so the use of directory assistance isn’t required. Person documents
that the Dircat task aggregates are trusted for client authentication, and Groups documents that are
aggregated can be used automatically for database authorization.

Servers outside the domain of the Domino Directory into which the Extended Directory Catalog is
aggregated can use directory assistance to access the integrated directory. From the perspective of these
servers, the integrated directory is a secondary directory that is searched after their primary Domino
Directory; these servers only trust the integrated directory for client authentication, and can only use
groups in the integrated directory for database authorization, if you set up the Directory Assistance
document for the directory to allow this.

Dircat task processing affects only the documents the Dircat task aggregates from other Domino
Directories, and not native documents that originate in NAMES.NSF. For example, rebuilding an
Extended Directory Catalog that is integrated into a primary Domino Directory does not have any effect
on the native documents.

You can remove an Extended Directory Catalog that is integrated into a primary Domino Directory by
deleting the directory catalog configuration document, and then rebuilding the Extended Directory
Catalog by running the dircat on it with the -r switch. Any native documents created outside of the
aggregation process remain.

Chapter 26. Setting Up Directory Catalogs 621

Planning issues specific to condensed Directory Catalogs
Consider these issues that are specific to planning a condensed Directory Catalog:
v Deciding how to sort entries
v Setting the view sort order
v Deciding whether to support Soundex seaches
v Using performance settings
v Replicating a condensed Directory Catalog

You can set up a condensed Directory Catalog on a server to work in conjunction with directory
assistance. For example, you can set up directory assistance to look up information directly in a Domino
Directory when the information isn’t aggregated into a condensed Directory Catalog. For information, see
the chapter ″Setting Up Directory Assistance.″

Deciding how to sort entries in a condensed Directory Catalog

One of the reasons condensed Directory Catalogs are small is they don’t contain multiple, sorted views
for lookups as a Domino Directory and an Extended Directory Catalog do. Instead, these types of
directory catalogs provide only one option for sorting names, determined by the ″Sort by″ field in a
Directory Catalog Configuration document. The choices are:
v Distinguished name (default) - sorts entries by the Notes distinguished name, first name, followed by
last name.
v Last name - sorts entries by last name
v Alternate Fullname - sorts entries by certified alternate names

The ″Sort by″ option is unnecessary and isn’t available for an Extended Directory Catalog because this
type of directory catalog retains the multiple sorted views available in a Domino Directory.

Note: Always keep the default ″Sort by″ selection, ″Distinguished name,″ if servers use the condensed
Directory Catalog.

How the ″Sort by″ selection affects type-ahead addressing on Notes clients: Type-ahead addressing is
a feature that assists Notes users with mail addressing. As a user begins typing a name when addressing
mail, type-ahead searches for the name in order to fill in the name automatically for the user.

The Notes client only uses type-ahead addressing to look up a name in a condensed Directory Catalog if
the user types the name in a way that corresponds to the ″Sort by″ selection. For example, if the selected
″Sort by″ format is ″Distinguished name,″ type-ahead looks up the name in a condensed Directory
Catalog only when a user types the first name before the last name. Or, if the ″Sort by″ format is set to
″Last name,″ type-ahead looks up the name only when a user types the last name before the first name.

Make sure your ″Sort by″ selection corresponds to the way in which type-ahead is typically used in your
organization. For example in large, enterprise organizations, users often address mail by entering the
recipients’ last names, in which case the Sort by selection should be set to Last name.

You can create more than one condensed Directory Catalog, each with a different ″Sort by″ selection to
accommodate different styles of type-ahead use.

Note: If there is a condensed Directory Catalog on a Notes client, type-ahead never searches a directory
on a server, even if the client Location document is set to ″Recipient name type-ahead - Local then Server.

How the ″Sort by″ selection affects browsing a directory catalog: The ″Sort by″ selection in a
condensed Directory Catalog also determines how names are sorted when users open the directory
catalog, for example when using the ″Select Addresses″ dialog box to browse the directory catalog.

622 Lotus Domino Administrator 7 Help

Setting the view sort order
Unlike most databases including extended Directory Catalogs, the condensed Directory Catalog (CDC)
uses a unique design that combines multiple documents from Domino directories into single documents.
While document in most databases are possible through searches to sorted views, lookups to CDCs
require entries to be ordered within documents in the same manner as the view’s sort ordering.

To set both a CDC’s view sort order and the ordering of the multiple entries in a document, set the
desired sort order in the database’s File - Database - Properties - Design ″Default sort order″ tab and run
the Dircat task. End users must not change the default sort ordering of the CDC replicas themselves,
since doing so will not have the desired effect (CDC entry intra-document ordering is fixed at the time of
aggregation), and may return fewer than expected lookup results in response to a lookup.

If you have different sets of end users each wishing to have different sort orderings, you must create
separate copies (not replicas) of the CDC with the desired sort orders. For example, if you have English,
French, and Danish users who each want their CDC contents ordered according to their locale, you must
create three separate copies of the CDC. The files should have their default sort order set respectively to
Latin1, French, and Danish/Norwegian. It may be useful to establish a naming convention where the sort
order appears in the CDC file names: CDC-EN.NSF, CDC-FR.NSF, and CDC-DK.NSF.

Extended Directory Catalogs are created using the same design the Domino Directory, and therefore
contain views that have a Unicode sort ordering set by default so that directory searches yield consistent
search results across Domino servers, even if those servers have different sort orderings. However, if you
wish to use a CDC on a server, you must enable ″Unicode standard sorting″ on the design tab in the
CDC’s database properties.

When the Dircat task performs the initial build or full rebuild of a CDC, it stores the entries inside the
CDC documents in accordance with the default sort order. If the default sort order is blank, the Dircat
task will obtain a sort ordering from the Domino environment and explicitly set the CDC’s default sort
order with it. When the Dircat task updates a CDC, it first verifies the default sort order matches the
ordering of entries in CDC documents. If it discovers discrepancies between the two orderings, the Dircat
task will issue an event telling the administrator to use Dircat to perform a full rebuild.

Supporting Soundex searches of a condensed Directory Catalog

Use the ″Use Soundex″ field in a directory catalog configuration document for a condensed Directory
Catalog to control whether the directory catalog supports Soundex lookups. Choose Yes (default) to
support Soundex lookups, or No to omit support for Soundex lookups.

Soundex allows Notes users to use phonetic spellings to search for names. Supporting Soundex lookups
increases the size of the directory catalog by about 4 bytes for every entry. Soundex is not effective for
finding names in non-Latin characters.

This field is not available in a configuration document for an Extended Directory Catalog, since
minimizing the size of an Extended Directory Catalog is not a typical goal.

Using performance settings in a condensed Directory Catalog

Directory catalog performance settings in the Advanced tab of a configuration document for a condensed
Directory Catalog are ″Packing density″ -- that is, how many source Domino Directory entries can be
combined in one directory catalog aggregate document -- and ″Incremental fields″ -- that is, how and
when the Dircat task updates changes to fields in the aggregate documents. The default directory catalog
performance settings work fine in most situations.

Note: Change these settings only on a condensed Directory Catalog used only by servers, and not on a
condensed Directory Catalog used by clients.

These settings are irrelevant and unavailable for an Extended Directory Catalog which doesn’t combine
multiple source Domino Directory entries into aggregate documents.

Chapter 26. Setting Up Directory Catalogs 623

Packing density: The packing density is the number of entries from a source Domino Directory that can
be stored in one aggregate document in the condensed Directory Catalog. 255 is the maxium packing
density and the default. If full-text searching is frequently used to search a server directory catalog, for
example if the LDAP service uses the directory catalog, and these searches of the directory catalog are
slow, you can decrease the packing density to improve performance of these searches.You might also
decrease the packing density to reduce the odds that a particular aggregate document needs to replicate.

Incremental fields: Because a single field in an aggregate document contains values for the field from
many of the source Domino directories, it’s likely that at any one time every field in the aggregate
document might require updating and, therefore, would need to replicate. To manage changes to fields in
a condensed Directory Catalog, the Dircat task, by default, uses an incremental merge process that stores
the changes in temporary fields in aggregate documents until, by default, 5 percent of the total entries
from the source Domino Directories change. Then the Dircat task merges the changes stored in the
temporary fields into the permanent fields in the aggregate documents and deletes the temporary fields.
This process occurs somewhat randomly over a period of time so that at any time, only a few aggregate
documents need to replicate. When the directory catalog on the server running the Dircat task replicates,
only the updated fields replicate. This incremental replication results in improved replication
performance, especially when replication occurs over a dial-up connection.

The alternative to incrementally merging fields is to make changes as they occur directly in the original
fields in aggregate documents. Disabling incremental merging provides some modest gains in search
performance. However, if replication with the source Directory Catalog occurs over dial-up connections,
keep incremental merging enabled.

Next to the Incremental fields option in a configuration document for a condensed Directory Catalog,
Choose Yes (the default) to use incremental merging and temporarily store field changes in duplicate
fields in aggregate documents to optimize replication performance. Or choose No to immediately makes
changes in the original fields in the aggregate documents.

Merge factor: The Merge factor option in a configuration document for a condensed Directory Catalog is
a value representing the percent of total field changes that must occur before Domino merges the changes
stored in duplicate fields into the original fields in aggregate documents; default is 5 percent.

This field applies only when ″Incremental fields″ is set to Yes.

Note: We don’t recommend changing this setting.

Replicating a condensed Directory Catalog

There are many fields combined in each aggregate document in a condensed Directory Catalog, and for
this reason aggregate documents frequently change and require replication. Schedule replication between
a server that builds a directory catalog and other servers that have replicas to occur at least several times
a day to keep up with changes in the aggregate documents.

Notes clients should replicate local condensed Directory Catalog with a replica on a server either daily or
weekly, depending on whether the clients have fast connections to the server. It’s best for clients that
connect on the road over dial-up connections to wait to replicate a directory catalog until a fast
connection is available.

Give all servers that are not Dircat servers, as well as all clients, only Reader access (the default) to a
condensed Directory Catalog, to prevent the clients/servers from being able to replicate changes to the
replica on a Dircat server.

Multiple directory catalogs

You can set up Notes clients to use more than one condensed Directory Catalog, set up servers to use
more than one Extended Directory Catalog, and set up groups of clients or servers to use separate
directory catalogs.

624 Lotus Domino Administrator 7 Help

Setting up Notes clients to use more than one condensed Directory Catalog
You can set up a Notes client to use more than one condensed Directory Catalog. For example, you can
set up two condensed Directory Catalogs on Notes clients, one that sorts entries by distinguished name
(first name, then last name), and another that sorts entries by last name. Then, type-ahead addressing can
locate names regardless of whether users begin addressing mail using first names or last names.

For more information on type-ahead addressing and directory catalogs, see ″Deciding how to sort entries
in a condensed Directory Catalog.″

Setting up servers to use more than one Extended Directory Catalog

You can set up a server to use more than one Extended Directory Catalog. For example, suppose you
want all servers to use directories A, B, C, D, and E, but to trust only directories A and B for client
authentication. You can aggregate A and B in an Extended Directory Catalog that is trusted for
authentication, and aggregate C, D, and E in another Extended Directory Catalog that is not trusted it for
authentication.

Note: A server can use one condensed Directory Catalog only.

Setting up groups of clients and servers to use different directory catalogs

You can create multiple directory catalogs, and set up groups of clients or servers to use specific ones. For
example, if user group 1 sends mail only to users registered in directories A, B, and C, and user group 2
sends mail only to users registered in directories D and E, you can create a client-based condensed
Directory Catalog that aggregates A, B, and C for group 1 to use, and create another condensed Directory
Catalog that aggregates D and E for group 2 to use.

You can set up servers to use specific Extended Directory Catalogs or condensed Directory Catalogs in a
similar manner.

Overview of setting up a condensed Directory Catalog

The following tables describe the databases, documents, and fields you use to set up a condensed
Directory Catalog, in the order in which you use them.

Document/Database
Directory Profile of each
Domino Directory to be
aggregated in the directory
catalog
Directory Catalog
Configuration document in
database created from
DIRCAT5.NTF
File / Database /
Properties / Design in
database created from
DIRCAT5.NTF
Domino Directory Server
document of Dircat server
that builds the directory
catalog
Used for an
Extended
Directory
Field(s)/Tab(s) Purpose Catalog too?
″Domain defined by Associates groups in the directory with a Yes
this Domino Directory″ domain to distinguish between different
on the Basics tab groups with the same name in more than
one Domino Directory
All fields Used for directory catalog configuration No
Default sort order Provides the Dircat task with the sort order No
of entries in the condensed directory
catalog
All fields in the Server Provides the Dircat task with the file Yes
Tasks - Directory name(s) of the local directory catalog(s) to
Cataloger tab aggregate and a schedule for running

Chapter 26. Setting Up Directory Catalogs 625

Additional configuration to set up a condensed Directory Catalog on clients
Used for an
Extended
Directory
Document/Database Field(s)/Tab(s) Purpose Catalog too?
Desktop policy settings ″Mobile directory Sets up a condensed Directory Catalog No
document and/or Setup catalogs″ field on the automatically on Notes clients
policy settings document in Databases tab
Domino Directory in which
clients are registered

Additional configuration to set up a condensed Directory Catalog on servers

Used for
Extended
Directory
Document/ Database Field(s)/Tab(s) Purpose Catalog too?
Domino Directory Server ″Name of condensed Specifies the file name of a server’s local No
document of each server directory catalog on condensed Directory Catalog
that uses the condensed this server″ field on
Directory Catalog Basics tab
Directory Profile document ″Directory catalog file Specifies the file name of servers’ local No
in the Domino Directory of name for domain″ field condensed Directory Catalogs if there is
the servers that use the on Basics tab no file name specified in Server
condensed Directory documents
Catalog
Domino Directory Server ″Trust the server based Indicates whether a server should trust all No
document of each server condensed directory user entries in its condensed Directory
that uses the condensed catalog for Catalog for client authentication1
Directory Catalog authentication with
internet protocols″ field
on the Basics tab

1
Can use directory assistance instead to trust for client authentication only some rather than all of the
aggregated directories

Setting up a condensed Directory Catalog

When you finish planning a condensed Directory Catalog, follow these steps to set it up:

Step 1: Verify that each Domino Directory has a defined domain: Each Domino Directory aggregated
in a directory catalog should have a domain defined in its Directory Profile. The Dircat task appends the
domain name to the names of groups in the directory catalog, to distinguish between identically named
groups from different directories.

Do the following for each Domino Directory you will aggregate into the directory catalog:
1. Open a Domino Directory.
2. Choose Actions - Edit Directory Profile.
3. Make sure the field ″Domain defined by this Domino Directory″ contains a valid domain name. This
field is usually filled in automatically.
4. Click Save & Close.

Step 2: Create the condensed Directory Catalog database:

1. Choose File - Database - New.

626 Lotus Domino Administrator 7 Help

2. Next to Server, select the Dircat server you picked to aggregate the directory catalog.
3. Next to Title, enter a title for the directory catalog, for example Condensed Directory Catalog.
4. Next to Filename, enter a file name for the catalog, for example CDC.NSF.
5. Select ″Create full text index for searching.″
6. Click ″Show advanced templates.″
7. Below ″Template server,″ select a server that stores the Directory Catalog template, and then click OK.
8. Select the Directory Catalog template (DIRCAT5.NTF). Do not select the Catalog (V6) template
(CATALOG.NTF).
9. Click OK.

Note: Keep the - Default - entry in the database access control list (ACL) set to Reader.

Step 3: Create the directory catalog configuration document and run the Dircat task::
1. In the database you created, choose Create - Configuration.
2. Complete the following fields in the Directory Catalog Configuration document:

Note: The ″Directories to include″ field is the only field you must complete. In many situations you
can accept the default values in the other fields. However, read the complete descriptions of the fields
before you run the Dircat task to build the directory catalog.

Fields in Basics tab Description

Directories to include Specifies which Domino Directories the Dircat task aggregates,
and the order in which it processes the directories. For more
information, see the earlier topic ″Specifying the Domino
Directories for the Dircat task to aggregate.″
Additional fields to include Specifies which fields from Domino Directories to aggregate. For
more information, see the earlier topic ″Choosing which fields to
aggregate in a directory catalog.″
Sort by Specifies how to sort entries in the directory catalog. For more
information, see the earlier topic ″Deciding how to sort entries in
a condensed Directory Catalog.″
Use Soundex Specifies whether to support Soundex lookups. For more
information, see the earlier topic ″Supporting Soundex searches of
a condensed Directory Catalog.″
Remove duplicate users Specifies whether to aggregate multiple user entries with the same
name. For more information, see the earlier topic ″Removing
duplicate user entries from a directory catalog.″
Group types Specifies which types of groups to aggregate. For more
information, see the earlier topic ″Choosing the types of groups to
aggregate in a directory catalog.″
Include Mail-in Databases Specifies whether to aggregate Mail-In Database documents.
Default is Yes. Consider setting to No if the directory catalog is
used only on clients, since Notes users don’t typically send mail
to Mail-In Databases.
Restrict aggregation to this server (Recommended) Specifies the one Dircat server that can aggregate
this directory catalog. For more information, see the earlier topic
″Allowing only one server to aggregate a directory catalog.″
Send Directory Catalog reports to: (Optional) Specifies the names of people to receive Directory
Catalog status reports. For more information, see the later topic
″Mailing Directory Catalog reports.″

Chapter 26. Setting Up Directory Catalogs 627

Fields in Advanced tab Description
Version Read only field that can increment after a Domino upgrade.
Selection formula (Optional) Specifies a selection formula to control which
documents are aggregated. For more information, see the earlier
topic ″Using a selection formula in a directory catalog
configuration document.″
Total number of people/group/mail-in Read-only field that shows the total number of entries aggregated
databases and resources from Domino Directories after the Dircat task runs.
Packing density Specifies the maximum number of Domino Directory entries that
can be aggregated into each aggregate document.

You usually do not have to change the default setting. Do not

change the default setting if clients use local replicas of the
directory catalog.

For more information, see the earlier topic ″Using performance

settings in a condensed Directory Catalog.″
Incremental fields Specifies whether changed fields are stored in a temporary
location.

You usually do not have to change the default setting. Do not

change the default setting if clients use local replicas of the
directory catalog.

For more information, see the earlier topic ″Using performance

settings in a condensed Directory Catalog.″
Merge factor If Incremental fields is enabled, controls the percent of total field
changes that must occur before original fields in aggregate
documents are updated.

You usually do not have to change the default setting. Do not

change the default setting if clients use local replicas of the
directory catalog.

For more information, see the earlier topic ″Using performance

settings in a condensed Directory Catalog.″
Replication history Replication history Shows the date and time when the Dircat task last aggregated the
source directories listed in the field ″Directories to Include.″

Click Clear History to do a full rebuild of the directory catalog.

Do not click Clear History unless you understand Dircat rebuilds.
For more information, see the later topic ″The Dircat task.″

3. Click Save and Close.

4. Click File - Database - Properties. Choose how you want entries sorted.

Fields in Design tab Description

Multilingual database Leave this unchecked
Default language Leave this unchecked
Default sort order Specifies both the order that entries are stored in CDC documents and the
ordering of document in CDC views. If you leave this blank, the Dircat
task will use the default for your Domino task when it rebuilds the CDC.
Unicode standard sorting Uncheck this if you wish to use the default sort order. Check this box if
the CDC will be either run on a server (step 5) or you want a
language-insensitve sort ordering.

628 Lotus Domino Administrator 7 Help

 Note: See the topic ″Planning issues specific to condensed directory catalogs″ section if you have
different sets of users each wishing to have different sort orderings.
5. Run the Dircat to build the condensed Directory Catalog. For more information, see the topic
″Running the Dircat task.″

Step 4: Set up clients to use the condensed Directory Catalog: Use Desktop policy settings or Setup
policy settings to automate setup of a condensed Directory Catalog on Notes clients. The automated
setup creates a replica stub (an empty replica) of the directory catalog on the clients, with a replication
schedule enabled to a replica of the directory catalog on a server that you specify. When the client
replicates with a replica of the directory catalog on a server, a full-text index is created on the client
replica after replication is complete. The automated setup process also adds the file name of the
condensed Directory Catalog to the ″Local address books″ field in user preferences for mail, after the file
name of the Person Address Book.

If you don’t automate the directory catalog setup, you must create the replica and add the file name to
clients manually.

Note: User Setup Profiles used in Lotus Domino Release 5 for automated directory catalog setup
continue to work in Lotus Domino 7.

To automate setup of a condensed Directory Catalog on clients:

1. (Optional) Create a replica of the condensed Directory Catalog on other servers. Then users have
more choice of servers to use when they replicate to update their local replicas of the directory
catalog. Domino creates a full-text index automatically on the replicas you create.
2. If you haven’t already done so, create a Desktop policy settings document or a Setup policy settings
document to use to use to automate setup of the directory catalog. Make sure you understand how to
set up policies before you create a Desktop or Setup settings document.
For information, see the chapter ″Using Policies.″
3. From the Domino Administrator, click the Files tab, and open a replica of the directory catalog.
4. Choose Edit - Copy As Link - Database Link, then close the directory catalog.
5. Open the Desktop policy settings document or Setup policy settings document you want to use to
automate setup of the condensed Directory Catalog on clients.
6. Click the Databases tab, and then click the ″Mobile directory catalogs″ field.
7. Choose Edit - Paste to past the directory catalog database link into the ″Mobile directory catalogs″
field.
8. Click Save & Close.

Note: Notes users should do pull replications regularly with up-to-date replicas of the directory catalog
on servers.

Step 5: Set up servers to use the condensed Directory Catalog:

Note: It is strongly recommended that you use the Extended Directory Catalog on servers, as they
provide faster and more flexible directory lookups.

Note: Make sure the CDC has ″Unicode standard sorting″ enabled in the CDC’s database properties
design tab. See Step 3.

To set up a server to use a condensed Directory Catalog:

1. Create a replica of the built directory catalog on the server. Set up replication between the server and
the Dircat server so that this server’s replica of the directory catalog is kept up-to-date.
2. If necessary, from the Domino Administrator choose File - Open Server, to open the server you are
setting up to use the directory catalog.

Chapter 26. Setting Up Directory Catalogs 629

 3. Click the Configuration tab.
4. In the left pane, expand Server - Current Server Document.
5. Click Edit Server.
6. On the Basics tab, in the ″Name of condensed directory catalog on the server″ field, enter the file
name of the directory catalog replica you created on this server. If multiple servers use the same file
name for their local replicas of the directory catalog, see the Tip below for a quick way to specify the
file name.
7. (Optional) To allow the server to use all user names aggregated in the condensed Directory Catalog
for client authentication, on the Basics tab of the Server document select ″Trust the server based
condensed directory catalog for authentication with internet protocols.″ If you don’t want to trust the
entire directory catalog for authentication, do not select this option.

Note: To specify instead that the server trust for authentication names from only one or some of the
directories aggregated in the directory catalog, in a directory assistance database used by the server,
create a Directory Assistance document for each aggregated Domino Directory to trust that has a
trusted rule enabled.
For more information, see the topic ″Using a condensed Directory Catalog for client authentication″
earlier in the chapter, and also the chapter ″Setting Up Directory Assistance.″
8. Click Save & Close
9. If necessary, wait for the Domino Directory changes to replicate to the server. Or force the
replication.
10. Use the Restart Server command to Restart the server so it detects the changes to the Server
document.

Tip: If multiple servers use the same file name for their local replicas of the condensed Directory Catalog,
you can specify that file name once in the Directory Profile of the domain Domino Directory, rather than
multiple times in individual Server documents. To use the Directory Profile method, from the Domino
Directory for the servers that will use the directory catalog, choose Actions - Edit Directory Profile and
add the directory catalog file name to the ″Directory catalog database name for domain″ field. Then a
server that doesn’t have a directory catalog file name entered in its Server document uses the Directory
Profile to find its local replica of the condensed Directory Catalog.

Overview of setting up an Extended Directory Catalog

The following table describes the databases, documents, and fields used to set up an Extended Directory
Catalog, in the order in which you use them.

Used for a
condensed
Directory
Document/Database Field(s)/Tab(s) Purpose Catalog too?
Directory Profile of each ″Domain defined by this Associates groups in the directory with Yes
Domino Directory to be Domino Directory″ field on a domain to distinguish between
aggregated in the the Basics tab different groups with the same name in
Directory Catalog more than one Domino Directory
Extended Directory All Used for directory catalog configuration No
Catalog document in
Database created from
PUBNAMES.NTF
Domino Directory Server All fields in Server Tasks - Provides the Dircat task with the file Yes
document of the Dircat Directory Catalog tab name(s) of the local directory catalog(s)
server that builds and to aggregate and a schedule for running
updates the directory
catalog

630 Lotus Domino Administrator 7 Help

 Used for a
condensed
Directory
Document/Database Field(s)/Tab(s) Purpose Catalog too?
Directory Assistance All fields related to a Notes Provides a server with the location of No
document in Directory Directory Assistance the Extended Directory Catalog and
assistance database used document indicates whether to trust the lookups
by each server that uses for client authentication and group
the directory catalog authorization1
Server document in the ″Directory Assistance Allows a server to use directory No
Domino Directory of database name″ field on the assistance1
each server that uses the Basics tab.
directory catalog

1
Unnecessary if the Extended Directory Catalog is built directly into the primary Domino Directory

Setting up an Extended Directory Catalog

When you finish planning an Extended Directory Catalog, follow these steps to set it up:

Step 1: Verify that each Domino Directory has a defined domain: Each Domino Directory aggregated
in a directory catalog should have a domain defined in its Directory Profile. The Dircat task appends the
domain name to the names of groups in the directory catalog, to distinguish between different groups
with the same name in more than one Domino Directory.

Do the following for each Domino Directory you will aggregate into the directory catalog:
1. Open the Domino Directory.
2. Choose Actions - Edit Directory Profile.
3. Make sure the field ″Domain defined by this Domino Directory″ contains a valid domain name. This
field is usually filled in automatically.
4. Click Save & Close.

Step 2: Create the Extended Directory Catalog database::

Note: If you will integrate an Extended Directory Catalog into a primary Domino Directory, skip this
step.
1. Choose File - Database - New.
2. Next to Server, select the Dircat server you picked to aggregate the directory catalog.
3. Next to Title, enter a title for the directory catalog, for example Extended Directory Catalog.
4. Next to Filename, enter a file name for the directory catalog, for example EDC.NSF. Do not use the
file name NAMES.NSF.
5. Select ″Show advanced templates.″
6. Below Template server, select a server that stores the Domino Directory template.
7. Select the Domino Directory template (PUBNAMES.NTF).
8. Keep ″Inherit future design changes″ selected.
9. Click OK.

Step 3: Create the Extended Directory Catalog configuration document and run the Dircat task::
1. Open the database you created in Step 2.

Note: To integrate the Extended Directory Catalog into a primary Domino Directory, open that
primary Domino Directory instead.

Chapter 26. Setting Up Directory Catalogs 631

2. Choose Create - Extended Directory Catalog. Complete the following fields in the Configuration
document. Read the complete descriptions of the fields before you run the Dircat task to build the
directory catalog.

Fields in Basics tab Description

Directories to include
Additional fields to include
Remove duplicate users
Group types
Include Mail-in Databases
Include Servers
Restrict aggregation to server
Send Aggregation reports to:
Specifies which Domino Directories the Dircat task aggregates, and the order in
which it processes the directories. For more information, see the earlier topic
″Specifying the Domino Directories for the Dircat task to aggregate.″
Specifies which fields from Domino Directories to aggregate. Aggregating all fields
is recommended. To aggregate all fields, leave the ″Additional fields to include″
field blank by deleting all fields from it. For more information, see the earlier topic
″Choosing which fields to aggregate in a directory catalog.″
Specifies whether to aggregate multiple user entries with the same name. For
more information, see the earlier topic ″Removing duplicate user entries from a
directory catalog.″
Specifies which types of groups to aggregate. For more information, see the earlier
topic ″Choosing the types of groups to aggregate in a directory catalog.″
Specifies whether to aggregate Mail-In Database documents. Default is Yes.
Specifies whether to aggregate Server documents. Default is No.
(Recommended) Specifies the one Dircat server that can aggregate this directory
catalog. For more information, see the earlier topic ″Allowing only one server to
aggregate a directory catalog.″
(Optional) Specifies the names of people to receive Directory Catalog status
reports. For more information, see the later topic ″Mailing Directory Catalog
reports.″

Fields in Advanced tab Description

Version Read-only field that can increment after the DIRCAT5.NTF template is upgraded.
Used only for internal purposes.
Selection formula (Optional) Specifies a selection formula to control which documents are
aggregated. Click Check Syntax to verify that the syntax specified in a selection
formula is valid.

For more information, see the earlier topic ″Using a selection formula in a
directory catalog configuration document.″
Replication history Shows the date and time when the Dircat task last replicated the aggregated
directories

Click Clear History to do a full rebuild of the directory catalog. Do not click Clear
History unless you understand Dircat rebuilds. For more information, see the later
topic ″The Dircat task.″

3. Click Save & Close to save the configuration document.

4. Run the Dircat task to build the directory catalog. For information, see the later topic ″Running the
Dircat task.″

Step 4: Create at least one replica of the Extended Directory Catalog: Create at least one replica of the
directory catalog on another server for performance and failover benefits. Make sure replication occurs
between the server(s) with the replica(s) and the Dircat server, so the replicas of the directory catalog are
kept up-to-date.

Step 5: Set up servers to use the Extended Directory Catalog: To set up a server to use an Extended
Directory Catalog, create a Directory Assistance document for the Extended Directory Catalog in a
directory assistance database the server uses.

632 Lotus Domino Administrator 7 Help

For information, see the topic ″Extended Directory Catalogs and directory assistance″ earlier in the
chapter, and the chapter ″Setting Up Directory Assistance.″

Note: If you integrate the Extended Directory Catalog into a primary Domino Directory, steps 4 and 5 are
unnecessary.

The Dircat task

When the Dircat task runs it can do one of these things to a directory catalog: build it, update it, partially
rebuild it, or fully rebuild it. The first time the Dircat task runs on a directory catalog it builds it.
Subsequently, the Dircat task usually updates a directory catalog, which means it checks for changes to
the contents of fields in the source Domino Directories, and then makes the appropriate changes to the
directory catalog.

Full rebuilds
If you change any of the following fields in a directory catalog configuration document, the Dircat task
must do a full rebuild of the directory catalog to incorporate the indicated changes into the directory
catalog:
v Directories to include
v Additional fields to include
v Sort by (condensed directory catalog)
v Use Soundex (condensed directory catalog)
v Remove duplicate users
v Group types
v Include Mail-in Databases
v Include Servers (Extended Directory Catalog)
v Selection Formula

When the Dircat task does a full rebuild, it completely re-aggregates of all the configured source Domino
Directories, similar to what occurs during the initial build of the directory catalog. For example, if you
add a field to the ″Additional fields to include″ field to aggregate an additional field, that field isn’t
aggregated until the Dircat task does a full rebuild of the directory catalog. A full rebuild is a much
longer process then an update. After a full rebuild, there must also be a full replication of the directory
catalog to the servers and clients that use it, which can be time consuming, especially for replication of
condensed Directory Catalogs.

When you change one of the above fields in a configuration document for a condensed Directory Catalog,
the next time the Dircat task runs, it automatically does a full rebuild. When you change one of these
fields in a configuration document for an Extended Directory Catalog, the Dircat task does not do a
rebuild automatically. Instead, you must initiate the rebuild by running the Dircat task with the -r switch
against the Extended Directory Catalog, or by clicking the Clear History button on the Advanced tab of
the directory catalog configuration document.

Note: Dircat processing of changes to the ″Directories to include″ field in a configuration document for
an Extended Directory Catalog causes a partial rebuild, rather than a full rebuild, that processes only
directories affected by the change.

Partial rebuilds
If the replica of a source Domino Directory the Dircat task uses is deleted, and then replaced with a file
operating system copy with the same replica ID, then the Dircat task does a partial rebuild, which
involves comparing all documents in the new file system copy of the Domino Directory to the
corresponding contents in the directory catalog to look for changes. The Dircat task also does a partial

Chapter 26. Setting Up Directory Catalogs 633

rebuild if the Fixup task deletes corrupted documents from a source Domino Directory which are then
replaced through replication. A partial rebuild is a longer process than an update, but takes less time than
a full rebuild.

Note: This is true of any replica of the Domino Directory that the DirCat task aggregates. If a replica of a
Domino Directory is replaced with a file operating system copy with the same replica ID, when the Fixup
task runs on that replica those changes are replicated back to the aggregation server’s Domino Directory.
This in turn flags the DirCat task to do a partial rebuild on the aggregation server.

Running the Dircat task

Run the Dircat task to build a directory catalog initially. Then continue to run the task at scheduled
intervals to keep the contents of the directory catalog synchronized with the contents of the source
Domino Directories and to keep the directory catalog synchronized with the directory catalog
configuration selections.

Always run the Dircat task on one server to build and update a particular directory catalog. If you run
the Dircat task on more than one server against the same directory catalog, replication conflicts occur. Use
the field ″Restrict aggregation to server″ in a directory catalog configuration document to ensure that the
Dircat task on only one server can process a particular directory catalog.

Running the Dircat task on schedule: Schedule the Dircat task on a Dircat server to run at regular
intervals by doing the following:
1. Make sure there is a directory catalog database with a completed configuration document.
2. From the Domino Administrator, click the Configuration tab.
3. Expand Directories - Directory Cataloger, and choose Settings.
4. Click the Server Tasks tab, then the Directory Cataloger tab.
5. Complete these fields, and then click Save & Close:

Field Enter
Directory Catalog The file name(s) of the directory catalog(s) the Dircat task should process. Separate
filenames multiple file names with commas.
Schedule Select Enabled.
Run Directory Catalog A time range or one or more specific times to update the source directory catalog.
aggregator at Separate multiple time entries with commas (,).The default is the range 08:00 AM to
10:00 PM.
Repeat interval of A number representing the minutes between updates that are scheduled during a time
range. The default is 360 minutes (every 6 hours). Consider reducing this interval to
have the Dircat task run every 60 or 120 minutes.
Days of week The days of week to run the Dircat task. The default is daily.

Running the Dircat task manually: To run the Dircat task manually on a Dircat server, issue this server
command:
load dircat dc.nsf

where dc.nsf is the file name of a local directory catalog on the server.

You can do a full rebuild of a directory catalog. Keep in mind that a full rebuild removes and recreates all
the aggregated documents so that the first replication after the rebuild will require a full replication of the
database.

To do a full rebuild of a directory catalog, you can run the dircat task against the directory catalog using
the -r switch, for example:
load dircat dc.nsf -r

634 Lotus Domino Administrator 7 Help

Or you can do a full rebuild by clicking the Clear History button on the advanced tab of the directory
catalog configuration document.

Pausing the Dircat task: Before you shut down a server that is in the middle of Dircat processing, pause
the Dircat task. When you pause the Dircat task, the Dircat task finishes aggregating the directory catalog
it is currently running on and then goes idle. if you don’t pause the Dircat task before server shutdown,
the Dircat task must reaggregate the directory catalog it was processing at the time of server shutdown
from the beginning.

To pause the Dircat task, enter this server command:

Tell Dircat Pause

You can then shut down the server. Or, to resume Dircat processing, enter this server command:
Tell Dircat Resume

Opening the configuration document for a directory catalog

To open the configuration document for a directory catalog:
1. From the Domino Administrator, open the Dircat server or another server with a replica of the
directory catalog. To open a configuration document for a condensed Directory Catalog, make sure
the Basics tab of the Server document includes the directory catalog file name.
2. Click the Configuration tab.
3. Expand Directory in the left pane.
4. Do one of the following:
v To see the configuration document for a condensed Directory Catalog, choose Directory Catalog.
v To see the configuration document for an Extended Directory Catalog, choose Extended Directory
Catalog.

Note: Change a directory catalog configuration document on the Dircat server that aggregates the
directory catalog.

Monitoring directory catalogs

v Mailing Directory Catalog reports
v Using other directory catalog monitoring tools

Mailing Directory Catalog reports

A directory catalog stores an agent called Directory Catalog Status Report. A server can use this agent to
mail in your name a Directory Catalog report once a week to users you specify in a directory catalog
configuration document.

A Directory Catalog report includes the following:

v A database link to the replica of the directory catalog on the Dircat server for the directory catalog, and
information about this directory catalog including its database title, server location and file path, size,
number of entries, and configuration settings; the agent derives this information from the Dircat task.
v A database link to each source Domino Directory used the Dircat task uses to aggregate into the
directory catalog, and information about each directory including the database title, server location and
file path, size, and date last updated in the directory catalog.
v The size of the directory catalog as a percentage of the combined size of the Domino Directories
aggregated into it.

To mail Directory Catalog reports:

1. Open the configuration document for the directory catalog.
2. Specify the name(s) of users to receive the reports; separate multiple names with commas:

Chapter 26. Setting Up Directory Catalogs 635

 v For a condensed Directory Catalog, enter the name(s) in the field ″Send Directory Catalog reports
to.″
v For an Extended Directory Catalog, enter the name(s) in the field ″Send Aggregation reports to.″
3. When prompted, select the name of the server that should run this agent to mail the reports on your
behalf. You must have ″Run restricted LotusScript/Java agents″ access to the server you pick.
4. Click Save & Close.

Using other directory catalog monitoring tools:

v Use the NOTES.INI setting Log_DirCat=1 to display additional information to the server console when
the Dircat task runs. This includes when the task starts and finishes, what directory it’s aggregating,
the domain name of the directory, and how many entries were processed. For more verbose
information, including the names of all the entries that are processed, you can set log_dircat=3.
However, this setting may slow performance and fill up the server log file, so its use is not
recommended.
v Use the Show Xdir command to show information about the directory catalogs and other directories
that a server uses.
v If you’ve configured the Dircat task to run on schedule, use the Show Schedule command to see when
the task is next scheduled to run.

636 Lotus Domino Administrator 7 Help

Chapter 27. Setting Up Extended ACLs
This chapter describes how to set up and manage an extended access control list (ACL), which is an
access control feature available for a Domino Directory and an Extended Directory Catalog.

Extended ACL
An extended access control list (ACL) is an optional directory access-control feature available for a
directory created from the PUBNAMES.NTF template -- a Domino Directory or an Extended Directory
Catalog. An extended ACL is tied to the database ACL, and you access it through the Access Control List
dialog box using a Notes 7 or Domino Administrator 7 client. You use an extended ACL to apply
restrictions to the overall access the database ACL allows a user -- you cannot use it to increase the access
the database ACL allows. Use an extended ACL to set access to:
v All documents with hierarchical names at a particular location in the directory name hierarchy, -- for
example all documents whose names end in OU=West/O=Acme.
v All documents of a specific type, -- for example all Person documents
v A specific field within a specific type of document
v A specific document

An extended ACL allows you to:

v Delegate your Domino administration, for example, allow a group of administrators to manage only
documents named under a particular organizational unit.
v Set access to precise portions of the directory contents.
v Set access to documents and fields easily and globally at one source, rather than requiring you to
control access through features such as multiple Readers and Authors fields.
v Control the access of users who access the directory through any supported protocol: Notes (NRPC),
Web (HTTP), LDAP, POP3, and IMAP.

For information on using Extended ACLs in a multi-release environment, see the Upgrade Guide.

Note: Server processes such as the Router task do not enforce extended ACL restrictions. However, in the
case of the Router task specifically, you can prevent some users from sending mail to a group by editing
the Readers field for the group and including only the names of users you want to allow to send mail to
the group. When users omitted from the Readers field attempt to send mail to the group, the Router
won’t deliver the mail.

For more information, see the chapter ″Customizing the Domino Mail System.″

How other database security features restrict extended ACL access

settings
The access set for a user in an extended ACL can never exceed the access the database ACL, including
the database ACL privileges and roles, allows the user. For example, if the database ACL allows a user
only Reader access, you can’t use the extended ACL to allow Write access. Or if a user is omitted from
the database ACL User Creator role, you can’t use the extended ACL to allow the user Create access to
Person documents.

Access set through a security feature in the database design also restricts the access you can specify in an
extended ACL. For example, if a Readers field on a particular form prevents a user from reading fields in
documents created with that form, giving a user Browse access to the form in the extended ACL does not
override the access specified in the Readers field.

637
Elements of an extended ACL
To set up an extended ACL, you use the ″Extended Access at target″ dialog box, which you open from the
database Access Control List dialog box. The elements of an extended ACL are:
v Access settings -- the allowed access
v Subjects -- the users and groups whose access you control
v Targets -- categories of documents or specific documents to which access settings apply

Extended ACL access settings

There are several access settings you use to control a subject’s access to an extended ACL target. For each
access setting you choose Allow or Deny. You can leave an access setting unchecked, but if you do, other
subjects in the extended ACL or database ACL determine whether the subject is allowed or denied the
access. It’s better to select Allow or Deny to help ensure you get the access control results you expect.

Access settings apply to existing documents at a selected target. If the selected target is a category of
documents, access settings also apply to documents added to the category in the future.

An extended ACL cannot restrict the access of a user with Manager database access or an administrator
with ″Full Access administrators″ access to a server (controlled through the Server document in the
Domino Directory.) An extended ACL also cannot prevent a user with Designer or Manager database
access from modifying the directory design.

Note: For ease of reading, this topic uses the terms document, field, and form. If an extended ACL will
control LDAP access, apply the LDAP-equivalent terms instead: entry, attribute, and object class.

The following access settings control access to a document as a whole:

Access
setting Tasks allowed
Browse Allows a user to access a document.
Create Allows a user to create a document.
Delete Allows a user to delete a document.

The following access settings control access to a field within a document:

Access
setting Tasks allowed
Read Allows a user to read a field. The user must also have Browse access to the document.
Write Allows a user to modify a field.

When more than one type of document uses a particular field, you control access to the field separately
for each type of document.

If you are controlling the access of Notes and Web users, be aware of the following issues. These issues
do not apply to access through other means, such as LDAP access or Notes application access, except
where indicated.
v If you deny a Notes or Web user access to a field in a document, when the user opens the document,
the document does not show the field and the text (TRUNCATED) shows in the tab of the document.
In addition, the user is unable to edit the document, even if the user has write access to the fields in it.
v If you deny a Notes or Web user access to a field in a document that a view uses to sort the document,
the name of the document is blank in the view. The user can still select the document to open it.

638 Lotus Domino Administrator 7 Help

v To delete a document, a Notes or Web user must be able to see the document in a view. To see a
document requires Browse access to the document.
v To create a document, a Notes or Web user or a Notes application must have Create access to the
document as well as Write access to the fields to which the user/application will add values.

Administer access
Grant Administer access to allow someone with Designer or Editor access in the database ACL to modify
access settings at an extended ACL target. Someone with Manager access in the database ACL can modify
an extended ACL without having Administer access. Grant Administer access to allow someone to
manage access to documents under a target category without granting the person Manager access in the
database ACL. A user with Editor or Designer access in the database ACL does not have the Administer
access by default; you must grant the user that access explicitly. You grant someone Administer access to
a target category and not to a specific document.

Note: You can give a Domino 7 server Administer access to a selected target category. This access enables
the server to be an extended administration server whose Administration Process manages documents
below the selected target category.

For more information, see the chapter ″Setting Up the Administration Process.″

Default access compared to form-specific access

When you set a subject’s access to a selected target, you specify default access settings that generally
apply to all types of documents at the selected target. Then you can also set form-specific access settings
that are different than the default access settings. For example, by default you can deny a subject Browse
and Read access, but then allow Browse access to Person and Group documents and Read access to the
fields in those documents.

Default access: You use the ″Extended Access at target″ dialog box to set a subject’s default access to a
target. The following figure shows default access set to Deny all for the -Default- subject at / (root):

Chapter 27. Setting Up Extended ACLs 639

Form-specific access: You click Form and Field Access from the ″Extended Access at target″ dialog box
to use the ″Form and Field access at target″ dialog box to set form-specific access settings that are
exceptions to the selected subject’s default access at the selected target. The following figure shows access
set for the Person form for the -Default- subject at / (root):

640 Lotus Domino Administrator 7 Help

Note: The Administer access setting is available only as a default access setting, and not as a
form-specific access setting.

Displaying LDAP attributes and object classes when setting form-specific access
Use the Schema option in the ″Form and Field access at target″ dialog box to control whether the dialog
box shows the directory contents in terms of LDAP object classes and attributes or in terms of Domino
forms and fields. Domino is selected by default, meaning the dialog box shows Domino forms and fields.
To show LDAP object classes and attributes, select LDAP next to the Schema option.

When you set a subject’s access to a form or field, the access setting automatically applies to the
corresponding LDAP object class or attribute, if there is one. Similarly, if you set a subject’s access to an
object class or attribute, the access also applies to the corresponding form or field if there is one.

For example, if you deny a subject Read access to the InternetAddress field of a Person form when
Domino is selected as the Schema option, the subject is also denied LDAP Read access to the mail
attribute of the dominoPerson object class that shows when LDAP is selected as the Schema option. If the
Schema option is set to LDAP and you deny a subject Read access to the mail attribute of the
dominoPerson object class, the subject is also denied Read access to the InternetAddress field of a Person
form that shows when the Domino is selected as a Schema option.

Some object classes and attributes that the ″Form and Field access at target″ dialog box displays when
you select LDAP as the Schema option do not correspond to forms and fields and are useful only for
controlling LDAP access. For example, the object class residentialPerson does not correspond to a form.
Similarly, some forms and fields that the dialog box displays when you select Domino as the Schema
option do not correspond to LDAP object classes and attributes and are useful only for controlling Notes
or Web user access. For example, the form DirectoryProfile does not correspond to an object class.

Chapter 27. Setting Up Extended ACLs 641

Note: Domino uses the Domino LDAP Schema database (SCHEMA.NSF) to generate the LDAP object
classes and attributes that display when you choose LDAP for the Schema option in the dialog box. So to
use the LDAP schema option, the directory for which you are setting access must be located on a server
that runs the LDAP service. If you extend the schema, you can use the extended ACL to control access to
the new object classes and attributes.

For more information on the LDAP schema, see the chapter ″Managing the LDAP Schema.″

Precedence rules used to resolve access conflicts at a target

When you select a target in the ″Extended Access at: target″ dialog box, by default the dialog box shows
all the subjects in the extended ACL with access settings to the target. Included are subjects whose access
is set at and inherited from a higher target through the scope ″This container and all descendants.″ (You
can select ″Show Modified″ to see only the subjects with access set directly at the target.)

More than one subject that is shown at a selected target can apply to a particular user. For example, a
user might be a member of two groups, both of which have access set to the target O=Acme. The
following precedence rules are applied to determine the access a user has to a target when there are
multiple subjects that apply to the user at the target.

Note: Even after precedence rules are applied, a user’s access can never exceed the access the database
ACL allows the user.
1. Access set for a subject with the scope ″This container only″ take precedence over access set for a
subject with the scope ″This container and all descendants″ regardless of subject type. For example,
the access set for the subject */Acme and the scope ″This container only″ takes precedence over the
access set for the subject Kathy Brown/Acme and the scope ″This container and all descendants.″
2. Among subjects with the same scope, access for a more-specific type of subject take precedence over
access for a less-specific type of subject. The order of subject specificity, from most specific to least
specific, is:
a. Individual user or server
b. Self
c. Group
d. A wildcard, -- for example */Acme
e. -Default-
For example, the access set for Kathy Brown/Acme with the scope ″This container and all
descendants″ takes precedence over the access set for the group Admins/Acme with the scope ″This
container and all descendants″.
3. When evaluating more than one group subject or more than one wildcard subject, the access settings
of the subjects are combined, with Deny access taking precedence over Allow access. For example, if
the group Admins/Acme denies Write access and allows all other access, and the group
Managers/Acme denies Create access and allows all other access, users that are members of both
groups are denied Write and Create access and allowed all other access.

Tip: To determine a user’s effective access to an extended ACL target after extended access settings and
database access are evaluated, select the target in the ″Extended Access at target″ dialog box, then click
Effective Access.

For more information on using the Effective Access tool, see the topic ″Showing a subject’s effective
access to an extended ACL target″ later in the chapter.

642 Lotus Domino Administrator 7 Help

Examples of precedence rules:

Combined access (can never

exceed the access granted in
Subject 1 Subject 2 the database ACL) Rule applied
Subject: */Acme Subject: */Acme Allow: Create, Delete, Write Rule 1

Scope: ″This container and all Scope: ″This container only″ Deny: Read, Browse
descendants″
Allow: Create, Delete, Write
Allow: Read, Browse
Deny: Read, Browse
Deny: Create, Delete, Write
Subject: Admins/Acme group Subject: */Acme Allow: All Rule 2

Scope: ″This container and all Scope: ″This container and all
descendants.″ descendants″

Allow: All Deny: All

Subject: Admins/Acme group Subject: Managers/Acme Deny: All Rule 3
group
Scope: ″This container and all
descendants″ Scope: ″This container and all
descendants″
Allow: Read, Browse
Allow: Create, Delete, Write
Deny: Create, Delete, Write
Deny: Read, Browse

Extended ACL subject

An extended ACL subject is a name for which you are setting access to a selected extended ACL target.
To add a subject to an extended ACL, you select the target and then click Add below the People, Servers,
Groups box in the ″Extended Access at target″ dialog box.

The following figure shows an example of the -Default- subject selected at the / (root) target.

Chapter 27. Setting Up Extended ACLs 643

You can specify any of the following as subjects in an extended ACL:
v Individual user or server
v Group
v Wildcard that represents documents at a specific location in the directory name hierarchy, for example,
*/West/Acme
v Anonymous
v -Default-
v Self

With the exception of Self, these are the same types of entries that are acceptable in a database ACL.

For more information on the database ACL, see the chapter ″Controlling User Access to Domino
Databases.″

You specify more than one subject at a target to give each subject its own access to the target. For
example the group Admins/West/Acme and the group Admins/East/Acme might each have access set
at the / (root) target. You can also add the same subject at multiple targets, to give the subject different
access to each target.

If the database ACL and an extended ACL both list a particular subject, Administration Process requests
can rename or delete the subject in the extended ACL, as well as in the database ACL.

644 Lotus Domino Administrator 7 Help

Anonymous as subject
As in the database ACL, the subject Anonymous controls the access of all users and servers that access a
server without first authenticating. Anonymous access applies to access via all the supported protocols.

Self as a subject
The subject Self is available only for an extended ACL and not the database ACL. At a target category
only, you can use Self to define the access that all users have to their own documents that fall under the
target category. A user’s own document is one with a distinguished name that matches a distinguished
name presented by the user. Use Self so that you can use one subject to control all users’ access to their
own documents at a target category.

-Default- as a subject
Adding and setting access for the -Default- subject at a target is optional. If you set access for -Default- at
a target, all users and servers whose access is not determined by another subject at the selected target get
the access set for -Default-. If you add the -Default- subject to a target and you want some users to have
different access to the target than the -Default- access, add a subject or subjects that represent those users
to the target with the desired access.

Lotus Domino 7 servers as subjects

In general an extended ACL can’t restrict the access of a Domino 6 server. The exception is granting a
Domino 7 server Administer access to a target category that represents a particular location in the
directory name hierarchy. Doing so allows the server to be an extended administration server that can
carry out Administration Process requests for documents under the selected target category.

For more information, see the chapter ″Setting Up the Administration Process.″

Advantages to using subjects that represent a group of users

When possible use subjects that represent groups of users -- -Default-, Self, groups, wildcard subjects --
rather than use individual users as subjects. For example, set access for the group Admins/Acme, rather
than setting access for Acme administrators individually. When you use subjects that represent groups of
users you minimize the number of subjects in the extended ACL to add and manage and you optimize
access-checking performance.

Extended ACL target

You select a target to specify either a category of documents or a specific document to which you are
controlling a subject’s access. Selecting a category of documents as a target is recommended because you
can set access to multiple documents at once and because the access applies to documents added to the
category in the future. You use the Target box in the ″Extended Access at target″ dialog box to select a
target. You can set access for more than one subject at a target.

The following figure shows the / (root) target selected in the ″Extended Access at target″ dialog box. By
default you can see only the document categories in the Target box and not individual documents.
Deselect ″Show only containers″ to see the documents below the categories.

Chapter 27. Setting Up Extended ACLs 645

How the Target box categorizes documents
The target box categorizes documents by their names. The top category in the Target box is / (root).
Access set at / (root) applies by default to all the documents in the directory because documents
subcategorized below / (root) inherit the access set at / (root) by default. The Target box subcategorizes
documents that have hierarchical names defined by a FullName, ListName, or ServerName field below /
(root) by their location in the directory name hierarchy. For example, the Target box categorizes Person
documents containing the names CN=Alan Jones/O=Acme, CN=Derek Malone/OU=East/O=Acme, and
CN=Karen Lessing/OU=West/O=Acme as follows:

/ (root)

O=Acme

Alan Jones/Acme

OU=East

Derek Malone/East/Acme

OU=West

Karen Lessing/West/Acme

For a document to be categorized by name hierarchy in a subcategory below / (root) its name must
contain more than just one part. For example a Person document whose name is defined by a certifier is
subcategorized in a category below / (root). In addition, the name of the document must be stored in a

646 Lotus Domino Administrator 7 Help

field called FullName, ListName, or ServerName. The ListName field stores the names of Domino Group
documents, the ServerName field stores the names of Domino Server documents, and the FullName field
stores the names of other types of documents, for example Domino Person, Certifier, and Policy
documents.

A document with a flat name -- a name with only one part --, or a document with a name specified in a
field other than FullName, ListName, or Servername, is categorized directly under / (root). The Target
box does not show the documents under / (root) that are named through a field other than FullName,
ListName, or ServerName. You can set access to these types of documents through the / (root) target, but
cannot set access to an individual one. For example, the names of Holiday and Connection documents are
not controlled through a FullName, ListName, or ServerName field, so you cannot see or select these
documents under / (root). However, when you set access at / (root), the access applies to the documents.

Advantages to using categories rather than single documents as targets

You can select a specific document as a target at which to set a subject’s access, however selecting a target
category is recommended instead. When you select a target category, by default you are automatically
setting access to all the documents immediately below the selected category as well as to documents
below subcategories of the selected category so you minimize the number of times the subject appears in
the extended ACL. For example, by setting a subject’s access at the target O=Acme, the access by default
automatically applies to all documents below O=ACME and any organizational units below, such as
OU=West and OU=East.

Domino can verify a subject’s directory access more quickly when there are fewer occurrences of the
subject in an extended ACL than when there are many. In addition, when you use categories as targets
it’s easier to manage the extended ACL because there are fewer subjects to track.

To take full advantage of using categories as targets, you may want to specify hierarchical names for
documents that have flat names in a FullName, ListName, or ServerName field so the Target box can
subcategorize them under an appropriate location in the directory name hierarchy. For example, Group
documents often have flat names, and in this case the Target box categorizes them directly below / (root),
so you may want to change the names of such Group documents to hierarchical.

The following documents usually have hierarchical names defined in a FullName, ListName, or
ServerName field and are therefore subcategorized below / (root) under at the appropriate location in the
directory name hierarchy.
v Person documents
v Server documents
v Certifier documents
v Policy documents

Target scope
When you select a category as a target in the Target box, you use the Scope of Target box to specify
whether a subject’s access settings apply only to documents at that category or also to documents under
subcategories as well. Keep ″This container and all descendants″ (the default) selected to apply the
subject’s access settings to documents under the selected target category as well as to documents under
subcategories. Select ″This container only″ to apply the subject’s access settings to documents under the
selected target category only.

The following figure shows the target scope ″This container and all descendants″ selected for the subject
Admins/Acme at the / (root) target.

Chapter 27. Setting Up Extended ACLs 647

You select a scope for each subject with access at a target category.

Example of using ″This container and all descendants″ as a target scope: Suppose you want users who
access the database through the -Default- entry to see any Person and Group document in the directory
but no other type of document. You could do the following:
v Give the -Default- subject Reader access in the database ACL.
v In the extended ACL, add the -Default- as the subject at / (root) and deny it all access by default, but
allow it Browse and Read access to the Person and Group forms.
v Keep ″This container and all descendants″ as the scope to apply the access settings to the entire
directory.

The following figure illustrates these access settings.

648 Lotus Domino Administrator 7 Help

Example of using ″This container only″ as a target scope: Suppose the names of documents in your
company fall under the organization O=Acme or one of the organizational units OU=East or OU=West.
You want to deny the group Admins/Acme all access to documents in the directory except documents at
O=Acme. You want to allow the group all access to documents at O=Acme. You could give the group
Admins/Acme Editor access in the database ACL with all database ACL privileges and administration
roles. At / (root) deny Admins/Acme all access and select ″This container and all descendants.″ At
O=Acme allow Admins/Acme all access and select ″This container only″ as the scope. Admins/Acme
deny access set at / (root) continues to apply to OU=East and OU=West.

The following figure illustrates these access settings.

Adding a subject twice to a target category with different target scopes: Although not typically done,
you can add one subject two times to one target category with different access settings. Add the subject
to the target category and specify access for the scope ″This container only.″ Add the subject again to the
same target category and specify access for the scope ″This container and all descendants.″ Using this
approach, you can use one subject entry to set a subject’s access to multiple target subcategories, rather
than setting the subject’s access separately at each subcategory.

For example, suppose you want to allow members of the group Admins/Acme full access to documents
categorized directly under O=Acme. You also want to allow members of the group to browse and read
documents categorized under OU=East and OU=West, but want to prevent them from creating, deleting,

Chapter 27. Setting Up Extended ACLs 649

writing, and setting extended access settings for these documents. You want to deny the group access to
all other documents. To accomplish this you could do the following:
v Add Admins/Acme to the database ACL with Editor access and all privileges and administration roles.
v Add Admins/Acme as a subject at / (root), deny all access and select the scope ″This container and all
descendants.″
v Add Admins/Acme to O=Acme, allow all access and select the scope ″This container only.″
v Add Admins/Acme to O=Acme again, allow only Browse and Read access and deny all other access
and select the scope ″This container and all descendants.″

Assuming there are no other subjects in the extended ACL that control access for the members of the
Admins/Acme group, precedence rules determine that the access set for Admins/Acme at O=Acme with
the scope ″This container only″ controls Admins/Acme’s access to the documents directly under
O=Acme. The access set for Admins/Acme at O=Acme with the scope ″This container and all
descendants″ controls Admins/Acme’s access to the documents subcategorized under OU=East and
OU=West below O=Acme.

The following figure illustrates these access settings.

Extended ACL examples

v Example 1
v Example 2

Extended ACL: example 1

The Acme company uses this name hierarchy within its Domino Directory: the organization O=Acme,
and two organizational units below it, OU=Sales and OU=Engineering. The Acme company wants to
prevent users registered under OU=Sales from accessing documents within OU=Engineering, and wants
to prevent users registered under OU=Engineering from accessing documents within OU=Sales. Acme
does the following to accomplish these security goals:
1. Sets the -Default- access in the Domino Directory database ACL to Reader.
2. Denies the subject */Sales/Acme all access to the target OU=Engineering.
3. Denies the subject */Engineering/Acme all access to the target OU=Sales.

650 Lotus Domino Administrator 7 Help

Extended ACL: example 2
The Acme company uses one Domino domain. The directory name hierarchy within the Domino
Directory consists of the organization O=Acme, and two organizational units below that, OU=West and
OU=East. The Acme Domino Directory includes three groups of administrators:
v The Admins/Acme group, responsible for managing documents throughout the directory.
v The Admins/West/Acme group, responsible for managing documents that fall under OU=West and
that have names ending in West/Acme.
v The Admins/East/Acme group, responsible for managing documents that fall under OU=East and that
have names ending in East/Acme.

Security goals

To establish security, Acme has these goals:

1. Allow members of the Admins/Acme group to:
v Have full access to all documents in the directory
v Manage access at any target in the extended ACL
2. Allow members of the Admins/West/Acme group to:
v Read all fields in all documents in the directory
v Create, modify, and delete only documents that fall under OU=West
v Manage the extended ACL at the OU=West target
3. Allow members of the the Admins/East/Acme group to:
v Read all fields in all documents in the directory
v Create, modify, and delete only documents that fall under the OU=East
v Manage the extended ACL for the OU=East target.
4. Allow authenticated users not in any of the administration groups to browse and read only Person,
Group, and Resource documents throughout the database but not other documents, and prevent these
users from creating, deleting, and modifying any documents.
5. Prevent anonymous users from accessing the directory.

How Acme achieve its goals: The following tables describe how Acme sets up the Domino Directory
database ACL and the extended ACL to accomplish its security goals.

Database ACL:

Subject Access Description

-Default- Reader Required to allow non-administrators to browse and
read Person, Group, and Resource documents
Admins/Acme group v Manager Allows members of Admins/Acme to manage all
documents and the entire extended ACL -- no
v Delete
extended ACL settings needed
v All administration roles
Admins/West/Acme group v Editor Required to allow members of Admins/West/Acme
to create, modify, delete, and manage the extended
v Create, Delete
ACL for West/Acme documents
v All administration roles
Admins/East/Acme group v Editor Required to allow members Admins/East/Acme to
create, modify, delete, and manage the extended ACL
v Create, Delete
for East/Acme documents
v All administration roles
Anonymous No Access Prevents anonymous users from accessing any
information in the directory. No extended ACL
settings needed

Chapter 27. Setting Up Extended ACLs 651

/ (root) target in extended ACL:

This container and

Subject Access all descendants? Description
-Default- Default: Yes Allows non-administrators to read only Person,
v Deny all Group, and Resource documents

Person, Group, and

Resources:
v Allow: Browse,
Read
v Deny: Create,
Delete, Write,
Administer
Admins/West/Acme Default: Yes Prevents members of the Admins/West/Acme
group v Allow: Browse, group from modifying documents at the /
Read (root) and O=Acme targets
v Deny: Create,
Delete, Write,
Administer
Admins/East/Acme Default: Yes Prevents members of the Admins/East/Acme
group v Allow: Browse, group from modifying documents at the /
Read (root) and O=Acme targets
v Deny: Create,
Delete, Write,
Administer

OU=West target in extended ACL:

This container and

Subject Access all descendants? Description
Admins/West/Acme Default: Yes Allows members of Admins/West/Acme to
group v Allow all have full access to documents under OU=West

OU=East target in extended ACL:

This container and

Subject Access all descendants? Description
Admins/East/Acme Default: Yes Allows members of Admins/East/Acme to
group v Allow all have full access to documents under OU=East

Extended ACL guidelines

Plan an extended ACL on paper before you implement it. After you have planned the extended ACL on
paper, test it in a non-production environment before deploying it. When planning an extended ACL use
a sparse access control model that minimizes the number of extended ACL subjects you specify:
v Use categories as targets -- / (root) or subcategories below / (root) -- rather than individual
documents. To subcategorize documents below / (root), you may have to give some documents, for
example Group documents, hierarchical names manually.
v As a general rule use the default target scope ″This container and all descendants″ as the target scope
to extend subjects’ access to target subcategories.
652 Lotus Domino Administrator 7 Help
v Use names that represent groups of users -- Self, groups, wildcard subjects, -Default- -- as subjects
rather than the names of individuals.

When you use a sparse access control model Domino can check extended ACL access settings quickly
and you can manage extended ACL access settings easily.

Setting up and managing an extended ACL

Follow these procedures to set up and manage an extended ACL:
v Enable extended access
v Set a subject’s access to a target
v Modify or remove a subject’s access setting at a target
v Show a subject’s effective access to a target
v Use the history log to monitor changes to an extended ACL
v Disable extended access

For information on troubleshooting extended ACLs, see the chapter ″Troubleshooting.″

Enabling extended access

To set up an extended ACL for a Domino Directory or Extended Directory Catalog, you must enable
extended access for the database. Before you enable extended access, make sure you understand the
implications of doing so:
v Enabling extended access may take a few minutes on a very large directory database. The Notes or
Domino Administrator client is unavailable for other purposes during this process.
v To ensure that the database replicates properly, extended access requires use of the advanced database
ACL option ″Enforce a consistent Access Control List across all replicas.″
v After you enable extended access, you can’t make changes to the database on a server running an
earlier release because the changes can’t replicate to a Domino 6 or later server. If you enable extended
access, you must make directory changes only to a replica on a Domino 6 or later server.
v Enabling extended access enforces the database ACL, extended ACL, and Readers and Authors fields
for Notes clients looking up names in the directory. For example, if you enable extended access, then
Notes users who are addressing mail must have at least Reader access in the database ACL to use
type-ahead addressing or F9 address resolution against the directory. Or a Notes application that calls
NAMELookup functions to search the directory must have the necessary database access to carry out
the operation.
v Enabling extended access enforces the database ACL and extended ACL for anonymous LDAP searches
of the directory. Enabling extended access removes the anonymous LDAP access settings from the
domain Configuration Settings document, and they remain removed unless you disable extended
access at a later point. By default the directory database ACL gives Anonymous users No Access, so if
you want LDAP users to search the directory anonymously, you must change the access for the
Anonymous entry if you enable extended access.

For more information on converting anonymous LDAP access settings in a domain Configuration Settings
document to database ACL and extended ACL settings, see the chapter ″Setting Up the LDAP Service.″

CAUTION:
Do not enable extended access if you have any uncertainty about doing so.

To enable extended access for a Domino Directory or Extended Directory Catalog:

1. Open the database, and choose File - Database - Access Control.
2. Make sure you have Manager access in the database ACL.
3. Click Advanced, and then select ″Enable Extended Access.″
4. At this prompt, click Yes to continue:

Chapter 27. Setting Up Extended ACLs 653

 ″Enabling extended access control enforces additional security checking. See Domino Administrator
Help for more details. Do you want to continue?″
5. At this prompt, which appears only if the advanced database ACL option ″Enforce a consistent Access
Control List across all replicas″ is not yet enabled, click Yes:
″Consistent access control must be enabled first. Do you want to enable it now?″
6. At this prompt, click OK:
″If more than one administrator manages extended access control for this database, enable document
locking on the database to avoid conflicts.″
7. Click OK in the Access Control List dialog box.
8. At this prompt, click OK:
″Enabling extended access control restrictions. This may take a while.″
9. Look at the status bar on the client to see the status of this process.

Setting a subject’s access to an extended ACL target

To set a subject’s access to an extended ACL target in a Domino Directory or an Extended Directory
Catalog, follow these steps:
1. Review the guidelines for setting up an extended ACL.
2. Open the Domino Directory or Extended Directory Catalog.
3. Make sure you have enabled extended access for the directory.
4. If more than one administrator manages the extended ACL, enable the advanced database property
″Allow document locking.″ Document-locking ensures that only one administrator can modify the
extended ACL at a time.
a. Choose File - Database - Properties
b. Select ″Allow document locking.″
For more information on locking documents, see Notes 6 Help.
5. Choose File - Database - Access Control to open the Access Control List dialog box. Make sure you
have one of the following:
v Manager access.
v Editor or Designer access and the Administer extended ACL access to the target for which you are
setting the subject’s access. Either a database manager or someone with Administer access to the
target must give you this access.
6. With Basics selected, click Extended Access.
7. In the Target box at the left of the ″Extended Access at target″ dialog box, expand target categories as
necessary and select the target.
For information, see the topic ″Extended ACL target″ earlier in the chapter.

Tip: Below the Target box, deselect ″Show only containers″ to show the documents under each
target category. Select the option to show only the target categories. You can choose a single
document as a target, but doing so is discouraged.
8. Next to ″People, Servers, Groups″ below the Access List box, select one:
v Show Modified -- to show only subjects whose access to the selected target is set at the target.
v Show All -- (default) to show subjects whose access to the selected target is set at a higher target
using the ″This container and all descendants″ scope, as well as to show subjects whose access to
the selected target is set at the target.
9. To add the subject for which you are setting access to the selected target, do one:
v Click Add - Name and type or select a subject name, then click OK. If the subject is a user, server,
or group that is not in the directory for which you are controlling access, this prompt appears:
″Subject can not be found in the directory. To continue, please specify the subject’s type: Person,
Server, Group.″ Select one of the options presented, then click OK.

654 Lotus Domino Administrator 7 Help

 v Click Add - Default to add the subject -Default-.
v Click Add - Self to add the subject Self.
v Click Add - Anonymous to add the subject Anonymous.
If a subject’s access to the selected target is set at a higher target through the scope ″This container
and all descendants″ and you add the subject to the selected target with new access settings, the
new access settings then control the subject’s access to the selected target.
For more information on extended ACL subjects, see the topic ″Extended ACL subject″ earlier in the
chapter.
10. Below the Scope of Target box at the top, right of the ″Extended Access at target″ box, select one of
the following to specify the scope of the subject’s access at the selected target.
v This container and all descendants (default) -- to apply the subject’s access to the selected target
and to all targets subcategorized below it.
v This container only -- to apply the subject’s access to the selected target only and not to targets
subcategorized below it.
For more information, see the topic ″Target scope″ earlier in the chapter.

Note: If you selected a single document as a target in Step 7, the ″This container and all
descendants″ option is not available.
11. Below the Attributes section at the right of the ″Extended Access at target″ box, for each of the
following select Allow or Deny to set the selected subject’s default access to the selected target.
v Browse
v Create
v Delete
v Read
v Write
v Administer
For more information, see the topics ″Extended ACL access settings″ and ″Default access compared
to form-specific access″ earlier in the chapter.
12. (Optional) Set form-specific access to make exceptions to the default access.
13. Click OK to save the extended ACL changes and close the ″Extended Access at target″ box.

Setting a subject’s form-specific access to an extended ACL target

When you set a subject’s access to an extended ACL target, you can use this optional procedure to make
exceptions to the subject’s default access to the selected target and set access differently to documents
created from a specific form.

For each form for which you want to set different access than the subject’s default access set for the
selected target, do the following:
1. Select the subject for which you are setting access in the ″Extended Access at target″ dialog box and
click ″Form and Field Access″ to open the ″Form and Field access at target″ dialog box. The dialog
box shows the forms in the directory in the Forms box. When you select a form in the Forms box,
the Fields box shows only the fields in the selected form.
2. (Optional) To set the ″Form and Field Access at target″ dialog box to display LDAP object classes and
attributes rather than forms and fields, next to Schema select LDAP. This option works only if you
are setting access to a directory on a server running the LDAP service.
For more information, see the topic ″Displaying LDAP attributes and object classes when setting
form-specific access″ earlier in the chapter.
3. (Optional) To look at the subject’s default access to the selected target you previously specified in the
″Extended access at target″ dialog box.

Chapter 27. Setting Up Extended ACLs 655

 a. Below the Forms box, select the -Default- entry and look at the default Browse, Create, and
Delete access settings. Optionally, modify these default access settings. The changes will show in
the ″Extended access at target″ dialog box when you close the ″Form and Field Access at target″
dialog box.
b. With the -Default- entry still selected in the Forms box, look at the -Default- entry in the Fields
box to see the default Read and Write access. Optionally, modify these default access settings .
The changes will show in the ″Extended access at target″ dialog box when you close the ″Form
and Field Access at target″ dialog box.
4. In the Forms box, select the form for which you want to set access. Notice that the Fields box
changes to show only the fields on the selected form.
5. In the Forms box, set the desired Browse, Create, and Delete access settings for the selected form.
6. To set the subject’s Read and Write access to all fields in the selected form:
a. Keep the form for which you are setting access selected in the Forms box.
b. Select -Default- in the Fields box.
c. Set the subject’s general Read and Write access to the fields on the selected form.
7. To set the subject’s Read and Write access to a specific field in the selected form:
a. Keep the form for which you are setting access selected in the Forms box.
b. Select the field in the Fields box.
c. Set the subject’s Read and Write access to the selected field. These settings take precedence over
the settings specified in step 6.
8. (Optional) To show the form-specific access you have set:
a. Above the Forms box, select Show - Modified. Notice that Show - Modified is also selected above
the Fields box.
b. Select a form listed in the Forms box to see the access set specifically for that form.
c. With the form still selected, look at the Fields box to see the fields on the form for which you’ve
set access.
9. When you’ve finished setting form-specific access, click OK to close the ″Form and Field access at
target″ dialog box.
10. Continue to Step 13 in the procedure ″Setting a subject’s access to an extended ACL target.″

Showing a subject’s effective access to an extended ACL target

You can determine the effective access a subject has to a target in an extended ACL. The effective access
is the actual access a subject has to a target after the database ACL and extended ACL access settings and
conflicts are evaluated.
1. Open the database that uses the extended ACL, and choose File - Database - Access Control.
2. With Basics selected, click Extended Access. You see Extended Access only if you have enabled
extended access.
3. In the Target box to the left, expand the target categories as necessary and select the target for which
you want to determine a subject’s access.
4. Click ″Effective Access″ to open the ″Effective Access access at target″ dialog box.
5. Below the ″People, Servers, Groups″ box at the top of the dialog box, type or select the subject
whose effective access you want to determine. If the subject you cannot be found in the directory,
this prompt appears:
″Name type cannot be determined. Is this a group? Click Yes if the name is a group, or No if the
name is not a group.″

Note: You cannot determine the effective access for the subject Self.
6. Click ″Calculate Access.″
7. The Default Access section shows the subject’s default access to the selected target.

656 Lotus Domino Administrator 7 Help

 8. The Modified Forms section shows any forms for which the subject’s access is different than the
default access for the selected target.
a. Select a form in the Modified Forms section to see the access set for the form.
b. Look at the Modified Forms section to see the Browse, Create, and Delete access set for the
selected form.
c. Look at the Modified Fields section to see the field access set for the selected form. -Default-
shows the default field access for the select form. If there are individual fields listed, select a field
to see how its access is different than the default field access.
9. The ″Database access″ section shows the access the database ACL grants the subject.
10. The ″Access derived from″ box shows all the subjects that can control the subject’s access allowed in
the database ACL and the extended ACL and displays a check mark next to the subject or subjects
that determine the access.
11. When you are finished viewing the effective access, click Done.

Modifying or removing a subject’s access settings at an extended ACL target

You can modify a subject’s access to an extended ACL target. You can also remove a subject from a target
to remove the subject’s access settings for the target.

To modify a subject’s access to an extended ACL target: To modify a subject’s set at an extended ACL
target, follow the steps described in the topic ″Setting a subject’s to an extended ACL target,″ except in
step 9 select the subject rather than add it.

Note that if you select a subject in the ″Extended access at target″ dialog box and the subject’s access
settings are grayed out, check that you have the access required to change the settings: Manager access in
the database ACL or Editor access in the database ACL with Administer access to the selected target.

If you have the required access to make the change and the subject’s access settings are grayed out, the
subject’s access to the selected target is set at a higher target with the scope ″This container and all
descendants.″ In this case you can do one of the following:
v At the selected target, click Add to add the subject to the selected target and set different access for the
subject at the target. The new access to the selected target overrides the access set at the higher target.
If you choose the scope ″This container and all descendants″ the new access applies to all documents
subcategorized below the selected target as well. If you choose the scope ″This container only,″
documents categorized immediately below the selected target get the new access settings, but
documents under subcategories of the selected target continue to have the access settings specified at
the higher target.
v Select the higher target, select the subject at the higher target, and change the access. The changes
apply to documents directly under the higher target and to documents below all subcategories of the
higher target, including the target for which the subject’s access is grayed out.

To remove a subject’s access settings from an extended ACL target: Remove a subject from an
extended ACL target to remove the access settings specified for the subject at the target.
1. Make sure you have one of the following levels of access:
v Manager access in the database ACL.
v Editor or Designer access in the database ACL and Administer extended ACL access to the target
from which you are removing the subject. A database manager or someone with the Administer
access to the target must give you this access.
2. Open the database with the extended ACL, and choose File - Database - Access Control.
3. With Basics selected, click Extended Access.
4. In the Target box at the left of the ″Extended Access at target″ box, select the target from which you
want to remove the subject.
For information, see the topic ″Extended ACL target″ earlier in the chapter.

Chapter 27. Setting Up Extended ACLs 657

5. In the Access List box, select the subject that you want to remove, and click Remove.
6. Click OK and when you see the prompt ″Save changes before exiting?″ Click Yes to save the changes
and close the Extended access at target″ dialog box.
7. Click OK to close the Access Control List dialog box.

Using the history log to monitor changes to an extended ACL

You can display a log of all changes made to an extended ACL and to the database ACL. Each entry in
the list shows when the change occurred, who made the change, and what changed.
1. Open the database that uses the extended ACL, and choose File - Database - Access Control.
2. Do one of the following:
v Click Log from the Access Control List dialog box
v Click Extended Access and then click Log from the ″Extended Access at target″ box.
3. Select 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.
4. (Optional) Click Copy to copy the log to the Clipboard so that you can paste it into a document.

Note: If you use a Macintosh client, you cannot do Step 4.

Disabling extended access

Disabling extended access takes effect immediately and irreversibly removes any extended ACL
restrictions that have been set and so will alter security checking for the database. You will remove all
restrictions set on forms and fields, and the database ACL will no longer be restricted by extended ACL
access settings. In addition, the database ACL will no longer be enforced for Notes client lookups to the
directory, and the domain Configuration Settings will resume as the access control mechanism for
anonymous LDAP searches of the directory.

Disabling extended access removes all evidence of extended ACL settings, information that cannot be
recovered unless you restore it from a recent backup or archive of the directory, or unless you write
down the settings prior to disabling them and then reapply them manually later.

CAUTION:
Do not disable extended access if you have any uncertainty about doing so.

Note: Disabling extended access may take a few minutes on a very large directory database. The Notes
client or Domino Administrator client is unavailable for other purposes during this process.

To disable extended access:

1. Open the database and choose File - Database - Access Control.
2. Make sure you have Manager access in the database ACL.
3. Click Advanced and then click the ″Enable Extended Access″ check box to remove the selection.
4. At this prompt, click Yes if you are sure you want to disable extended access; otherwise, click No:
″Warning: Disabling extended access removes all extended access control restrictions that have been
set. Do you want to continue?″
5. Click OK in the Access Control List dialog box.
6. At this prompt, click OK:
″Disabling extended access control restrictions. This may take a while.″

The status bar indicates when the process is complete.

658 Lotus Domino Administrator 7 Help

Chapter 28. Overview of the Domino Mail System
This chapter describes how the Domino mail system works and provides information that you need to
consider before you deploy mail.

Messaging overview
The Domino mail system has three basic components: Domino mail servers, Domino mail files, and mail
clients. The Domino mail server is the backbone of an organization’s messaging infrastructure, acting
both as an Internet mail server and a Notes mail server. Domino provides standards-based Internet
messaging through its support of the Simple Mail Transfer Protocol (SMTP), Post Office Protocol version
3 (POP3), Internet Message Access Protocol (IMAP), and Multipurpose Internet Mail Extensions (MIME).
At the same time, Domino supports Lotus Notes mail through the use of Notes routing protocols -- Notes
remote procedure calls (NRPC) -- and the Notes rich text message format.

Domino mail servers provide services that directly and indirectly support messaging. These include
specialized databases for locating users and servers, for message storage and transit, and for collecting
statistics; and processes that initiate and receive connections between servers, route messages, and allow
users to retrieve mail.

Every mail user in a Domino system has a mail file on a Domino mail server. You can create a replica of
the mail file on other servers for failover in case the primary server is unavailable. Users create mail
messages using a mail client, such as Lotus Notes, or a POP3 or IMAP client, and send mail through the
Domino mail server, which routes the message to its recipient. The recipient then uses a mail client to
read the message. To protect confidential information in mail messages, Domino supports Notes public
key encryption and S/MIME encryption.

The Lotus Notes client and the Domino mail router (the Router) create and send messages in the format
(MIME or Notes rich text) appropriate for each recipient, as determined from the address format and
settings in the recipient’s Person document. If conversion between formats is necessary, Domino performs
the conversion automatically.

The Router uses information in the Domino Directory to determine where to send messages and what
transfer protocol to use. For messages sent over SMTP, the Router also uses information from the Domain
Name System (DNS).

Domino provides tools for monitoring mail, controlling unsolicited commercial e-mail (UCE), and
preventing unauthorized access to the mail system. To reduce the space needed to store users’ mail, you
can set quotas on users’ mail files, restrict users from creating full-text indexes, and implement Domino
shared mail on the server. Domino provides migration tools and message transfer agents to help you
move from a heterogeneous system to a Domino mail server, which combines support for Notes mail
alongside support for Internet mail standards.

This section includes overview information on the following topics:

v Supported mail routing and mail access protocols
v The Domino mail server and mail routing
v The Domino Directory and mail routing
v Domino mail files
v Mail security
v Mail clients
v Working with other mail systems

659
v Mail performance and monitoring

Supported routing, format, and access protocols

The Lotus Domino server and Lotus Notes client support both Internet standards and Notes protocols for
message routing, retrieval, and formatting. On the server, the Domino mail router (the Router) can send
and receive messages using the Simple Mail Transfer Protocol (SMTP) and Notes Remote Procedure Calls
(NRPC), or Notes routing. To enable users to retrieve mail, the server supports the Internet access
protocols, IMAP and POP3, as well as NRPC. In addition. the Domino HTTP service interacts with
Domino mail databases to provide mail service for HTTP clients, such as the Domino Web Access client.

Domino sends and stores messages in both MIME format and Notes rich text format, and the Notes client
creates and sends messages in either format.

Mail clients retrieve messages from the server using NRPC, IMAP and POP3. In addition, Web clients,
such as the Domino Web Access client, access mail through the Domino HTTP service. The Notes client
sends and retrieves mail using NRPC, or Internet protocols (SMTP, IMAP and POP3).

Mail routing protocols

When a new message arrives in MAIL.BOX, the Router determines where and how to send the message.
By default, the Router uses Notes routing to transfer mail from one server to another. If the server has
both SMTP and Notes routing enabled for the local Internet domains, the Router chooses the optimal
protocol to use to move the message to its destination. The protocol selection is based on the current
message format, the Domino version of the server that holds the recipient’s mail file, and the format
preference specified in the recipient’s Person document. For example, the Router uses SMTP to route the
MIME copy of a message to a POP3 recipient’s server, and uses Notes protocols to route the Notes rich
text format copy of a message to a Notes recipient’s server.

You can also configure Domino to use SMTP to route mail. SMTP routing can be used instead of, or in
addition to, Notes routing. You can configure a Domino server to use SMTP when transferring mail to
destinations within the local Domino domain only, to external Internet domains, or both.

Supported message formats

Domino transports and stores messages in both MIME format and Notes rich text format. The transit
format of a message depends in part on the routing protocol used, and can differ from the format in
which the message is stored in the destination mail file. When transferring messages over Notes routing
the Router handles messages in either MIME or Notes format. Messages sent over SMTP are always sent
in MIME format.

The format used to store a message depends on the storage preference specified in the user’s Person
document. A mail file can store messages in MIME format only, Notes rich text format only, or in both
formats, accepting messages as is, regardless of format. Administrators should ensure that each user’s
Person document specifies the format preference appropriate to their mail client. For example, because
IMAP clients require messages in MIME format, the Person document of a user who always accesses mail
from an IMAP client should specify MIME as the format preference for incoming mail.

To ensure that users receive messages in the format best suited to their chosen mail clients, Domino
converts messages between formats as needed. The Router may convert a message during transfer
between servers or when delivering the message to a user’s mail file. Conversion during transfer occurs
when a message in Notes format must be sent over SMTP, or when routing a MIME message to a Notes
user that is set to Notes Rich Text in their Person document. For example, The Domino IMAP and POP3
services also convert messages, as when an IMAP or POP3 client needs to retrieve a message stored in
Notes format.

Because Notes routing can transport messages in MIME format, on networks that support both Notes
routing and SMTP, a MIME message may travel over both protocols enroute to its destination.

660 Lotus Domino Administrator 7 Help

POP3 and IMAP clients, which always send messages to the server over SMTP, create messages in MIME
format. The Notes client creates messages in either Notes rich text or MIME format, depending on the
format required by the intended recipient. When a user sends a message from a Notes client to another
Domino mail user, the client software looks up the format preference specified in the recipient’s Person
document to determine which format to send. If the Person document indicates that the user’s mail file
stores messages in MIME format (as when a user accesses mail from an Internet mail client, such as an
IMAP client), the sender’s Notes client software sends messages to that recipient in MIME format.

If a recipient is not listed in the Domino Directory, the client software sends the message in the format
that corresponds to the address type; sending recipients with Internet-style addresses, such as
jane_doe@acme.com, messages in MIME format; and recipients with Notes-style addresses (Jane
Doe/Sales/Acme@Acme), Notes rich text.

When sending messages to multiple recipients, the client software creates the message in both MIME and
Notes rich text formats if necessary. For example, the client software creates a Notes rich text format
message for a recipient who uses a Release 4 Notes client and creates a MIME message for a recipient
who uses a POP3 client.

By combining SMTP, Notes routing, and automatic message conversion, Domino provides flexibility in
setting up your mail infrastructure. For example, you can set up a mail system that is based completely
on Internet standards and use the Router to route MIME messages over SMTP. You can set up a mail
system that is based completely on Notes mail and use the Router to route Notes format messages over
Notes routing. Or you can set up a mail system that uses both SMTP and Notes routing, sends both
MIME and Notes format messages, and uses automatic message conversion to ensure that clients receive
mail in the proper format.

Mail access protocols

Domino supports Internet mail access protocols such as IMAP and POP3 and also offers mail access to
Notes clients. IMAP and POP3 clients connect to their respective protocol services to retrieve and send
mail by way of an SMTP server. The Notes client can use Notes protocols to connect to a Domino mail
server to read and send mail, and can also use IMAP or POP3 to access mail on a Domino server or on
non-Domino mail servers -- for example, a UNIX sendmail server.

The Domino mail server and mail routing

To process incoming and outgoing mail, Domino mail servers run a variety of server tasks and maintain
a number of special databases. Some components are required for all Domino messaging systems; others
are needed to support specific configurations only.

The following table lists some of the required and optional components Domino uses to route mail:

Component
type Name Description
Server tasks
Router task Monitors the MAIL.BOX database for new messages. Responsible for
transferring messages to other servers and delivering messages to local mail
files. Can transfer mail using Notes remote procedure calls (NRPC) as well as
SMTP. Converts message format between Notes rich text and MIME as needed.
Maintains a routing table comprised of information derived from the Domino
Directory and NOTES.INI file.
SMTP task (Optional) Enables the SMTP listener, which lets the server receive messages
sent over SMTP routing.
Server task Listens for incoming messages sent by clients and servers over Notes routing
and for Notes client requests.

Chapter 28. Overview of the Domino Mail System 661

Component
type Name Description
IMAP task (Optional) Enables IMAP clients to access messages in user mail databases on
the Domino server.
Converter (Optional) Enables mail files for IMAP access.
Message Tracking (Optional) Maintains the MTSTORE.NSF database used to perform message
Collector (MT tracking.
Collector)
Object Store (Optional) Performs maintenance activities on databases and mail files that use
Manager shared mail.
POP3 task (Optional) Enables POP3 clients to access messages in user mail databases on
the Domino server.
HTTP task (Optional) Allows the server to host Web applications. Needed to provide Web
clients and Domino Web Access users with access to their mail databases on
the Domino server.
DOLS (Optional) Provides Domino Web Access users with offline access to their mail
databases.
Databases and Mail Router Special Notes database that acts as a temporary repository for all messages in
database Mailbox transit to and from mail clients, applications, other servers. Created
templates (MAIL.BOX) automatically at startup. The server creates the number of MAIL.BOX
databases specified on the Configuration Settings document.
Domino Directory Repository for documents that mail clients and the Router use to determine
(NAMES.NSF) where and how to send messages. Server document, Configuration Settings,
Person documents - security/message format, Domain, Connection, Internet
Site documents.
Mail file databases End-user mailbox for receiving and sending electronic mail. Every user who
accesses mail on a Domino server has a mail file.
Object Store (Optional) Repository for shared messages. The Router automatically creates
(Shared mail) the number of shared mail databases to meet the quantity and directory
databases locations you specify in the Server document. Domino also creates an
(SMXXXXXX.NSF) associated database link in the Data directory.
Mail Journaling (Optional) Stores copies of messages that pass through the Router Mailbox. A
database Mail journaling database is automatically created at startup after you enable
(MAILJRN.NSF) journaling.
Mail Tracking Repository for summary information about mail flowing through a server.
database Created and written to by the MTC add-in task after you enable message
(MTSTORE.NSF) tracking. The Mail Tracking database is read by the message tracking tool.
DOLADMIN.NTF Contains Security Policy documents and user profile documents for DOLS and
Domino Web Access applications. DOLADMIN.NSF is automatically created at
startup.
MAIL6EX.NTF Template for Web mail.

662 Lotus Domino Administrator 7 Help

How mail routes in a Domino system

These steps describe how mail routes in a Domino mail system.

1. Using a mail client, a user creates and addresses a mail message to a recipient.
2. The user sends the message.
3. The user’s mail client does one of the following:
v Uses Notes protocols to deposit the message into the MAIL.BOX database on the user’s Domino
mail server.
v Uses SMTP to send the message to the user’s Domino mail server, which must be running the
SMTP listener task. The SMTP listener task deposits the message into MAIL.BOX (Lotus Notes,
IMAP clients, POP3 clients).
v Uses HTTP to send the message to the user’s Domino mail server, which must be running the
HTTP task. The HTTP task deposits the message into MAIL.BOX (Web clients).
4. The Router finds the message in MAIL.BOX and determines where to send the message for each
recipient. The Router checks its routing table to calculate the next ″hop″ for the message on the path
to its recipients and determines the appropriate protocol -- either SMTP or Notes routing -- to transfer
the message.
v Using SMTP routing, the Router connects to the destination server -- the recipient’s mail server, a
relay host, a smart host, or one of the servers in the recipient’s Internet domain -- and transfers the
message.

Chapter 28. Overview of the Domino Mail System 663

 v Using Notes routing, the Router moves the message to the MAIL.BOX database on the server that
is the next hop in the path to the recipient’s mail server. The Router on that server transfers the
message to the next hop, until the message is deposited in the MAIL.BOX database on the
recipient’s home server.
5. The Router on the recipient’s server finds the message (in MAIL.BOX on a Domino server) and
delivers it to the recipient’s mail file.
6. Using a mail client, the user retrieves the message from the mail file. Depending on the type of mail
client, one of the following protocols is used: Notes remote procedure calls, IMAP, POP3, or HTTP.

Domino mail files

When you create a user account through the Domino registration process, Domino creates a Notes
database (NSF file) to serve as the user’s personal message store. Each mail file database is created from a
mail file template on a Domino server. The server where the mail file resides is known as the user’s home
server or mail server. Users can access a Domino mail file from a Notes client, a Web browser, a POP3
client or an IMAP client or from multiple types of clients (for example, a user might access mail from a
Notes client while at work and from a POP3 client at home). For users to access mail from the Domino
Web Access client, an administrator must create the mail file using the Domino Web Access template
(DWA7.NTF).

Mail databases support full-text indexing, encryption, replication, soft deletions, and archiving.
Administrators can specify properties or policies to limit the use of these features on mail files.

For users who access mail primarily or exclusively from the Notes mail client, you must create User IDs
during registration. A User ID is not required if a user accesses mail only from a mail client other than
the Notes client. For example, although a user who accesses mail from a Domino Web Access, POP3, or
IMAP client must have a Person document and Internet passwords, a User ID is not required. However, a
User ID is required for iNotes Web Access users who wish to work offline or read encrypted mail.

The Router on a user’s home server delivers incoming messages for the user to the mail file. Messages in
a mail file may be stored in either Notes rich text format (also known as Compound Document, or CD
format) or MIME format. The format used depends on settings in the user’s Person document. If a user’s
mail client opens or downloads a message that is stored in a format it cannot read, Domino automatically
converts the message. For example, if an IMAP client opens a message stored in Notes rich text format,
the Domino IMAP service converts the message to MIME before passing it to the client.

In environments where all users access mail from Notes mail clients, you might specify rich text storage.
For users who always access mail from IMAP or POP3 clients, MIME storage eliminates the need to
convert messages before they can be read. If you set a user’s preferred storage format to ″Keep in
sender’s format,″ the Router does not change the format of messages before placing them in the mail file,
so the mail file is likely to contain a mix of rich text and MIME messages.

By default, each user is considered to be the owner of their personal mail file, and as such, is granted
Manager access in the mail file’s Access Control List (ACL). Users with Manager access can delegate
subsidiary access to their mail files to specified, trusted individuals from a Notes client, Domino Web
Access client, or Webmail client. For example, executives in an organization may allow their secretaries to
read and send mail on their behalf.

To allow for mail delivery, the default ACL also grants Manager access to a user’s mail server and other
servers in the local Domino Domain. The ACL provides no access to other users in the mail system.

During registration, the presiding administrator can assume Manager access of a user’s mail file by
resetting the mail file owner access from Manager to Designer. Users require a minimum of Editor access
to their mail files to perform routine mail operations -- creating, sending, replying to, and deleting
messages. Other mail file operations require greater access privileges. For example, users must have at
least Designer access to create a full-text index.

664 Lotus Domino Administrator 7 Help

To help manage disk space, you can set database quotas to restrict the mail file size. In the Configuration
Settings document, you can enable the Router to withhold delivery of new mail when a mail file reaches
its quota. The Router continues to withhold mail until the user reduces the size of the mail file by
deleting or archiving messages.

In addition to a user’s primary mail file, users and administrators can replicate mail files to other
locations. Administrators can create server replicas to provide failover. A user can create a local replica on
a workstation or laptop and use it to work off-line.

Notes client users can create mail filtering rules to manage inbound messages. Administrators can use the
Domino Administrator and other standard Notes database tools, such as Compact and Fixup, to perform
a variety of maintenance tasks.

Mail clients
Clients interact with mail files on the Domino server in different ways. All clients can create, send, and
receive mail. Some clients, such as Web browsers, can only interact with mail on the server and cannot
store mail locally. Some clients, such as POP3 clients, can only download mail from the server and work
with it locally. Some clients, such as Lotus Notes, Domino Web Access, and IMAP clients, can download
mail or work with it on the server and can store mail locally. You can use the following types of clients
with the Domino mail server:
v Lotus Notes clients
v IMAP clients, such as Microsoft Outlook Express
v POP3 clients
v Web browsers, such as Mozilla Browser and Microsoft Internet Explorer
v Domino Web Access clients
v Domino Access for Microsoft Outlook clients

Lotus Notes clients

A Notes client can interact with a Domino server using either Notes protocols or Internet protocols, such
as IMAP, POP3, and SMTP. If your organization uses Notes clients, select any of these protocols for server
access. Enable the protocol on the server that clients use for access.

Notes clients access the Domino Directory using either Notes protocols or Lightweight Directory Access
Protocol (LDAP). Users can create a local replica of their mail file while maintaining a complete mail file
on a Domino server. Notes users can work off-line and then connect to their server to replicate changes to
documents and send mail.

IMAP clients
Users with IMAP clients can download mail to a local mail file or interact with and manage mail directly
on a Domino server that runs the IMAP service. They use the IMAP protocol to read and manage mail,
use SMTP to send mail, and can use LDAP to access the Domino Directory.

Enable the IMAP service and enable the SMTP listener to let IMAP clients use the Domino server for
mail.

For more information, see the chapter ″Setting Up the IMAP Service.″

POP3 clients
Users with POP3 clients can download mail to a local mail file and interact with it there, as well as leave
a copy of the mail in their file on the Domino server. POP3 clients retrieve mail from a Domino server
that runs the POP3 service, use SMTP to send mail, and can use LDAP to access the Domino Directory.

Enable the POP3 service and enable the SMTP listener so that POP3 clients can use the Domino server for
mail.

Chapter 28. Overview of the Domino Mail System 665

For more information, see the chapter ″Setting Up the POP3 Service.″

Domino Web Access clients and Web mail clients

Users with mail files on a Domino server running the HTTP service can retrieve and send mail from a
Web browser. All mail-related tasks and actions are transmitted to the server over HTTP and performed
by the server.

From a Web browser, a user accesses mail using either the standard mail template or the Domino Web
Access template (DWA7.NTF). Users whose mail files are based on the standard mail template can
interact with mail on the server but cannot store mail locally.

Users whose mail files are based on the Domino Web Access template and who use Internet Explorer as
their Web browser can use the Domino Web Access mail client. On servers running Domino Off-Line
Services (DOLS), Domino Web Access users can create a local mail file replica and work offline. Changes
made to the offline mail file are replicated to the server the next time the user connects. Users whose mail
files are based on the standard mail template cannot access a local mail file replica from the browser.

Enable the HTTP service for Web clients to use the Domino server for mail.

For more information, on setting up the HTTP service, see the chapter ″Setting Up the Domino Web
Server.″ For more information on supporting Domino Web Access, see the chapter ″Setting Up Domino
Web Access.″

Domino Access for Microsoft Outlook

Users whose mail files are based on any of the Domino 6 or newer mail templates on a Domino server,
can use Domino Access for Microsoft Outlook to access mail from a Microsoft Outlook client.

Domino Access for Microsoft Outlook communicates with the server using a Notes MAPI service
provider. Installing Domino Access for Outlook on the client automatically creates and configures a MAPI
profile associated with the user’s Domino server and mail file. Data exchanged between client and server
travels over Notes routing protocols. Users can send and receive Mail using Outlook, as well as create
and update entries in the mail file’s calendar view using calendaring and scheduling tools in the Outlook
client.

Using Domino Access for Microsoft Outlook, users store their Domino data in Outlook’s local .PST file,
which is synchronized with the Domino mail file on the server. Domino Access for Microsoft Outlook can
also be used offline. Any changes to the offline .PST file are replicated to the server and synchronized the
next time the user connects.

For more information about Domino Access for Microsoft Outlook, see the chapter ″Setting up Domino
Web Access.″

Mail security
To provide secure message transfer among clients and servers, the Domino mail server supports name
and password authentication and Secure Sockets Layer (SSL) for SMTP mail routing, IMAP, and POP3
access, and supports Notes encryption when routing mail over Notes routing.

To encrypt and sign messages, Notes clients can use Notes encryption with User ID files and
public-private keys or Internet mail security with X.509 certificates. Internet mail clients can use X.509
certificates.

For more information, see the chapters ″Planning Security,″ ″Setting Up SSL on a Domino Server,″
″Encryption and Electronic Signatures,″ and ″Setting up Clients for S/MIME and SSL.″

666 Lotus Domino Administrator 7 Help

Working with other mail systems in your organization
Domino interoperates with other mail servers and systems through its support of Internet standards and
message transfer agents (MTAs), for example, Microsoft Exchange. Domino can exchange mail with other
SMTP servers and route mail to and from Microsoft Exchange and other systems through the MTAs.
Additional third-party tools are available to provide interoperability with and gateways to other mail
systems.

If you have some users who use Microsoft Exchange, you need at least one Exchange server running the
Exchange message transfer agent (MTA) to connect your Domino system to the Microsoft Exchange
system.

If you have users in the local Internet domain who are not listed in the Domino Directory, set up a smart
host so the Router can forward messages for users in other local mail systems.

Mail performance and monitoring

Domino offers many performance-enhancing features, such as using multiple MAIL.BOX databases and
shared mail. Using multiple MAIL.BOX databases allows multiple server processes to write mail at once;
the Router can operate on messages in one MAIL.BOX database, while clients or other servers deposit
mail to other MAIL.BOX databases. Shared mail provides more efficient disk usage by storing a single
copy of a message addressed to multiple recipients on a server in a shared mail database on the server.
Each recipient receives a header for that message, but the body of the message is stored in the shared
mail database to save disk space in users’ mail files. Users can still forward and reply to mail as usual.

Domino and the Domino Administrator have a number of monitoring features to help you plan, review,
and troubleshoot your Domino system. You can record server statistics, see which tasks are running on
servers, track mail messages, and make changes to multiple databases at once.

For more information, see the chapters ″Setting Up Shared Mail,″ ″Monitoring the Domino System,″ and
″Monitoring Mail.″

The Domino Directory and mail routing

The Domino Directory (NAMES.NSF) is the most important database on a server. It defines the primary
administrative unit in a Domino network, the Domino domain, which is a group of servers that have the
same Domino Directory. The Domino Directory serves as the control center for the domain.
Administrators use it to manage users and connect and configure servers and it contains almost all of the
essential information required for routing mail.

When you set up the first Domino server, the setup program creates your Domino domain’s Domino
Directory. Each server in the domain stores a replica of the Domain’s Domino Directory. Domino
replication synchronizes the Domino Directories on each server.

In addition to the Domino Directory, Domino retrieves information from the server’s NOTES.INI file and,
when routing mail over SMTP, from the Domain Name System (DNS), which is maintained separately.

The Domino Directory supports LDAP so that Internet mail clients can use LDAP to query and modify
the directory if they have access to do so.

For more information on LDAP, see the chapter ″Setting Up the LDAP Service.″

Domino routing tables

A routing table is a list of connections from a Domino server to all other servers it can contact. Domino
uses the routing table to determine the best, least-cost path to deliver mail. When you start the Router on
a server, it gathers information from the NOTES.INI file, and the Configuration Settings, Connection,
Domain, and Server documents in the Domino Directory to build a dynamic routing table.

Chapter 28. Overview of the Domino Mail System 667

The Router automatically recalculates the routing table after you reboot the server or restart the router
task. In addition, the Router checks the Domino Directory for changes at intervals of approximately five
minutes. If it detects changes in these source documents, it rebuilds the routing table to incorporate the
new information.

Note: Changing routing information in the NOTES.INI file or in the Domino Directory, does not force the
Router to immediately recalculate the routing table.

You can use a TELL command to refresh the routing table without having to restart the Router. The
ability to update the routing table on demand is especially useful when testing new configuration
settings. See the chapter ″Setting Up Mail Routing″ for more information about using the update
configuration TELL command.

How the Router uses the Domino Directory to look up mail recipients
When a user sends mail to a recipient in the local domain, the Router looks up the complete address in
the ($Users) view of the Domino Directory (if you set up Directory Assistance, the Router can also look
up the address in a secondary directory) for the recipient’s Person document, which lists the recipient’s
home server. If the recipient’s home server is the current server, the Router will deliver the message. If it
is a different server, the Router consults the routing table to determine the best route, or least-cost path,
for transferring the message to the destination home server and routes the message along that path..

If the Router cannot find a match for the recipient in the specified directories, it can forward the message
to a ″smart host,″ which is a server that has a directory of users who are in the local domain but who are
not listed in the Domino Directory. For example, if you are migrating users from a UNIX sendmail
system to a Domino mail system but you have not migrated all users yet, you set up a UNIX server as a
smart host that can locate the sendmail users and route mail to them. Enter the name of the smart host in
the Local Internet domain smart host field on the Router/SMTP-Basics tab of the Configuration Settings
document.

For more information setting up routing in the local Internet domain and setting up a smart host, see the
chapter ″Setting Up Mail Routing.″

Documents used for routing mail

The Domino Directory uses numerous documents to define the messaging topology. Depending on your
needs, you may need to create or edit the following documents:

Documents
Server documents
Configuration Settings
documents
Connection documents
Global Domain documents
Description
Every Domino server requires a Server document. Server documents specify the
following for each server: Notes name; IP address; fully-qualified Internet
hostname; Domino domain; the Notes Named networks it is a member of;
Internet messaging ports and services available, such as the IMAP, POP, and
SMTP ports; the security options for each port.
Configuration Settings documents provide additional information that determines
how servers process incoming and outgoing mail. They define Router settings for
SMTP and Notes routing; set inbound SMTP restrictions; provide MIME
conversion information; configure mail access for IMAP and Domino Web Access
clients.
Connection documents define the routing path to servers outside the current
Domino domain or Notes Named Network.
Global Domain documents identify the Internet domains considered to be
internal to a Domino domain and for which the local domain can accept mail.
Also provides instructions for converting the sender’s Notes mail address to an
SMTP address.

668 Lotus Domino Administrator 7 Help

Documents
Adjacent and Non-adjacent
Domain documents
Foreign SMTP Domain
documents
Internet Site documents
File Identification documents
Person documents
Description
Adjacent and Non-adjacent Domain documents specify the domains from which
the current domain will accept mail destined for a specified adjacent or
non-adjacent domain. Non-adjacent Domain documents also define the
intermediary domain through which the local domain routes mail intended for a
Notes domain to which no direct connection exists.
Foreign SMTP Domain documents define the relationship between Domino
domains and SMTP mail systems.
Internet Site documents provide protocol information for IMAP, POP3 and SMTP
ports. If configured, the information in a Site document takes precedence over
settings for the port in the Server document.
File Identifications documents define the relationships between the file extensions
and MIME types and subtypes of various file types.
Person documents provide information about the location of the user’s mail file;
Notes and Internet mail addresses; Internet passwords required for HTTP, POP3,
and IMAP access; and mail storage preferences.

Host names in the Domino system

For ease of maintenance, when entering server information in the Domino Directory, refer to the server
by its fully-qualified host name rather than its IP address. Although Domino fully supports IP addresses,
host names are less subject to change than numeric addresses. For example, for TCP/IP to work properly
a server’s numeric IP address must change if you move the server to a new subnet, or have to merge two
networks as the result of reorganization. Using a host name in the same documents, on the other hand,
would not require any update.

Overview of routing mail using Notes routing

By default, Domino uses Notes Remote Procedure Calls (NRPC) -- also called Notes routing or the Notes
routing protocol -- to transfer mail between servers. Notes routing uses information in the Domino
Directory to determine where to send mail addressed to a given user. Notes routing moves mail from the
sender’s mail server to the recipient’s mail server. The Router for the sender’s server determines the next
server to move the message to -- or in other words, the next ″hop″ on the path to the message’s
destination. Each server uses its routing table to calculate the next hop along the route to the destination
server. When the message reaches the destination server, the Router delivers it to the recipient’s mail file.

How Notes routing moves a message

When a user sends mail to a recipient with a Notes address -- for example, Jane Doe/Acme -- the Router
picks up a message in MAIL.BOX to determine where to direct the message. The Router first looks in the
Domino Directory for a Person document for the recipient, Jane Doe/Acme. The Person document
contains the name of Jane Doe’s mail server. From this information the Router uses its knowledge of the
network (that is, the routing table) to determine the next stop for the message. How the Router
dispatches the message depends on whether the recipient’s mail file is located:
v On the same server
v On a different server in the same Notes named network
v On a server in a different Notes named network within the local Domino domain
v On a server in an external Domino domain

Moving a message to a recipient on the same server

After checking the recipient’s Person document, if the Router determines that the recipient’s mail server
is the same as the sender’s server, the Router delivers the message to the recipient’s mail file.

Moving a message to a recipient on another server within a Notes named network

If the sender and recipient don’t share a mail server, the Router checks the Domino Directory to
determine whether the servers are in the same Domino domain.

Chapter 28. Overview of the Domino Mail System 669

If the Server document for the destination server is found within the Domino Directory, the Router
checks that document to determine the network information for the server. On the Ports - Notes Network
Ports tab of the Server document, the server is assigned to one or more Notes named networks (NNNs).
A Notes named network is a group of servers in a given Domino domain that share a common protocol
and are connected by a LAN or modem connections.

Note: Servers within the same domain may or may not be in the same Notes named network. Servers
that share a Notes named network are always in the same Domino domain.

If the two servers share a Notes named network, the Router immediately routes the message from the
MAIL.BOX file on the sender’s server to the MAIL.BOX file on the recipient’s server. The Router on the
recipient’s server then delivers the message to the recipient’s mail file. Because mail routes automatically
within a Notes named network, you do not need to create any additional connections or documents.

Moving a message to a recipient in a different NNN within the same Domino

domain
If the sender’s and recipient’s mail servers are in the same Domino domain, but don’t share either a mail
server or a Notes named network, for transfer to succeed there must be some connection between the
two networks. Connections between Notes named networks can be achieved by two means:
v Using a ’bridge″ server that is a member of multiple Notes named networks
v Using a Connection document

When a Connection document provides the information for routing mail between NNNs, the source and
destination networks can be in different Domino domains. The document contains all of the information
the Router needs to locate the destination network.

Using a ″bridge″ server to connect two networks in the same Domino domain
Two networks in the same domain can communicate with each other in the absence of a Connection
document if any one server is a member of both networks. Servers that reside in multiple networks can
act as a bridge between networks running diverse protocols. For example, if you have one Notes named
network running TCP/IP and another running SPX, you can set up a server that runs both protocols to
be a member of both Notes named networks. This server acts as a bridge between the networks.

When a user in the TCP/IP network sends a message to someone in the SPX network, the Router
transfers the message from MAIL.BOX on the sender’s server to MAIL.BOX on this ″bridge″ server. After
the message reaches a server in the destination Notes named network, the Router on that server transfers
the message to the MAIL.BOX on the recipient’s server. The Router on the recipient’s server delivers the
message to the recipient’s mail file.

If the path between servers involves multiple server ″hops,″ the Router transfers the message to
MAIL.BOX on the next server in the path. Each Router on the path transfers the message to the
MAIL.BOX on the next server in the path.

Using Connection documents to connect networks and domains

When there is no common server to provide a bridge between networks, the Router requires a
Connection document to transfer mail between them. A Connection document specifies the sending and
receiving servers, when and how to connect, and what tasks -- such as, replication and mail routing -- to
perform during the connection. The source, or sending, server, and the receiving, or destination, server
named in a Connection document may reside within the same Domino domain, or in different Domino
domains.

After the Router finds a connection between the two Notes named networks, it routes the mail to the
next server along the connection path.

670 Lotus Domino Administrator 7 Help

Connection documents for mail routing specify connections in one direction and are generally found in
pairs. For example, one Connection document schedules a connection from Server A to Server B, and
another Connection document schedules a connection from Server B to Server A.

For more information about connecting servers in different Notes named networks, see the chapter
″Setting Up Mail Routing.″

Moving a message to a recipient in an external Domino domain

When a message in MAIL.BOX has a recipient address that points to a destination outside of the local
Domino domain, the Router checks the Domino Directory for a Connection document that describes how
the local domain communicates with the destination domain. You can create a Connection document
between two domains whenever there is a direct physical connection between them.

After finding the Connection document, the Router routes the message to the server in the sender’s
domain that connects to a server in the recipient’s domain. When the servers connect, the message is
transferred to the other domain, where it routes to the recipient’s server and mail file.

Indirect connections between Domino domains

In organizations that have three or more Domino domains, you may not be able to use Connection
documents to connect certain domains, because the network topology does not allow for direct physical
connections between them. However, if they both have Connection documents to a common intermediate
domain, you can route mail from the source domain to the destination domain through the domain (or
domains) that bridge them. For example, if Domain A and Domain B do not have any server connections
but both have connections to Domain C, mail between Domain A and Domain B can route through
Domain C. To set up this routing path, you create Non-adjacent Domain documents that specify the
target domain and the domain through which to route mail to reach that target domain.

Addressing mail to users in a different domain

When sending mail within a Domino domain, the sender only has to specify the user’s common name,
for example, John Smith. Since John Smith has a Person document in the same Domino Directory as the
sender, the Router finds John’s entry in the directory and determines the location of his mail file.
However, when sending mail to a user in a different Domino domain, the Router does not have access to
the recipient’s Person document, since it is stored in a different Domino Directory. When addressing mail
to a user in a different Domino domain, the sender must append the recipient’s domain to the recipient’s
address. For example, a user in the Lotus domain who wants to send mail to John Smith in the Acme
domain must address the message to jsmith@Acme, not just jsmith or John Smith. The domain name in
the address signals the Router to look for a Connection document to this domain and transfer the
message to the server specified in that document.

To make it easier to address mail to users in other domains, users can create an entry in their Personal
Address Book to specify the recipient’s complete address -- for example, jdoe@Acme. Alternatively, an
administrator can create an entry in the Domino Directory to specify the recipient’s address in the
Forwarding address field of the recipient’s Person document, or use Directory Assistance or a Directory
Catalog to share Domino Directories across domains.

For information about setting up Directory Assistance and Directory Catalogs, see the chapter, ″Planning
Directory Services″. For information on using LDAP directories, see the chapter, ″Setting up the LDAP
Service.″

Overview of routing mail using SMTP

By default, Domino uses the Notes routing protocol to transfer mail between servers. You can configure
Domino to use SMTP to route mail instead of or in addition to using Notes routing.

Message transfer over SMTP routing is performed as a point-to-point exchange between two servers. The
sending SMTP server contacts the receiving SMTP server directly and establishes a two-way transmission
channel with it. To send a message over SMTP:

Chapter 28. Overview of the Domino Mail System 671

1. The sending server checks the recipient’s address, which is in the format localpart@domain, and looks
up the domain in the Domain Name System (DNS).
2. DNS returns the Mail Exchanger (MX) record for the domain, indicating the IP address of the servers
in the domain that accept mail over SMTP.
3. The sending server connects to the destination server over TCP/IP, establishes an SMTP connection
on port 25, transfers the message, and closes the connection.

Enabling SMTP on the Domino server

Domino supports sending and receiving mail over SMTP by means of the SMTP listener task and SMTP
Router, respectively, each of which you enable separately. The SMTP listener task handles incoming SMTP
connections and delivers messages received over those connections to MAIL.BOX. It does not handle
subsequent delivery or transfer of those messages. You configure the SMTP listener task for receiving
mail on the Basics tab of the Server document. For more information about configuring Domino to
receive SMTP mail from other servers in your organization and/or from the Internet over SMTP, see the
chapter, ″Setting Up Mail Routing.″

The Router task for SMTP is the same Router task that handles Notes routing. When a message in
MAIL.BOX requires transfer to another server, the Router determines where to send it and whether to
send it over Notes routing or SMTP.

By default, SMTP is disabled. To configure Domino to use SMTP to send mail, you must change settings
on the Router/SMTP-Basics tab of the Configuration Settings document. You can configure Domino to
use SMTP when sending mail to destinations:
v Outside the local Internet domain
v Within the local Internet domain
For more information, see the chapter ″Setting Up Mail Routing.″

How the Router determines when to use SMTP

On servers that support both SMTP and Notes routing, each time the Router detects a new message in
MAIL.BOX, it chooses the protocol by which to transfer the message. The routing decision is based on the
message’s address and format, and whether the server is configured to send SMTP within the local
Domino domain, outside the local Internet domain, or both.

Using SMTP to send mail to local domain addresses

Enabling SMTP within the local Domino domain allows the Router to consider SMTP as an alternative
routing protocol when transferring mail to another Domino server in the same Domino domain. When
configuring servers to send SMTP within the local Domino domain, you have the following options:
v SMTP allowed for MIME messages only - If the destination is a Domino server running the SMTP
listener and the message deposited in MAIL.BOX is already in MIME format, the Router sends it using
SMTP. Messages in Notes rich text format are sent over Notes routing.
v SMTP allowed for all messages - If the destination is a Domino server running the SMTP listener, the
Router always uses SMTP when transferring a message to another Domino SMTP host, regardless of
the message’s current format. If a message deposited in MAIL.BOX is in Notes format, the Router
converts the messages to MIME before sending.

When the Router picks up a message in MAIL.BOX, it reads the address to determine whether the
recipient is in the local domain. If the recipient is local, the Router looks in the ($Users) view of the
Domino Directory for a Person document containing that address. If SMTP is allowed within the domain
and the message format matches the format specified in this setting, the Router uses TCP/IP to connect
to the destination server, establishes an SMTP connection, and transfers the message.

By default, enabling SMTP within the local Domino domain allows the Router to use SMTP to transfer
mail to any other Domino SMTP host in the same Domino domain. You can restrict the use of SMTP
within the local domain so that SMTP is allowed only for message transfers that take place between

672 Lotus Domino Administrator 7 Help

servers in the same Notes named network. To set this restriction, use the field ″Servers within the local
Domino domain are reachable via SMTP over TCPIP″ on the Router/SMTP - Basics tab of the
Configuration Settings document.

If the receiving server is running the SMTP listener, servers configured to send SMTP within the local
Domino domain always use SMTP to send MIME messages to destinations within the same Notes named
network. For messages in Notes format, the Router sends SMTP only if the server is configured to send
all messages over SMTP.

Sending SMTP outside the local Internet domain

Enabling Domino to send SMTP to external Internet domains allows the server to transfer outbound
Internet mail either directly to a host in the receiving domain or indirectly to an Internet host.

If a message in MAIL.BOX has a recipient address that contains an @ sign and a domain part (the part of
the address to the right of the @ sign) that does not resolve to the local Domino domain, the Router
identifies the message destination as non-local. A non-local address can be an RFC 821 Internet address
(where the domain part contains a period and is in the form localpart@org.domain) or an address in
another Domino domain (including Foreign domains such as a pager or fax gateway).

To determine whether an Internet address is local, the Router checks whether the domain part of the
address matches any of the local Internet domains defined in the Global Domain document in the
Domino Directory. Local Internet domains include any domains listed in the Local primary Internet
domain and Alternate Internet domain aliases fields in the Global Domain document. If there is no
Global Domain document, the Router compares the domain in the recipient’s address to the server’s host
name. For example, if the message is addressed to jdoe@mailhost3.acme.com and the Router is on the
server mailhub.acme.com, the Router knows that the recipient is in the local Internet domain.

Connecting the Domino mail system to the Internet

Because Domino routes mail using the Internet-standard SMTP routing protocol, it’s easy to configure the
Domino system to send and receive mail from external Internet domains. For outgoing mail you can use
a gateway routing architecture in which only designated servers use SMTP to route mail to external
domains, or you can enable all mail servers to use SMTP to route mail to external domains. For inbound
mail, you need to decide how to route mail coming in to your Internet domain from a firewall to Domino
servers. How you set up inbound mail depends on whether your organization uses a single Internet
domain name or multiple names and on the distribution of your servers.

For information on connecting Domino to the Internet, see the topics Preparing to send and receive mail
to the Internet and Routing mail to external Internet domains.

For information on connecting Domino to the Internet, see the chapter ″Setting Up Mail Routing.″

Using a relay host

A relay host is an SMTP server or firewall that connects to the Internet and forwards, or relays, inbound
or outbound Internet mail. A relay host can also be a DNS name that maps to multiple MX records. To
configure Domino to use a relay host, you use two fields on the Configuration Settings document of the
sending server. Add the relay’s DNS or host name to the ″Relay host for messages leaving the local
Internet domain″ field and enable ″SMTP used when sending messages outside of the local Internet
domain.″

Using Notes routing to transfer outbound Internet mail to an SMTP server

On internal Domino servers that do not use SMTP to route mail, Domino uses Notes routing to transfer
outbound Internet messages to a Domino SMTP server, which then transfers the messages to the Internet,
either directly or through a relay host. To configure servers that use Notes routing to transfer Internet
mail to a Domino SMTP server requires use of a Foreign SMTP Domain document and an SMTP
Connection document.

Chapter 28. Overview of the Domino Mail System 673

For more information on setting up Notes routing for Internet mail, see the chapter ″Setting Up Mail
Routing.″

The Domain Name System (DNS) and SMTP mail routing

The Domain Name System (DNS) is a directory used by SMTP to convert a name, such as acme.com, to a
list of servers that can receive connections for that name and to find the IP address of a specific server. By
looking up a destination server’s address in the DNS, the sending server can properly route a message to
a recipient. DNS uses two kinds of records: Mail Exchanger (MX) records and A records. An MX record
maps a domain name to the names of one or more mail hosts. An A record maps a host name to the IP
address of a server.

Mail servers also use other DNS records. For example, servers that receive Internet mail perform a
reverse lookup to a DNS PTR record to determine the host name for a given IP address. Reverse lookups
are useful in verifying the source of a message, an important tool for restricting relay access through your
server or preventing unsolicited commercial e-mail (UCE).

You must correctly configure DNS to support your use of SMTP. To determine the IP address of the mail
server for the destination domain, Domino does the following:
1. The server looks up the domain part of each recipient’s address in DNS.
2. If DNS finds an MX record, the server tries to connect to the server listed in that MX record. If there
is more than one MX record, the server tries to connect to the record that has the lowest cost. If more
than one MX record has the lowest cost, the server randomly selects one and tries to connect to the
server listed in that MX record.

Note: There may be more than one MX record for a specific domain name. The host name is looked
up in DNS to find an A record. An A record contains the IP address for the host.
3. If DNS finds only an A record, Domino routes the message to the IP address in that A record.
4. If DNS does not find a record, Domino cannot deliver the message and sends a nondelivery message
to the sender.

An MX record maps a domain name to one or more host names. An A record maps a host name to the IP
address of a server. You may want to use a host name in the MX record instead of just an A record for
the following reasons:
v Some third-party tools recognize only host names, not IP addresses.
v If you replace or relocate a machine, you can assign the existing host name and IP address to the new
or relocated machine. This change is transparent to users, and messages continue to route properly.

You can use DNS to provide failover and load-balancing for your mail servers by creating multiple MX
records for a domain name on the DNS server. When you set more than one MX record for a name, you
can set preference values to control how DNS selects those records. DNS selects lower value preferences
first -- for example, DNS selects 5 before 10. If more than one MX record has the same preference value,
DNS randomly selects from among those MX records. If one of those MX records fails -- for example,
because a server is unavailable -- DNS caches that failure and tries other MX records of equal weight,
followed by less-preferred MX records.

For example, the acme.com domain has four MX records:

v MX record: acme.com IN MX 5 mail1.acme.com
v MX record: acme.com IN MX 5 mail2.acme.com
v MX record: acme.com IN MX 10 mail3.acme.com
v MX record: acme.com IN MX 10 mail4.acme.com

When a server tries to connect to acme.com, the DNS first uses MX records with preferences of 5. If there
are two MX records with preferences of 5, DNS randomly selects between the MX record for

674 Lotus Domino Administrator 7 Help

mail1.acme.com or mail2.acme.com. If the DNS returns the MX record for mail1.acme.com and
mail1.acme.com is unavailable, the DNS returns the MX record for mail2.acme.com. If mail2.acme.com is
unavailable, both MX records with a cost of 5 have failed. The DNS then selects MX records that have a
cost of 10 and uses them the same way it used the MX records that have a cost of 5.

Examples of using multiple MX records

These are examples of setting up multiple MX records in the DNS.

Using a single Internet domain with a single domain name

You can specify MX records for a single Internet domain -- for example, acme.com -- with a single
Internet domain name, such as acme.com. Use the server’s fully-qualified Internet host name in the MX
and A records -- for example, mail1.acme.com.

For example, configure a backup SMTP server (mail2.acme.com) to deliver or forward mail when the
primary SMTP server (mail1.acme.com) is unavailable:
1. MX record: acme.com IN MX 5 mail1.acme.com
A record: mail1.acme.com IN A 192.168.10.17
2. MX record: acme.com IN MX 10 mail2.acme.com
A record: mail2.acme.com IN A 192.168.10.18
Messages addressed to acme.com route to mail1.acme.com first because the record’s preference (5) is
lower. If mail1.acme.com is unavailable, mail is routed to mail2.acme.com.

Using a single Internet domain name with two balanced servers

If you specify equal preference for two servers, DNS randomly selects a server to balance the load of
incoming mail.
1. MX record: acme.com IN MX 5 mail1.acme.com
A record: mail1.acme.com IN A 192.168.10.17
2. MX record: acme.com IN MX 5 mail2.acme.com
A record: mail2.acme.com IN A 192.168.10.18

Using a single Internet domain with multiple domain names

You can create MX records for a single Internet domain -- for example, acme.com -- with multiple
Internet domain names -- for example, acme.com, qrs.com, and xyz.com.

Note: Users can address mail to each domain name and each domain has a backup SMTP server.
1. MX record: acme.com IN MX 5 mail1.acme.com
2. MX record: acme.com IN MX 10 mail2.acme.com
3. MX record: qrs.com IN MX 5 mail1.acme.com
4. MX record: qrs.com IN MX 10 mail2.acme.com
5. MX record: qrs.com IN MX 5 mail1.acme.com
6. MX record: xyz.com IN MX 10 mail2.acme.com

Chapter 28. Overview of the Domino Mail System 675

676 Lotus Domino Administrator 7 Help
Chapter 29. Setting Up Mail Routing
This chapter describes how to set up mail routing on your Domino system. If you are upgrading a mail
system from a previous Domino release, see the Upgrade Guide.

Planning a mail routing topology

Domino offers you considerable flexibility in configuring your mail system infrastructure, allowing you to
use Notes routing, SMTP routing, or both, for internal and external messages. In determining how to set
up mail routing, you need to consider:
v How clients access the server
v How to route internal mail
v How to route mail to external destinations
v Connection topologies for mail routing

Connection topologies for mail routing

Typically, mail routing on the network occurs across a mix of hub-and-spoke and peer-to-peer
connections. In a hub-and-spoke topology, mail traffic passes between a central hub server and multiple
spoke servers; no mail is exchanged directly among the spokes. A hub-and-spoke topology is suited to
handling a high volume of mail across a large organization. In a peer-to-peer topology, on the other hand,
every server connects to every other server. A peer-to-peer topology is commonly used when connecting
a small number of servers in a workgroup or department.
v In larger networks, create a Domino server cluster to act as the mail hub and specify the cluster as the
destination in Connection documents originating from spoke servers.
v When connecting Domino domains, designate one server in each domain to connect to other domains.
In larger networks, make this connecting server part of a Domino cluster to provide failover.
v When connecting domains across a wide-area network (WAN), ensure that the Connection documents
match the physical network path of the WAN. For example, in a network where multiple WAN
connections originate from a central site (hub-to-spoke design), create Connection documents that
follow this same design, with Connection documents between the hub server or server cluster and each
spoke server, and vice-versa.
v When setting up a connection from a spoke server to a clustered hub, specify the name of the cluster
as the destination server in Connection documents.
v Establish a single Connection document to define routing from all spoke servers in a domain to a
central hub server or server cluster by using a wildcard (*) to represent part of the source server’s
name in the Connection document. For example, enter */acme as the source server to set up a
connection from all servers in the /acme organization (Mail1/acme, Mail2/acme, SalesMail/acme,
HRMail/acme, and so forth) to a designated destination server.
v Establish a single Connection document to define routing from a hub server to each spoke server by
creating a server group that includes each spoke server as a member and specifying this group as the
destination server in the Connection document from the hub server. For example, create a group
MailSpokes and add the servers Mail1/acme, Mail2/acme, SalesMail/acme, and HRMail/acme to this
group. Then create a Connection document from the hub server that lists MailSpokes as the destination
server.

For more information on connecting servers, see the chapter ″Setting Up Server-to-Server Connections.″

677
The Domino mail router
The Domino mail router (the Router) is a special server task responsible for the delivery and transfer of
the messages in MAIL.BOX. Delivery refers to moving messages from MAIL.BOX into a local mail file or
database; while transfer refers to sending messages from MAIL.BOX across the network to another server.

Mail routing on a Domino server begins when a mail server receives a message from a mail client, a
Router on another Domino server, or an application. The message is transferred to a special Notes
database, called MAIL.BOX, on the server. The server temporarily stores all incoming and outgoing mail
in the MAIL.BOX database.

The Router periodically checks MAIL.BOX for new or changed messages. When it finds a message that
requires processing, the Router reads the recipient list and for each recipient determines whether the
destination mail file is on the current server or a different server. The Router then moves the message,
delivering it to local mail files on the server or transferring it to MAIL.BOX databases on other servers as
necessary.

When a recipient’s mail file is not on the local server, but is in the Domino domain, Domino calculates
how to route the message to the recipient’s server and whether to use SMTP or Notes routing (NRPC).
The configuration of the local server and the message format determine how Domino moves the message
to the server. For messages in MIME format, if the local server can send SMTP within the local Internet
domain and the home mail server can receive SMTP, the Router uses SMTP to send the message.
Otherwise the message is routed using NRPC.

When necessary, the Router converts the format of the message. Conversion can occur during message
delivery and during message transfer. For example, if a recipient’s Person document specifies MIME
storage for incoming mail, but the original message was sent in Notes rich text format, the Router
converts the message to MIME before delivering it to the local recipient’s mail file. To determine whether
the receiving server can handle MIME messages, the sending server checks the Server document of the
receiving server to find out what version of Domino it’s running.

To minimize the number of conversions, Domino servers running Release 5 or later support the transfer
of MIME messages over Notes routing. As a result, MIME messages destined for Internet recipients can
route through internal servers ″as is,″ regardless of whether the intermediate servers use Notes routing or
SMTP.

Starting, stopping, and restarting the mail router

By default, when you start the server, the Router task automatically loads and starts. You can manually
shut down and restart the Router to troubleshoot server and messaging problems. You can also disable
automatic loading of the Router.

To shut down the Router from the console: Enter this command at the console:
tell router quit

This shuts down the Router. Mail accumulates in MAIL.BOX, since other servers and clients continue to
deposit mail, but the Router does not deliver or transfer the messages.

To reload the Router, enter this command at the console:

load router

The Router task starts and begins routing and delivering mail.

To shut down the Router from the Domino Administrator:

1. From the Domino Administrator, click the Server -- Status tab.
2. Select the Server Tasks view.
3. From the list of tasks, right-click Router and select Stop Task.

678 Lotus Domino Administrator 7 Help

4. Click Yes when prompted to confirm the operation. The Router task shuts down and no longer
appears in the list of active tasks. Mail accumulates in MAIL.BOX, since other servers and clients
continue to deposit mail, but the Router does not deliver or transfer the messages.

To start the Router from the Domino Administrator:

1. From the Domino Administrator, click the Server -- Status tab.
2. Choose Tools -- Task -- Start.
3. From the Start New Task dialog box, select Router and click Start Task. The Router task starts and
begins routing and delivering mail.
4. Click Done to close the dialog box.

To prevent the Router from automatically starting when the server starts:
1. Shut down the server.
2. Edit the NOTES.INI file to remove Router from the ServerTasks setting.
3. Restart the server so that the change takes effect.

When you restart the server, it does not load the Router task.

To restore automatic loading, add Router back to the ServerTasks setting in the NOTES.INI file.

To restart the router from the Domino Administrator:

1. From the Domino Administrator, click the Server -- Status tab.
2. Click Server Tasks.
3. Choose Router from the Task list.
4. Choose Tools -- Task -- Restart.
5. From the Restart Router dialog box, click OK. The Router task restarts and begins routing and
delivering mail.

To shut down the Router from the console: Enter this command at the console:
tell router restart

The Router task restarts and begins routing and delivering mail.

Recalculating the server’s routing table

The Router on each server maintains a dynamic routing table, which specifies the best route to each
possible destination server. The routing table builds on information contained in the server’s NOTES.INI
file and in the Configuration Settings, Domain, Connection, and Server documents in the Domino
Directory.

By default, at intervals of approximately 5 minutes, or after you restart the task, the Router examines the
Domino Directory for changes that would warrant rebuilding the routing table. In cases where you want
new settings to take effect immediately, but do not want to interrupt the flow of mail by stopping and
restarting the Router, you can use a TELL command to force an update.

To update the server’s routing table: Enter the following command at the server console:
Tell router update config

The Router checks the Server, Server Configuration, Connection, Adjacent and Non-Adjacent domain
documents, and the NOTES.INI file for changes that might effect the routing topology. The Router then
builds a new routing table that incorporates the changes. The Router reprocesses any messages currently
in MAIL.BOX based on the new routing table.

Chapter 29. Setting Up Mail Routing 679

The Router does not check the Global Domain document for changes in response to the update
configuration command. The information contained in the Global Domain document is loaded into
memory only after server initialization. It is not refreshed when the routing tables reload.

Routing mail on demand to a specific server

You can route mail to another Domino server between scheduled intervals, forcing all mail in the transfer
queue of the specified server to route immediately. Use one of the following methods:
v Console ROUTE command
v Domino administrator

Clients accessing the Domino server

Users who have mail files on the Domino server can use either the Notes client or an Internet mail client
to access their mail. By default, Notes clients use Notes protocols to send and access mail on a Domino
server, but a Notes client can also act as an Internet mail client. Internet mail clients access mail files
through the Domino POP3, IMAP, or HTTP servers. POP3 and IMAP clients send mail using SMTP.

When deciding how to route local mail, keep in mind what types of mail clients you support. For
example, if users have Internet mail clients, such as POP3 or IMAP, you’ll need servers that can receive
mail over SMTP. On the other hand, if most users send mail from the Lotus Notes mail client, you’ll want
to implement Notes routing to ensure support for Notes public key security and features such as Notes
Document links and workflow applications.

For more information about Domino mail clients, see the chapter ″Overview of the Domino Mail System.″

Sample mail routing configurations

These sample mail routing configurations represent typical messaging implementations; however, other
configurations are possible. Use these sample configurations to help you plan and refine the messaging
infrastructure in your organization:
v Use one server for all Internet messages
v Use one server for inbound and one server for outbound messages
v Use two servers to balance Internet mail load
v Set up mail routing in the local Internet domain
v Set up mail routing between a third-party server and Domino in the same Internet domain
v Use a smart host
v Use all servers to route outbound mail and one to route internal mail

680 Lotus Domino Administrator 7 Help

Example of using one server for all Internet messages

In this example, a single Domino server, Mail2, handles messages from the Acme organization destined
for other Internet domains (external addresses) and receives all mail addressed to the Acme Internet
domain (acme.com). Mail2 has the field ″SMTP used when sending messages outside of the local Internet
domain″ enabled on the Router/SMTP-Basics tab of the Configuration Settings document that applies to
the server, and has the SMTP listener task enabled on the Basics tab of its Server document.

If a user on either of the two Acme internal mail servers, Mail1 or Mail3, sends a message to an external
address -- one with a domain other than acme.com -- the server routes the message to Mail2, which can
route mail to external domains. Any mail from an external Internet domain -- one other than acme.com --
is routed to Mail2, which is listed in the DNS as the Mail Exchanger (MX) host for acme.com. After the
mail reaches Mail2, the server routes it to its destination.

The two internal mail servers, Mail1 and Mail3, can route Internet mail to the server with SMTP enabled
for external mail (Mail2) either via Notes routing, with a Foreign SMTP Domain document and SMTP
Connection document linking to Mail2, or via SMTP routing, with Mail2 configured as the relay host.

Configuring these servers requires:

v Enabling ″SMTP used when sending messages outside of the local Internet domain″ for Mail2.
v Enabling the SMTP listener task for Mail2.
v Setting up DNS correctly to list Mail2 as the connecting server for the acme.com domain for inbound
mail.
v Either enabling ″SMTP allowed outside of the local Internet domain″ for Mail1 and Mail3 and listing
Mail2 as the relay host, or creating a Foreign SMTP Domain document and SMTP Connection
document that define the route to Mail2.

Chapter 29. Setting Up Mail Routing 681

Example of using separate servers for inbound and outbound Internet mail

In this example, one Domino server, Mail2, routes messages from the Acme organization destined for
other Internet domains (external addresses) and a second Domino server, Mail3, receives mail addressed
to the Acme Internet domain (acme.com). Mail2 has the field ″SMTP used when sending messages
outside of the local Internet domain″ enabled on the Router/SMTP-Basics tab of the Configuration
Settings document that applies to the server. Mail3 has the SMTP listener task enabled on the Basics tab
of its Server document, and has an MX (mail exchanger) record in the external DNS.

If a user on the Acme internal mail server, Mail1, sends a message to an external address -- one with a
domain other than acme.com -- the server routes the message to Mail2, which can route mail to external
domains. Any mail from an external Internet domain -- one other than acme.com -- is routed to Mail3,
which is listed in the DNS as the MX host for acme.com. Once the mail reaches Mail3, the server routes it
to its destination.

The internal mail server, Mail1, can route Internet mail to the server with SMTP enabled for external mail
(Mail2) either via Notes routing, with a Foreign SMTP Domain document and SMTP Connection
document linking to Mail2, or via SMTP routing, with Mail2 configured as the relay host.

Configuring these servers requires:

v Enabling ″SMTP used when sending messages outside of the local Internet domain″ for Mail2.
v Enabling the SMTP listener task for Mail3.
v Setting up DNS correctly to list Mail3 as the MX host for the acme.com domain for inbound mail.
v Either enabling ″SMTP allowed outside of the local Internet domain″ for Mail1 and listing Mail2 as the
relay host, or creating a Foreign SMTP Domain document and SMTP Connection document that define
the route to Mail2.

682 Lotus Domino Administrator 7 Help

Example of using two servers to balance Internet mail load

In this example, two Domino servers, Mail1 and Mail3, route messages from the Acme organization
destined for other Internet domains (external addresses) and receive mail addressed to the Acme Internet
domain (acme.com). Mail1 and Mail3 have the field ″SMTP used when sending messages outside of the
local Internet domain″ enabled on the Router/SMTP-Basics tab of the Configuration Settings document
that applies to the servers and have the SMTP listener task enabled on the Basics tab of their Server
documents.

Mail2 outbound relays to Mail1 and Mail4 outbound relays to Mail3.

If a user on the Acme internal mail server Mail2 sends a message to an external address -- one with a
domain other than acme.com -- the server routes the message to Mail1, which can route mail to external
domains. If a user on the Acme internal mail server Mail4 sends a message to an external address -- one
with a domain other than acme.com -- the server routes the message to Mail3, which can route mail to
external domains. This splits the load of outbound messages -- half route to Mail1 and half route to
Mail3.

Any mail from an external Internet domain -- one other than acme.com -- is routed to either Mail1 or
Mail3. The external DNS has two MX records for the acme.com domain, one for Mail1 and one for Mail3.
When an Internet mail server tries to connect to the acme.com domain to transfer a message, it looks up
acme.com in the DNS. The server finds the MX records for acme.com and, based on the record
preferences of the MX records, returns the IP address of either Mail1 or Mail3. If the MX records have
equal weight, the server randomly selects one of the records and returns the IP address of that record’s
server. Should that server be unavailable, the other MX record is selected and the IP address of the other
server is returned. This provides load balancing through the random selection of the MX records when
record preferences are equal and provides failover since the DNS shifts to another MX record when a
connection fails. Once the mail reaches Mail1 or Mail3, that server routes the message to its destination.

Chapter 29. Setting Up Mail Routing 683

The internal mail servers can route Internet mail to the server with SMTP enabled for external mail either
via Notes routing, with a Foreign SMTP Domain document and SMTP Connection document linking to
the SMTP server, or via SMTP routing, with the SMTP server configured as the relay host.

Configuring these servers requires:

v Enabling ″SMTP used when sending messages outside of the local Internet domain″ for Mail1 and
Mail3.
v Enabling the SMTP listener task for Mail1 and Mail3.
v Setting up DNS correctly to include MX records for Mail1 and Mail3, indicating to external SMTP
systems that these are the hosts that receive inbound mail for the acme.com domain.
v Either enabling ″SMTP allowed outside of the local Internet domain″ for the internal mail servers,
Mail2 and Mail4, and listing Mail1 or Mail3 as the relay host, or creating a Foreign SMTP Domain
document and SMTP Connection document that define the route to Mail1 or Mail3.

Example of using SMTP to route mail within the local Internet domain

In this example, Acme users send messages in the acme.com domain (internal messages) over SMTP.
Mail1, Mail2, and Mail3 are Domino mail servers with ″SMTP allowed within the local Internet domain″
enabled for ″MIME messages only″ on the Router/SMTP-Basic tab of the Configuration Settings
document that applies to the servers and have the SMTP listener task enabled on the Basics tab of their
Server documents. This allows the servers to send mail to each other over SMTP and to receive mail over
SMTP.

The servers must be in the same Notes named network, based on TCP/IP, to route mail unless each
server has the field ″Servers within the local Domino domain are reachable via SMTP over TCPIP″ set to
Always in the Configuration Settings document that applies to it.

684 Lotus Domino Administrator 7 Help

If a user sends a MIME message to another user in the acme.com domain, her mail server determines
which server the recipient’s mail file is on, connects to that server over TCP/IP, and transfers the message
using SMTP. If the message is in Notes format, the message is routed using Notes routing.

Configuring these servers requires:

v Enabling the SMTP listener task for Mail1, Mail2, and Mail3.
v Enabling ″SMTP allowed within the local Internet domain″ for ″MIME messages only″ for Mail1, Mail2,
and Mail3.
v Either having all three servers in the same Notes named network or enabling ″Servers within the local
Domino domain are reachable via SMTP over TCPIP″ for each server.
v Entering the server’s Fully qualified Internet host name field on the Basics tab of the Server document.
The local Router uses the value in this field to define the local Internet domain in the absence of a
Global Domain document. Other Domino servers on the network check this field before attempting
inbound SMTP connections to this server. If the field is blank or contains an invalid value, all inbound
mail transfers take place over Notes routing.

Example of mail routing between a third-party server and Domino in the same
Internet domain

In this example, Acme has three Domino servers and a third-party SMTP host in the local Internet
domain that handles mail for some users. All users have entries in the Domino Directory. When a user
sends mail to another user in the acme.com domain, the Domino server looks up the recipient in the
Domino Directory. If the recipient has a mail file on one of the Domino mail servers -- Mail1, Mail2, or
Mail3 -- the server routes the message to its destination over Notes routing. Notes routing handles both
MIME and Notes format messages. If the recipient has a mail file on the third-party server,
non-Notesserver.acme.com, their Person document has a forwarding address with the domain
″non-Notesserver.acme.com.″ To route mail over SMTP, Mail1 and Mail3 find a Foreign SMTP Domain
document for ″*.non-Notesserver.acme.com″ that corresponds to an SMTP Connection document listing
Mail2 as the server to which to transfer messages. The server sends the message via Notes routing to

Chapter 29. Setting Up Mail Routing 685

Mail2, which has the field ″SMTP used when sending messages outside of the local Internet domain″
enabled on the Router/SMTP-Basics tab of the Configuration Settings document that applies to it. If the
message is in Notes format, Mail2 converts it to MIME. Mail2 connects to non-Notesserver.acme.com over
TCP/IP and transfers the message over SMTP.

If a user on non-Notesserver.acme.com sends a message to a user on Mail1, Mail2, or Mail3, the server
transfers the message over SMTP to Mail2, which has the SMTP listener task enabled on the Basics tab of
its Server document, and Mail2 routes the message to its destination over Notes routing.

Configuring these servers requires:

v Enabling the SMTP listener task for Mail2
v Setting up DNS correctly
v Creating a Foreign SMTP Domain document for ″*.non-Notesserver.acme.com″ and an SMTP
Connection document that links to Mail2

Example of using a smart host

If the local Internet domain includes mail systems other than Domino, users who have Internet addresses
ending in yourdomain.com may not have mail files on a Domino server or Person documents in the
Domino Directory. When Domino receives a message for such a user, the Router cannot resolve the
address. To prevent Domino from generating delivery failures, set up the Domino server to forward mail
it receives for unknown local domain users to a local smart host. A smart host is typically a more central
computer that has an authoritative directory of all users in the local domain. When Domino receives mail
it doesn’t know how to deliver, it sends it to the smart host.

In this example, Acme has three Domino servers (Mail1, Mail2, and Mail3) and a third-party SMTP host,
smarthost.acme.com, that houses the directory for users who have non-Domino mail files within the
acme.com domain. Users in the non-Domino system do not have Person documents in the Domino
Directory. The Domino servers have the field ″SMTP allowed within the local Internet domain″ enabled

686 Lotus Domino Administrator 7 Help

and have smarthost.acme.com listed in the ″Local Internet domain smart host″ field on the
Router/SMTP-Basic tab of the Configuration Settings document.

If a user on one of the Domino mail servers sends a message to a user in the acme.com Internet domain,
and the Router cannot find the recipient in the Domino Directory, the Router forwards that message to
smarthost.acme.com over SMTP.

Configuring these servers requires:

v Setting up DNS correctly
v Enabling ″SMTP allowed within the local Internet domain″ for ″MIME messages only″ for Mail1, Mail2
and Mail3
v Listing ″smarthost.acme.com″ as the ″Local Internet domain smart host″ for Mail1, Mail2, and Mail3.

Example of using all servers to route outbound mail and one to route inbound
mail

In this example, Acme has three mail servers, Mail1, Mail2, and Mail3, each of which can route messages
from the Acme organization destined for other Internet domains (external addresses). All three servers
have the field ″SMTP used when sending messages outside of the local Internet domain″ enabled on the

Chapter 29. Setting Up Mail Routing 687

Router/SMTP-Basics tab of the Configuration Settings document that applies to them. One server, Mail2,
receives mail addressed to the Acme Internet domain (acme.com). Mail2 has the SMTP listener task
enabled on the Basics tab of its Server document.

If a user on one of the mail servers sends a message to an external address -- one with a domain other
than acme.com -- the server looks up the destination domain in the DNS, connects to the destination
server over TCP/IP, establishes an SMTP connection, and transfers the message.

Any mail from an external Internet domain -- one other than acme.com -- is routed to Mail2. The DNS
lists Mail2 as the MX host for acme.com. Once the mail reaches Mail2, the server routes the message to its
destination.

Since each server can send messages directly to external domains, no relay host, Foreign SMTP Domain
documents, or SMTP Connection documents are needed.

Configuring these servers requires:

v Enabling ″SMTP used when sending messages outside of the local Internet domain″ for all three
servers
v Enabling the SMTP listener task for Mail2
v Setting up DNS correctly to list Mail2 as the connecting server for the acme.com domain for inbound
mail

Creating a Configuration Settings document

Using a Configuration Settings document you can set up mail routing on multiple Domino servers at
once. The Configuration Settings document includes settings that affect both Notes routing and SMTP
routing. Administrators can create a single Configuration Settings document for:
v All Domino servers in the Domino domain
v Servers in a specific group
v A specific server

You can designate a Configuration Settings document to serve as the default for all servers in the Domino
domain by selecting the field ″Use these settings as the default settings for all servers″ or by entering a
wildcard (*) in the Group or Server field. Using a default Configuration Settings document simplifies
administration and saves time because you can change the settings for the entire Domino domain by
editing a single document.

Each setting applies to every server included in the Configuration Settings document. Therefore, you
need multiple Configuration documents if you need different settings for specific servers. For example, if
your Domino domain includes three geographic locations, you may want a Configuration Settings
document for each location. You can create groups that include all the servers in the specific location and
use the location as the group name.

To specify additional restrictions for a server that is included in a group, create a separate Configuration
Settings document for the specific server. For example, assume you have a Configuration Settings
document for a group of servers or for all servers. The executives in your organization have their own
mail server and require different settings. You will need to create a Configuration Settings document for
the specific server. The document that is most specific (in terms of which servers it applies to) will take
precedence.

Each server checks the Configuration Settings documents in the following order -- a document specific to
the server, then a group document for any group the server is in, and then for the default document. If
there are multiple Configuration documents for groups containing the same server, the results are
undefined. For example, if ServerA has a Configuration Settings document and is also listed in a Group

688 Lotus Domino Administrator 7 Help

Configuration document or an All Server’s Configuration document, the only settings that the server will
use are those listed in the Configuration Settings document specific to ServerA.

For more information about creating groups, see the chapter ″Setting Up and Managing Notes Users.″

Note: Use fully qualified host names in fields on the Configuration Settings document instead of IP
addresses. While IP addresses will work and are fully supported, using host names ensures that you
won’t need to change a server entry in the event that a subnet change requires a change to the server’s IP
address. You can change the server’s record once in the Domain Name Service (DNS) rather than having
to search through the Domino Directory to find every instance where the server is referenced.

To create a Configuration Settings document

1. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
2. Choose Configurations.
3. Click Add Configuration to create a new Configuration Settings document.
4. Click the Basics tab.
5. Complete one of these fields, and then click Save & Close.

Field
Use these settings as the default
settings for all servers
Group or server name
Enter
Select the Yes checkbox to have this document serve as the default
Configuration Settings document for all Domino servers in the Domino
domain. If you create additional Configuration Settings documents in the
Domino Directory for specific servers or groups of servers, settings in those
documents override equivalent settings in the default document.
Enter the name of the individual server or server group to which this
Configuration Settings document applies.

Routing internal mail

Internal mail consists of messages sent between users within an organization and its local Internet
domains. The Domino mail router (the Router) uses both SMTP and Notes routing to transfer messages
between network servers, and handles messages in both MIME format and Notes rich text format. By
default, the Router transfers local mail using the Notes routing protocol only. Within a given Notes
named network, servers that use Notes routing automatically transfer mail among themselves.

For information about configuring Notes routing to support messaging across multiple Notes named
networks and domains, see the topic ″Setting up Notes routing″ later in this chapter.

To use SMTP routing to transfer local mail, you must enable the SMTP listener for receiving mail and
enable servers to send SMTP within the local Domino domain. In addition, the Server document for each
SMTP-enabled server must specify a valid, fully qualified Internet host name for the server. In most cases
the host name field is populated during server setup or by the Admin process (AdminP).

For information about setting up internal SMTP routing, see the topic ″Setting up SMTP routing within
the local Internet domain″ later in this chapter.

Implementing different protocols for internal and external routing

When selecting the protocol to use for internal mail routing, don’t base your decision on whether you’re
using SMTP to transfer mail to external systems. Domino can send mail to the Internet even if you use
Notes routing for internal mail. Rather than having all your servers route SMTP, you may want to retain
a gateway-style architecture wherein you channel all mail to and from the Internet through a few
designated servers and prohibit the majority of internal servers from sending directly to the Internet.

Chapter 29. Setting Up Mail Routing 689

Ensuring support for Lotus Notes functionality
When choosing a routing protocol, consider security requirements and the need to support Notes
applications. Using Notes as the internal routing protocol and SMTP for external routing can provide
greater protection for your network against external intrusion. Certain Lotus Notes features, such as
mail-enabled workflow applications, Notes public key security, and Notes items, such as Doclinks, require
Notes routing to work properly.

Routing mail to local users not listed in the Domino Directory

If you have users in your organization who are not listed in the Domino Directory, but in an alternate
directory on another SMTP server, set up Domino to use this other server as a smart host. When
processing a message in MAIL.BOX, if the Router comes across a recipient address that is in the local
Internet domain, but does not have a match in the Domino Directory, it forwards the message to the
specified smart host, which routes it to the recipient.

For information about setting up a smart host, see the topic ″Setting up a smart host″ later in this chapter.

A Domino SMTP server in your organization may receive Internet mail for recipients in Domino domains
that are within the local Internet domain, but outside the local Domino domain, and thus not listed in the
Domino Directory. To ensure that the server can access other Domino Directories and route messages to
servers in other Domino domains, configure Directory Assistance on the server.

For more information, see the chapter ″Setting Up Directory Assistance.″

Setting up Notes routing

By default, Domino uses Notes routing to transfer messages between servers. Notes routing uses
information in the Domino Directory to determine where to send mail addressed to a given user. If two
servers are in the same Notes named network, Notes routing automatically transfers mail between them.
A Notes named network is a group of servers in a given Domino domain that share a common protocol
and are connected by a LAN or modem connections.

To set up routing between servers that are not in the same Notes named network, you must create
documents in the Domino Directory to specify how to route mail within the Notes mail system, as
follows:
1. Create Connection documents to enable message transfer between servers in different Notes named
networks. A Connection document specifies how and when two servers connect to exchange mail and
update common databases through replication. To route mail between servers in different Notes
named networks requires a pair of Connection document, one from each server to the other.
2. Depending on your messaging system topology, create these documents, as necessary:
v Non-adjacent domain documents.
v Adjacent domain documents.
v Foreign domain documents.
v Foreign SMTP domain documents.
v SMTP Connection documents.

How you create connections for Notes routing depends on:

v The location of the two servers: same Notes named network, same Domino domain, adjacent Domino
domain, non-adjacent Domino domain
v The type of network connection between the two servers: LAN, direct dialup, network dialup, or
passthru

In addition, the number of Connection documents you need to create depends on how you want to route
mail -- that is, whether you want to route mail both to and from a server, only to a server, or only from a
server. Since, in most cases, you’ll want to route mail in both directions, you generally need to create two
Connection documents for each connection.

690 Lotus Domino Administrator 7 Help

In small Domino networks, you can minimize the number of Connection documents by using the same
document to schedule mail routing and replication. Or you can create a separate Connection document
for each task.

This table describes the typical types of connections and the documents required to set them up.

Type of connection required Documents required to create connection

To a server in same Notes No Connection documents required. There must be a common entry on the Ports -
named network Notes Network Ports tab of each server’s Server document.
To a server in a different Notes Two Connection documents -- one from each server -- to ensure that mail routes in
named network within the both directions.
local Domino domain
To an adjacent Domino Two Connection documents, one in each Domino domain, to ensure that mail
domain routes in both directions.

One Adjacent domain document if you need restrictions.

To a non-adjacent Domino Two Connection documents, one in each Domino domain that connects to the
domain adjacent Domino domain.

Two Non-adjacent domain documents, one in each Domino domain that are not
adjacent, to provide restrictions and simplify addressing across the intermediary
domain between the first and third domains.
To a gateway for a foreign One Foreign domain document to identify the foreign domain for non-mail
domain messaging systems, such as fax or pager systems.
To an SMTP-enabled server One Foreign SMTP domain document to identify the destination for messages being
(for example, a server that can sent to the Internet.
send mail to the Internet)
One SMTP connection document to specify the SMTP-enabled server.

Note: When you create a Connection document, Notes routing is enabled by default.

For complete information on creating Connection documents, see the chapter ″Setting up Server-to-Server
Connections.″

Creating an Adjacent domain document

You create an Adjacent domain document when you need to restrict the transfer of mail from one
adjacent domain to another. For example, if you are in domain B and want to prevent mail from an
adjacent domain A from traversing your domain to reach another adjacent domain C, create an Adjacent
domain document that names C as the adjacent domain and denies mail from A.

Chapter 29. Setting Up Mail Routing 691

The restrictions you define in the Adjacent domain document apply to the domain of the previous hop
only. That is, in the Adjacent domain document created in the previous example, adding A to the Deny
list prevents mail originating in A from routing to C. This includes mail that domain A may receive from
domain Z for eventual transfer to C.

But suppose you want to allow mail from A, but deny mail from domain Z, which uses A and B as
intermediate domains to reach C. If the administrator in domain B removes domain A from the deny list
of the Adjacent domain document for domain C, and adds domain Z, domain Z is allowed to route mail
to C. This is because once the message arrives in domain B the domain of origin appears to be A, rather
than Z. In the absence of restrictions on transferring mail from A to C, Domino allows the message to
route.

You also use Adjacent domain documents to allow Free Time searches across domains. For more
information, see the chapter ″Setting up Calendars and Scheduling.″

Note: Restrictions set in an Adjacent domain document work in conjunction with those in the
Configuration Settings document. Domino always defaults to the most restrictive entry.

692 Lotus Domino Administrator 7 Help

Adjacent Domain documents do not provide connectivity to adjacent domains, and are not required to
enable connections between adjacent domains. To define routes between adjacent domains, create a
Connection document.

Using Adjacent domain documents to restrict mail: By default, a domain that can route mail to your
domain can also route mail through your domain to another adjacent domain. When mail routes from
one domain to another through your domain, it ties up your resources. To prevent your servers from
being used to transfer mail between other domains, you can selectively allow and deny mail routing
through your domain to the domain named in the Adjacent domain document.

The Allow and Deny fields on the Restrictions tab of the Adjacent domain document let you control the
flow of messages from other domains to the adjacent domain. Entries in these fields must be the names
of adjacent domains; the Router ignores entries for non-adjacent domains beyond the previous hop. If
you deny a domain from sending mail through your domain, the Router denies all mail received from
that domain, including messages the domain may have passed on from another, non-adjacent domain.
There is no way to restrict specific users from routing to a Notes domain. Restrictions apply to all users
in specified domain.

The settings in the Allow and Deny fields work in conjunction with the Allow and Deny fields on the
Router/SMTP - Restrictions and Controls - Restrictions tab of the Configuration Settings document. In the
event of any conflict between settings, Domino applies the most restrictive entry.

Messages may be further restricted by Adjacent Domain documents, Non-adjacent Domain documents,
and Configuration Settings documents set up between domains along the routing path.

To create a Adjacent domain document:

1. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
2. Choose Domains.
3. Click Add Domain to create a new Domain document.
4. On the Basics tab, complete these fields:

Field Enter
Domain type Choose Adjacent domain
Adjacent domain name The name of the adjacent Domino domain. The current domain must have a Connection
document to this domain.
Domain description Optional description of the domain

5. To restrict other domains from routing mail through the current domain to the adjacent domain, click
the Restrictions tab, complete the following fields, and then click Save and Close:

Field Enter
Allow mail only from Enter the names of adjacent Domino domains that are allowed to route mail to this
domains adjacent domain.

To allow any domain to route mail through the local domain to this adjacent domain,
leave this field blank.
Deny mail from domains Enter the names of adjacent Domino domains that are not allowed to route mail to this
adjacent domain.

To allow any domain to route mail through the local domain to this adjacent domain
leave this field blank.

Note: You cannot use wildcards in the Restrictions fields. You must enter explicit domain names.

Chapter 29. Setting Up Mail Routing 693

6. Create a Connection document to specify how servers in the current domain connect to the adjacent
domain.

Setting up routing to non-adjacent Domino domains

Non-adjacent domains are Domino domains that are not directly connected, but have an intermediary
domain, adjacent to both of them in common. For example, domain A and domain B are adjacent and
have Connection documents defining the route between them. Similarly, domain B, in turn, is adjacent to
domain C and mutual Connection documents exist between them; and domains C and D are likewise
adjacent to each other and linked by Connection documents. Domain B is thus adjacent to domain A on
one side, and domain C on the other; and domain C is adjacent to B and D, respectively. If no direct
connection exists between A and C, these two domains are considered to be non-adjacent domains.
Similarly if there is no direct connection between B and D, these two domains are also non-adjacent.

Because there is no direct connection between two non-adjacent domains, you cannot define the routing
path between them in a Connection document. Connection documents can only be used between two
directly-connected, adjacent domains. However, users in non-adjacent domains can send mail to each
other by routing it through the intermediary domain.

One way to do this is to use explicit addressing -- telling the Router how to reach the destination domain
through the intermediary domain by placing the entire routing path in the address field. For example, if
Kathy Burke in domain A wants to send a message to Robin Rutherford in the non-adjacent domain C,
she addresses the message by way of domain B, as follows:
Robin Rutherford@C@B

In processing the message, the Router on the domain A mail server looks only at the last part of the
address, and uses the Connection document to determine the route to domain B. The domain B server
then uses the Connection document in its Domino Directory to transfer the message to domain C.

Although the use of explicit addressing is an effective method for directing mail to non-adjacent domains,
because it relies on a complete knowledge of the inter-domain routing topology, it’s also not a very
practical solution. This information is not readily available to a typical user. To simplify routing and
addressing to non-adjacent domains, you can create a Non-adjacent domain document in the Domino
Directory to define the path between the non-adjacent domains.

Using a Non-adjacent domain document: Administrators can create a Non-adjacent domain document
to control message routing to a non-adjacent domain. A Non-adjacent Domain documents serves three
functions:
v Specifies a routing path to the non-adjacent domain by supplying next-hop domain information
694 Lotus Domino Administrator 7 Help
v Restricts mail from other domains from routing to the non-adjacent domain
v Defines the Calendar server used to enable free time lookups between two non-adjacent domains.
For more information on how to enable free time lookups between non-adjacent domains, see the
chapter ″Setting up Calendars and Scheduling.″

Non-adjacent domain documents are only required to specify routing restrictions to a non-adjacent
domain. However, to simplify addressing on messages destined for a non-adjacent domain, it’s useful to
have a Non-adjacent domain document for that domain. Without a Non-adjacent domain document in
the Directory, the Router has no defined routing path to the non-adjacent domain. The Router can
transfer a message to the non-adjacent domain if the recipient address uses explicit path routing
(User@AdjacentDomain@NonAdjacentDomain), but cannot transfer a message with a simple domain
address (User@NonAdjacentDomain). When explicit addressing is used the Router uses the Connection
documents between domains to calculate the path to the next-hop domain.

But when a Non-adjacent domain document is available, the Router obtains intermediary domain
information from that document. This eliminates the need for users sending mail to a non-adjacent
domain to use complex, explicit addressing. Thus, if domain A has a Non-adjacent domain document for
domain C, when Kathy Burke in domain A sends mail to Robin Rutherford in domain C, she uses the
address Robin Rutherford@C (rather than Robin Rutherford@C@B). Because the Router finds the
intermediate domain information in the Non-adjacent domain document, the message is transferred
successfully to domain C by way of domain B.

Using Non-Adjacent domain documents to restrict mail: Using Non-adjacent domain documents to
simplify addressing makes them valuable enough. But Non-adjacent domain documents play another
equally significant role. Although they are not strictly required to enable routing between non-adjacent
domains, they are needed if you want to restrict routing of messages from certain domains.

By default, any domains that can route mail to your domain can also route mail to the destination
domains named in a Non-adjacent domain document. Mail routed from one domain to another through
your domain consumes your network resources. To prevent your servers from being used to transfer mail
between other domains, you can selectively allow and deny mail routing through your domain.

The Allow and Deny fields on the Restrictions tab of the Non-adjacent domain document let you control
the flow of messages from other domains to the non-adjacent domain. Entries in these fields must be the
names of adjacent domains; the Router ignores entries for non-adjacent domains beyond the previous
hop. If you deny a domain from sending mail through your domain, the Router denies all mail received
from that domain, including messages the domain may have passed on from another, non-adjacent
domain.

The ″Deny mail from domains field″ in a Non-adjacent domain document does not block messages that
use explicit domain addressing, that is, addresses that explicitly name every domain on the routing path.
A Non-adjacent domain document can only block mail that relies on information in the Non-adjacent
domain document to supply the name of a a missing intermediate domain. If the entire routing path is
contained in the recipient address, the Router doesn’t need to check the document to determine where to
route the message, and thus cannot block it. For example, if in the previous example, the administrator in
domain B creates a a Non-adjacent domain document for domain D and adds domain A to the Deny mail
from domains field. Kathy Burke in domain A can still send mail to Judy Kaplan in domain D by
specifying the following explicit domain address: Judy Kaplan@D@C@B.

To prevent Kathy Burke from sending this message, the administrator in Domain B would have to create
an Adjacent domain document for domain C that names domain A in the Deny mail from domains field.

The settings in the Allow and Deny fields work in conjunction with the Allow and Deny fields on the
Router/SMTP - Restrictions and Controls - Restrictions tab of the Configuration Settings document. In the
event of any conflict between settings, Domino applies the most restrictive entry.

Chapter 29. Setting Up Mail Routing 695

Messages may be further restricted by Adjacent Domain documents, Non-adjacent Domain documents,
and Configuration Settings documents set up between domains along the routing path.

To create a Non-adjacent domain document:

1. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
2. Choose Domains.
3. Click Add Domain to create a new Domain document.
4. On the Basics tab, complete these fields:

Field Enter
Domain type Choose Non-adjacent domain
Mail sent to domain The name of the non-adjacent Domino domain you want to route mail to.
Route through domain The name of the intermediary Domino domain through which you want to route mail
for the destination domain. The current domain must have a Connection document to
this domain.

Also, the Domino Directory in the intermediary domain must have a Connection
document to the destination domain.
Domain description An optional description of the domain

5. Click the Restrictions tab, complete one or both of these fields, and then save the document:

Field Enter
Allow mail only from Enter the names of Domino domains adjacent to the current domain that are allowed to
domains route mail to this non-adjacent domain.

Leave this field blank to allow any domain to route mail through the local domain to
the non-adjacent domain.
Deny mail from domains Enter the names of Domino domains adjacent to the current domain that are not
allowed to route mail to this non-adjacent domain.

Leave this field blank to allow any domain to route mail through the local domain to
the non-adjacent domain.

Note: You cannot use wildcards in the Restrictions fields. You must enter explicit domain names.
6. Create a Connection document to specify how servers in the current domain connect to the
intermediary adjacent domain.

Note: Since, by definition, all servers in a domain use the same Domino Directory, only one Non-adjacent
domain document is required for each non-adjacent domain. You do not have to create a separate
document for each server.

Setting up routing to external application gateways

Domino treats external messaging applications, such as fax or pager gateways, as foreign domains. To
route mail from a Domino domain to an external application, create a Foreign domain document.

Creating a Foreign domain document: A Foreign domain document defines the path between a Domino
domain and an external application, such as a fax or pager gateway. A Foreign domain document
identifies the Domino server that acts as the gateway to the external application.

Although Foreign domains are mostly used for third party applications, you can also use them to transfer
messages between a Release 5.0 or later server and a Release 3.x SMTP server.

696 Lotus Domino Administrator 7 Help

Restrictions that you set on this Foreign domain document apply only to the From domain of the
previous hop. These restrictions work in conjunction with those in the Configuration Settings document.
Domino always defaults to the most restrictive entry.

To create a Foreign domain document:

1. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
2. Choose Domains.
3. Click Add Domain to create a new Domain document.
4. Click the Basics tab, and complete these fields:

Field Enter
Domain type Choose Foreign domain.
Foreign Domain Name The domain name of the foreign mail system. This name was chosen when the
MTA or gateway was installed.
Domain description An optional description of the gateway or MTA.

5. Click the Restrictions tab, and then complete these fields:

Field
Allow mail only from domains
Deny mail from domains
Enter
The names of Domino domains that are allowed to route messages to this foreign
domain. Leave this field blank to allow any domain to route mail through the
local domain to the foreign domain.
The names of Domino domains that are not allowed to route messages to this
foreign domain. Leave this field blank to allow any domain to route mail through
the local domain to the foreign domain.

6. Click the Mail Information tab and complete these fields, and then save the document:

Field Enter
Gateway server name The name of the Domino server running the gateway software.
Gateway mail filename The gateway’s mail file name. See the documentation that came with the gateway
for the proper file name.

7. Create a Connection document to specify how servers in the current domain connect to the foreign
domain.

Sending mail outside the local Internet domain

Because all mail on the Internet travels over SMTP routing, for your organization to send mail to Internet
addresses you’ll need to set up at least one Domino server to send SMTP to external Internet domains
and one to listen for incoming SMTP connections. Alternately, you can enable multiple, or even all, of
your servers to route mail over SMTP to external Internet domains. Although you can use a single server
to handle incoming and outgoing SMTP connections, if you anticipate a high volume of Internet mail, to
avoid bottlenecks consider balancing the load among multiple servers.

The Domino SMTP servers you use for inbound and outbound Internet mail can connect to the Internet
either directly or through an SMTP relay host or firewall. Routing between the Domino Internet mail
server and internal mail servers can be over either SMTP or Notes routing. It’s not necessary to enable
SMTP routing on your internal servers.

Using a single server to route mail to external Internet domains: In this configuration, a single
designated mail server connects to the Internet. All other internal mail servers route messages addressed
to recipients in external Internet domains to this server. If you use SMTP for internal mail routing, you
can configure all of your internal servers to use the server that is connected to the Internet as a relay
host. In the Configuration Settings documents that apply to any mail servers that do not connect directly

Chapter 29. Setting Up Mail Routing 697

to the Internet, enter the host name of the designated relay host in the ″Relay host for messages leaving
the local Internet domain″ field. When the Router on these internal servers finds a message addressed to
a recipient in an external Internet domain, it looks up the specified relay host in the DNS and forwards
the message to it.

To set this up using Notes protocols, create a Foreign SMTP Domain document and an SMTP Connection
document. When the Router on a server not connected directly to the Internet finds a message addressed
to a recipient in an external Internet domain, the Router forwards the message to the domain in the
Foreign SMTP Domain document, which is connected to the server with an Internet connection by the
SMTP Connection document. When that server receives the message, its Router connects to the external
Internet domain and routes the message.

Using multiple servers to route mail to external Internet domains: In this configuration, a few
designated mail servers connect to the Internet. Other mail servers route messages addressed to recipients
in external Internet domains to these servers. To set this up using SMTP, configure the servers that are
connected to the Internet as relay hosts -- for example, create a DNS name, such as outbound.acme.com,
that maps to multiple MX records. Each MX record lists one of the connected servers. Enter the DNS
name in the ″Relay host for messages leaving the local Internet domain″ field in the Configuration
Settings document that applies to all servers that do not connect directly to the Internet. When the Router on
those servers finds a message addressed to a recipient in an external Internet domain, it forwards the
message to one of the servers that are listed in DNS and correspond to that name.

To set this up using Notes protocols, create Foreign SMTP Domain and SMTP Connection documents.
When the Router on a server not connected directly to the Internet finds a message addressed to a
recipient in an external Internet domain, the Router forwards the message to the domain in the Foreign
SMTP Domain document, which is connected to one of the servers with an Internet connection by the
SMTP Connection document. When that server receives the message, its Router connects to the external
Internet domain and routes the message.

Enabling all mail servers to route mail to external Internet domains: In this configuration, every mail
server connects to the Internet and runs the TCP/IP network protocol. Each server has the setting ″SMTP
used when sending messages outside of the local Internet domain″ enabled in its Configuration Settings
Document. When a user sends a message to a recipient in an external Internet domain, the Router looks
up the domain in the Domain Name Service (DNS) and uses SMTP to connect to the receiving server in
that domain. The Router transfers the message and closes the connection.

Routing SMTP mail over dialup connections: Your organization may connect to the Internet and
external Internet domains through a dialup connection -- for example, to an Internet Service Provider
(ISP). To set up a dialup connection in your Domino mail system:
v For Notes routing, create a Notes Direct Dialup Connection document
v For SMTP routing, create a Network Dialup Connection document that specifies TCP/IP as the
network protocol

After you create the appropriate Connection document, specify how Domino exchanges messages over
that connection.

For more information on creating Connection documents for dialup connections, see the chapter ″Setting
up Server-to-Server Connections.″ For information on setting up mail routing over a dialup connection,
see the topic ″Routing mail over transient connections″ later in this chapter.

Routing Internet mail through a relay host: A relay host is an SMTP server that receives mail from
other servers and then transfers, or relays, it to the next SMTP server on the route to the recipient’s
domain. A relay host can be a Domino SMTP server, or a non-Domino SMTP host -- for example, you
might relay mail to an SMTP server hosted by your ISP, or through a firewall server. If only a small
number of servers on the network have direct connections to the Internet, set these servers up as relay
hosts to which other internal servers forward messages for recipients in external Internet domains. You

698 Lotus Domino Administrator 7 Help

can set up a single relay host that handles messages addressed to any external Internet domain, or set up
multiple relay hosts, and set up each one to route messages addressed to specific Internet domains.

For more information on setting up relay hosts, see the topic ″Configuring Domino to send mail to a
relay host or firewall″ later in this chapter.

Transferring outbound Internet mail to an SMTP server over Notes routing

On Domino networks that don’t use SMTP for internal mail routing you can implement a gateway
topology for sending outbound mail to the Internet. Your internal servers can continue to use Notes
routing to transfer mail and send Internet mail to an SMTP server that connects to the Internet. Your
″gateway″ server must be a Domino server able to send SMTP mail to external Internet domains.

To define a route between your internal servers and the SMTP gateway server, create:
v One or more Foreign SMTP domain documents that define the next domain for sending SMTP mail
addressed to a given set of destination addresses
v SMTP Connection documents specifying the server that processes outbound SMTP mail for each
Foreign SMTP domain document

The gateway server receives outbound mail from internal servers over Notes routing and then transfers it
to the Internet over SMTP. The gateway server can connect to the Internet directly or through an SMTP
relay host or firewall that connects to the Internet.

The Foreign SMTP domain document: A Foreign SMTP domain document provides servers that don’t
use SMTP routing and which do not have access to DNS with the next hop information required to route
Internet mail. You can also use Foreign SMTP domain documents with servers that route mail over SMTP
to configure different routing paths for mail sent to different destinations.

A Foreign SMTP Domain document provides servers in a Domino domain with information on where to
transfer mail destined for external SMTP addresses. The Foreign SMTP domain document specifies the
name of the next hop domain to which messages addressed to a specific Internet domain or domain
pattern are sent. For example, a Foreign SMTP Domain document might specify that the next hop for
messages addressed to the domain company.com should be the domain TheInternet.

The next hop domain can either be an actual Domino domain -- that is, a group of servers sharing a
Domino Directory -- or a ″virtual″ domain. Use the name of an existing Domino domain if you can create
a Connection document to it and it already has SMTP servers connected to the Internet. If the network
does not currently have a Domino domain that routes outbound Internet mail, use a virtual, or logical,
domain name. The name must not correspond to the name of any servers or domains in the Domino
Directory. Domino uses the virtual domain name to link this SMTP domain document with an SMTP
Connection document, which, in turn, specifies the name of an SMTP-enabled server that can process
outbound mail, for example, a firewall server that can route outbound Internet mail.

Configuring different relay hosts for different destination domains: To explicitly control message
routing, you can set up multiple Foreign SMTP domain documents, splitting outbound mail traffic so that
messages destined for one Internet domain route through one Domino host and those destined for others
go to a different host.

For example, you can configure one Foreign SMTP Domain document to route all mail addressed to
domains ending in lotus.com; a second can route all mail addressed to domains ending in ibm.com; and
a third can process mail addressed to all other Internet domains (*.*). For each of the three configured
Foreign SMTP domains, you must create an SMTP Connection document that describes how to transfer
the messages routed to that domain.

Note: If you use a wildcard when specifying which messages to route to a domain, you can still restrict
messages destined for specific Internet domains using the SMTP Outbound Controls in the Configuration
Settings document.

Chapter 29. Setting Up Mail Routing 699

The Router always uses the Foreign SMTP Domain document that most closely matches the address. For
example, if a message is addressed to jdoe@server1.japan.lotus.com and there are two Foreign SMTP
Domain documents -- one for lotus.com and one for japan.lotus.com -- the Router uses the document for
japan.lotus.com.

After the Router determines which Foreign SMTP Domain document most closely matches the address of
the message, it forwards the message to the specified next domain. If the domain is a real Domino
domain, the Router looks in the Domino Directory for a connection to that domain and routes the
message. If the domain is a logical domain, the Router checks for an SMTP Connection document that
describes the next hop for mail routed to that domain.

To create a Foreign SMTP domain document:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Choose Domains, and then click Add Domain.
4. On the Basics tab, complete this field:

Field Enter
Domain type Foreign SMTP Domain

5. Click the Routing tab, complete these fields, and then click Save & Close:

Field Enter
Messages Addressed to -- The name of the Internet domain to which this document applies, for example,
Internet Domain company.com, or a wildcard (*.*) to indicate all Internet domains.
Should be Routed to -- A fictitious, logical domain name -- for example, TheInternet -- to which messages that
Domain name match the pattern in the Internet Domain field will be routed. The name you specify
serves as a placeholder; Domino uses the name to pair the Foreign SMTP Domain
document with the connection document you create in the next step.

6. Create an SMTP Connection document to associate the Foreign SMTP Domain document with an
SMTP server that can send outbound mail to the Internet.

Creating an SMTP Connection document

On networks where internal mail travels over Notes routing, the SMTP Connection document works in
conjunction with a Foreign SMTP Domain document to route messages from non-SMTP servers to an
SMTP server that can send messages outside the local Internet domain.

SMTP Connection documents link the virtual foreign SMTP domain specified in a Foreign SMTP Domain
document, to a Domino SMTP server. For example, an SMTP Connection document might link the virtual
domain TheInternet to the firewall server that routes mail to the Internet. In the SMTP Connection
document, you specify the source server (the server that can connect directly to the Internet and route
SMTP mail), the destination domain (which must match the Internet domain in the Foreign SMTP
Domain document), and the method to use when connecting to the source server (direct or dialup). An
SMTP Connection document lets Internet messages travel from a Domino domain to a server that is
enabled to use SMTP to route outbound Internet mail.

When the Router receives a message for a recipient outside the local Internet domain, it forwards the
message to the domain specified in the Foreign SMTP Domain document. After the message reaches a
Domino server that can connect to the Internet, that server establishes a connection with a server in the
destination domain and routes the message.

To create an SMTP Connection document:

1. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.

700 Lotus Domino Administrator 7 Help

2. Choose Connections and click Add Connection.
3. On the Basics tab, complete these fields, and then save the document:

Field Enter
Connection type SMTP
Source server The name of the SMTP-enabled server where non-SMTP servers send mail destined for the
Internet domains specified in the Foreign SMTP domain document. This server must have
access to DNS and have SMTP enabled for sending messages outside the local Internet
domain.
Connect via Choose one:
v Direct connection - For servers that communicate over LAN connections
v Dial-up connection - For servers that communicate over transient connections, such as
phone lines. If you select this option, Domino displays the field ″Dial using connection
record.″
Dial using connection Specifies the Network Dialup Connection document containing the dialup settings for
record connecting to the SMTP server specified in the Source server field. This field appears only
if you selected ″Dial-up connection″ in the preceding field.

Click ″Choose record,″ to select a Network Dialup Connection document (remote LAN
service connection record) from the list of previously created Network Dialup Connection
documents.
Destination server A unique, fictitious, placeholder name -- such as, all_internal_hosts. Domino does not use
the value in this field, but the Connection document will not work if the field is empty.
The name you specify must not match the name of any server on the network.
Destination domain The fictitious, logical domain name specified in the Internet Domain name field of the
corresponding Foreign SMTP domain document. The name in this field links this SMTP
connection document with the Foreign SMTP Domain document.
SMTP MTA relay host Specifies the SMTP host to which the source server transfers outbound mail. This allows a
SMTP server to further split Internet destinations and configure multiple relays.

If this field is blank, the Router transfers outbound mail to the relay host specified in the
server’s Configuration Settings document.

If there is no relay host specified in either this field or in the Configuration Settings
document, the Router determines the next hop by looking up the destination domain in
the DNS or a local hosts file, depending on the value of ″Host name resolution″ field on
the Router/SMTP- Basics tab of the Configuration Settings document.

For information on configuring how the Router resolves host names, see the topic ″Specifying how
Domino looks up SMTP hosts when sending outbound mail″ later in this chapter.
4. On the Replication/Routing tab, complete these fields:

Field Enter
Replication task Disabled
Routing task Choose Mail Routing. Because the same routing task is responsible for transferring
messages over NRPC and SMTP, there’s no need to specify SMTP routing. The source
server must have SMTP routing enabled in its Server document; otherwise, the Router
discards the information in the SMTP Connection document.
Route at once if The number of pending messages that will force routing. Default is 5.

5. On the Schedule tab, specify the desired routing schedule.

6. Click Save & Close. Replicate the Domino Directory to all servers in the Domino domain.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, recalculate the routing tables on all effected servers.

Chapter 29. Setting Up Mail Routing 701

Configuring Domino to send and receive mail over SMTP
Setting up a Domino server as an SMTP server consists of enabling two separate tasks: a listener task and
a routing task. Enabling the SMTP Listener allows a server to receive mail over SMTP. Enabling SMTP
routing lets the Domino Router send mail to other servers using SMTP. You enable SMTP routing to
destinations within the local Internet domain separately from SMTP routing to external destinations. It’s
also possible to enable SMTP routing on a server without enabling the Listener task, and vice-versa.

For example, to support POP3 and IMAP clients, which use SMTP to send mail, you must have at least
one internal server running the SMTP Listener task. However, the server does not have to use SMTP
when transferring messages it receives over SMTP to the next hop on the routing path. After the server
has accepted a message over SMTP, it can use Notes routing to transfer the message to other servers.

By default, Domino uses Notes routing only and is not configured for SMTP routing. To have Domino
use SMTP to send and receive mail, do the following:
v Prepare your system for sending messages to the Internet by testing your Internet connection and
verifying that DNS is set up properly.
v Enable the SMTP Listener task in the Server document of each server you want to receive mail over
SMTP
v Enable SMTP routing within the local Internet domain so that servers can send mail over SMTP within
the local Internet domain.
v Enable SMTP to be used to send messages outside the local Internet domain.
v Specify the relay host, if any, to be used when sending mail outside the local Internet domain.
Configure a relay host for SMTP servers that do not have direct access to the Internet.
v Set up inbound and outbound mail restrictions to protect against misuse of the mail infrastructure.
v To allow POP3 or IMAP users who connect to Domino from an external network to send mail to
external Internet domains, specify exceptions to inbound relay enforcement for authenticated users.

If you intend to allow users to access mail from POP3 or IMAP mail clients, you must install and enable
these access protocols on users’ mail servers. By default, Domino supports only Notes client access.

For information about using POP3 mail, refer to the chapter ″Setting Up the POP3 Service.″ For
information about using IMAP mail, see the chapter ″Setting Up the IMAP Service.″

Preparing to send and receive mail to the Internet

Use this list to ensure that your system is ready to send mail to and receive mail from the Internet or
another private SMTP network.
1. Make sure that you have a connection to the Internet via an Internet Service Provider (ISP) or a direct
connection.
2. Use the Ping command to test the connectivity between the SMTP-enabled server and any external
host to which it connects. Test the connection between machines from which messages will be sent
and the servers from which you send mail to the outside world, such as your ISP. Ping tests only the
accessibility of the host, not the existence or proper configuration of SMTP.
3. Define a list of the inbound Internet domain names by which your organization is known. In some
cases, a company may have multiple Internet domain names. Enter these names as aliases in the
Global domain document.
4. Make sure that the DNS is set up to include all the Internet domain names that your company uses.
5. If your company uses a mail relay or firewall, obtain the host name.

Setting up SMTP routing to external Internet domains

To send messages over SMTP to destinations outside of the local Internet domain -- for example, to the
Internet or another private network -- you must enable external SMTP routing.

To enable SMTP routing outside of the local Internet domain:

702 Lotus Domino Administrator 7 Help

1. Make sure that you prepared your system to send mail to the Internet.
2. Make sure you already have a Configuration Settings document for the server(s) to be configured.
3. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
4. Choose Configurations.
5. Select the Configuration Settings document and then click Edit Configuration.
6. On the Router/SMTP - Basics tab, complete this field, and then save the document:

Field
SMTP used when sending messages
outside the local Internet domain
Enter
Choose one:
v Enabled to use SMTP to route mail to the Internet
v Disabled (default) to prevent the server from routing mail outside the
local Internet domain

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Setting up SMTP routing within the local Internet domain

You can set up servers to use SMTP routing when transferring messages to other servers in the local
Internet domain.

You can enable SMTP routing on every server or only on servers that route to destinations outside of the
Notes named network. For example, you may not have a direct IP connection between all the servers in
one TCP/IP Notes named network and all the servers in another. You may still require that all messages
moving from one Notes named network to another be routed through hub servers.

To set up SMTP routing within the local Internet domain:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Choose Configurations.
4. Select the Configuration Settings document to be edited and then click Edit Configuration.
5. Click the Router/SMTP- Basics tab.
6. Complete these fields, and then save the document:

Field Enter
SMTP allowed within the Choose one:
local Internet domain v MIME messages only -- The Router uses SMTP to transfer MIME messages to other
Domino servers that are within the same Domino domain and that run the SMTP
Listener.
v Disabled (default) -- The Router uses Notes routing to transfer mail to other servers
in the same Domino domain.
v All messages -- The Router uses SMTP to transfer both Notes format and MIME
format messages to other Domino servers that are within the same Domino domain
and that run the SMTP Listener. This will cause Notes format messages to be
converted to MIME format before being transferred. This may cause loss of fidelity
and performance. For example, Notes Doclinks will not work.
Note: You can limit the use of SMTP to transfer mail within the Domino domain by
setting the next field (″Servers within the local Domino domain are reachable via
SMTP over TCPIP″) to only allow SMTP within the same Notes named network.

Chapter 29. Setting Up Mail Routing 703

Field
Servers within the local
Domino domain are
reachable via SMTP over
TCPIP
Enter
Choose one:
v Always (default) -- The Router can use SMTP to transfer mail to any Domino
server in the local Domino domain that runs the SMTP Listener.
v Only if in same Notes named network -- The Router can use SMTP to transfer mail
to other Domino servers in the local Domino domain only if the destination server
is in the same Notes named network. If the destination server is in the local
Domino domain, but resides in a different Notes named network, the Router must
use Notes routing to transfer mail.

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Enabling a server to receive mail sent over SMTP routing

To set up a server to receive SMTP-routed messages, you must enable the SMTP Listener. Then the server
can ″listen″ for SMTP traffic over the TCP/IP port (usually port 25) and receive SMTP messages in the
MAIL.BOX database(s).

Enabling the SMTP listener causes the server SMTP task to start up automatically every time the server
starts. Disabling the SMTP listener prevents the SMTP task from starting up when the server starts.

Note: Do not add SMTP as a task to the task list in the NOTES.INI file or this feature will not work.

To enable or disable the SMTP Listener:

1. From the Domino Administrator, click the Configuration tab and then expand the Server section.
2. Select the Server document to be edited it and then click Edit Server.
3. On the Basics tab, complete these fields:

Field Enter
Fully qualified Internet The server’s complete combined host name and domain name, including the top-level
host name domain. For example, smtp.acme.com; smtp is the host name; acme is the second-level
domain; and .com is the top level domain.

In the absence of a Global Domain document, the Router uses the entry in this field to
determine the local Internet domain. Typically, the fully qualified host name is added to
the Server document during server setup or by the Administration process (AdminP). A
routing loop can result if this field does not contain a valid entry.
SMTP listener task Choose one:
v Enabled to turn on the Listener so that the server can receive messages routed via
SMTP routing
v Disabled (default) to prevent the server from receiving messages routed via SMTP
routing

4. Click the Ports - Internet Ports - Mail tab.

5. In the Mail (SMTP Inbound) column, ensure that the TCP/IP port status is set to Enabled, and then
click Save and Close.
Refer to ″Reconfiguring the SMTP port″ for more information about modifying the default SMTP port
settings.

Setting up how addresses are resolved on inbound and outbound mail

To ensure that messages are properly routed, you can configure the following addressing and lookup
options:
v Create forwarding addresses for users that do not have Notes mail files
v Specify a smart host that contains a master directory for the organization

704 Lotus Domino Administrator 7 Help

v Enable Domino to accept mail for multiple Internet domains used by the organization
v Specify how Domino looks up the recipients of incoming SMTP messages
v Specify how Domino resolves host names for outbound SMTP messages
v Enable Domino to look up the sender’s Internet address from a Person document when sending
outbound SMTP messages
v Specify how Domino forms the sender’s return address when sending outbound Internet messages

Setting up a forwarding address

A forwarding address allows users who have Person documents in the Domino Directory to have their
mail forwarded to another address. Set up forwarding addresses for users who:
v Change their names -- for example, because of marriage -- but still want to receive all their messages.
v Move -- for example, a user may resign from the company but leave a forwarding address so that mail
addressed to the old address is forwarded to the new location.
v Use a different mail system and do not have Notes mail files.

Configure the forwarding address on the user’s Person document.

For more information about creating a Person document for a user, see the chapter ″Setting Up and
Managing Notes Users.″

By default, the Router supports use of the ″Send copy to″ rule action, which lets Notes users create mail
rules to automatically forward copies of messages delivered to their mail files to another address, such as
a forwarding address.

For information on disabling automatic message forwarding, see the chapter ″Customizing the Domino
Mail System.″

Setting up a smart host

A smart host is a directory server to which SMTP-routed messages are sent when the message recipient
cannot be found in the Domino Directory or other secondary directories configured on the server.

Typically, a smart host is used in organizations that employ multiple mail systems within a single
Internet domain. Users on these systems may not be in the Domino Directory. For example, if some users
are on a UNIX sendmail system but their inbound messages are routed through the Domino mail system,
you can set up a smart host to ensure proper address resolution.

After you set up a smart host, when Domino receives a message, if the domain part of the recipient’s
address matches the local Internet domain or one of the alternate Internet domain aliases defined in the
Global Domain document, the Router looks up the address against all configured directories. If the
address is not found, the Router then uses SMTP to forward the message to the configured smart host.

Domino sends all messages addressed to unknown recipients in the local Internet domain to the
configured smart host. You cannot configure Domino to send to the smart host only messages addressed
to recipients in some subset of the internal domains and domain aliases defined in the Global domain
document.

Note: Domino does not send messages addressed to unknown Notes addresses to the smart host.

You must have DNS set up correctly to use a smart host. For more information about DNS, see the
chapter ″Overview of the Domino Mail System.″

To set up a smart host:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.

Chapter 29. Setting Up Mail Routing 705

3. Choose Configurations.
4. Select the Configuration Settings document and then click Edit Configuration.
5. Click the Router/SMTP - Basics tab.
6. Complete these fields, and then save the document:

Field Enter
Local Internet domain The host name for the server that hosts the directory for SMTP recipients who are not in
smart host the local Domino Directory. To provide a level of failover and load-balancing, specify a
host name that maps to an existing MX record. You can also specify IP address.
Note: If this field contains a host name entry and the field ″Verify that local domain
recipients exist in the Domino Directory″ is enabled, messages addressed to local
recipients that can not be resolved are not accepted; therefore, there is no transfer of
messages to the smart host.
Smart host is used for all Choose one:
local Internet domain v Enabled to route all incoming SMTP messages to the smart host for lookup before
recipients routing elsewhere.
v Disabled (default) to route only messages whose recipients are not found in the
Domino Directory to the smart host for lookup.
Note: If this field is set to Enabled, and the field ″Verify that local domain recipients
exist in the Domino Directory″ is enabled, messages are received only for recipients
whose names can be resolved in the Domino Directory. If this field is set to Enabled, and
messages are accepted, all of these messages for local recipients are forwarded to the
smart host.

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Setting up a server to receive mail for multiple Internet domains

Every organization has a primary Internet domain name -- for example, acme.com -- by which it is
known to the rest of the world. By default, Domino considers the local, primary Internet domain to be
the domain specified in the server’s host name. For example, for a server with the host name
Server1.acme.com, both Server1.acme.com and acme.com are considered local Internet domains. The
server does not accept messages addressed to recipients in any other Internet domain.

In addition to having a primary Internet domain, some organizations use alternate Internet domain
names. If your organization uses more than one Internet domain name, you’ll want Domino to consider
other domain suffixes as local. Using multiple Internet domain names typically results when:
v An organization changes names
v An organization acquires or merges with another company that already has an existing Internet
domain name, and users continue to use the other Internet domain in their addresses
v You set up a mail topology to route messages addressed to other subsidiaries through your firewall
before routing the messages to the Internet or another private network
v You set up a mail topology specifically to include more than one Internet domain name

If for any of the preceding reasons people in your organization have addresses in an Internet domain
other than the primary domain, create a Global Domain document. A Global Domain document identifies
the Internet domains that are considered to be internal to a Domino domain and for which the local
domain can accept mail. By default, the Domino Directory does not contain a Global domain document.
Within the Global Domain document, you specify one primary Internet domain name and multiple
secondary domains. Secondary domains are listed as alternate Internet domain aliases.

You must ensure that the DNS is set up to include all the Internet domain names that your company
uses.

706 Lotus Domino Administrator 7 Help

To create a Global Domain document:
1. Make sure you already have a Configuration Settings document for the server(s) to be configured. For
Domino Release 5 and greater servers, a Configuration Settings document is required to set up SMTP
routing.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Choose Domains, and then click Add Domain.
4. On the Basics tab, complete these fields, and then click Restrictions and complete that field:

Field Enter
Domain type Choose Global Domain
Global domain name (Optional) A word or phrase that describes the domain. Never use the
name of an existing domain for your Global Domain
Global domain role Choose one:
v R5 Internet Domain - For Domino Release 5 and greater SMTP servers.
v R4.x SMTP MTA - For Domino servers that use the SMTP MTA to send
Internet mail.

Field Enter
Domino domains and aliases The Domino domain name and aliases. Domino uses the
domain name and aliases when accepting mail from the
alternate domains listed in the Global Domain document.

5. Click the Conversions tab, complete these fields, and then save the document:

Field Enter
Local primary Internet The primary Internet domain name that your company uses to represent themselves to the
domain outside world -- for example, another.com.
Alternate Internet Additional Internet domain names that your company uses -- for example,
domain aliases still.another.com, yet.another.com, have.another.com, and so on.

Use the asterisk (*) as a wildcard to represent the names of subdomains. Wildcard use is
valid only if the wildcard character appears as the first character of a given entry and
represents an entire subdomain name, for example: the entry *.another.com indicates that
Domino treats any subdomain of ″another.com″ as a local domain.

Entries that use wildcards in any other way are considered invalid, including:
v Using a wildcard in any position other than as a leading character in the entry. For
example, the entries another.*, and still.*.com are not valid.
v Using a wildcard on its own to represent an entire domain suffix. For example, the
entry * is not valid.
v Using a wildcard to represent a portion of a name only. For example, the entries
*other.com and *ill.another.com are not valid.

These fields represent the only ones you must complete if you are using the Global Domain document
solely for the purpose of defining the internal Internet domains in an organization running Domino
Release 5 and greater.
6. Restart the server to put the changes into effect. The server reloads information in the Global Domain
document into memory only after a restart.
For more information about DNS, see the chapter ″Overview of the Domino Mail System.″

If a Domino server uses ETRN to pull mail for multiple Internet domains from another mail host, you
can set up the Connection document to that host to request mail for alternate Internet domains.

Chapter 29. Setting Up Mail Routing 707

Specifying how Domino looks up the recipients of incoming SMTP messages
When Domino receives a message over SMTP, the message recipient is identified by an Internet-style
address, in the format Genevieve_Martin@acme.com, rather than a Notes-style address, such as
Genevieve Martin/Acme. To determine the correct destination mail file, Domino must match the SMTP
address to a Person document in the Domino Directory. To find a match, the Router checks the $Users
view of the directory. This view displays all name entries in all Person documents in the directory,
including Internet mail addresses, as well as all user name variations, first names, last names, common
names (CN), distinguished names (DN), short names, and soundex names.

Note: To display the hidden $Users view: Open the directory, press CTRL-SHIFT and select View-Go To.
In the Go To dialog box, select the view ($Users) and click OK.

Inbound recipient lookups are controlled by the Address lookup setting on the Router/SMTP - Basics tab
of the Configuration Settings document. This setting determines the criteria that the Router uses when
attempting to match the SMTP address on an incoming message to an entry in the $Users view. The
Router matches addresses based on:
v The full SMTP address only -- for example, Genevieve_Martin@acme.com
v The local part of the SMTP address (that is, the part to the left of the @ sign) only -- for example,
Genevieve_Martin
v The full SMTP address, and then if no match is found, the local part address

When using full name matching, the Router searches the Domino Directory for an exact match of the
entire SMTP address (for example, First_Last@Acme.com). If an exact match is not found, the Router
performs a secondary search if the domain suffix of the incoming address is listed in the Global domain
document as an Internet domain alias. For this secondary search, the Router replaces the given domain
suffix with the domain suffix designated in the Global domain document as the Primary domain name.

To prevent the Router from using domain aliases when looking up addresses, do not include alternate
Internet domain aliases in a Global domain document. Instead, create multiple Global Domain
documents, each specifying a different primary Internet domain.

Restricting the Router to matching addresses on the full Internet address only ensures that each user’s
Internet address complies with a standard format. Users cannot receive inbound mail addressed to their
short names, soundex names, or other name variations that exist in the $Users view. When configuring
the Router to look up users’ full Internet addresses only, complete the Internet address field in all Person
documents, and Mail-in database documents for mail-in databases that receive mail over SMTP.

To specify how addresses are looked up:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Choose Configurations.
4. Select the Configuration Settings document to be edited and then click Edit Configuration.
5. Click the Router/SMTP - Basics tab.

708 Lotus Domino Administrator 7 Help

6. Complete these fields, and then save the document:

Field Enter
Address lookup Specifies how the Router searches the Domino Directory to determine the Notes
recipient of an inbound Internet message. Choose one:
v Fullname then Local Part - (default) The Router first searches the Domino Directory
for a match for the full Internet address (localpart@domain.com). If no match is
found, it searches the directory again, looking for a match for the local part of the
address only.
v Fullname only - The Router searches the Domino Directory for full Internet
addresses only. For example, it searches for ″user@domain.com″ but not for ″user.″ If
an exact match is not found and the domain suffix is equivalent to an Internet
domain alias defined in the Global domain document, a secondary search is
performed using the domain suffix of the primary Internet domain.
v Local Part only - The Router searches the Domino Directory for a match of the local
part of the Internet address, that is, the part before the @ symbol. Local part
matching matches periods and underscores in the address with spaces in the
directory.
Exhaustive lookup Choose one:
v Enabled - The Router searches all directories to ensure that there are no duplicate
recipient names that might prevent the message from getting to the right person.
Performing exhaustive lookups is time-consuming and places a heavy load on the
server.
v Disabled - (default) The Router limits its search to the first directory that contains
the address.

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Specifying how Domino looks up SMTP hosts when sending outbound mail
You can specify how the Router determines the IP address(es) for destination SMTP systems (for
example, the Internet). Known as address resolution, the method you select determines how the Router
performs domain-name-to-IP-address translation.

Address resolution methods are:

v Dynamic lookup only (DNS only)
v Local lookup only
v Dynamic then local

If you configure TCP/IP to use the Domain Name System (DNS), select Dynamic mapping only or
Dynamic then local. For Dynamic mapping only, the Router queries a DNS server to map a fully
qualified host name to an IP address.

For Dynamic then local, the Router first queries the DNS and then checks a file on your local drive. This
file, known as a hosts file, maps destination host names to IP addresses. The Dynamic then local option
can be useful if you need to connect to internal hosts that are not listed in the DNS.

If you configure TCP/IP to use local hosts lookup, select ″Local lookup only.″ If you use this option, the
IP address and fully qualified host name for each destination must exist in the hosts file. This option
requires more administrative attention than the Dynamic mapping only option because you need to
maintain the file.

If the DNS does not list a destination host name, the Router designates the message as non-deliverable. If
the DNS is unavailable, the Router retries delivery up to the configured number of times as indicated in
the Initial transfer retry field on the Configuration Settings document.

Chapter 29. Setting Up Mail Routing 709

To set how host names are looked up:
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Choose Configurations.
4. Select the Configuration Settings document to be edited and then click Edit Configuration.
5. Click the Router/SMTP tab.
6. On the Basics tab, complete this field, and then save the document:

Field Enter
Host name lookup Choose one:
v Dynamic lookup only (DNS only) - The Router determines the IP address for a host by
looking it up in DNS. SMTP transfer can occur only if the destination host is listed in
DNS.
v Local lookup only (host files only) - The Router determines the IP address for a host
by looking it up in a hosts file on the local machine.
v Dynamic then local - (default) The Router determines the IP address for a host by
looking it up in DNS first and then checking the local hosts file if no DNS entry exists.

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Enabling the Router to look up the sender’s Internet address from the Person
document
When a Notes client is configured to send mail for Internet recipients in Notes rich text format, a Domino
server must convert outbound mail from the client to MIME format for Internet mail transport over
SMTP. The Domino server responsible for the conversion must ensure that all addresses in the message
headers, including both the recipient and sender addresses, are in Internet mail (RFC 821/822) format.

If the sending user’s Location document specifies an Internet address, Domino places this address in the
From field of the MIME message. However, if the Location document does not specify an Internet
address, Domino must obtain the address by other means. By default, Domino forms an Internet address
by converting spaces in the user’s Notes address into underscores, and prefixing the names of Domino
domains in the address with percent signs. For example, a Domino server in the acme.com Internet
domain converts the Notes address John Smith@Notes to the Internet address
John_Smith%Notes@acme.com. Domino determines the Internet domain from the Server document or the
Global Domain document.

If your organization prefers to standardize Internet addresses using a format that does not reveal internal
domain names, you can specify an Internet address in each user’s Person document and configure
Domino to look up the specified addresses during MIME conversion.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the MIME - Conversion Options - Outbound tab.

710 Lotus Domino Administrator 7 Help

6. Complete the following and click Save & Close:

Field
Lookup Internet address for all
Notes addresses when Internet
address is not defined in
document
Description
Addresses on all messages sent to Internet recipients must be in Internet format
(RFC 821/822 format). A Notes user may send a message to both Notes addresses
and Internet addresses. To specify how Domino converts the addresses of Notes
recipients on messages sent to the Internet, choose one:
v Enabled - On outbound Internet messages, if the address of the sender or any
recipient is in Notes format, Domino looks up the user’s Internet address from
the Person document and, if found, substitutes it for the Notes address before
sending.
v Disabled - (default) Domino forms Internet addresses based on rules in the
Global Domain document. If a Global domain document is not present, Domino
constructs addresses by converting spaces into underscores and encoding
Domino domains with percent signs. For example, Domino converts the Notes
address John Smith@Notes to the Internet address
John_Smith%Notes@acme.com
Note: When this option is disabled, Domino will continue to perform Internet
address lookups if configured to do so in the field ″Internet address lookup″ in the
SMTP Address Conversion section of the Conversion tab of the Global Domain
document.

How Domino formats the sender’s Internet address in outbound messages

Outbound SMTP messages always include the Internet address of the sender. Domino can obtain the
sender’s address, sometimes called the reply address, from the sender’s Location document, the sender’s
Person, or by constructing the address based on a default format or rules configured in the Global
Domain document. To ensure that message replies are routed correctly to the original sender, reply
addresses should match the sender’s Internet address.

To comply with Internet addressing standards, Domino uses RFC 821 or RFC 822 address formats for any
message sent over SMTP, as illustrated in the following table.

Internet
Address Style Address Format Example
RFC 821 Username@IPDomain.TopLevelDomain Tyler_Hamilton@acme.com
RFC 822 ″FriendlyName″ ″Tyler Hamilton″
<Username@IPDomain.TopLevelDomain> <Tyler_Hamilton@acme.com>

If a Domino SMTP server receives a message that is in Notes mail format -- as when a server in the local
network transfers a message to an SMTP server for routing to the Internet -- it must convert that message
to MIME before transferring it over SMTP. As part of the conversion process, the Router replaces
Notes-style addresses in the message, including the sender’s address, with an Internet-style address.

It’s easy for the Router to add the appropriate address when it’s been defined in the sender’s Person
document. In this case, the sender’s Notes client enters the Internet address in the INetFrom field of the
message. When converting the message for SMTP transfer, the Router uses the supplied Internet address.

For more information about Location documents, see the topic ″Creating or editing a Location document
manually″ in Lotus Notes 7 Help. You can download or view Notes 7 Help from the Documentation
Library of the Lotus Developer Domain at http://www.lotus.com/ldd/doc.

If the sender’s Internet address is not present in the Notes message, the Router can attempt to retrieve it
from the Person document. For address lookups to occur, you must enable them on the MIME -

Chapter 29. Setting Up Mail Routing 711

Conversion Options - Outbound tab of the server’s Configuration Settings document (if lookups are
disabled in the Configuration Settings document, they can occur if enabled in the Global domain
document).

For information about enabling outbound address lookup in the Configuration Settings document, see the
chapter ″Customizing the Domino Mail System.″

Finally, if the Router cannot obtain the sender’s Internet address from either the message itself or the
Person document, it will construct the address. You can specify the rules for constructing this address in
the Global domain document, but in the absence of a Global domain document, the Router constructs
Internet addresses using the following default format:
Full_Name/Org%DominoDomain@IPDomain.TopLevelDomain

For example, the Router on the host smtp.acme.com would construct the following default Internet
address for the Notes user Tyler Hamilton/Sales@Europe: Tyler_Hamilton/Sales%Europe@acme.com.

Internet Address component Description

Full_Name The Notes common name of the sender. The Router replaces spaces in the name
with underscores. For example, Tyler Hamilton becomes Tyler_Hamilton.
Org The organizational certifier or certifiers in the sender’s Notes hierarchical name. For
example /Sales.
DominoDomain The name of the Domino domain that hosts the user’s mail file. For example,
Europe. By default, the Domino domain is separated from the Org name by the
percent (%) character.
IPDomain.TopLevelDomain The Internet domain suffix listed in the Fully qualified Internet host name field of
the Server document of the server converting the message for SMTP transfer. For
example, the domain suffix of the server smtp.acme.com is acme.com.

To ensure that messages always include the sender’s correct and reply-able Internet address, always add
the Internet address to a user’s Location document and Person document. To fill in the Internet Address
field for all Person documents in which the field is blank, use the Internet Address Tool.

For more information about the Internet Address tool, see the Upgrade Guide.

Changing the default format for constructing the sender’s Internet address on
outbound mail
When converting a Notes message for SMTP transfer, the Router replaces the Notes address of the sender
with an Internet address. If the Router cannot determine the sender’s Internet address, either from the
InetFrom field of the Notes message, or the Internet address field of the user’s Person document, it
constructs an Internet address by combining the user’s Notes name with Domino domain and Internet
domain information. The rules for constructing the sender’s Internet address are specified in the Global
domain document. By default, the Global domain document constructs addresses in the following format:
First_Last/ou/org%DominoDomain@Internetdomain.TopLevelDomain

For example:
Meredith_Richards/East/Acme%Acme@acme.com

The address conversion settings in the Global domain document apply to all mail sent over SMTP from
servers in this Global domain -- including messages for recipients in the local Internet domain as well as
messages for recipients in external Internet domains.

The Router uses the address conversion settings in the Global domain document for outbound mail only
in cases where the sender does not have an Internet address defined in the Location and Person
documents, or address lookup to the Domino Directory either fails or is disabled.

712 Lotus Domino Administrator 7 Help

To ensure that every user has a standard Internet address, populate the Internet address field in each
user’s Person document. The Internet address tool available in the Domino Administrator lets you specify
an address format for creating unique Internet addresses in every Person document in which the Internet
address field is not currently set.

Generally speaking, if all users have Internet addresses in their Person documents and address lookups
are always successful, address construction on outbound SMTP messages never occurs. However, even if
you complete the Internet address field of every user’s Person document, configure address conversion in
at least one Global domain document to ensure that addresses are formed correctly in the event that
lookups fail and address conversion occurs. Only in the most limited of deployments can one expect
never to require address conversion.

For information about enabling Internet address lookup for outbound SMTP mail, see the topic ″Enabling
the Router to look up the sender’s Internet address from the Person document″ earlier in this chapter.

How Domino uses Global domain documents during inbound and outbound SMTP
routing
When Domino receives an inbound SMTP message, it attempts to determine whether the message is for a
local recipient. When the Domino Directory does not include a Global Domain document, Domino
accepts only messages addressed to users in the same Internet domain as the server, as indicated in the
Fully-qualified Internet host name that appears in the Server document.

But if the Domino Directory includes a Global domain document, Domino can receive mail for multiple
Internet domains. To determine whether to accept a message, Domino compares the domain part to the
local primary Internet domain listed in the Global domain document. If it does not find a match in this
field, it examines the secondary Internet domains -- the ″alternate Internet domain aliases″ -- listed in that
document.

The role of Global domain documents in determining whether to accept inbound SMTP mail: If the
Domino Directory contains multiple Global domain documents, Domino uses a similar process to
determine whether a recipient is local: it first checks the primary Internet domain in each Global Domain
document, and then, if it still hasn’t found a match, it continues by checking the alternate Internet
domains. If the domain in the address does not match any of the domain entries in any Global domain
document, the message is considered an attempt to relay, and Domino rejects the message.

Inbound address lookup when the Domino Directory contains multiple Global Domain documents:
After Domino accepts a message, the Router attempts to match the recipient’s Internet address to an
entry in the Domino Directory. When looking up the recipient in the Domino Directory, if the domain
suffix in the address matches an alternate Internet domain aliases defined in a Global Domain document,
and no Person document includes this address, the Router performs a secondary lookup. In this
secondary lookup, the Router pairs the local part of the address with the domain suffix of the primary
Internet domain specified in the Global domain document.

For example, a server receives a message for craig_bowker@acmewest.com. The Router searches all of the
Person documents in the Domino Directory for this Internet address, but cannot find a match. However,
in the Domino Directory, there is a Global domain document that includes the domain suffix
acmewest.com as an alternate Internet domain alias. In this same Global Domain document, the primary
Internet domain is acme.com. After the primary lookup fails, Domino performs a secondary lookup,
using the address craig_bowker@acme.com. Domino performs secondary lookups only if the Router is
configured to perform fullname, or fullname, then local part lookups.

In cases where the Domino Directory contains multiple Global domain documents, and a secondary
lookup is required, when replacing the domain suffix in the original address with the domain suffix of
the primary Internet domain, the Router only considers Global domain documents that list the alternate

Chapter 29. Setting Up Mail Routing 713

Internet domain alias. That is, Domino always replaces the domain suffix from within a given document;
it never replaces an alternate domain listed in one document with a primary domain from another
document.

To prevent the Router from using domain aliases when looking up addresses, do not include alternate
Internet domain aliases in a Global domain document. Instead, create multiple Global Domain
documents, each specifying a different primary Internet domain.

Controlling outbound addresses construction with multiple Global domain documents: When the
Domino Directory contains a single Global Domain document, the address construction rules in that
document determine how a server forms the sender’s address in an outbound SMTP message. However,
if the Domino Directory contains multiple Global Domain documents, when constructing the sender’s
address, Domino uses the Internet domain specified in the Server document and the address construction
rules defined in the Global Domain document listed last, alphabetically, in the directory. If you want
Domino to form the sender’s outbound address from the primary Internet domain and the address
construction rules contained in a particular Global domain document, designate that document as the
default Global Domain document.

Designating a default Global domain document: When there are multiple Global Domain documents in
the Domino Directory, designate one as the default so that when a servers construct a sender’s outbound
Internet address, the addresses created are based on the primary Internet domain and address
construction rules specified in the designated document.
1. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
2. Choose Domains, and click Global Domain
3. Select the Global Domain document you want to designate as the default and click Edit Domain.
4. On the Basics tab, complete following field, and then click Save & Close:

Field Enter
Use as default Global Domain (for use Select Yes to designate this Global Domain document as the default Global
with all Internet protocols except domain for this Domino Directory.
HTTP)

Configuring Domino to send mail to a relay host or firewall

A relay host can be a server within your organization or an Internet Service Provider (ISP) that routes
messages addressed to destinations outside the local Internet domain. Often the same server acts as a
firewall through which your organization funnels all messages outbound to the Internet. It can be a
Domino server or another type of server -- for example, a UNIX sendmail server.

To configure internal SMTP servers to send mail to a relay host, you specify the IP address or host name
of the relay host in the Configuration Settings document. If connections from the internal mail server to
an ISP mail server pass through a firewall, specify the internal interface of the of the firewall in this field,
and configure the firewall to forward traffic received on port 25 to the ISP mail server.

Servers that do not route mail over SMTP require special configuration to transfer messages to a relay
host or firewall. For more information, see the topic ″Transferring outbound Internet mail to an SMTP
server over Notes routing″ earlier in this chapter.

For information about restricting relay access through an Internet domain, see the chapter ″Customizing
the Domino Mail System.″

Configuring multiple relay hosts: To enable greater control over outbound message routing, you can
configure multiple relay hosts. Using multiple relay hosts enables Domino to route mail addressed to
certain Internet domains to certain relay hosts, without first performing a DNS lookup. For example, you

714 Lotus Domino Administrator 7 Help

can split external SMTP mail routing so that Domino routes all outbound Internet mail along one path,
except mail addressed to a specific domain, such as *.acmepartner.com, which it sends through a specific
SMTP server.

To configure multiple relay hosts, create a Foreign SMTP Domain document for each set of destinations,
and then create SMTP connection documents to match these foreign SMTP domain documents. For
example, using the previous example, you would create one Foreign SMTP Domain document for *.* and
another for *acmepartner.com.

Foreign SMTP Domain documents are used by servers that route mail over SMTP as well as those using
NRPC. For servers that use SMTP routing, Foreign SMTP Domain document indicate the destinations that
need relay hosts and the relay hosts to use in each case.

For more information on creating Foreign SMTP Domain documents, see the topic ″Transferring
outbound Internet mail to an SMTP server over Notes routing″ earlier in this chapter.

To set up a relay host:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Choose Configurations.
4. Select the Configuration Settings document and then click Edit Configuration.
5. Click the Router/SMTP - Basics tab.
6. Complete this field, and then click Save & Close:

Field Enter
Relay host for messages leaving the local Internet The host name, domain name, or IP address of the server being
domain used as a relay host.

A domain name is a valid entry only if the internal DNS contains

an MX record for that domain and can resolve it to a host name.

When entering an IP address, enclose it within square brackets;

for example, [127.0.0.1].

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
8. After you set up a relay host, you can set up restrictions based on where the message originated or
the message destination.

Routing mail over transient connections

Sites that do not have permanent connections to the Internet, or to other servers on the Domino network,
can send and receive messages over a transient connection, such as a dialup connection.

For example, an organization that does not have a constant connection to the Internet might use a remote
mail server at its ISP to hold mail until a local mail server calls in to the ISP server to retrieve or ″pull″
pending messages from the ISP server. If the ISP mail server supports the SMTP ETRN command, you
can configure the Domino server to ″pull″ mail over SMTP. A local Domino server can also use Notes
routing protocols to pull messages from a remote Domino server over a Notes Direct Dialup connection.

Setting up Domino to pull mail from a remote server: By default, when a local server initiates a
connection to a remote server, it uses the connection to push messages to the remote server. The local
server does not ″pull″ pending messages from the remote server. Instead, the local server only receive
mail from the remote server when the remote server initiates a connection to route those pending

Chapter 29. Setting Up Mail Routing 715

messages. To change this default behavior and have the local server retrieve messages from a remote
server during the same session in which it sends messages to the remote server, set up the local server to
send a ″pull request″ to the remote server.

When the local server is configured to send a ″pull request,″ it sends a message to the remote server
requesting that the server deliver any messages it has pending for the local server. The remote server
receiving the pull request can be any SMTP host; it does not have to be a Domino server. When the
remote server receives the ″pull request,″ it checks its mail queues for any messages pending for the
initiating server and starts the processing necessary to transfer those messages.

If you are using SMTP routing, you must make sure that ETRN protocol extension has been enabled on
the other server (the one receiving the ″pull request″), or it will not be able to receive the pull request.
Also the remote server must be able to resolve the DNS host name of the initiating server to an IP
address to ensure that the messages can be sent. Generally, ETRN requires that the initiating server has a
static IP address, which is available in DNS to the server holding the pending messages.

Note: Some ISPs use DHCP to assign a host a new IP address whenever it connects. If the remote system
assigns a new IP address every time you connect, do not configure dialup systems to use pull routing.

When configuring dialup routing, you can indicate how long the initiating server keeps the line open to
allow the remote server to establish a connection. This is useful to prevent the initiating server from
hanging up the line before the remote server is able to attempt to transfer any pending mail. The
initiating server sends a pull request, then pushes any messages it has for the remote server, and then
waits for any messages pending from the remote server.

When sending a pull request, the initiating server can also request messages for other servers, domains,
hosts, or any queue name within your organization for which the initiating server is responsible.

The ETRN command: With ETRN support, a dialup SMTP host can notify an SMTP server holding
messages for it when to deliver those messages. ETRN enables servers to use bandwidth resources
efficiently, because the dialup host sends and receives mail during the course of a single session.

ETRN stands for Extended Turn and is an SMTP service extension command, defined in RFC 1985. that
provides improved security over the SMTP TURN command, originally defined in RFC 821. The TURN
command allows hosts involved in a SMTP session to reverse their respective roles, so that, for example,
if Server1 is sending an SMTP message to Server2, Server1 can issue the TURN command so that Server2
then becomes the sender and Server1, the receiver.

However, because the TURN command has no mechanism for verifying the identity of the calling host,
use of the command poses a security risk. A malicious user who spoofs the identify of a server can
falsely appear to belong to a someone else’s Internet domain and then use the TURN command to
retrieve messages intended for that domain.

The ETRN command plugs this security hole by redefining the sending and receiving roles during the
course of the SMTP session. For example, after Server1 issues the ETRN command to Server2, ETRN
instructs Server2 to open a new SMTP session with Server1. Because Server2 has to resolve the name of
Server1 to an IP number in the DNS, Server2 is more likely to open a new SMTP session with the correct
machine.

For Domino to use ETRN to retrieve new mail over a dialup connection, your ISP must support this
command. Check with your ISP to verify whether they support this command or not. You can also verify
support for the command by establishing a telnet connection to port 25 of the ISP’s SMTP server. After
the SMTP session starts, type EHLO and press Enter. The response from the ISP’s SMTP server indicates
whether the server supports ETRN.

716 Lotus Domino Administrator 7 Help

For more information about Notes Direct Dialup Connections and Network Dialup Connections, see the
chapter ″Setting Up Server-to-Server Connections.″

To set up a server to route mail over a transient connection:

1. For SMTP routing, on the Router/SMTP Basics tab of the Configuration Settings document for the
sending server, enable SMTP for messages sent outside the local Internet domain.
For information on how to enable SMTP for outbound Internet mail, see the topic ″Setting up SMTP
routing to external Internet domains″ earlier in this chapter.
2. From the Domino Administrator, click the Configuration tab and then expand the Messaging section.
3. Click Connections.
4. Click Add Connection.
5. On the Basics tab, complete these fields:

Field Description
Connection type Choose one:

Network Dialup - Choose this option for servers that will route mail over SMTP using this
dialup connection. You can also use this option for NRPC routing.

Notes Direct Dialup - Choose this option only for servers that will use this connection to
route mail over NRPC to another Domino server.
Source server The Notes hierarchical name of the local Domino server initiating the routing request, for
example, SMTP/East/Acme.
Source domain The Domino domain of the source server, for example, AcmeEast
Use the LAN port(s) For Network dialup connections, enter the port name for the Domino TCP/IP port on the
local server.
Use the port(s) For Notes Direct Dialup connections, specifies the name of the communications port that
the source server uses.
Destination server The name of the Domino server, or SMTP server to which you want to route mail.

For SMTP routing connections to an ISP server, enter the host name of the ISP server, for
example, internet.isp.com. Depending on the requirements of your ISP, the specified host
can be used for outbound mail, inbound mail (using ETRN), or both. If the host is used
for outbound mail, enter the same host name on the Router/SMTP - Basics tab of the
Configuration Settings document, in the field ″Relay host for messages leaving the local
Internet domain.″
Destination domain For routing to Domino servers over Notes routing, enter the Domino domain of the
destination server.

Leave this field blank when configuring SMTP routing to an ISP server.

6. On the Routing and Replication tab, complete these fields, and then click Save & Close:

Field Description
Routing task Select Mail routing

Chapter 29. Setting Up Mail Routing 717

Field Description
Router type Choose one:
v Push/Wait - Select this option when the destination server is used for outbound mail
only, and initiates the connection to the source server. After the source server
establishes the dialup connection, it waits to receive a connection from the destination
server. When the destination server connects and issues a ″pull request,″ the source
server then pushes any messages pending for the remote server.
v Push Only - (default) Select this option if the destination server is used for outbound
mail only. The source server calls the destination server and sends messages queued
for that destination. You’ll need to create a separate Connection document to the server
used for inbound mail.
v Pull Push - Select this option if the ISP host to which the source server connects is
used for both inbound and outbound routing. The source server calls the destination
server, pushes, or sends, any pending messages for that destination, and then ″pulls″
messages from the destination server (actually, the calling server issues a request to the
other server to push messages back to it). The destination server pushes any pending
messages back to the source server. If you select this option, you must specify whether
the source server issues the pull request using Notes routing or SMTP.
v Pull Only - Select this option if the destination server is used for inbound mail only.
The source server calls the destination server and issues a pull request (a request for
the other server to push back messages). The destination server pushes any pending
messages to the source server. You’ll need to create a separate Connection document to
the server used for outbound mail.
Pull routing request Choose one:
protocol v Notes RPC - The server makes the pull request using Notes Remote Procedure Calls.
v SMTP - The server makes the pull request using SMTP. Select this option for SMTP
connections that support ETRN.
Note: When the destination server is a Domino server, the protocol specified in this field
only applies when the Router type is set to Pull Only. By contrast, if the Router type is
set to Pull/Push, the sending server always uses the same protocol to issue the pull
request that it used to transfer messages to the destination server.
Request the following Specifies the servers, hosts, or domains on whose behalf the source server issues a pull
when issuing a pull request. As a result of the request, the remote server sends all messages it is holding for
request the specified entities. Choose one or more of the following:
v Source server name (both Notes and Host) - (default) The source server requests that
the remote server transfer any messages addressed to recipients on the source server.
The source server receives messages for addresses that specify either the Domino
server name or the DNS host name (for example, CN=Server/Org=ACME or
server1.acme.com).
v All local primary Internet domains listed Global Domain(s) - (default) The source
server requests that the destination server transfer all messages it is holding for
recipients with addresses in the primary Internet domain named in the source server’s
Global Domain document (for example, acme.com).
v All alternate Internet domain aliases listed in Global domain(s) - The source server
requests that the destination server transfer all messages it is holding for recipients
with addresses in any of the Internet domain names listed in the source server’s Global
Domain document (for example, acme.com, sales.acme.com, acme-alias.com).
v The following servers/domains/hosts - The source server requests that the destination
server transfer all messages it is holding for recipients in the specified Domino servers,
Internet domains, or DNS host names. If you select this option, list the specific servers,
domains, or hosts on whose behalf the pull request is made. Use this option if the
remote server requires the calling server to use a specific syntax or name when
sending the ETRN pull request to initiate message transfer.
Pull router timeout The number of seconds that the calling server waits for the answering server to respond
to a pull request before disconnecting. The default is 30 seconds.

718 Lotus Domino Administrator 7 Help

7. For outbound SMTP connections, configure other servers on the local network to use the dialup
system as a relay.
8. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Updating the SMTP configuration

The SMTP service controls the SMTP listener on the Domino server. By default, whenever you restart the
SMTP service, and at two-minute intervals thereafter, the SMTP service automatically checks the
NOTES.INI file, Configuration Settings document, and Server document to see if any settings have
changed. If the service detects that settings have changed, it rebuilds its internal configuration to
incorporate the changes.

You can use a server console command to manually trigger such a service update. Using the console
command allows you to immediately put into effect changes to the SMTP configuration without
disrupting normal service operation.

To update the SMTP service configuration:

1. Modify settings in the NOTES.INI file, Configuration Settings document, or Server document.
2. At the server console, enter:
Tell smtp update config
If the server’s logging level is set to Informational or Verbose, the server console displays messages to
indicate when the update begins and completes.

Chapter 29. Setting Up Mail Routing 719

720 Lotus Domino Administrator 7 Help
Chapter 30. Customizing the Domino Mail System
This chapter explains how to customize messaging for your Domino system after you set up mail
routing.

Customizing mail
After you set up basic mail routing, you can customize the Domino messaging system to improve
performance and meet the specific needs of your organization. For example, you can set inbound
messaging restrictions to prevent unwanted commercial e-mail (UCE) from entering your system;
implement restrictions on message size to conserve network bandwidth; enforce database quotas to
ensure that users promptly delete old messages; set system mail rules to automatically process messages
that meet certain criteria; and enforce security policies by encrypting messages delivered to user mail files
and restricting message transfer to the Internet.

Before you customize your messaging system, you must:

1. Make sure that your mail system is properly set up.
2. Evaluate your customizing options and decide which you want to implement.

Requirements for a working mail system

For the Domino mail system to work properly you must first complete the following tasks:
v Install a Domino server.
v Load the Router task and verify that it runs properly.
v Create a mail file and Person document for every user in the Domino mail system.
v Set up Notes routing or SMTP mail routing.

For more detailed information on setting up mail routing, see the chapter ″Setting Up Mail Routing.″

Controlling messaging
After you set up basic mail routing, use Domino’s administrative controls to customize the messaging
system to your environment. Using the Domino Administrator and other tools you can change settings
that affect routing performance, protect the system from unauthorized use, schedule message transfer,
and ensure efficient use of network bandwidth and storage space.

Some of the settings you change apply to all of the messages that the server processes, regardless of
whether a message is sent or received using Notes routing or SMTP routing; other settings are specific to
a particular routing protocol.

These topics provide additional information on customizing the Domino system:

v Improving mail performance
v Customizing message transfer
v Customizing Notes routing
v Customizing SMTP routing
v Setting server mail rules
v Configuring message delivery options
v Setting up and using message disclaimers
v Using mail journaling

721
As you customize your messaging system, you may need to troubleshoot problems that occur. To assist in
troubleshooting, Domino lets you:
v Change the log level to record additional messaging information
v Temporarily disable mail routing

Improving mail performance

Domino includes features that improve efficiency in specific environments, but these features may not be
switched on by default. See the following topics for information about how you can improve the
efficiency of the Domino mail system:
v Creating multiple MAIL.BOX databases
v Disabling type-ahead addressing

Creating multiple MAIL.BOX databases

Domino mail servers use a MAIL.BOX database to hold messages that are in transit. Mail clients and
other servers use SMTP or Notes routing protocols to deposit messages into MAIL.BOX. The Router on
each server checks the address of each message in MAIL.BOX and either delivers the message to a local
mail file or transfers it to the MAIL.BOX database on another server.

Server processes -- including server threads and the Router -- that write to MAIL.BOX require exclusive
access to it. To ensure exclusive access, processes that write to or read from MAIL.BOX lock the database
to prevent simultaneous access by other processes. Other processes trying to access the database must
wait until the currently active process completes and unlocks the database before they can complete.

In most cases, a mail process locks MAIL.BOX for only an instant. However, longer wait times occur
when the Router or another process reads or writes a large message. When there is a large amount of
new mail -- for example, on a busy system with heavy mail traffic -- several server threads may try to
deposit mail into MAIL.BOX while the Router attempts to read and update mail. Under heavy loads,
such contention for a single MAIL.BOX database degrades performance.

On servers that run Domino Release 5 and higher, you can improve performance significantly by creating
multiple MAIL.BOX databases on a server. Using multiple MAIL.BOX databases removes contention for
MAIL.BOX, allows multiple concurrent processes to act on messages, and increases server throughput.
While reading one MAIL.BOX, the Router marks the database ″in use″ so other server threads trying to
deposit mail move to the next MAIL.BOX. As a further benefit, having multiple MAIL.BOX databases
provides failover in the event that one MAIL.BOX becomes corrupted.

When creating additional MAIL.BOX databases, consider placing each one on a separate disk. Because
disk contention is rarely an issue for MAIL.BOX, placing each additional MAIL.BOX database on a
different disk will not improve performance per se. However, distributing the databases across multiple
disks does ensure greater availability in the event of a disk failure.

Creating a second MAIL.BOX database offers a large performance improvement over using a single
MAIL.BOX. Depending on server mail traffic, adding a third and fourth MAIL.BOX database may further
improve performance. However, the improvement gained with each additional MAIL.BOX is increasingly
smaller.

You specify the number of MAIL.BOX databases on the Router/SMTP - Basics tab of the Configuration
Settings document. Changes to the mailbox count take effect only after the next server restart.

After you configure a second MAIL.BOX database, you can use mail statistics to determine whether
additional MAIL.BOX databases are needed.

After the new mailboxes are created, the old MAIL.BOX file is no longer used by the router. Any
messages in MAIL.BOX need to be copied into one of the newly created mailboxes on the server. The file

722 Lotus Domino Administrator 7 Help

naming convention used when multiple mailboxes are created is MAIL1.BOX, MAIL2.BOX, ...
MAILN.BOX, where N is the number of mail boxes specified in the Configuration Settings document.

To create multiple MAIL.BOX databases:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab, and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Basics tab.
6. Complete this field and then click Save & Close:

Field Description
Number of mailboxes Indicates the number of mailboxes (MAIL.BOX databases) on servers that uses this
Configuration Settings document. If this field is blank, one mailbox is used. Configure a
maximum of ten mailboxes.

7. Restart the server to put the new setting into effect.

Determining how many MAIL.BOX databases to place on a server

When a server sends and receives mail, server processes, such as the Router, access the server’s
MAIL.BOX database, writing messages to it and reading messages from it. Because only one process at a
time can access MAIL.BOX, when mail traffic is heavy, access conflicts occur as multiple processes try to
access the database simultaneously.

For servers that support a small number of users, access conflicts are rare, and the default of a single
MAIL.BOX usually provides an acceptable level of service. However, on servers that support a higher
numbers of users, creating an additional MAIL.BOX database can eliminate most access conflicts.

Statistic name Description

Mail.Mailbox.Accesses Total number of times that threads accessed any mailbox on the server.
Mail.Mailbox.AccessConflicts The number of times that a thread attempting to access a mailbox had
to wait because the number of concurrent threads exceeded the number
of mailboxes configured.

For example, if there are three mailboxes configured, and there are four
concurrent accesses, the conflict count would be incremented.

If the number of access conflicts consistently exceeds two percent of the

Mail.Mailbox.CurrentAccesses
Mail.Mailbox.AccessWarnings
value of Mail.Mailbox.Accesses, consider creating an additional mailbox.
The total number of current accesses (for example. a count of 2 would
indicate that two threads are accessing mailbox at this time.
The number of times that the number of threads accessing the mailbox
(that is, the value of Mail.Mailbox.CurrentAccesses) reached one less
than the number of configured mailboxes.

For example, the warning count is incremented when two threads

attempt to access MAIL.BOX concurrently and there are three mailboxes
configured.

If the number of warnings consistently exceeds ten percent of the value

of Mail.Mailbox.Accesses, consider creating an additional mailbox.
Mail.Mailbox.MaxConcurrentAccesses The highest number of current accesses recorded.

Chapter 30. Customizing the Domino Mail System 723

By calculating the number of access conflicts as a percentage of total accesses, you can determine whether
a server will benefit from the addition of another MAIL.BOX. In general, the number of access conflicts
should be no more than two percent of the total number of accesses. However, because some access
conflicts may result from unusually high peak loads, there’s no need to eliminate all access conflicts. Only
when the percentage of access conflicts remains consistently greater than 2 percent is an additional
MAIL.BOX database warranted.

Note: Mailbox statistics are available only on servers where two or more MAIL.BOX databases are
configured. You must restart the server to put into effect any changes to the number of mailboxes.

Disabling type-ahead addressing

Type-ahead addressing displays names that match the letters a user types in the To, cc, and bcc fields in a
mail message. For example, if a user types Jane D in the To field of a mail memo and Domino finds a
Person document for Jane Doe/Acme in the Domino Directory, Domino automatically completes the rest
of the recipient’s address. The user can change or retype the address as needed.

To save bandwidth and improve server performance, you can disable type-ahead addressing. If you
disable type-ahead addressing on a mail server, users can still use type-ahead addressing to find
addresses in their Personal Address Book or mobile Directory Catalog.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers to administer, and click Edit
Configuration.
5. On the Basics tab, complete this field, and then click Save & Close:

Field Enter
Type-ahead Choose one:
v Enabled - (default) The server checks the Domino Directory for an address that matches
what a user enters in the To, cc, or bcc field of a message.
v Disabled - The server does not try to match addresses. Matches occur only in the user’s
Personal Address Book or local Directory Catalog.

Changing the logging level for mail

By default, when the Router is unable to deliver a mail message, Domino records information in the
server log file (LOG.NSF). When you troubleshoot messaging, you may want to record additional
information in the log file.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Advanced - Controls tab.

724 Lotus Domino Administrator 7 Help

6. Complete this field in the Miscellaneous Controls section, and then click Save & Close:

Field Enter
Logging level Choose one:
v Minimal - Domino logs all mandatory status messages and fatal error messages.
v Normal (default) - Domino logs all minimal events, plus warning messages indicating
conditions that do not cause processing to stop.
v Informational - Domino logs all minimal and normal events, plus informational
messages involving intermediate storage, MAIL.BOX access, message handling,
message conversion, and transport status.
v Verbose - Domino logs all minimal, normal, and informational events, plus additional
messages that may help you troubleshoot system problems.
Note: To prevent the log file from becoming excessively large, use Verbose logging only
when troubleshooting specific problems.

The change takes affect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Controlling message delivery

Message delivery occurs when the Router deposits a message in the recipient’s mail file. You can control
how the Router behaves when delivering messages to mail files on the Domino server. For example, you
can specify whether messages are always encrypted, how many server threads the Router can use to
deliver messages, and what the Router does with messages sent to users whose mail files are larger than
the allowed size.

You set delivery controls in the Configuration Settings document on the Router/SMTP - Restrictions and
Controls - Delivery Controls tab. You can also set quota controls to help control the size of user mail files.

Setting delivery controls

You can customize message delivery on Domino, including how many threads are used to deliver
messages, whether the messages must be encrypted, how long the server waits for a pre-delivery agent to
run, and whether the Router supports the forwarding action in client mail rules.

Using client mail rules: Notes users can create mail file rules that automatically process new mail.
Servers that are delivering mail and running client mail rules must be running Domino 6.0.3, Domino 6.5,
or more recent versions. Client mail rules specify an action to take when a newly-delivered message
meets certain conditions. For example, one action that may be included in client mail rules is the stop
processing action. The stop processing action stops the processing of all rules that are preceded by the
rule containing the stop processing action. You can use the stop processing action alone, that is, as the
only action in a mail rule, or you can use it with another action in a rule. The stop processing action can
also be included in one rule that is in a series of rules. This is especially useful when more than one rule
applies to a message, but you want execution of client mail rules to stop after the first action is executed.

For information about client mail rules see the Notes client online help.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - Delivery Controls tab.

Chapter 30. Customizing the Domino Mail System 725

6. Complete these fields in the Delivery Controls section, and then click Save & Close:

Field Description
Maximum delivery The maximum number of server threads Domino can create to deliver mail from
threads MAIL.BOX to local mail files. The Router automatically sets the default maximum
number of delivery threads based on server memory. Letting the Router select the
maximum number is usually best. To set the maximum number manually, enter a
maximum between 1 and 25, based on the server load.
Encrypt all delivered Choose one:
mail v Enabled - When delivering messages to local mail files, Domino encrypts the messages,
regardless of whether the sender encrypted the message or the recipient’s mail file
encrypts messages.
v Disabled (default) -- Domino encrypts messages only if the recipient’s mail file is set to
encrypt received messages.
Note: When encryption is enabled and an external user requests a return receipt for a
message sent to a user whose mail file is on the server, the return receipt message that
Domino generates contains a blank message body.
Pre-delivery agents Users who create LotusScript or Java agents for their mail files can set the agent to run
before new mail arrives. When delivering a new message, if the Router detects such a
pre-delivery agent, it runs the agent against the message before the message ever appear
in the recipient’s Inbox. Use this field to specify whether the server permits the use of
pre-delivery agents. Choose one:
v Enabled - (default) Allows the Router to run agents that process mail before delivering
it to user mail files on the server.
v Disabled - Prevents the Router from running pre-delivery agents.
Pre-delivery agent The maximum time (in seconds) that a pre-delivery agent, such as a mail filter, can run
timeout before the Router interrupts it. Because the Router waits for pre-delivery agents to
complete, failure to restrict agents can slow routing performance on the server. The
default time-out is 30 seconds.
User rules mail Notes users can create mail file rules that automatically process new mail. User mail
forwarding rules specify an action to take when a newly-delivered messages meets certain
conditions. Use this field to specify whether the Router on this server supports the rule
action to send copies of selected messages automatically to other recipients. Choose one:
v Enabled - The Router supports the ″Send copy to″ action for Notes client mail rules,
allowing users to send copies of messages automatically to other recipients.
v Disabled - Prevents Notes clients from using the ″Send copy to″ rule action.

The change takes affect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Using quotas to manage the size of user mail files

Users may receive and save a high volume of e-mail, including their own sent messages, in their mail
files. Large mail files can overwhelm a server’s disk capacity and reduce the performance of the mail
client. Because you generally cannot provide users with unlimited storage space, set a size limit, or
database quota, for each mail file. When delivering mail to a user’s mail file, the Router checks the
current size of the mail file against the specified quota.

You can configure the Router to respond in several ways when a mail file exceeds its quota, each
representing a higher level of enforcement. The least restrictive response is to have the Router issue
automatic notifications to users when their mail files exceed the quota. If users fail to respond to
notifications, you can hold pending messages in MAIL.BOX or return messages to the senders as
undeliverable until the users reduce the size of their mail files.

In addition to setting a quota, you can configure a warning threshold and use it as the basis for
providing users with advance notice that their mail files have grown too large. For example, you might

726 Lotus Domino Administrator 7 Help

set a warning threshold of 25MB on a mail file that has a 30MB quota. In the Configuration Settings
document, you can enable the Router to send notifications to users who exceed their warning threshold.
If you enable this option, the Router delivers an Quota Warning Report to users whose mail files exceed
the warning threshold. Sending such warnings allows users to reduce the size of their mail files before
they exceed the quota.

When used with the setting ″Hold mail and retry″ in the Over quota enforcement field of the
Configuration Settings document, the NOTES.INI setting, MailTimeout, designates the number of days
that mail is held for the user when the user’s mail file exceeds the mail file size quota. By default,
MailTimeout=1. If a user’s mail file exceeds the quota for mail file size, mail is held for that user for one
day. If the user does not reduce the size of the mail file within one day, mail is returned to the sender as
undeliverable. If the mail file size is reduced during that one day, mail that was being held is delivered.
You may want to use a value greater than one so that users are allowed a reasonable grace period before
their mail is returned to the sender. For example, if a user is on vacation and is notified that their mail
file exceeds the set mail file size quota, the user would not be able to reduce the size of the mail file.
After being held for one day, mail would be returned to the sender as undeliverable. You can set a value
greater than one (1) to allow mail to be held for several days before being returned to the sender.

Note: MailTimeout affects all message time-outs, including other delivery errors that can be retried and
transient transfer errors.

Along with the methods the Router uses to enforce quotas, the Notes client also displays a warning to
any user who has exceeded their designated warning threshold or quota whenever the user attempts to
send mail.

Setting mail file quotas: You can set two types of size limits on a user’s mail file: an absolute quota size
and a warning threshold. Set a quota if you intend to establish a policy of interrupting users’ mail usage
if their mail files exceed a specified size. Set a warning threshold to provide users with advance notice
when their mail files approach the designated mail file quota, so they can reduce the size of their mail
files before message flow is interrupted. You must set a quota before you can set a warning threshold.

Quotas and warning thresholds are associated with a particular mail file database only, not with a user
ID. If a user has access to an alternate mail file, the quota set on the primary mail file has no effect on the
alternate mail file.

You set quota limits and warning thresholds:

v During registration - quotas specified during registration apply only to new users, not to existing users.
For users migrated from other mail systems, the restrictions do not apply to mailbox contents brought
over from the old system. In other words, a mail file limit of 5MB does not prevent you from
migrating a user’s 6MB mail box from cc:Mail. However, the user will not be able to receive new mail.
v Per database - Using the Domino Administrator, you can manually specify the warning threshold and
quota of one or more mail files using the same method you would to set these limits for any Notes
database.

Detecting when a mail file exceeds its quota:

Note: While this topic refers to behavior of the Router during delivery of new messages to a mail file, be
advised that the ″Check space used in file when adding a note″ setting is a server-wide setting that
applies to all updates to databases with quotas enabled on the server. For example, when a mail message
is sent for delivery and the message is saved in the Send folder, the Notes client initiates saving the sent
mail message on a server-based mail file, and the server then processes the note update.

If quota enforcement is enabled, whenever the Router delivers mail, it compares the current size of the
destination mail file against its configured database quota or threshold. If the size exceeds one of these,
the Router takes appropriate action.

Chapter 30. Customizing the Domino Mail System 727

If a mail file uses shared mail, Domino factors in the complete size of any messages stored in shared mail
databases when calculating mail file size.

When calculating mail file size, Domino does not take into account the space consumed by a file’s
full-text index. When setting a mail file quota, be sure to consider the additional space required for the
file’s full-text index. Over time, the full-text index of a typical mail database can reach a size between 5
and 15 percent of the database size.

To specify the method a server uses to calculate the size of a mail file:
1. From the Domino Administrator, click the Configuration tab, expand the Server section, and click ″All
Server Documents.″
2. Select the Server document to edit, and then click Edit Server.
3. Click the Transactional Logging tab, and in the Quota enforcement field, select one of these methods
and then click Save & Close:

Method for enforcing

quotas Description
Check space used in file This setting is most commonly used by the Router when calculating mail file size, but it
when adding a note can be used by any process that is updating one or more notes on a server.

The Router calculates the current size of a mail file from the amount of space that
messages occupy in the database and determines whether mail files are in compliance
with configured warning thresholds or quotas based on this calculation. White space in
the database is discounted. If the user is over quota and quota enforcement is enabled,
no new messages are delivered. If the mail file is close to its quota, the Router continues
to deliver messages only until their cumulative size exceeds the quota; thereafter,
messages are held or rejected, depending on the enforcement setting.

When a user deletes a message, the space occupied by that message is immediately
removed from the calculated size of the mail file. There is no need to run the Compact
task to recover space. Users who cannot receive mail because of a quota violation can
reduce the current size of the mail file immediately by archiving or deleting messages.

If transaction logging is enabled on the server, select this method of enforcement, because
it does not require administrative intervention to compact mail files.
Check file size when (Default) The Router calculates the current size of a mail file from its actual physical size.
extending the file The calculated physical size includes the unused ″white space″ in a file that results when
a user deletes or archives a message. Domino does not immediately recover this white
space. As a result, accumulated white space may account for a large portion of the file
size, so that the actual mail file size is considerably larger than the combined size of its
stored messages.

The size check occurs only if adding a message requires an increase in the size of the
mail file. When quota enforcement is enabled and this option is selected, if a message
delivered to the mail file requires an increase in the file size that would result in a quota
violation, delivery fails. However, a message is always delivered if there is sufficient
white space to accommodate it.

On servers that do not use transaction logging, users can run the Compact task to
remove white space and decrease the file size. However, when transaction logging is in
effect, users cannot compact their own mail files. An administrator must run Compact
with the -B option to reduce the size of the file.

728 Lotus Domino Administrator 7 Help

Method for enforcing
quotas Description
Check file size when The Router calculates the current size of a mail file from its actual file size. Both the
adding a note space occupied by messages and white space in the database count toward the total size.

This option is more restrictive than the preceding option, because the Router checks the
quota every time it adds a message to the mail file, regardless of whether this results in
an increase in file size.

On servers that do not use transaction logging, when quota enforcement is enabled,
select this option to eliminate inconsistent behavior during delivery to the mail files of
users who exceed their quotas. Because the Router always checks the current file size
when delivering a message, after a mail file reaches quota, no new messages are
delivered, even if a particular message is small enough to fit within the available white
space in the mail file.
Note: On servers where transaction logging is enabled, selecting this option can prevent
a user from recovering from a quota violation, since compacting the mail file does not
reduce its size, preventing the user from getting back under quota. An administrator
must run Compact with the -B option to reduce the size of the file.

How the configured size method effects over-quota enforcement: Unless you configure the Router to withhold
mail from or send warnings to users whose mail files exceed their quotas or warning thresholds, you
won’t notice any differences between the various methods for calculating file size. However, the method
you select for calculating file size becomes significant if you enable quota enforcement or warning
notifications on the server.

When servers are set to use file size to determine whether a user is over quota, a user who is over quota
might not be able to receive mail immediately after deleting messages. This is because white space
remains in the mail file until the Compact task removes it. As a result, a user whose mail is withheld due
to a quota error typically experiences some delay between removing messages and achieving the reduced
mail file size required to reinstate mail delivery.

On servers where quota enforcement is set to ″Hold mail and retry,″ you choose whether the Router
attempts delivery to mail files that exceed quota.

If database usage is enabled as the method for calculating size, message delivery always fails after a mail
file exceeds its quota. If a mail file is close to its quota but has not yet exceeded it, the Router may
succeed in delivering smaller messages. But eventually the file will exceed its quota, and subsequent
deliveries will fail.

Reclaiming space in mail files for which soft deletions are enabled: When soft deletions are enabled for a mail
file, deleting messages from a mail file doesn’t immediately reduce its size. Instead, the ″deleted″
messages are moved to the Trash view until they expire - after 48 hours, by default. Only then are the
messages permanently removed from the database.

To reclaim space immediately, a user must open the Trash view of the mail file and click Empty Trash or
select a message in the view and then click Delete Selected Item. By default, soft deletions are enabled for
mail files that use the Release 7 mail template (MAIL7.NTF) or more recent mail template.

For more information about soft deletions, see the chapter ″Improving Database Performance.″

Notifying users who exceed their mail file’s quota or warning threshold: You can configure the Router
to notify a user whose mail file exceeds a warning threshold or quota. The following table lists the
information contained in the notification message:

Chapter 30. Customizing the Domino Mail System 729

Message field Description
Notification type Describes why the user received the notification. For example, an over quota report
explains that an incoming message caused the user’s mail file to exceed the quota set for
their mail file. Over quota and quota warning reports contain default text, which you can
customize.
Message headers The sender (FROM field), recipients (TO and CC), subject of the effected message.
Message size The size of the affected message, in KB.
Current mail file usage Database usage or current size of the user’s mail file, in KB.
Current quota settings The warning threshold and quota currently set for the user’s mail file.
What you should do Explains what action, if any, was taken -- for example, whether the message was returned
to the sender or is being held for retry; and provides instructions explaining what actions
the user should take to reduce the size of the mail file -- for example, deleting or archiving
messages. If you customize the text of the notification to provide users with additional
instructions or information, the text you add appears as part of the Notification type
information at the beginning of the message.

For information on adding custom text to over quota and quota warning reports, see the topic
″Customizing the text of mail failure messages″ later in this chapter.

Users who exceed the quota for their mail file receive over quota warnings. Over quota warning
threshold notifications are sent to mail files that are over the warning threshold but under the database
quota. Over quota notifications are sent to mail files that exceed database quota.

Message tracking is not enforced or supported for either type of warning notification.

If Domino rejects an inbound message as the result of a quota violation, it returns a failure message
stating the reason for the failure to the sender.

Specifying how often users receive notifications: You have three options for specifying how often the Router
delivers warning notifications to users who violate their mail file’s warning threshold or quota:
v None - (Default ) - Users receive no warning if their mail files exceed the size limit.
v Per Message - Users whose mail files exceed the size limit receive a warning notification every time
MAIL.BOX receives a new message for them.
v Per time interval - Users whose mail files exceed the size limit immediately receive a warning message;
the warning message is not sent according to the specified per time interval setting.

Withholding mail from users who exceed their quota: Quota controls enable the Router to selectively
hold or reject mail if the destination mail file has exceeded its quota. When the Router has new mail to
deliver to a user whose mail file is already full, it checks the Configuration Settings document to
determine the appropriate action. By default the Router continues to deliver mail, even after a mail file
exceeds its quota. To change the default behavior, you must configure the Router to refuse or hold mail.

When delivering mail to a user’s mail file, the Router checks the mail file’s size. If the file will remain
within the specified threshold after delivery of the message, no action is taken.

The Router recognizes certain exceptions to the specified quota setting. For example, users who are over
quota continue to receive over quota notifications from the Router, regardless of the current setting.
However, if the Router is configured to Hold and Retry, all messages are held, and the owner of the mail
file receives no further notifications until the size of the mail file is reduced or the administrator takes
action to allow messages to be delivered.

To prevent an excessive number of messages from accumulating in MAIL.BOX when you choose the
Hold and Retry method of enforcing quota violations, it’s best to have Domino calculate database size

730 Lotus Domino Administrator 7 Help

based on usage, rather than file size. This is especially true on servers where transaction logging is
enabled, because users cannot reduce the size of their mail files without assistance from an administrator.

Limiting the size and number of messages held for retry: If you set the Router to temporarily hold mail
intended for users whose mail files exceed the specified quota, the increased number of pending
messages can increase the size of MAIL.BOX and decrease Router performance. To help ensure service
quality, you can limit the number of pending messages.

You can also specify the maximum size of messages that the Router will hold. If a message is larger than
the configured size, it is returned to the sender as undeliverable, rather than held.

Restrictions do not apply to sent messages: Router enforcement of mail file quotas is limited to withholding
new mail from users who exceed their quotas. The Router continues to accept outgoing mail from whose
mail files are full. However, these users are not able to save any messages to mail files on the server.

When a user who exceeds the configured warning threshold or quota sends a message from a Notes
client, the client displays a warning, but the user can still send the message.

Setting quota controls for the Router:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - Delivery Controls tab.
6. In the Quota Controls section, complete these fields:

Field Enter
Over Warning Specifies how often the Router delivers notifications to users who exceed their warning
Threshold threshold.
Notifications
Choose one:
v None - The Router does not deliver notifications when mail files grow larger than the
specified warning threshold.
v Per Message - The Router delivers a notification for every message it delivers after the mail
file exceeds the specified warning threshold.
v Per Interval N - Send notifications at a specified interval until the user deletes or archives
enough messages to bring the size of the mail file below the specified Warning Threshold.
When this option is selected, an additional field, ″Warning Interval Minutes,″ appears.
Warning Interval Specifies, in minutes, how long the Router waits to send the next Over Warning Threshold
Notification
Over Quota Specifies how often the Router delivers notifications to users who exceed their quota.
Notification
Choose one:
v None - The Router does not deliver notifications when mail files grow larger than the
specified quota.
v Per Message - The Router delivers a notification for every message it delivers after the mail
file exceeds the specified quota.
v Per time interval - When a message delivery is attempted and no notifications were sent
during the previous time interval, the router sends an ″over quota″ notification to the user’s
mail file. Over quota notifications are triggered by normal mail delivery; therefore, over
quota notifications may not be sent at the exact time interval setting. The router limits the
number of notifications sent to one notification during each time interval.

Chapter 30. Customizing the Domino Mail System 731

Field Enter
Error Interval Specifies, in minutes, hours, or days, how long the Router waits to send the next over quota
notification.
Over Quota Specifies the action the Router takes when receiving new mail for a user whose mail file is
Enforcement larger than the specified quota.

Choose one:
v Deliver anyway (don’t obey quotas) - (Default) The Router continues to deliver mail to a
mail file that is over quota.
v Non Deliver to originator - The Router stops delivering new messages to the mail file and
returns a nondelivery message to the sender reporting that the message could not be
delivered because the intended recipient’s mail file was full.
v Hold mail and Retry - The Router stops delivering new messages to the mail file and
temporarily holds incoming messages in MAIL.BOX until space is available in the mail file.
After an interval, the Router tries to deliver the message. If the user has sufficiently reduced
the size of the mail database by the next scheduled delivery attempt, the mail is delivered.
Messages that cannot be delivered before the expiration time (default =1 day) are returned to
the sender as undeliverable. If you choose this option, the document displays additional
fields where you can specify how the server handles held messages.
Note: To prevent an excessive number of messages from accumulating in MAIL.BOX when
this option is selected, it’s best to have Domino calculate database size based on usage, rather
than file size.

7. If you selected ″Hold mail and Retry″ in the ″Over Quota Enforcement″ field, complete the following:

Field Description
Attempt delivery Pending messages may be of different sizes. A mail file that has reached its quota may have
of each message sufficient space available to fit some messages, but not others. Use this field to specify whether
the Router delivers messages small enough to fit the available space in a destination mail file.
Choose one:
v Enabled - The Router attempts delivery of each new message. Messages that fit the available
space are delivered. Other messages are held.
v Disabled - After a mail file reaches its quota, the Router holds all messages until the file size
is reduced.
Maximum number Specifies the maximum number of messages that the Router will hold in MAIL.BOX for a
of messages to given mail file. After the number of pending messages reaches the specified number, the
hold per user Router returns a delivery failure report to the sender of each additional message in first-in,
first-out order.
Maximum message Specifies the maximum size, in KB, of messages that the Router can hold in MAIL.BOX for
size to hold over quota users. If a message larger than the specified size is received for the user, the Router
returns a delivery failure report to the sender.

8. Click Save & Close.

9. The change takes affect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

Overriding quotas: Administrators can provide users who are over quota with temporary access to their
new mail by:
v Modifying the quota currently in effect for the user’s database.
v Changing the Router setting, so that the Router ignores database quotas and delivers mail. If you set
the Router to ignore database quotas, all users who exceed their quotas are able to receive mail.

To permanently change a quota, reset its size value.

732 Lotus Domino Administrator 7 Help

Setting server mail rules
You can create content filtering rules for a server that define actions to take on certain messages. When a
new message that meets a specified condition is deposited in MAIL.BOX, Domino automatically performs
the designated action. Possible actions include journaling a message, moving it to a database, refusing to
accept or deliver a message, changing the routing state of a message, or stopping the processing of
subsequent rules. Rule conditions are based on content in the message headers or in the message body.

Mail rules automatically handle mail in a variety of situations. By configuring a set of conditions and
actions, you can customize rules to block spam mail or intercept messages with questionable content. For
example, you could create a rule that rejects mail with subjects like ″make money fast″ or that comes
from a known spam vendor. Similarly you can restrict users from receiving message attachments that do
not have a business purpose by setting up a rule to intercept messages that contain attachments of certain
file types (EXE, VBS, VBE, SCR, and so forth) and redirect them to a quarantine database where they
could be reviewed by an administrator and optionally sent on to the intended recipient.

Except where a rule action explicitly indicates, Domino does not notify the sender or recipient if a rule
prevents a message from reaching its destination. For example, if a rule results in a message being routed
to a graveyard database, Domino does not generate a delivery failure report or indicate to the intended
recipients that a message for them has been intercepted. By contrast, if a message triggers a rule with the
specified two-part action ″Don’t deliver message/ Send NDR,″ the sender receives a delivery failure
report stating that the message was rejected for policy reasons.

Note: Although Domino does not generate a notification to the sender when a rule condition triggers the
action ″don’t accept message,″ because rules execute as mail is deposited to MAIL.BOX, the sender may
still receive notification that the message was rejected. For example, when the Domino SMTP listener
refuses a message because of a mail rule, the sending SMTP server receives the error indicating that the
transaction was rejected for policy reasons. Typically, servers receiving this type of error generate a
delivery failure report to the sending user. Similarly, when a mail rule prevents the server from accepting
a message, a Notes client attempting to deposit the message in MAIL.BOX displays an error indicating
that the message cannot be sent.

Mail rules are not intended to serve as an anti-virus solution and should not be considered a replacement
for anti-virus software. Although you can configure rules to quarantine messages with known virus
attachments, the available rule actions do not include typical anti-virus features such as generating
warnings upon detecting a virus or automatically disinfecting files.

Domino stores the mail rules you create in the Configuration Settings document. On startup, each server
retrieves from the appropriate Configuration Settings document and registers them as monitors on each
MAIL.BOX database in use.

Whenever MAIL.BOX receives a new message from any source -- the SMTP process, the Router on
another server, or a client depositing a message -- the server evaluates the various message fields against
the registered mail rules. Each message is evaluated only once. Additional updates occurring after a
message is added to MAIL.BOX -- such as updates to reflect the number of recipients handled -- do not
cause reevaluation of the rules.

Stopping the processing of a mail rule

You can now use a ″stop processing″ action when setting up mail rules. The stop processing action stops
the processing of all rules that follow the rule containing the stop processing action. You can use the stop
processing action alone, that is, as the only action in a mail rule, or you can use it with another action in
a rule, and it can also be in one rule that is in a series of rules. This is especially useful when more than
one rule could apply to a message, but you want execution of mail rules to stop after the first action is
executed. For example, you can define the following rules:
v Rule 1) If Subject contains Marketing Move to database Marketing Information and Stop Processing
Rules

Chapter 30. Customizing the Domino Mail System 733

v Rule 2) If Subject contains Sales Don’t deliver message
Result: If the subject line contains the subject ″Marketing and Sales,″ the message is moved to the
Marketing Information database and processing stops. No other action is taken on the message.

Note: The stop processing action requires new formula language that is available on Domino server
versions 6.0.3, 6.5, or more recent. The stop processing rule does not execute correctly on Domino servers
released prior to versions 6.0.3 and 6.5. If mail is delivered to a Domino 5.x server with this rule defined,
the rule does not execute as expected and processing of mail server rules does not stop. Action that is
indicated by subsequent mail server rules would occur.

Prioritizing mail rules

When multiple mail rules are enabled, you can set their relative priority by moving them up and down
in the list.

Putting new rules into effect

The Configuration Settings document displays new mail rules only if the document has been previously
saved.

When you add a new rule, it takes effect only after the server reloads the mail rules. A reload is
automatically triggered if the Server task detects a rule change when performing its routine check of the
Configuration Settings document. This check occurs approximately every five minutes.

You can force the server to reload rules, using a console command.

Enter the following command at the server console:

set rules

To create a new mail rule

To configure system mail rules, use the Configurations view or the Server view that are also on the
Configuration tab in the Domino Administrator.

Note: If you create a rule that includes a backslash, semicolon, comma, asterisk, or quotation mark, an
error message appears indicating that these characters are not allowed. This message does not yet display
for forward slashes, but forward slashes should not be used when setting rules.
1. Make sure you already have a Configuration Settings document for the server(s) where the rules will
apply.
If you are creating a new Configuration Settings document, complete the Group or Server name field
on the Basics tab, and then click Save & Close. Then reopen the document to begin adding rules.
If you attempt to add a new rule before saving a new document, you are prompted to save the
configuration before proceeding.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer,
and click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - Rules tab.
6. Click New Rule.
7. In the Specify Conditions section of the New Rule dialog box, set the criteria the server uses to
determine whether to apply a rule to a given message. A rule condition can include the following
components:

734 Lotus Domino Administrator 7 Help

Condition component Description
Message item to examine Specifies the Notes message item that the SMTP listener, the router, or the client
examines when evaluating whether to apply a rule. Choose one of the following:
Sender, Subject, Body, Importance, Delivery priority, To, CC, BCC, To or CC, Body or
subject, Internet domain, Size (in bytes), All documents, Attachment name, Number of
attachments, Form, Recipient count, Any recipient, Blacklist tag, or Whitelist tag.
Note: To create a rule that acts on all messages deposited in MAIL.BOX, choose All
Documents
Logical operator or Specifies how the Router evaluates the content of the target field. Choose one of the
qualifier following:
v contains (for text field values)
v does not contain (for text field values)
v is
v is not
v is less than (for numeric field values)
v is greater than (for numeric field values)

For example, if you selected the message item Attachment Name, selecting the qualifier
″is″ defines a rule that acts on all messages having an attached file with a name that
exactly matches the name you specify.
Value to check in message Specifies the content to search for in the target message item.
item
For example, if the target message item is Attachment Name and the qualifier is
″contains,″ enter .VBS to create a rule that acts on all messages having an attached file
with a name containing the string .VBS, including, LOVE-LETTER.VBS,
CLICK-THIS.VBS.TXT, and MY.VBS.CARD.EXE.
Note: When defining a match against a user’s name, specify the canonical format, for
example, UserName/Sales/East
v Text fields do not support wildcard values, such as the asterisk character (*). To
specify a search string for a target field, use the ″contains″ operator and enter the
search string in the accompanying text field. For example, as in the preceding
example, to search for an attached file with a name that contains the string .VBS,
create the condition ″Attachment Name contains .VBS,″ not ″Attachment Name is
*.VBS.″
v Search string text is not case sensitive.
v When indicating numeric values, always enter a numeral, rather than its text
equivalent (that is, enter 2, not two).

8. Click Add.
9. (Optional) Modify the condition by doing the following:
v Add more conditions, by selecting Condition, selecting ″AND″ or ″OR,″ and repeat Steps 7 and 8
for each new condition.
v Add an exception by selecting Exception and repeating Steps 7 through 9 for each exception. You
can add only one exception to a condition statement.
10. In the Specify Actions section specify the action to perform when a message arrives that matches the
condition statement, and click Add Action. You can specify one action per rule.
The following actions are available:

Action name Description

Journal this message The Router sends a copy of the message to the configured Mail journaling
database and continues routing the message to its destination. Journaling must
be enabled on the Router/SMTP - Advanced - Journaling tab.

Chapter 30. Customizing the Domino Mail System 735

Action name
Move to database
Don’t accept message
Don’t deliver message
Change routing state
Description
The Router removes the message from MAIL.BOX and quarantines it in the
database specified in the accompanying text field, for example,
GRAVEYARD.NSF. The specified database must already exist. The message is
not routed to its destination. Placing messages in a quarantine database lets
you examine them more closely for viruses or other suspicious content.
Domino rejects the message, but the Router does not generate a delivery
failure report. Depending on the message source, the sender may or may not
receive an NDR or other indication that the message was not sent.
v When Domino does not accept an incoming SMTP message it returns an
SMTP ″permanent error″ code to the sending server, indicating that the
message was rejected for policy reasons. SMTP permanent errors (500-series
errors) indicate error types that will recur if the sender attempts to send to
the same address again. Depending on the configuration of the sending
client and server, the message originator may then receive a Delivery Failure
report.
v For messages received over Notes routing, Domino returns a Delivery
Failure Report indicating that the message violated a mail rule.
v For messages deposited by a Notes client, the sending client displays an
error indicating that the message violated a mail rule.
Domino accepts the message, but rather than sending it to its destination, it
processes the message according to one of the following specified options:
v Silently delete - Domino deletes the message from MAIL.BOX with no
indication to the sender or recipient.
v Send NDR - Domino generates a nondelivery report and returns it to the
sender. The MIME and Notes rich-text versions of messages sent from a
Notes client result in separate delivery failure reports.
Domino accepts the message but does not deliver it. Instead, it marks it as
held, changing the value of the RoutingState item on the message to HOLD.
This change to the routing state of the message causes the Router to retain the
message in MAIL.BOX indefinitely, pending administrative action.
Note: When you mark a message as held, other rules are not executed until
the ″held″ message is released.

Domino differentiates between messages held by a mail rule and messages

held as undeliverable.
Note: This action may not work properly on servers where third-party
products, such as certain types of anti-virus software, also manipulate the
RoutingState item.
Stop processing Domino stops processing any rules that apply to the message when the stop
processing action is encountered in a rule. Subsequent rules for that message
are not executed.

For information on enabling mail journaling, see the topic ″Mail journaling″ later in this chapter.
11. To save the rule and put it into effect immediately, click OK.
To save the rule but wait before putting it into effect, click the Off radio button at the top of the
dialog box, and then click OK.
12. (Optional) After you create several rules, you can rearrange them to indicate their relative priority.
The server executes each rule in turn, beginning with the rule at the top of the list. To change the
position of a rule, select it and click Move Up or Move Down. Place rules with security implications
higher in the list to ensure that the server processes them before other rules.
13. Click Save & Close.
14. The change takes affect the server task registers it or after the ″set rules″ command is received.

736 Lotus Domino Administrator 7 Help

How mail rules handle encrypted messages
If MAIL.BOX receives an encrypted message (Notes encrypted, S/MIME, PGP, and so forth), the server
mail rules process any rule conditions that are based on unencrypted information in the message
envelope, such as the sender, importance, and recipients, but do not process conditions based on the
encrypted portion of the message body. Most rule conditions are based on information in the message
envelope. The server does not log instances in which rules are unable to process a message.

Specifying the message formin a condition

You can specify which types of messages a rule acts on by specifying the message form type in the rule
condition. When evaluating the form type, the server checks the Notes message form used (the Form
item displayed in the Document properties); it does not use form information defined in MIME items in
the message. All messages deposited in MAIL.BOX are rendered as Notes documents, including inbound
Internet messages in native MIME format. By default, messages received over SMTP use the Memo form,
except for SMTP Nondelivery reports, which Domino renders using the NonDelivery Report form.
Common Notes form names include:
v Appointment
v Delivery Report
v Memo
v NonDelivery Report
v Notice
v Reply
v Return Receipt
v Trace Report

Customizing message transfer

To control the transfer of messages between servers in your Domino system, you can:
v Restrict routing of large messages
v Route messages by priority
v Generate delay notifications for low-priority mail
v Restrict sending to groups listed in the Domino Directory
v Set transfer limits -- for example, the number of transfer threads and the retry interval
v Set advanced transfer controls -- for example, change the logging level and specify when to ignore
message priority
v Customize the text of mail failure messages

Transfer settings apply to messages sent using either Notes routing or SMTP.

Restricting mail routing based on message size

You can set size limits on messages to prevent large messages from consuming network bandwidth.
There are two types of message size limits: a maximum message size and a low-priority size range.
Messages that exceed the maximum message size are returned to the sender as undeliverable. Messages
that are smaller than the maximum size, but that fall within the specified size range, are marked
low-priority and routed during off-peak hours (12 AM to 6 AM by default).

Domino uses the maximum message size you specify as the upper limit of the low-priority size range.
Before specifying a low-priority size range, you must set a maximum message size.

The size restrictions you set in the Configuration Settings document apply to every message the Router
handles, regardless of whether the message is inbound or outbound, routed over Notes routing or over
SMTP. To set a unique size limit on some part of your messaging traffic, you must set up distinct routing
paths for that traffic and then create separate Configuration Settings documents for servers on those
paths. For example, if you want to place a 500KB limit on inbound SMTP mail and a 1000KB size limit on

Chapter 30. Customizing the Domino Mail System 737

internal mail, create two Configuration Settings documents: one for the servers that receive mail from the
Internet that specifies a 500KB size limit and a second for your internal mail servers that specifies a
1000KB limit.

To set message size restrictions:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - Restrictions tab.
6. Complete these fields in the Router Restrictions section, and then click Save & Close:

Field Enter
Maximum message size The maximum message size in KB (thousands of bytes) the server accepts. The
Router rejects any messages that exceed this size for both transfer and delivery. The
default is 0 KB, which does not limit message size.
Send all messages as Choose one:
low-priority if message size is v Enabled
between
v Disabled (default)

If you choose Enabled, specify the lower limit of the size range in KB. By default the
lower limit is 50KB. The upper limit of the size range is defined in the field
Maximum message size. When enabled, messages with a size between the value
entered in this field and the value in the Maximum message size field are sent as
low-priority messages.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
v Total message size is equal to the sum of the message text and the size of all attachments.
v You can change the default hours for routing low-priority mail.
For more information, see the topic ″Setting transfer limits″ later in this chapter.
v You can customize the text of delivery failure messages.
For more information, see the topics ″Customizing the text of mail failure messages″ later in this
chapter and ″Routing mail by priority″ earlier in this chapter.
v On Domino SMTP servers you can use the ESMTP SIZE extension to prevent inbound transfer of
messages that exceed the specified maximum message size. You can also use the outbound ESMTP
SIZE extension to configure Domino to honor size restrictions on a target server when transferring
outbound SMTP mail.
For information on setting the inbound and outbound SIZE extensions, see the topics ″Supporting
inbound SMTP extensions″ and ″Supporting outbound SMTP extensions″ later in this chapter.

Routing mail by priority

Notes users can click the Delivery Options button to specify a priority level -- high, normal, or low -- for
each message they create. The priority level determines how quickly the Domino Router transfers a
message over either Notes or SMTP routing. If you do not specify a priority for a message, the server
treats it as normal priority by default.

Priority level Default Notes routing

High The server routes the mail immediately.

738 Lotus Domino Administrator 7 Help

Priority level Default Notes routing
Normal The server routes the mail at the next scheduled connection time, based on the schedule in
the Connection document to the server that is the next hop for the message. Within the
same Notes named network, normal priority messages route immediately.
Low By default, the server routes low-priority mail only between midnight and 6 AM. Even if
low-priority mail is pending delivery when the server routes other mail, the server does
not route the low-priority mail except during the specified time interval. You can change
the default time for routing low-priority mail.

For information on changing the default time for routing low-priority mail, and setting the Router to
ignore message priority, see the topics ″Setting transfer limits″ and ″Setting advanced transfer and
delivery controls″ later in this chapter.

The Router typically processes delayed messages within 5 minutes of the start of the low-priority time
range.

Forcing low-priority mail to route: By default, the Router delays low-priority mail until the low-priority
time range, even for servers in the same Notes Named Network. If you do not want to delay low-priority
mail you can:
v Set Domino to ignore message priority.
For information on configuring Domino to ignore message priority, see the topic ″Setting advanced
transfer and delivery controls″ later in this chapter.
v Change the low-priority time range in the Configuration Settings document.
For information on changing the low-priority time range, see the topic ″Setting transfer limits″ later in
this chapter.
v Use the ″ROUTE servername″ command at the console to force all mail in the transfer queue of the
specified server to route immediately.
For information on using the ROUTE command, see the appendix ″Server Commands.″

Generating delay notifications for deferred low-priority mail

When Domino routes all low-priority mail within the specified low-priority time range, the affected
messages may remain in MAIL.BOX for a significant amount of time. The delay may be acceptable to
users who sent their messages as low priority, but users may be less forgiving if their messages were
relegated to late-night routing after the Router automatically demoted their priority -- as happens when
you set Domino to change the routing priority of messages above a certain size. Unexpected routing
delays are likely to cause concern and result in calls to the help desk.

You can configure the Router to notify senders when low-priority mail is delayed. Of course, you should
also educate users about your policy on routing low-priority mail. When delay notifications are enabled,
the Router delivers a message to the sender of the delayed message that explains that the message is
being held until the specified routing time.

When a message is delayed, users receive an informational Delay report, which identifies the number and
addresses of the intended recipients and indicates that transfer is delayed until the low-priority time
range. The notification includes the headers of the original message, but not the message body, and
explains that no additional user action is required to deliver the message. You can also customize the text
of the notification to include additional information.

For information on customizing the text of a delay notification, see the topic ″Customizing the text of
mail failure messages″ later in this chapter.

Chapter 30. Customizing the Domino Mail System 739

You can have the Router deliver delay notifications for every low-priority message held; for messages
held because the sender designated them as low-priority; or for messages held because Domino changed
the priority for policy reasons -- as, for example, when a size restriction forces a change to the routing
priority of a large message.

For information on configuring Domino to send delay notifications when it holds low-priority messages,
see the topic ″Setting transfer limits″ earlier in this chapter. For information on setting size limits on
messages, see the topic ″Restricting mail routing based on message size″ earlier in this chapter.

Normally, a server sends only one delay notification for each message. However, restarting a server or
Router can result in duplicate delay notifications. Also, a user may receive multiple delay reports for a
message that is delayed by servers at successive hops along the routing path. Servers at successive hops
can each send a delay report if delay notifications are enabled and they each receive the message before
their configured low-priority routing time and buffer time.

For example if a first hop server has a low-priority range of 12:00 AM to 3:00 AM and receives a
low-priority message at 11:30 PM, it generates a delay notification. At the start of the low-priority routing
time, the server routes the message to the next hop server. If this server also defers low-priority mail and
has a low-priority range of 4:00 AM to 6:00 AM, it generates an additional delay notification.

By default, the Router does not send delay notifications for low-priority messages that a user sends
within the low-priority time range or a buffer time of 30 minutes before the start of the time range. You
can alter the default behavior by adding the variable RouterLPDelayNotifyBufferTime to the NOTES.INI
file and setting its value to the length of the desired buffer time, in minutes. For example, if you would
like to prevent low-priority messages sent within an hour of the start of the time range from generating a
delay notification, enter the following line in the NOTES.INI file:
RouterLPDelayNotifyBufferTime=60

Exceptions to sending delay notifications: The Router does not send delay notifications in the following
cases:
v If you enabled the following setting in the Configuration Settings document: Router/SMTP -
Restrictions and Controls - Advanced - Controls- Advanced transfer controls - Ignore message priority.
v When inbound SMTP messages include a Delivery Status Notification (DSN) request that is set to
NOTIFY=NEVER. Only DSN requests with the value NOTIFY=DELAY result in delay notifications.
v If the delayed message is a delivery failure report. For example, if a message is demoted to low
priority and delayed because its size exceeds the threshold for normal priority mail, the resulting delay
notification (which includes the original message) is not delayed.
v If a Notes client user sets the Delivery Reports option to None in the Delivery Options dialog box.

Restricting users from sending mail to groups listed in the Domino Directory
By default, all users can send mail to groups defined in the Domino Directory. To reduce unnecessary
mail traffic, you can edit the reader fields for a Group document to restrict access to the group, specifying
the users who are allowed to send mail to the group. Only users to whom you grant reader access can
send mail addressed to the group. Users who do not have reader access to the group will not be able see
the group name listed in the Domino Directory.

The restrictions apply to messages sent to either a group’s Notes address or its Internet address and to
messages originating from a Notes client as well as messages sent and received over SMTP (as from an
IMAP or Notes client). From a Notes client, a user who does not have permission to use the group
receives an error when attempting to send mail to the restricted group. If the same user attempts to mail
from a POP3 or IMAP client, the Router generates a Nondelivery report indicating that the sender is not
authorized to send mail to the specified recipient.

To restrict users from sending mail to a group:

740 Lotus Domino Administrator 7 Help

1. From the Domino Administrator, click the People & Groups tab, expand the Domino Directory that
contains the group you want to restrict access to, and select the Groups view.
2. Right-click the Group document to manage and choose Document Properties.
3. Select the Security tab (the Key).
4. Deselect the All readers and above checkbox to enable editing of the readers list.
5. To enable a user to send mail to the group, select the user’s name in the list.
6. To provide access to users not listed, click the Person icon to the right, add the name in the Select
Names dialog box, and click OK. The user’s name appears at the bottom of the list with a check next
to it.
7. Deselect the names of users you want to prevent from sending mail to the group, including the
Anonymous entry.
8. Close the Document Properties dialog box.

Setting transfer limits

Transfer controls affect how Domino transfers messages between servers. They control the number of
threads used, the number of hops allowed before a message fails, the low-priority mail routing time
range, and the time-out and purge intervals. Transfer controls apply to both SMTP and Notes routing.

To set message transfer controls:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - Transfer Controls tab.
6. Complete these fields in the Transfer Controls section, and then click Save & Close:

Field Enter
Maximum transfer threads The maximum number of server threads Domino creates to transfer messages
to all other servers. The value applies to both Notes routing and SMTP. The
Router sets a default maximum number of transfer threads based on server
memory. Letting the Router select the maximum number is usually best. If
you set the maximum number manually, set the maximum to between 1 and
25 threads, depending on server load.
Maximum concurrent transfer The maximum number of server threads the Domino Router can use to
threads transfer messages to a single destination. The value applies to both Notes
routing and SMTP.

If no value is specified, the default value is equal to one-half of the maximum

Maximum hop count
transfer threads, rounded down to the nearest integer. For example, if the
maximum transfer threads is 5, the maximum concurrent transfer threads
defaults to 2. On servers that send outbound Internet mail to an SMTP relay
host, this setting effectively defines the total threads available for transferring
mail to the relay host.
Note: By default, when transferring messages over Notes routing from one
Domino domain to another, the Router does not use multiple concurrent
threads. To enable use of multiple concurrent transfer threads between
Domino domains, add the variable RouterAllowConcurrentXFERToALL to the
server’s NOTES.INI file.
The maximum number of times a message can be transferred between servers
before delivery fails and Domino sends a nondelivery message.

Chapter 30. Customizing the Domino Mail System 741

Field Enter
Low-priority mail routing time The time range when Domino routes messages marked as low-priority. The
range default is between 12 AM and 6 AM.

Low-priority delay notifications
Initial transfer retry interval
For low-priority mail to route at the specified time, the Router must be
configured to obey message priority. If you configure the Router to ignore
message priority, low-priority mail does not receive special handling.
If you configure the Router to hold low-priority messages until a given time
period, message originators may not be aware of the reason for the delay. To
inform senders when low-priority messages are delayed, have the Router
automatically generate delay notifications. The Router can either generate
delay notifications for every low-priority message it holds or when it holds
messages for a specific reason only. Choose one:
v Disabled - The Router does not notify senders when messages are delayed
for priority reasons.
v Only if priority changed for policy reasons - The Router notifies senders of
priority-related delays only for messages that were designated low-priority
as the result of a size restriction.
v Only if user requested low-priority - The Router notifies senders of
priority-related delays only for messages that the sender designated as
low-priority.
v All low-priority messages -- The Router notifies senders of priority-related
delays for all low-priority messages.
Note: Domino Release 5.0.x used the variable RouterLowPriorityDelayNotify
in the server’s NOTES.INI file to control the use of low-priority delay
notifications. If this setting is present, it takes precedence over the setting
specified in the Configuration Settings document.
The time (in minutes) that the Router waits after a message transfer failure
before retrying the transfer. If failure recurs, Domino doubles the interval
before a second retry. If additional retries are needed, they occur at three
times the initial retry value.

The default interval is 15 minutes. Lower values increase the retry attempts
per hour and could possibly increase the success rate of routing the messages.
Higher values decrease the retry attempts per hour, resulting in longer
routing times.

Expired message purge interval
The Router continues attempts to transfer a pending message until the age of
the message reaches the configured time-out value (by default, 24 hours).
After a message times out, the Router generates a delivery failure report to
the sender.
Specifies, in minutes, how often the Router checks MAIL.BOX for expired
messages to purge. The default is 15 minutes.

Values specified in the NOTES.INI file override settings in the Configuration Settings document. If
you use the NOTES.INI file to configure message transfer settings, the Domino server console
displays informational messages indicating that the setting can be specified in the Configuration
Settings document.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Enabling multiple concurrent transfer threads between Domino domains: In a Domino network,
message transfer over SMTP is always multithreaded, allowing multiple transfer threads to a single
destination. However, by default, Notes routing is multithreaded only for transfers within the local Notes

742 Lotus Domino Administrator 7 Help

Named Network (NNN). When using Notes routing to transfer mail outside the NNN, Domino does not
allow multiple concurrent transfer threads. You can add a setting in the NOTES.INI file to enable the use
of multiple concurrent transfer threads for inter-domain Notes routing.

To transfer a message, the Router assigns a transfer thread to a message in its transfer queue. When
Notes routing is used, the transfer thread moves the message across the network by copying it from the
queue and writing it to the MAIL.BOX database on the destination server by means of a Notes remote
procedure call. Each transfer thread processes a single message for a single destination only. If a message
has multiple recipients at that destination, the thread deposits a single message addressed to all of them.
To send additional messages or send the same message to additional destinations, the Router must
activate additional transfer threads.

When the transfer queue has many messages for a given destination, the messages may be able to be
transferred more efficiently if the server can create multiple transfer threads to that destination. However,
for multiple transfer threads to improve efficiency there must be ample bandwidth on the connection
between the servers. On a slow link, multiple active threads are forced to contend for bandwidth, with no
resulting increase in the total throughput, thus defeating the purpose of multiple threads. Furthermore, if
a high proportion of the total transfer threads are busy on a slow link, the server may be unable to
transfer messages to destinations over other, faster links because of a lack of available threads.

For Notes routing, connections that rely on Connection documents, including connections to remote
domain servers, are typically slower than local domain connections; so, by default, Domino does not
allow multiple concurrent transfer threads to destinations that require a Connection document. To ensure
that message transfer is not adversely affected, alter only the default behavior servers that have
high-bandwidth connections to other Domino domains.

To enable multiple concurrent transfer threads between Domino domains:

1. From the Domino Administrator, open the Domino Directory and click the Configuration tab.
2. To edit an existing Configuration Settings document, highlight and click Edit Configuration. To create
a new Configuration settings document, highlight the server for which the Configuration Settings
document will apply, then click Add Configuration.
3. Click the NOTES.INI Settings tab.
4. Click Set/Modify Parameters.
5. In the Item field, enter:
RouterAllowConcurrentXFERToALL
6. In the Value field, enter:
1
7. Click Add, and then click OK.
8. Click Save & Close.

Note: When this variable is set, the server does not attempt to determine the connection speed or
number of messages pending for a particular destination. The server allows multiple concurrent
transfer threads, regardless of whether the speed of a particular connection justifies the additional
threads. The number of transfer threads for each destination remains limited by the value you set for
the number of Maximum concurrent transfer threads.

Setting the message time-out value: When the Router is unable to transfer a message on the first
attempt, it continues to attempt delivery at intervals, as specified in the ″Initial transfer retry interval″
field of the Configuration Settings document. If a message cannot be delivered (or forwarded to the next
server on the path to the user’s mail server) within a specified time-out period, the Router returns a
delivery failure report to the sender. By default, the message time-out value is 24 hours.

Chapter 30. Customizing the Domino Mail System 743

In the event that mail files on certain servers become unreachable for an extended period, consider
increasing the default time-out value on other servers. A higher time-out value decreases the likelihood of
important mail being returned because of transfer and delivery failures.

On the Internet, the time-out value for message transfer is typically five days - that is, if the next hop
server is unreachable, the connecting server continues to retry transfer for five days before giving up and
generating a delivery failure report.

Increasing the time-out value to n days may result in senders receiving a delivery failure report for
undeliverable mail n days after the message was sent.

Because each successive retry consumes server resources, a high volume of undeliverable mail can place a
significant extra load on the server. If you notice an increase in the amount of pending mail in
MAIL.BOX, examine messages to determine the validity of their origins and destinations. If a large
portion of pending messages are addressed to nonexistent users or originate from known or possible
spam mailers, consider resetting the time-out interval to a lower value. Using a lower time-out value
reduces the time before the server marks a message as undeliverable, thereby decreasing the number of
retries.

For information about managing undeliverable mail, see the topic ″Managing undeliverable mail in
MAIL.BOX″ later in this chapter.

For information about methods for unwanted mail before servers accept it, see the topic ″Restricting
SMTP inbound routing″ later in this chapter.

For information about using mail rules to process mail automatically, see the topic ″Setting server mail
rules″ earlier in this chapter.

To set the message time-out value:

1. From the Domino Administrator, open the Domino Directory and click the Configuration tab.
2. To edit an existing Configuration Settings document, highlight and click Edit Configuration. To create
a new Configuration settings document, highlight the server for which the Configuration Settings
document will apply, then click Add Configuration.
3. Click the NOTES.INI Settings tab.
4. Click Set/Modify Parameters.
5. In the Item field, enter:
MailTimeout
6. In the Value field, enter the number of days after which Domino returns undeliverable mail to the
sender, click Add, and then click OK.

Note: To specify a time-out period shorter than one day, specify the variable MailTimeoutMinutes in
the Item field in Step 5, and specify a time-out period, in minutes, in Step 6.
7. Click Save & Close.

Setting advanced transfer and delivery controls

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Advanced - Controls tab.

744 Lotus Domino Administrator 7 Help

6. Complete these fields in the Advanced Transfer Controls section:

Field Enter
Ignore message priority Choose one:
v Enabled - The Router sends all messages as Normal priority.
v Disabled - (default) The Router honors message priority settings assigned by the
sender or another server process.
Note: Do not enable this setting if you restricted Domino to routing messages of a
specified size as low priority and want to confine routing of large messages to the
specified low priority routing time.
Dynamic cost reset The time, in minutes, after which the Router resets the costs for the various connections.
interval For example, if the cost reset interval is 15 minutes and a network failure caused the
Router to increase a connection cost from 1 to 2, the Router resets the connection cost to
1 after the 15-minute cost reset interval.

7. Complete these fields in the Additional Controls section, and then click Save & Close:

Field Enter
Restrict name lookups to Choose one:
primary directory only v Enabled - The router can only look up names and groups in the Domino Directory for
the server’s Domino domain. The router cannot look up names and groups in other
directories that are available through Directory Assistance or Directory Catalog.
v Disabled - (default) The router can look up names and groups in any directories
available from the server.
Cluster failover Choose one:
v Disabled - If a recipient’s server is unavailable, the Router does not automatically route
mail through a clustered server.
v Enabled for last hop only - (default) When the Router detects that a recipient’s mail
server (the last hop in the routing path) is unavailable, it attempts to locate a clustered
server and transfer the message to that server. For example, Server1 routes a message
addressed to Jane Doe, whose mail file is on Server3. Server1 fails to connect to
Server3, which is unavailable. Server1 checks the Domino Directory to see if there are
any servers clustered with Server3. Server2 is clustered with Server3, so the Router on
Server1 attempts to connect to Server2. If the connection is successful, the Router
transfers the message to Server2.
v Enabled for all transfers in this domain - When the Router detects that a server for any
hop in the routing path is unavailable, it attempts to locate a server clustered with that
hop server. If the Router can find another clustered server, it transfers the message to
that server. For example, if the Router on Server 1 attempts to transfer to HubA but
HubA is unavailable, the Router checks the Domino Directory to see if there are any
servers clustered with HubA. Because HubB is clustered with HubA, the Router
attempts to connect to HubB. If the connection is successful, the Router transfers the
message from Server1 to HubB, which continues routing the message.
Hold undeliverable mail v Enabled - When the Router cannot transfer or deliver a message, it leaves the message
in MAIL.BOX rather than generate a delivery failure report. Select this option if you
want to be able to examine messages with failures. You can then access these messages
and either release them, forward them, or delete them
v Disabled - (default) When the Router cannot deliver a message, it generates a delivery
failure report.
Note: If you configure MAIL.BOX to hold undeliverable messages, examine the database
frequently to check for accumulated messages.

For more information on directory assistance, see the chapter ″Setting Up Directory Assistance.″ For
more information on clusters, see Administering Domino Clusters.

Chapter 30. Customizing the Domino Mail System 745

 The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Managing undeliverable mail in MAIL.BOX: MAIL.BOX databases on the server may contain two
types of undeliverable messages: dead messages, designated by a stop sign icon; and held messages,
designated by a red exclamation point.

By default, when Domino cannot transfer or deliver a message -- for example, when the address is typed
incorrectly -- the Router returns a delivery failure report to the sender. If the Router can neither deliver
the message to its intended recipient (To, CC, or BCC) nor deliver the failure report to the sender -- for
example, when the recipient’s address is typed incorrectly and the sender’s mail server is unavailable --
the Router changes the routing state of a message to Dead.

A message that is marked Dead lists the originator of the message in the Recipients field and the address
to whom the originator first sent the message in the Intended Recipient field. You can correct addressing
errors in these fields to resend a delivery failure report to the originator or the original message to its
intended destination.

Undeliverable messages result when a server receives mail addressed to nonexistent local recipients.
Some undeliverable messages might be legitimate, as in the case where a recipient’s name is misspelled
or the intended recipient has left the organization. But a high volume of undeliverable messages may
represent what’s known as a ″dictionary attack″ in which a spam mailer attempts to harvest e-mail
addresses in a domain by guessing every possible user name in the domain. The attacker directs a bogus
mass-mailing to the target domain, using a list of names automatically generated by a script. The attacker
then uses delivery failure reports returned from the target domain to determine which names are valid.

Held messages: In some cases, rather than letting Domino generate delivery failure reports automatically,
you may want to examine messages before returning them. To trap undeliverable messages, you can
configure the Router to mark them as Held. For example, if you suspect that spam sites are using
delivery failure responses to test addresses in your organization, you can hold undeliverable mail to
eliminate this source of feedback.

When you configure the Router to hold undeliverable messages, each held message remains in
MAIL.BOX indefinitely and is processed only if an administrator releases the message.

Note: If you configure MAIL.BOX to hold undeliverable messages, examine the database frequently to
check for accumulated messages.

You can prevent servers from accepting mail addressed to nonexistent users by requiring Domino to
check whether a recipient has a Person document in the Domino Directory before it can accept a message.

For more information on configuring Domino to validate recipients before accepting messages, see the
topic ″Restricting users from receiving Internet mail″ later in this chapter.

The Router also changes the routing state of a message to Held when directed to do so by a mail rule.

By default, when you configure the Router to hold undeliverable mail, it does not mark messages as
Dead. Only if the Router cannot deliver a held message or its delivery failure report after you release it
for a final delivery attempt does the Router mark any message Dead.

For each held or dead message, the views in MAIL.BOX display information about when the server
received the message, as well as the sender and recipient, message size, and the reason why the message
failed. In addition, Dead messages display a Dead failure reason explaining why the message could not
be returned to the sender.

746 Lotus Domino Administrator 7 Help

You can use the following tools to manage undeliverable mail in MAIL.BOX:
v Check MAIL.BOX for undelivered mail
v Edit the recipient and subject items of held or dead messages
v Release held and dead messages from MAIL.BOX
v Delete messages from MAIL.BOX

To check MAIL.BOX for undelivered mail: Periodically examine MAIL.BOX for messages, especially if you
configure MAIL.BOX to hold undeliverable messages.
1. From the Domino Administrator, select the server on which you want to resolve undelivered mail.
2. Click the Messaging - Mail tab.
3. Select the MAIL.BOX database you want to examine by clicking Servername Mailbox (mail.box). On
servers with multiple mailboxes, a separate view is available for each mailbox.
4. Check Held and Dead messages. You can do one of three things with undeliverable messages:
v Correct the addresses of the message recipients
v Release the messages to their intended recipients
v Delete the messages

To edit and release held or dead messages: Edit messages in MAIL.BOX to specify the destination address for
resending the original message or resulting delivery failure report. You can also edit the Subject line to
insert additional information about the message, such as the reason it was held or the name of the
original recipient.
1. In the MAIL.BOX database, select the Held or Dead message for which you want to correct addresses
and click CTRL-E to edit the message.
2. Edit the address in the Recipients field or Intended Recipient field as follows:
To edit the address of a held message:
To correct the destination address to which the Router resends an original message, edit the Recipient
field. You can specify a Notes address or an Internet address.
When you release held messages, the Router ignores the entry in the Intended Recipient field.
To edit the address of a dead message:
To correct the destination address to which the Router resends the original message, edit the address
in the Intended Recipient field, and click Release - Resend dead message to originally intended
recipient. You can specify a Notes address or an Internet address. The Router ignores the entry in the
Recipients field. The received message displays the original recipient address.
To correct the destination address to which the Router resends the delivery failure report for a dead
message, change the address in the Recipients field, and click Release - Return Non Delivery Report
to sender. You can specify a Notes address or an Internet address.

To release held and dead messages from MAIL.BOX: Depending on what caused a message to be retained in
MAIL.BOX, you may be able to successfully resend it to its originally intended recipients or return a
delivery failure report to the sender. For example, if messages were marked held or dead as a result of a
temporary network failure, you may be able to release messages to their destinations after restoring
network connections. Or, if a message failed to reach its destination because of a misspelled address, you
can resend it by correcting the address and releasing the message.

When deciding what to do with dead messages, always examine them carefully before taking action.
Check the message origin and the list of intended recipients, and determine the failure reason. If the
From or Recipients fields of a dead message are blank or contain invalid addresses, or if the failure
reason indicates a null SMTP reverse path, consider deleting the message, rather than releasing it.
1. From the Domino Administrator, select the server on which you want to resolve undelivered mail.
2. Click the Messaging - Mail tab.

Chapter 30. Customizing the Domino Mail System 747

3. Click Servername Mailbox (mail.box) to select the MAIL.BOX database to examine. On servers with
multiple mailboxes, the view displays each of the available mailboxes (mail1.box, mail2.box, and so
forth).
4. Select the held or dead messages to release and click the Release button. Choose one of the following:

Release option Description

Resend all dead messages The Router attempts to resend each dead message in the current MAIL.BOX database
to originally intended to the originally intended recipient (To, CC, or BCC), listed in the Intended Recipient
recipients field. If the Router cannot deliver or transfer the message, it generates a delivery
failure report to the sender. If the NDR is also undeliverable, the Router again marks
the message Dead.
Note: This action applies to all messages in the current MAIL.BOX database only. On
servers with multiple MAIL.BOX databases, dead messages in other MAIL.BOX
databases are not released.
Resend selected dead The Router attempts to resend the selected dead message to the originally intended
messages to originally recipient (To, CC, or BCC) listed in the Intended Recipient field. If the Router cannot
intended recipients deliver or transfer the message, it generates a delivery failure report to the sender. If
the NDR is also undeliverable, the Router again marks the message Dead.
Return Non Delivery The Router attempts to resend the delivery failure report for the selected dead
Report to sender of all messages to the message originator specified in the Recipients field. If the failure
selected dead messages report is undeliverable, the Router again marks the message Dead.
Resend selected held The Router attempts to resend the selected held messages to the originally intended
messages recipient (To, CC, or BCC) listed in the Recipients field. The Router ignores the entry in
the Intended Recipient field.

If the Router cannot transfer or deliver a released message, it again marks the message
Held.
Resend selected held The Router attempts to resend the selected held messages to the originally intended
messages for a final time recipient (To, CC, or BCC) listed in the Recipients field. The Router ignores the entry in
the Intended Recipient field.

If the Router cannot deliver the messages to the recipients, it sends a nondelivery
failure report to the message originator and removes the message from MAIL.BOX. If
the delivery failure report cannot be sent, the Router marks the message Dead.

When you finish processing undeliverable messages, close the MAIL.BOX database.

To delete messages from MAIL.BOX: The Router automatically deletes sent messages from MAIL.BOX. If
you cannot resend a message or delivery failure report, or choose not to resend it, delete the message.
1. Select the Held or Dead to delete.
2. Click Delete Message. The messages are marked for deletion.
3. Press F9, and click Yes when prompted to delete the document.

Customizing the text of mail failure messages: You can customize the text of messages that Domino
sends when various mail failures occur. The text you specify is added to the default text for the message.
Customize messages to provide text in multiple languages or supply users with additional information
about how to respond to a failure. For example, add text that provides the phone number to call in case a
mail message does not reach your server.

You can enter customized text directly on the Configuration Settings document or create text files for
each customized message and then use the Configuration Settings document to specify the location of
each file.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.

748 Lotus Domino Administrator 7 Help

3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Advanced - Controls tab.
6. In the Failure Messages section, choose a method for specifying the customized text for failure
messages:

Method Description
Text file The Router adds customized text to failure messages from external files. For each
condition listed, enter the complete path to a text file that contains customized text you
want to add to the default failure message.
Text The Router adds customized text to failure messages from text entered in the
Configuration Settings document. For each condition listed, enter the customized text you
want to add to the default failure message.

7. Complete these fields, and then click Save & Close:

Field Enter
Transfer failure Transfer failures occur when there is a transient connection failure between the servers --
for example, a network problem.

If you specified Text in Step 6, enter text to add to the default transfer failure message;
otherwise specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\TRANSFER.TXT.
Delivery failure Delivery failures occur when the server is unable to deliver the message to the recipient’s
mail file -- for example, if the recipient’s mail file has moved and the Domino Directory
has not been properly updated.

If you specified Text in Step 6, enter text to add to the default delivery failure message;
otherwise specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\DELIVER.TXT.
Message expiration Message expiration failures occur when Domino cannot transfer the message to its
destination in a given period of time.

If you specified Text in Step 6, enter text to add to the default message expiration
notification; otherwise specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\EXPIRE.TXT.
Domain failure Domain failures occur when Domino cannot identify the destination domain for a
recipient of a message. For example, if you send a message to jdoe@lotus.com and
Domino cannot locate lotus.com in either the Domino Directory or the DNS, the server
generates a domain failure message.

If you specified Text in Step 6, enter text to add to the default message for domain
failures, or specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\DOMAIN.TXT.
Server failure Server failures occur when Domino cannot connect to the destination server. For
example, if you send a message to jdoe@lotus.com, and DNS instructs you to send mail
for the lotus.com domain to mail1.lotus.com but Domino cannot connect to
mail1.lotus.com, the sending Domino server generates a server failure message.

If you specified Text in Step 6, enter text to add to the default message for server failures;
otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\SERVER.TXT.

Chapter 30. Customizing the Domino Mail System 749

Field Enter
Username failure User name failures occur when Domino cannot match the local part of an address to a
recipient. For example, if you send a message to jdoe@lotus.com, but Domino cannot find
jdoe in the Domino Directory, the server generates a user name failure message.

If you specified Text in Step 6, enter text to add to the default message for user name
failures; otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\USER.TXT.
Size failure Size failures occur when Domino rejects a message because its size is greater than the
maximum message size (which you can specify in the ″Maximum message size″ field on
the Restrictions and Controls - Restrictions tab of the Server Configuration document)
and generates a size failure message.

If you specified Text in Step 6, enter text to add to the default message for size failures;
otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\SIZE.TXT.
Restriction failure Restriction failures occur when Domino rejects a message based on outbound Router
restrictions. For example, if you send a message to jdoe@lotus.com, but lotus.com is listed
in the ″Deny messages from the following Internet addresses to be sent to the Internet″
field on the Router/SMTP - Restrictions and Controls - SMTP Outbound Controls tab of
the Server Configuration document, Domino rejects the message and generates a
restriction failure message.

If you specified Text in Step 6, enter text to add to the default message for restriction
failures; otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\RESTRICT.TXT.
Delay notification Low-priority routing delays occur when MAIL.BOX receives a message that is marked
low priority and the Router waits to process the message until the specified low-priority
routing time (12:00 AM to 6:00 AM by default). If low-priority delay notifications are
enabled for the message, the Router sends a delay notification to the originator’s address.

If you specified Text in Step 6, enter text to add to the default low-priority delay
notification; otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\DELAY.TXT
Note: Domino Release 5.0.x specified this file using the MailTextFileForTransferDelays
setting in the server’s NOTES.INI file. If this setting is present, it takes precedence over
the setting specified here.
Quota warning The Router sends Quota warning notifications to users whose mail files exceed their
notification configured quota warning threshold.

If you specified Text in Step 6, enter text to add to the default quota warning notification;
otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\WARNING.TXT.
Quota error notification The Router sends Quota error notifications to users whose mail files exceed their
configured quota.

If you specified Text in Step 6, enter text to add to the default quota error notification;
otherwise, specify the path to a file containing the text -- for example,
C:\DOMINO\DATA\QUOTA.TXT.

For information on setting inbound mail restrictions see the topics ″Restricting mail routing based on
message size″ earlier in this chapter and ″Restricting who can send Internet mail to your users″ later
in this chapter.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

750 Lotus Domino Administrator 7 Help

Customizing Notes routing
To customize Notes routing in your organization, you can:
v Schedule routing for optimal efficiency
v Change the routing cost of connections between Domino servers
v Restrict mail routing based on Domino domains, organizations, and organizational units

Scheduling Notes routing

By default, when using Notes routing Domino can transfer messages only to other servers in the same
Notes Named Network (NNN). To extend Notes routing beyond a single NNN you must create
Connection documents in the Domino Directory and specify a routing schedule. Domino does not
automatically create Connection documents for mail routing.

Default schedule: By default, Connection documents instruct the Router to connect to the destination
server to transfer mail every six hours between 8:00 AM and 10:00 PM, or whenever the number of
pending messages in MAIL.BOX reaches 5. You can customize the schedule to specify the number of
pending messages that trigger routing, as well as the day, time range, and repeat interval for a
connection.

Using Connection documents to control routing within a Notes Named Network (NNN): You can use
Connection documents to restrict routing within a NNN to a specified schedule. Connection documents
apply to both Notes routing and SMTP routing. In the absence of any Connection documents, the Router
transfers all mail within a NNN immediately, except for low-priority messages. If the Router is
configured to use both SMTP and Notes routing, it queues messages pending in MAIL.BOX for each
protocol separately. Regardless of the schedule, high-priority messages continue to route immediately.

Forcing mail to route to a specific server: To force the server to immediately route all pending mail to
another server, use the Route command at the server console.

Routing schedules and low-priority messages: Routing schedules in Connection documents do not
apply to low-priority messages. Low-priority messages route only during the configured low-priority
mail interval, even among servers in the same Notes named network.

You can configure Domino to designate messages over a certain size as low-priority and send them when
the server is less busy.

For more information on changing the priority of large messages and scheduling the low-priority mail
interval, see the topics ″Restricting mail routing based on message size″ and ″Setting transfer limits″
earlier in this chapter.

To schedule Notes routing:

1. Make sure that you have already created the necessary Connection documents.
See the chapter ″Setting Up Server-to-Server Connections.″
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Connections.
4. Select the Connection document for the server connection you want to configure, and click Edit
Connection.
5. Click the Schedule tab.
6. Complete these fields in the Scheduled Connection section:

Field Enter
Schedule Choose one:
v Enabled to use this schedule to control connections between the specified servers.
v Disabled to cause the server to ignore the schedule.

Chapter 30. Customizing the Domino Mail System 751

Field Enter
Connect at times One or more time ranges and/or specific times when you want mail routing to occur
each day -- for example, 12:00 AM - 11:59 PM.
Repeat interval The number of minutes between routing attempts; the default is 360 minutes.
Days of week The days of the week when the server should use this schedule and route mail. The
default is to use this connection for each day of the week.

7. Click the Replication/Routing tab.

8. Complete these fields in the Routing section, and then click Save & Close:

Field Enter
Routing task Choose one or more:
v Mail Routing - (default) Enables Notes mail routing between the servers
v X400 Mail Routing - Enables routing of X.400 mail between servers in a system with an
X.400 Message Transfer Agent
v SMTP Mail Routing - Enables routing of Internet mail to a server that can connect to
the Internet
v ccMail Routing - Enables routing of cc:Mail mail between servers in a system with a
cc:Mail Message Transfer Agent
v None - The Connection document is not used to route mail between the servers
Route at once The number of normal-priority messages that accumulate before the server routes mail.
The default is 5.
Routing cost The relative cost of this server connection. Do not modify this cost unless you are an
experienced Domino administrator.
Router type How Domino routes mail between the servers.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″
For more information on Router types, see the chapter ″Setting Up Mail Routing.″

Example: Scheduling immediate 24 x 7 routing: To route mail immediately 24 hours a day, 7 days a
week, create a routing schedule for a 24-hour, 7-day period. Then set routing to begin as soon as
MAIL.BOX contains a single pending message.
1. Complete these fields in the Scheduled Connection section of the Connection document:

Field Enter
Schedule Enabled
Call at times 12:00 AM - 12:00 PM
Repeat interval Blank
Days of week Select Sun, Mon, Tue, Wed, Thu, Fri, Sat

2. Complete this field in the Routing section of the Replication/Routing tab.

Field Enter
Route at once if 1 message pending

3. Update the routing configuration to ensure that the new schedule takes effect.

752 Lotus Domino Administrator 7 Help

Changing the routing cost for a connection
Notes routing assigns a routing cost to each connection and uses these costs to select the most efficient
way to route mail from one server to another. The Router computes and stores information about these
costs in its routing tables. If there is more than one possible route for mail to travel between the source
server and the destination server for the message, the Router uses routing cost information in the tables
to calculate the least-cost route for the message.

The Router uses information in Server, Domain, and Connection documents to create the routing tables. A
LAN connection has low cost; a dialup modem connection has high cost. By default, each LAN
connection has a cost of 1, while each dialup modem connection has a cost of 5.

If server connections are disrupted or a network fails, the Router selects an alternate path and increases
the cost for the path that failed.

How the Router chooses a route:

1. It calculates and selects the least-cost route.
2. If the least-cost route fails -- for example, if there is no answer or if the network times out -- the
Router increases the cost of the initial route by 1. For example, if a LAN connection between Server A
and Server B initially has a cost of 1 but the connection fails during an attempted transfer, the Router
increases the cost of that LAN connection between Server A and Server B to 2.
3. The next time the Router tries to transfer mail between servers, it again looks for the least-cost route
between those servers. If there is an alternate route that is equal in cost and requires fewer hops, the
Router selects that alternate route. For example, if there are two paths between Server A and Server B,
each with a total cost of 4, the Router examines the number of hops in each path. If one route requires
three hops but the other requires only two hops, the Router uses the path that requires two hops
because the costs are equal.

The Router resets the cost for a connection when:

v The server receives an inbound connection from the failed server
v The dynamic cost interval occurs
v You stop and restart the Router

The routing tables reside in memory and are dynamic. When you restart the server or modify a
Connection, Server, Configuration Settings, or Domain document, the Router rebuilds the routing tables.

To override the default routing cost: You can override the default setting for the routing cost for a
connection. You can change this setting only for connections between servers in different Notes named
networks. Change the default routing cost for a connection only if you are an experienced Domino
administrator. Improperly changing routing costs can create routing loops and disable the Router’s
selection of an alternate route.
1. Make sure that you have already created the necessary Connection documents.
For more information on Connection documents, see the chapter ″Setting Up Server-to-Server
Connections.″
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Connections.
4. Select the Connection document for the server connection you want to configure, and click Edit
Connection.
5. Click the Replication/Routing tab.

Chapter 30. Customizing the Domino Mail System 753

6. Complete this field, and then click Save & Close:

Field Enter
Routing cost A number from 1 to 10. The default is 1. The Router chooses connections with lower cost
first; for example, the Router chooses a connection with a cost of 2 over a connection
with a cost of 3.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Restricting mail routing based on Domino domains, organizations, and

organizational units
You can use two methods to restrict how mail routes over Notes routing in your infrastructure.
v Create Adjacent domain documents in the Domino Directory to keep users from routing mail through
your domain to another domain. For example, if you have a connection from your domain, Acme, to
the Lotus domain and the IBM domain, you might set up an Adjacent domain document to keep users
in the Lotus domain from routing to the IBM domain through the Acme domain. Using these
restrictions reduces the mail load on your system. Adjacent domain documents keep users from using
your domain as a Notes mail relay.
For more information on Adjacent domain documents, see the chapter ″Setting Up Mail Routing.″
v Specify restrictions in the Configuration Settings document in the Domino Directory to restrict mail
from specified Domino domains.

Note: SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or
modify the SMTP and Router settings in the Configuration Settings document, be sure to enter group
names that have a group type of Mail-only or Multi-purpose. This applies to settings on the Restrictions
tab, the SMTP Inbound Controls tab, and the SMTP Outbound Controls tab.

To restrict Notes mail routing:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration document for the mail server or servers you want to administer, and click
Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - Restrictions tab.
6. Complete these fields in the Router Restrictions section, and then click Save & Close:

Field Enter
Allow mail only from Domino domains from which the server accepts mail. If you enter Domino domains in
domains this field, only messages from those domains can enter your domain over Notes routing.
Domino denies mail from all other Domino domains. For example, if you enter Lotus in
the field, Domino accepts only messages sent from the Lotus domain to your users.
Domino denies messages sent from all other Domino domains.

You can specify individual domain names or a group name. Group entries cannot contain
a domain part or dot (’.’). For example, the group with the name AllowMail is valid, but
the groups named Allow.iris.com or Allowmail@iris are not.
Note: This restriction does not affect mail in the local Domino domain.

754 Lotus Domino Administrator 7 Help

Field Enter
Deny mail from domains Domino domains from which the server denies mail. If you enter Domino domains in
this field, all messages except those from the domains listed in this field can route to
your users. For example, if you enter Lotus in the field, Domino accepts messages from
all Domino domains except the Lotus domain. Domino denies messages from the Lotus
domain.

You can specify individual domain names or a group name. Group entries cannot contain
a domain part or dot (’.’). For example, the group with the name DenyMail is valid, but
the groups named Deny.iris.com or Denymail@iris are not.
Note: This restriction does not affect mail in the local Domino domain.
Allow mail only from Organizations and/or organizational units from which the server accepts mail. If you
the following enter organizations and/or organizational units in this field, only messages from users in
organizations and those organizations and/or organizational units can enter your domain over Notes
organizational units routing. Domino denies mail from all other organizations and/or organizational units.
For example, if you enter */East/Lotus in the field, Domino accepts only messages from
the /East/Lotus organizational unit to your users. Domino denies messages from
organizations and/or organizational units other than */East/Lotus.

You can specify individual ogranization names, organizational unit names or a group
name.
Deny mail only from the Organizations and/or organizational units from which the server does not accept mail. If
following organizations you enter organizations or organizational units in this field, all messages except those
and organizational units from users in the organizations and/or organizational units in this field can enter your
domain over Notes routing. Domino denies mail only from organizations and/or
organizational units in this field. For example, if you enter */West/Lotus in the field,
Domino accepts messages from all organizations and organizational units except
/West/Lotus. Domino denies messages from the /West/Lotus organizational unit.

You can specify individual ogranization names, organizational unit names or a group
name.

Note: If you specify the same entry in an Allow field and a Deny field so there is a conflict between
the two fields, Domino denies messages for that entry. The Deny setting takes precedence for security
reasons. Avoid placing the same entry in both the Allow and Deny fields for the same setting.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Customizing SMTP Routing

If you enabled SMTP routing, you can customize it by:
v Stopping and starting the SMTP service
v Changing the inbound and outbound SMTP port settings
v Restricting inbound SMTP routing
v Restricting outbound SMTP routing
v Specifying inbound and outbound MIME settings

Stopping and starting the Domino SMTP service

The Domino SMTP service, or SMTP Server task, runs the SMTP listener, which checks for incoming
SMTP connections and messages. SMTP messages can originate from any Internet host or another
Domino Server in your domain. For Domino to receive inbound SMTP mail, the SMTP listener must be
running on the server.

Chapter 30. Customizing the Domino Mail System 755

The SMTP service does not control SMTP routing. SMTP routing is handled by the server’s Router task.

If the SMTP listener task is enabled on the Basics tab of the Server document, the SMTP service starts
automatically when you start the server. You can stop and start the SMTP service manually from the
Domino Administrator client or the server console. The following table shows how to restart, stop, and
start the SMTP service using both methods.

Task From the Domino Administrator From the server console

Restart the SMTP 1. Click the Server - Status tab and select the Server Tasks view. Enter:
service Restart Task SMTP
2. Select SMTP Server from the list of tasks.
3. Click Tools - Task - Restart, and then click Yes.
Stop the SMTP 1. Click the Server - Status tab and select the Server Tasks view. Enter:
service Tell SMTP quit
2. Select SMTP Server from the list of tasks.
3. Click Tools - Task - Stop, and then click Yes
Start the SMTP 1. Click the Server - Status tab and select the Server Tasks view. Enter:
service Load SMTP
2. Click Tools - Task - Start.
3. From the list of server tasks, select SMTP Server.
4. Click Start Task.
5. Click Done to close the Start New Task dialog box.

Note: The SMTP Server task is represented in the server task list by three related subtasks. The status of
all three tasks changes when you change the status of any one of them.

As an alternative to restarting the SMTP service to incorporate configuration updates, you can use a
console command to refresh SMTP service parameters.

For information on using a console command to refresh the SMTP configuration, see the chapter ″Setting
Up Mail Routing.″

Changing SMTP port settings

You can modify inbound and outbound SMTP port settings.
v Inbound SMTP port settings determine how the Domino SMTP listener receives SMTP connections
from other servers. For inbound connections, you can specify the port numbers, port status, and
authentication methods required for both TCP/IP and SSL ports.
For more information, refer to the topic ″Changing the inbound SMTP port settings″ later in this
chapter.
v Outbound SMTP settings determine how Domino makes SMTP connections to other servers. For
outbound connections, you can change the default port numbers and status of the TCP/IP and SSL
ports.
For more information, refer to the topic ″Changing the outbound SMTP port settings″ later in this
chapter.

Configuring SMTP authentication options on servers that use Internet Site documents: On servers
that use Internet Site documents, the SMTP service obtains inbound port authentication settings from the
Security tab of the SMTP Site document, rather than from the Server document. As a result, when
Internet Site documents are used, the TCP/IP and SSL port authentication settings described in the
procedures that follow are not available in the Server document. Settings in the Server document
continue to provide the inbound SMTP port number and status and determine whether the Domino
server allows incoming connections from the authenticated user.

756 Lotus Domino Administrator 7 Help

To determine whether the use of Internet Site documents is enabled for a server, check the value of the
following field on the Basics tab of the Server document: ″Load Internet configurations from
Server\Internet Sites documents.″ If this field is set to ″Enabled,″ the server uses Internet Site documents
to configure all of its Internet protocols (SMTP, POP3, IMAP, and so forth).

If the server uses Internet Site documents, and an Inbound SMTP Site document is not present in the
Domino Directory, or the authentication options in a configured Inbound SMTP Site document are set to
No, the SMTP service rejects incoming connections. In each case, connecting hosts receive the following
error when attempting to authenticate with the SMTP service:
This site is not enabled on the server.

For information on creating and using Internet Site documents, see the chapter ″Installing and Setting Up
Domino Servers.″

Ensuring that SMTP clients can connect to a nonstandard port: Because remote SMTP clients attempt
to connect to port 25 by default, if you specify a different port number, be sure to configure connecting
clients to use the new port, otherwise inbound SMTP connections will fail. This can cause routing
problems, especially if the server with the nonstandard SMTP port acts as a relay host for outbound
Internet mail.

To configure your other Domino servers to transfer outbound SMTP mail to a nonstandard SMTP port,
change the Outbound SMTP setting on the Port - Internet Ports - Mail tab of the Server document.

For example, if a server must initiate an SMTP session with a receiving server on which the SMTP task is
listening on port 26, set the SMTP Outbound port to 26 on the Server document of the initiating server.

Configuring SMTP port security: To prevent unauthorized access to the SMTP Listener and to protect
SMTP sessions from eavesdropping, you can require users and servers to provide name and password
credentials to authenticate with the server, and you can enable the use of SSL to encrypt both inbound
and outbound SMTP sessions.

On servers that support SSL, you can encrypt SMTP mail sessions by having the server send and receive
mail over the SSL port (port 465 by default). Domino also supports negotiated SSL for both inbound and
outbound sessions, which allows for encryption over the TCP/IP port between servers that support the
STARTTLS command.

For information on the STARTTLS command, see the topic ″Securing SMTP sessions using the STARTTLS
command″ later in this chapter.

You can restrict access to the SMTP listener so that only users who are allowed to access the server can
connect to the server’s inbound SMTP port. For more information on securing the SMTP port, refer to the
topic ″Changing the inbound SMTP port settings″ later in this chapter. For more information on
restricting server access, see the chapter ″Controlling Access to Domino Servers.″

Changing the inbound SMTP port settings: Inbound port settings affect how other SMTP hosts connect
to Domino. For inbound connections, you can specify TCP/IP port settings and SSL port settings. For
both ports you can define port numbers, port status, and the supported authentication methods.

Configuring SMTP authentication options on servers that use Internet Site documents: On servers that use
Internet Site documents, the SMTP service obtains port authentication settings from the Security tab of
the SMTP Inbound Site document, rather than from the Server document. As a result, when Internet Site
documents are used, you cannot use the Server document to configure TCP/IP and SSL authentication
settings for the SMTP port. Settings in the Server document still provide the port numbers and status for
the SMTP TCP/IP and SSL ports, and enable the SMTP ports to honor server access restrictions.

Chapter 30. Customizing the Domino Mail System 757

To determine whether the use of Internet Site documents is enabled for a server, check the value of the
following field on the Basics tab of the Server document: ″Load Internet configurations from
Server\Internet Sites documents.″ If this field is set to ″Enabled,″ the server uses Internet Site documents
to configure all of its Internet protocols (SMTP, IMAP, POP3, and so forth).

If the server uses Internet Site documents, then you must use Site documents to configure all Internet
protocols on the server. If an SMTP Site document is not present in the Domino Directory, or the
authentication options in a configured SMTP Site document are set to No, users cannot connect to the
SMTP service. In each case, SMTP clients receive the following error when attempting to connect to the
SMTP service:
This site is not enabled on the server.

For information on creating and using Internet Site documents, see the chapter ″Installing and Setting Up
Domino Servers.″

Changing the default port number: By default, after you enable the SMTP task, it ″listens″ for client
connections on TCP/IP port 25 on the Domino server. The default SMTP SSL port is port 465. In some
cases -- for example, on partitioned servers -- you might need to specify a port number other than the
default to avoid conflicts. You might also change the default port to a nonstandard port number to ″hide″
it from clients attempting to connect to the default port or if another application uses the default port on
the server.

Disabling the SMTP inbound TCP/IP port or SSL port prevents other servers from accessing the SMTP
Listener on that port.

Note: On servers with multiple TCP/IP ports, by default, the SMTP service uses the port listed first in
the NOTES.INI file as the preferred path. You can configure the service to use a different port.

For information on configuring the SMTP service on a server with multiple TCP/IP ports to use a specific
TCP/IP port, see the chapter ″Setting Up the Domino Network.″

Changing the default SMTP greeting: You can modify the default reply that the SMTP service sends in
response to a connecting host. By default, the Domino SMTP server reveals its host name and software
version to connecting clients. For security reasons, you can change the default greeting so that the server
does not disclose essential information. Use the variable SMTPGreeting in the NOTES.INI file to
customize the SMTP service greeting.

To change inbound SMTP TCP/IP port settings:

1. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the SMTP service.
2. Click the Ports - Internet Ports - Mail tab.
3. In the Mail (SMTP Inbound) column, complete these fields, and then click Save & Close:

Field Enter
TCP/IP port number Choose 25 (default) to use the industry standard port for SMTP connections over
TCP/IP. You can specify a different port, but 25 works in most situations. When
specifying a nonstandard port, make sure the port is not reserved for another service.
Port numbers can be any number from 1 to 65535.
TCP/IP port status Choose one:
v Enabled (default) - SMTP clients can connect to the Domino SMTP service using the
designated TCP/IP port. Depending on the authentication options you choose, users
may have to supply a user name and Internet password to connect.
v Disabled - SMTP clients cannot connect to the Domino SMTP service using the
TCP/IP port.

758 Lotus Domino Administrator 7 Help

Field Enter
Enforce server access Choose one:
settings v Yes - Access to the SMTP listener is controlled by the server access settings on the
Security tab of the Server document. Users and servers that are not allowed to access
the server cannot send mail to the SMTP port. For this option to be effective you
must enable authentication for the port.
v No - (default) The SMTP listener ignores the server access settings in the Server
document. Users and servers can send mail to the SMTP port, even if they are denied
other access to the server.
Authentication options: Choose one:
Name & password v Yes - Sets the ESMTP AUTH extension for the TCP/IP port. Domino advertises
AUTH=LOGIN to connecting SMTP clients. Clients must supply a user name and
Internet password to connect to the SMTP service over the TCP/IP port and transfer
mail. Remote SMTP servers that do not support the AUTH extension cannot connect
to the SMTP service over this port. When Name and password authentication is
enabled, you can specify whether authenticated POP3 and IMAP users sending mail
to the SMTP port are subject to anti-relay enforcement.
v No - (default) Domino does not support Name-and-password authentication over the
TCP/IP port. If you choose No, you must enable Anonymous connections to allow
SMTP connections to this port.
Note: On servers supporting negotiated SSL on the inbound TCP/IP port (STARTTLS),
the setting in the SSL Name & password field -- not the setting in the TCP/IP Name &
password field -- determines whether the server accepts SMTP AUTH commands for
SSL-over-TCP/IP sessions. For information about enabling support for STARTTLS, see
the topic ″Supporting inbound SMTP extensions″ later in this chapter.
Authentication options: If the TCP/IP port status is set to Enabled, choose one:
Anonymous v Yes - (default) The SMTP service allows clients and servers to connect to the TCP/IP
port anonymously to transfer mail. If both Name and password and Anonymous
authentication are enabled (set to Yes), the port allows connections from SMTP hosts
that supply a name and password as well as those that connect anonymously.
v No - The SMTP service does not allow anonymous connections over the TCP/IP port.
SMTP hosts can connect to the TCP/IP port only if Name & password authentication
for the port is set to Yes, and the connecting host must send the SMTP AUTH
command.

Note: If you enable the TCP port, at least one authentication option must be set to Yes to save the
document.

Note: To support inbound SMTP connections, the server must have at least one SMTP port enabled
and be running the SMTP task.
4. Restart the SMTP task to put the new settings into effect.
As an alternative to restarting the SMTP service to incorporate configuration updates, you can use a
console command to refresh SMTP service parameters.
For information on using a console command to refresh the SMTP configuration, see the chapter
″Setting Up Mail Routing.″
If you change the default SMTP port, inbound SMTP connections fail if the connecting host is not
configured to use the new port. See the topic ″Ensuring that SMTP clients can connect to a
nonstandard port″ earlier in this chapter for information about configuring Domino servers to connect
to nonstandard SMTP ports.

To change inbound SMTP SSL port settings:

1. Familiarize yourself with the Domino security model.
2. To secure SMTP sessions using SSL, set up SSL on the Domino server.

Chapter 30. Customizing the Domino Mail System 759

3. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the SMTP service.
4. Click the Ports - Internet Ports - Mail tab.
5. In the Mail (SMTP Inbound) column, complete these fields, and then click Save & Close:

Field Enter
SSL port number Choose 465 (default) to use the industry standard port for SMTP connections over SSL.
You can specify a different port, but 465 works in most situations. When specifying a
nonstandard port, make sure the port is not reserved for another service. Port numbers
can be any number from 1 to 65535.
SSL port status Choose one:
v Enabled - SMTP clients can connect to the Domino SMTP service using the designated
SSL port.
v Disabled (default) - SMTP clients cannot connect to the Domino SMTP service using
the designated SSL port.
Authentication options: Choose one:
Name & password v Yes - Enables the SSL port to support the SMTP AUTH command. POP3 and IMAP
clients, and remote SMTP servers that send AUTH, must supply a name and
password to connect to the SMTP service over the SSL port and transfer mail. To
allow remote SMTP servers that do not send the SMTP AUTH command to connect
to the SMTP service over this port, set Anonymous authentication to Yes.
v No - (default) Domino does not support name and password authentication for hosts
connecting to the SMTP service over the SSL port. If a connecting host sends AUTH,
Domino rejects the command and returns an error indicating that the command is not
implemented. If you choose No, you must set Anonymous authentication to Yes to
allow SMTP connections to this port.
Note: On servers supporting negotiated SSL on the inbound TCP/IP port (STARTTLS),
the setting in the SSL Name & password field -- not the setting in the TCP/IP Name &
password field -- determines whether the server accepts SMTP AUTH commands for
SSL-over-TCP/IP sessions.
Authentication options: If the ″SSL port status″ field is set to Enabled, choose one:
Anonymous v Yes - (default) The SMTP service allows clients and servers to connect to the SSL port
anonymously to transfer mail. If Anonymous is set to Yes and Name and password
authentication is also set to Yes, IMAP and POP3 clients are prompted to supply a
name and password when connecting to this port, but servers can connect
anonymously.
v No - The SMTP service does not allow anonymous connections over the SSL port.
IMAP and POP3 clients, and servers that send the SMTP AUTH command, may
connect to the SSL port if you set Name and password authentication for the port to
Yes.

6. Restart the SMTP task to put the new settings into effect.
As an alternative to restarting the SMTP service to incorporate configuration updates, you can use a
console command to refresh SMTP service parameters.
For information on using a console command to refresh the SMTP configuration, see the chapter
″Setting Up Mail Routing.″

If you change the default SSL port, inbound SMTP SSL connections fail unless the connecting host is
configured to use the new port.

For information about configuring Domino servers to connect to nonstandard SMTP ports, see the topic
″Ensuring that SMTP clients can connect to a nonstandard port″ earlier in this chapter.

760 Lotus Domino Administrator 7 Help

For information about enabling support for STARTTLS, see the topic ″Securing SMTP sessions using the
STARTTLS command″ later in this chapter.

Changing outbound SMTP port settings: Outbound SMTP port settings affect how Domino connects to
other SMTP servers. Change the default port numbers and the status of the TCP/IP and SSL ports to
match the settings on servers to which this server sends SMTP mail.

The outbound port settings apply to all outbound SMTP sessions. If you change an outbound port
number to a nonstandard value, the server cannot establish SMTP connections with servers that listen for
SMTP requests on the standard port. Similarly, if you set up the server to send SMTP over SSL only,
disabling the outbound SMTP TCP/IP port, the server cannot establish SMTP connections with a remote
server that accepts SMTP connections over the TCP/IP port only.

To change outbound SMTP port settings:

1. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the SMTP service.
2. Click the Ports - Internet Ports - Mail tab.
3. In the Mail (SMTP Outbound) column, complete these fields, and then click Save & Close:

Field Enter
TCP/IP port number The number of the TCP/IP port on the remote server to which Domino attempts to connect
when initiating an SMTP session. The default and industry standard port for SMTP
connections over TCP/IP is 25. Specify a nonstandard port only if this Domino server
makes all of its outbound SMTP connections over TCP/IP to a server that uses the
nonstandard port.
TCP/IP port status Choose one:
v Enabled - The Domino SMTP Router connects to the designated TCP/IP port number on
a remote server to initiate an SMTP session. If the SSL port status is also set to Enabled,
the Router attempts to use the SSL port first and uses the TCP/IP port only if it cannot
connect to the SSL port.
v Disabled (default) - The Domino SMTP Router cannot initiate an SMTP session using the
TCP/IP port on a remote server.
v Negotiated SSL - The Domino SMTP Router connects to the designated TCP/IP port on a
remote server to initiate an SMTP session. If the remote server advertises STARTTLS
during the EHLO greeting, Domino issues a STARTTLS command to request that the
remainder of the session be encrypted using SSL. If the remote server does not support
STARTTLS, an unencrypted TCP/IP session ensues.
SSL port number The number of the SSL port on the remote server to which Domino attempts to connect
when initiating an SMTP session. The default and industry standard port for SMTP
connections over SSL is 465. Specify a nonstandard port only if this Domino server makes
all of its outbound SMTP connections over SSL to a server that uses the nonstandard port.
SSL port status Choose one:
v Enabled - The Domino SMTP Router connects to the designated SSL port number on a
remote server to initiate an SMTP session. If the Router cannot connect to the SSL port
and the TCP/IP port is also enabled on both the Domino server and the remote server,
Domino makes a second attempt to connect, using the designated TCP/IP port.
v Disabled (default) - The Domino SMTP Router cannot initiate SMTP sessions over the
SSL port of a remote server.

Securing SMTP sessions using the STARTTLS extension: SMTP sessions conducted over a standard
TCP/IP channel are vulnerable to eavesdropping because the unencoded transmission can be easily
intercepted. To protect SMTP communications, servers can use transport-layer security (TLS), more
commonly known as SSL encryption, to provide privacy and authentication.

Chapter 30. Customizing the Domino Mail System 761

Some servers support SSL for SMTP communications by sending and receiving SMTP traffic through the
SSL port (port 465 by default) only. However, because this requires that both the sending and receiving
servers support SMTP over SSL, this solution isn’t always practical.

To provide SSL security for SMTP transfers over TCP/IP, Domino supports the use of negotiated SSL. In
a negotiated SSL scheme, the sending and receiving hosts each use the SMTP STARTTLS extension,
defined in RFC 2487, to signal their readiness to negotiate an SSL connection. The receiving server
displays the STARTTLS keyword in response to the sending server’s EHLO command. The sending
server issues the STARTTLS command to request the creation of a secure connection. After the initial TLS
handshake completes successfully, the two parties proceed to set up an SSL channel between them. Both
the sending and receiving server must possess SSL certificates.

For more information on obtaining server certificates, see the chapter ″Setting Up SSL on a Domino
Server.″

Supporting STARTTLS for outbound SMTP sessions: A Domino server configured to use negotiated SSL for
outbound mail connects to the receiving server’s SMTP TCP/IP port (port 25 by default). If the initial
SMTP response from the receiving server indicates that it supports the STARTTLS extension, Domino
issues the STARTTLS command to request the use of SSL to encrypt the rest of the session.

If the receiving server did not advertise support for STARTTLS in response to the Domino server’s EHLO
command, the sending Domino server continues with an unencrypted SMTP TCP/IP session.

To enable outbound STARTTLS support, set the SMTP outbound TCP/IP port status to: Negotiated SSL.

Supporting STARTTLS for inbound SMTP sessions: You can configure Domino to support the STARTTLS
command for inbound SMTP transactions. When a Domino SMTP server is set to use negotiated SSL for
inbound sessions, the server advertises support for STARTTLS in response to EHLO commands the
TCP/IP port receives from connecting hosts. A connecting host can then issue the STARTTLS command
to request an encrypted session.

If Domino is configured to require STARTTLS for SMTP sessions over TCP/IP and a connecting host
cannot meet this demand, no mail is sent over the connection.

To enable inbound STARTTLS support:

v Enable the SMTP listener task.
v Enable the SMTP inbound TCP/IP port.
v Enable the STARTTLS ESMTP extension. This causes Domino to advertise STARTTLS as one of its
supported extensions in the ESMTP EHLO greeting response.
v (Optional) Enable name-and-password authentication for the SSL port. Although SMTP sessions that
use negotiated SSL are conducted over the Domino TCP/IP port, Domino uses the authentication
options you set for the server’s SSL port to determine how to handle name-and-password arguments.

For information about enabling the ESMTP extension for inbound STARTTLS, see the topic ″Supporting
inbound SMTP extensions″ later in this chapter

Requiring name and password authentication for SMTP STARTTLS sessions: Enabling ESMTP support for
negotiated SSL allows a server to accept requests to use SSL over TCP/IP from remote servers that
connect anonymously. However, not all inbound connections are anonymous. A connecting SMTP server
may be configured to send Domino a name and password by means of the ESMTP AUTH command.

To support connections from SMTP clients that send a name and password during a negotiated SSL
session, set the value of the Name & password field for the SMTP inbound SSL port to Yes. You do not

762 Lotus Domino Administrator 7 Help

have to enable the SSL port. If the SSL port does not support name-and-password authentication, the
Domino SMTP server rejects the AUTH command from the remote server and returns an error indicating
that the command is not implemented.

Even though Domino receives the AUTH command over the TCP/IP port, Domino uses the SSL
name-and-password authentication settings to determine whether to accept the AUTH request because it
receives the command in the context of an SSL session. The Name & password authentication setting for
the TCP/IP port is ignored.

Restricting SMTP inbound routing

You can set up your Domino system to control, verify, and restrict inbound mail. Restricting inbound
mail routing prevents Domino from accepting unwanted commercial e-mail (UCE) sent to your users and
consequently reduces the load on your system. You can set these restrictions:
v Set anti-relay restrictions
v Enable DNS blacklist filters for SMTP connections
v Enable DNS whitelist filters for SMTP connections
v Enable private blacklist filters for SMTP connections
v Enable private whitelist filters for SMTP connections
v Verify and restrict inbound connections
v Verify and restrict who can send inbound Internet mail to your users
v Restrict who can receive Internet e-mail in your organization
v Set inbound SMTP extensions

In addition, on servers that receive some of their inbound mail over Notes routing, you can restrict
routing based on Domino domains, organizations, and organizational units

Error handling of messages rejected by SMTP inbound controls: The inbound SMTP restrictions are
enforced by the SMTP Listener before a message is accepted, rather than by the Router after a message is
already in the system. This difference in where restrictions are enforced affects how errors are handled
when a message is rejected. When a Router restriction results in a message being rejected, Domino
returns a failure message stating the reason for the failure to the sender. Domino-generated nondelivery
reports contain default text, which you can customize. For example, when you configure a maximum
message size for a server, Domino checks the size of the message only after it is received in MAIL.BOX. If
the message exceeds the configured size, the Router generates a failure message to the sender.

However, if you set an SMTP restriction that causes Domino to reject an inbound message, the SMTP
listener returns a permanent error during the SMTP transfer; the message never enters the server. In this
case, it is the responsibility of the originating SMTP server to generate a failure message to the sender.
For example, if both the receiving Domino SMTP server and the sending SMTP server support the
ESMTP SIZE extension, and the Domino server is configured to honor a maximum message size, when
the Domino SMTP listener receives a message that exceeds the defined limit, it rejects the message before
it is ever received and returns a permanent error to the sending server. You cannot use Domino
administrative tools to customize the server’s SMTP response.

Using Extension Manager to customize the server’s SMTP response: You can control the content of
SMTP responses using SMTP logical function hooks available in the Extension Manager services of the
IBM Lotus C API Toolkit for Notes/Domino 7. For additional information, and to download the toolkit,
see the web site at http://www.lotus.com/capi .

Restricting inbound SMTP connections: To prevent your mail system from accepting unwanted mail,
Domino provides a set of controls that let you restrict incoming SMTP connections. The Inbound
Connection controls let you specify:
v Whether Domino checks the names of connecting hosts in DNS
v By host name or IP address, the remote hosts from which the server allows and denies connections
Chapter 30. Customizing the Domino Mail System 763
To determine whether a connection attempt is allowed or denied, the Domino SMTP task first checks the
remote host’s IP address, which the server’s TCP/IP stack reads from the incoming IP packet headers. If
the IP address does not match any entry in the Inbound Connection control fields, the SMTP task
performs a second check, querying DNS to obtain the host name for the given address. If the query is
successful, Domino compares the name obtained against the host names in Allow and Deny fields.

If you create a separate Configuration Settings document for your internal SMTP servers, you can use the
inbound connection controls to ensure that these internal servers accept SMTP connections from specific
SMTP hosts only. For example, configure servers to allow SMTP connections only from servers that
receive mail from the Internet. Restricting connections in this way prevents users with POP3 or IMAP
clients from sending mail through the server, helps you define valid outbound routing paths, and limits
the load on the server.

Note: SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or
modify the SMTP and Router settings in the Configuration Settings document, be sure to enter group
names that have a group type of Mail-only or Multi-purpose. These groups must be in the primary
directory. This applies to settings on the Restrictions tab, the SMTP Inbound Controls tab, and the SMTP
Outbound Controls tab.

In addition to these inbound connection controls, Domino provides two other means for blocking
connections: DNS blacklist filters and access to the SMTP Listener through Domino Extension Manager
(EM) services. DNS blacklist filters enable a server to check a host against one or more blacklists during
the SMTP conversation. If a connecting host matches an entry in a blacklist, you can configure the server
to reject the connection, tag any received messages, or record the transaction in the Notes Log.

For more information on DNS blacklist filters, see the topic ″Enabling DNS blacklist filters for SMTP
connections″ later in this chapter.

Extension Manager (EM) services allow developers to access some functions of the SMTP Listener task.
The Extension Manager (EM) allows an executable program library, such as a dynamic link library or
shared object library, to register a callback routine that will be called before, after, or before and after
Domino performs selected internal operations. Using EM hooks in the SMTP Listener can extend current
functionality by providing:
v Additional anti-spam controls
v Custom address translation
v Custom SMTP responses
v Interception of messages

The Domino C API header file EXTMGR.H, included in the Software Development Kit, defines symbols
for the supported Extension Manager notification events and types. For additional information on the
Extension Manager and registering callback routines, see the Lotus C API Toolkit for Notes/Domino 7.
The toolkit is available at http://www.lotus.com/capi .

To restrict inbound SMTP connection:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to restrict mail on,
and click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab.

764 Lotus Domino Administrator 7 Help

6. Complete these fields in the Inbound Connection Controls section and then click Save & Close:

Field Enter
Verify connecting host Choose one:
name in DNS v Enabled - Domino verifies the name of the connecting host by performing a reverse
DNS lookup. Domino checks DNS for a PTR record that matches the IP address of the
connecting host to a host name. If Domino cannot determine the name of the remote
host because DNS is not available or no PTR record exists, it does not allow the host to
transfer mail. Although Domino accepts the initial connection, later in the SMTP
transaction it returns an error to the connecting host in response to the MAIL FROM
command.
Note: Internet SMTP hosts are not required to have PTR entries in DNS. As a result,
when this field is enabled, the SMTP task may reject connections from valid SMTP hosts.
v Disabled - (default) Domino does not check DNS to verify the name of the connecting
host.
Allow connections only The host names, group names, and/or IP addresses allowed to connect to the SMTP
from the following service on this server. If you enter host names and/or IP addresses in this field, only
SMTP Internet host servers matching these entries can connect to the SMTP listener; connection requests from
names/IP addresses all other servers are denied.

Enter IP addresses in brackets -- for example, [192.168.10.17].

Host name entries may be complete, as in the fully qualified host name of a particular
server, or partial and imply the existence of a wildcard. That is, if you enter:
abc.com

Domino extends accepts only connections from mail hosts in the domains represented by
*abc.com, that is, all host names ending in abc.com, including smtp.abc.com and
mailhost.abc.com. Domino rejects all other connection requests.

If you specify host name entries, each time a host connects, Domino checks DNS for a
PTR record for the connecting host. If Domino cannot resolve the IP address to a host
name because DNS is unavailable or no PTR record exists, no mail is accepted from the
connection.
Deny connections from The host names, group name, and/or IP addresses that are not allowed to connect to the
the following SMTP SMTP service on this server. If you enter host names and/or IP addresses in this field, all
Internet host names/IP servers except those matching entries in this field can connect to the SMTP listener;
addresses connection requests are denied only for servers matching the entries in this field.

Enter IP addresses in brackets -- for example, [192.168.10.17].

Host name entries may be complete, as in the fully qualified host name of a particular
server, or partial and use an implied wildcard. That is, if you enter:
abc.com

Domino implicitly extends the restriction to all mail hosts within the denied domain,
denying connections from *abc.com, that is, all hosts in the abc.com domain, including
smtp.abc.com and mailhost.abc.com.

The entry abc.com does not prevent connections from xyzabc.com.

Do not use a leading dot (.) in an entry; for example, .abc.com. Because Domino does not
match the leading dot, the entry .abc.com does not prevent connections originating from
the domain abc.com.

7. Reload the SMTP task or update the SMTP configuration to put changes into effect.

Note: Be careful not to specify the same entry in an Allow field and a Deny field because Domino will
deny messages for that entry. The Deny setting takes precedence for security reasons.

Chapter 30. Customizing the Domino Mail System 765

Restricting the total number of inbound SMTP sessions: By default, the SMTP service supports an unlimited
number of inbound sessions; that is, as many connections as the server’s resources physically permit. To
restrict the number of concurrent SMTP sessions that a server accepts, set the variable SMTPMaxSessions
in the server’s NOTES.INI file, where xxx is the maximum number of sessions allowed without any
buffering. When the specified number of inbound SMTP connections is reached, the server refuses
additional connections and returns the following error:
421 Server.domain.com SMTP service not available, closing transmission channel

How Domino uses reverse DNS lookups to control inbound SMTP sessions: Domino’s inbound relay
controls, DNS blacklist filters, and inbound connection controls allow or deny mail based on where
messages originate. For these controls to work, Domino must be able to identify the connecting host’s IP
address, host name, and Internet domain.

Domino obtains this information from two sources: the IP stack and the Domain Name Service (DNS).
When a host originates a connection to the Domino SMTP service, the connecting host passes its IP
address to the IP stack of the computer running the Domino server. The SMTP service reads the IP
address directly from this source.

For Domino to obtain host name and domain information, it must have access to the Domain Name
Service (DNS) and be able to locate a PTR record for the connecting host. A PTR record resolves an IP
address to a host name.

To request a PTR record, the Domino SMTP listener performs a reverse lookup to the DNS. From the host
name returned by this query, Domino parses out the domain name of the connecting host, comparing this
domain name to the list of local Internet domains in the Global domain document. Hosts from domains
listed in the Local primary Internet domain or Alternate Internet domain aliases fields of the Global
Domain document are considered to be part of the local Internet domain; all others are treated as external
hosts.

Preventing unauthorized SMTPhosts from using Domino as a relay: To protect SMTP servers from
unauthorized relaying, Domino provides inbound relay controls used to define the hosts to which and
from which a server can relay messages. The Domino SMTP listener denies requests to relay messages to
or from unauthorized hosts.

Setting and enforcing inbound relay controls: To prevent misuse of your system, configure Domino to
prevent open relaying, while allowing relays originating from and destined for known domains and
hosts. By default, a new Domino SMTP server prevents external hosts from relaying mail to any
destination. You can further customize Domino’s anti-relay controls to specify when relays are and are
not allowed.

The Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab of the Configuration Settings
document provides two sets of controls for managing relay access:
v Inbound relay controls
v Inbound relay enforcement

Use the Inbound relay controls to restrict relays by destination and origin. Use the relay enforcement
controls to selectively apply the relay restrictions based on the originator’s relation to the local Internet
domain, host name, or authentication status.

Open relays: An SMTP server that indiscriminately accepts mail from outside the local Internet domain
and attempts to dispatch it to another external destination is known variously as a spam relay,
third-party relay, or open relay host (open relay, for short). Leaving a mail server open to use by
anonymous third parties is generally considered irresponsible, largely because open relays are often the
target of Internet mass-mailers who use them to distribute unsolicited commercial e-mail (UCE),

766 Lotus Domino Administrator 7 Help

commonly referred to as electronic junkmail or spam. Spam vendors use open relays as waypoints
between themselves and their target recipients, allowing them to distribute vast quantities of mail
anonymously.

When someone reads a spam message that has been relayed through one of your SMTP servers, the
message appears to originate in your Internet domain. In other words, your organization seems to be
linked with the spam source.

Not only does relaying spam reflect badly on your organization, but there are other more serious and
costly implications. Relayed mail consumes network bandwidth and server resources, reducing your
system’s ability to handle legitimate mail. As mail backs up, administrators and help desk personnel are
faced with service interruptions and the task of sorting out the backlog of undeliverable messages.
Failure to restrict access to an open relay could result in the server being reported on Internet blacklists.
Because SMTP hosts in many organizations will not accept mail from blacklisted servers, if your
outbound mail server is blacklisted, your organization may be unable to transfer mail to other Internet
domains.

Setting inbound relay controls: To block relays to a specific domain or from a specific host, set restrictions
in the inbound relay controls on the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls
tab of the Configuration Settings document.

Use the inbound relay controls to define:

v The destination domains to which you allow and deny relays
v The originating hosts from which you allow and deny relays

In determining whether to allow a relay, Domino checks the original sender, not just the last hop domain.
This prevents people from routing from a denied source through an accepted one to your domain.

Note: SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or
modify the SMTP and Router settings in the Configuration Settings document, be sure to enter group
names that have a group type of Mail-only or Multi-purpose. These groups must be in the primary
directory. This applies to settings on the Restrictions tab, the SMTP Inbound Controls tab, and the SMTP
Outbound Controls tab.

To set inbound relay controls:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab.
6. Complete these fields in the Inbound Relay Controls section, and then click Save & Close:

Inbound Relay Controls

Field Enter

Chapter 30. Customizing the Domino Mail System 767

Inbound Relay Controls
Allow messages to be Internet domains to which Domino can relay messages. Domino relays messages to
sent only to the recipients in the specified domains only. Messages for recipients in other external Internet
following external domains are denied.
Internet domains
For example, if you enter abc.com and xyz.com in this field, Domino accepts only
messages to recipients with addresses that end in abc.com or xyz.com domains. Messages
for recipients in other domains are denied.

To name a domain explicitly, prefix an @ sign to the entry. For example, if you enter
@xyz.com the server relays messages only if the domain part of the address matches
xyz.com exactly, such as User@xyz.com. Messages to addresses in other domains that end
in xyz.com, such as User@uvwxyz.com or User@abc.xyz.com, are denied.

Prefix a percent sign (%) to specify the name of a Domino domain to which mail can be
sent; for example, enter %AcmeEast to specify that the server can send mail to the
Domino domain AcmeEast.

Group entries cannot contain a domain part or dot (’.’). For example, the group with the
name AllowMail is valid, but the groups named Allow.iris.com or Allowmail@iris are not.
Deny messages to be Internet domains to which Domino will not relay messages. An asterisk (*) in this field
sent to the following prevents Domino from relaying messages to any external Internet domain.
external Internet
domains Domino denies only messages destined for recipient addresses in the specified domains.
All other messages may relay.

For example, if you enter abc.com in the field, Domino relays messages to recipients in
all external Internet domains except abc.com. Domino denies messages for recipients in
the abc.com domain.

To name a domain explicitly, prefix an @ sign to the entry. For example, if you enter
@xyz.com, the server rejects messages addressed to users if the domain part of the
address matches xyz.com exactly, such as user@xyz.com, but allows messages to relay to
other domains that end in xyz.com, such as user@server.xyz.com.

Prefix a percent sign (%) to specify a Domino domain name; for example, entering
%AcmeEast specifies the Domino domain AcmeEast. This lets you prevent SMTP users
from sending mail to certain internal Domino domains or even foreign domain servers,
such as FAX systems.

Group entries cannot contain a domain part or dot (’.’). For example, the group with the
name DenyMail is valid, but the groups named Deny.iris.com or Denymail@iris are not.
Allow messages only Specifies the hosts or domains that the Domino SMTP service allows to relay outbound
from the following Internet mail. If this field contains valid entries, Domino allows only servers matching
Internet hosts to be sent these entries to relay. Message relays from other servers are denied. You can specify
to external Internet individual host names or a group name.
domains
Enter host names or IP addresses to designate the sites that are authorized to use
Domino to relay messages to recipients outside your local Internet domain. For example,
if you enter lotus.com or ibm.com in the field, Domino accepts messages for recipients in
external Internet domains only from servers with host names that end in lotus.com or
ibm.com. Domino rejects messages for external recipients from any server not listed in
this field.

768 Lotus Domino Administrator 7 Help

Inbound Relay Controls
Deny messages from the Specifies the hosts or domains that the Domino SMTP service does not allow to relay
following Internet hosts outbound Internet mail. If this field contains valid entries, Domino denies message relays
to be sent to external from servers matching those entries. Domino allows message relays from all other
Internet domains servers. You can specify individual host names or a group name.

Enter host names or IP addresses to designate the sites that cannot use Domino to relay
messages to recipients outside the local Internet domain.

For example, you enter lotus.com in the field. Domino accepts messages to recipients in
external Internet domains from all servers except those with host names ending in
lotus.com. Domino denies messages to recipients in external Internet domains from
servers in the lotus.com domain.

An asterisk (*) in this field prevents Domino from relaying messages from any host
subject to the relay controls.

7. Reload the SMTP task, or update the SMTP configuration to put the changes into effect.
v You can use an asterisk (*) to indicate ″all domains.″ For example, putting * in an Allow field
allows all hosts in all domains to perform that operation.
v Wildcards may be used in place of an entire subnet address; for example, [127.*.0.1]. Wildcards are
not valid for representing values in a range -- for example, the entry [123.234.45-*.0-255] is not valid
because the asterisk is used to represent the high-end value of the range that begins with 45.
v When entering multiple addresses, separate them with carriage returns; after the document is
saved, Domino automatically reformats the list, inserting semicolons between the entries.
v When entering an IP address, enclose it within square brackets; for example, [127.0.0.1].

How Domino resolves conflicts between settings in the inbound relay controls: When there is a conflict between
the allowed and denied relay destinations, and the allowed/denied relay sources, the entry in the
″Allow″ field takes precedence. Thus, a host that you explicitly allow to relay can always relay to any
destination, including denied destinations. Similarly, if you allow relays to a given domain, all hosts can
relay to that destination, including hosts to which you have explicitly denied relaying. Denied hosts
cannot relay to domains other than those that you specifically list in the Allow field. The following table
provides several examples of how Domino resolves conflicts between entries in the Allow and Deny
fields of the Inbound relay controls.

Example of conflict between an allowed relay destination and denied relay source:

Field Entry Results of settings

Allow messages to be sent only to the
following external internet domains:
Deny messages from the following
internet hosts to be sent to external
internet domains: (* means all)
xyz.com All hosts can relay to xyz.com, including
smtp.efg.com, which is a denied host.
smtp.efg.com smtp.efg.com cannot relay to any
destination, except xyz.com, which is
explicitly allowed.

Example of conflict between a denied relay destination and allowed relay source:

Field Entry Results of settings

Deny messages to be sent to the qrs.com No relays are allowed to qrs.com, except
following external internet domains: (* relays originating from relay.abc.com, which
means all) is specifically allowed.
Allow messages only from the following relay.abc.com Relay.abc.com can relay to any destination,
internet hosts to be sent to external including qrs.com, which is a denied
internet domains: destination.

Chapter 30. Customizing the Domino Mail System 769

Note: This differs from the behavior of Domino Release 5, where if you denied relays to a destination
domain, an allowed source host could not relay to the denied domain, and a denied source could not
relay to any destination. You can revert to the Release 5 behavior by setting the variable in the
NOTES.INI file.

For information on the NOTES.INI setting SMTPRelayAllowHostsandDomains, which is required to make

the inbound relay controls behave as they did in Domino Release 5, see the appendix ″NOTES.INI File.″

Example of conflict between allowed and denied relay destinations: If the same entry is placed in the list of
allowed and denied destinations, or the list of allowed and denied sources, Domino honors the entry in
the Deny list. For example, Domino rejects relays to xyz.com if you configure the relay controls as
follows:

Field Entry
Allow messages to be sent only to the xyz.com, abc.com, qrs.com
following external internet domains:
Deny messages to be sent to the xyz.com
following external internet domains: (*
means all)

Specifying enforcement of inbound relay controls: When you first create a Configuration Settings document
for a server, by default, the SMTP inbound relay controls, or anti-relay settings, apply to all external hosts
only, that is, to hosts that are not located in the local Internet domain. After you set inbound relay
controls, you can customize how Domino applies them by selecting inbound relay enforcement options.

The available options allow you to specify how strictly to enforce the relay controls by letting you exempt
certain hosts from enforcement. You can exempt hosts from relay enforcement based on:
v Domain location - By default, Domino enforces relay controls for hosts outside the local Internet
domain only. You can enforce stricter control by applying them to all connecting hosts or relax
enforcement entirely so Domino does not perform any relay checks (not recommended).
v Authentication status - By default, Domino applies relay controls to authenticated SMTP sessions. You
can relax enforcement by exempting all authenticated users from relay checks.
v Host name or IP address - By default, all external hosts are subject to relay controls. You can specify a
list of hosts (by IP address or host name) to exempt from relay checks.

Applying relay restrictions to internal hosts: By default, Domino enforces anti-relay settings for external
hosts only. Internal hosts are exempt from anti-relay checks so Domino does not consider an internal host
as a possible relay, even if it’s explicitly listed in the Inbound relay controls’ ″Deny messages from the
following Internet hosts to be sent to external Internet domains″ field.

Depending on your environment, you may want to extend the scope of enforcement by applying relay
restrictions to both internal and external hosts. This is equivalent to setting the variable
SMTPAllHostsExternal=1 in the NOTES.INI file.

Applying relay enforcement to internal hosts lets you achieve more secure and controlled routing. For
example, you can configure your Domino SMTP server so that only other Domino mail servers are
allowed to relay. By doing so you can prevent internal users who run other mail clients (for example,
POP or IMAP clients), as well as servers in other internal mail systems, from using the Domino SMTP
server to send mail to the Internet.

You might also enable relay enforcement for internal hosts if you have a Domino SMTP server that
receives mail from a dual-interface firewall server. For security purposes, some organizations may not
connect their Domino SMTP servers directly to the Internet, choosing instead to set up an internal SMTP

770 Lotus Domino Administrator 7 Help

relay host or firewall to receive Internet mail destined for the organization’s Internet domain. The relay or
firewall then routes the mail to a Domino SMTP server, which, in turn, transfers it to the organization’s
internal mail servers.

A host in the local Internet domain can always relay to external Internet domains unless it is explicitly
denied by an entry in the field ″Deny messages from the following internet hosts to be sent to external
internet domains.″

If the internal relay or the firewall does not implement its own relay controls, the Domino SMTP server
may then receive mail that is not destined for a local user. If the Domino server is set up to perform
anti-relay enforcement on external hosts only, then mail received from the internal relay or firewall is not
subject to the Inbound Relay Controls because the sending system, the relay or the firewall, belongs to
the same local Internet domain. Thus, when the Router determines that the Internet address listed in the
RCPT TO command has no match in the $Users view in the Domino Directory, it routes the message back
out to the Internet.

Note: SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or
modify the SMTP and Router settings in the Configuration Settings document, be sure to enter group
names that have a group type of Mail-only or Multi-purpose. These groups must be in the primary
directory. This applies to settings on the Restrictions tab, the SMTP Inbound Controls tab, and the SMTP
Outbound Controls tab.

Allowing relays from authenticated users connecting from outside the local domain: By default, if you deny
relaying for a domain or set of domains (for example, all external domains), all hosts in the denied
domains are subject to the relay controls. This level of restriction prevents remote IMAP or POP3 clients
that connect to Domino by way of Internet service providers (ISPs) in external domains from sending
outbound Internet mail because Domino does not recognize the source of the message as a valid relay
origin.

To ensure that Domino allows POP3 or IMAP users to send outbound Internet mail, you can customize
relay enforcement to allow all authenticated users to relay. After the Domino SMTP listener determines
that a connecting host has been authenticated, it treats the connection as though it originated from a local
user and exempts it from the Inbound relay controls.

Specifying enforcement exceptions based on host name or IP address: By default, after you deny relaying for a
domain, all hosts in that domain are subject to the relay controls. You can customize relay enforcement to
allow specific clients or servers in a domain to relay by entering host names or IP addresses in the field
″Exclude these connecting hosts from anti-relay checks.″ For each specified exception, Domino does not
enforce the inbound relay controls. Use exceptions to allow hosts outside the local Internet domain to use
the Domino SMTP server as a relay to send and receive their mail from the Internet, while still
preventing Domino from being used as an open relay by unauthorized Internet hosts.

Note: Because many ISPs use the dynamic host control protocol (DHCP) to assign IP addresses to each
connecting user, a user’s IP address may differ from session to session. As a result, specifying
enforcement exceptions based on host name or IP address is not effective for ensuring relay access for
IMAP and POP3 users who connect to Domino from an ISP. To ensure relay access for these users, enable
enforcement exceptions for authenticated users.

For more information on relay hosts and Global domain documents, see the chapter ″Setting Up Mail
Routing.″

To specify relay enforcement:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.

Chapter 30. Customizing the Domino Mail System 771

4. Select the Configuration Settings document for the mail server or servers you want to restrict mail on,
and click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab.
6. Complete these fields in the Inbound Relay Enforcement section, and then click Save & Close:

Inbound Relay
Enforcement
Field Description
Perform Anti-relay Specifies the connections for which the server enforces the inbound relay controls.
enforcement for these Choose one:
connecting hosts v External hosts (default) - The server applies the inbound relay controls only to hosts
that connect to it from outside the local Internet domain. Hosts in the local Internet
domain are exempt from anti-relay restrictions. The local Internet domain is defined by
either a Global Domain document, if one exists, or as the Internet domain of the host
server.
v All connecting hosts - The server applies the Inbound relay controls to all hosts
attempting to relay mail to external Internet domains.
v None - The server ignores the settings in the Inbound relay controls. All hosts can
always relay.
Exceptions for Specifies whether users who supply login credentials when connecting to the server are
authenticated users exempt from enforcement of the inbound relay controls. Choose one:
v Perform anti-relay checks for authenticated users - The server does not allow
exceptions for authenticated users. Authenticated users are subject to the same
enforcement as non-authenticated users.
v Allow all authenticated users to relay - Users who log in with a valid name and
password are exempt from the applicable inbound relay controls. Use this to enable
relaying by POP3 or IMAP users who connect to the network from ISP accounts
outside the local Internet domain.
Exclude these connecting You create an exceptions list containing the IP addresses or host names of hosts that relay
hosts from anti-relay to any permitted domain. For each specified exception, the inbound relay controls will
checks not be enforced. Enter the IP addresses or host names of hosts to be exempted from the
restrictions specified in the Inbound relay controls section. You can also enter group
names in this field.

When entering an IP address, enclose it within square brackets; for example, [127.0.0.1].
You can use wildcards to represent an entire subnet address, but not to represent values
in a range. For example, [127.*.0.1] is valid; [123.123.12-*.123] is not.

7. Reload the SMTP task or update the SMTP configuration to put changes into effect.

How inbound anti-relay settings control message transfer to external Internet domains:
1. The SMTP listener receives a connection request.
2. The server performs a reverse DNS lookup, querying DNS to find the host name that matches the
connecting host’s IP address. If the address resolves to a name in one of the local Internet domains,
the host is considered internal. IP addresses that resolve to host names outside the local Internet
domains or that do not have DNS entries are considered external.
3. The server checks the setting in the field ″Perform Anti-Relay enforcement for these connecting hosts″
to determine whether anti-relay controls are enabled, and if so, whether they apply to all hosts or
external hosts only. If connections from the sending domain are not subject to inbound relay controls,
the server allows relays for this session.
4. If the relay controls apply, Domino next checks whether the host name appears in the field ″Exclude
these connecting hosts from anti-relay checks. ″If the host name is found, the server allows relays for
this session.

772 Lotus Domino Administrator 7 Help

5. If the relay controls still apply and the connecting host successfully authenticated with the server, the
server checks the field ″Exceptions for authenticated users″ to determine whether authenticated users
are exempt from the inbound relay checks. If authenticated users are exempt, the server allows relays
for this session.

Note: A connecting host provides authentication credentials only when Domino requests them.
Because Domino closes the session if authentication is not successful, there is no case where Domino
needs to determine whether a host that could not authenticate might be allowed to relay.
6. The SMTP listener receives ″RCPT TO″ commands from the connecting host.
7. The server examines each recipient address to see if the message would be a relay to an external
domain. If so, the server checks the Inbound relay controls to determine:
v Whether the connecting host is allowed to relay
v Whether relays are allowed to the target domain
Matching for domain is performed by looking for the restricted domain name as a trailing substring
of the recipient’s domain. If you deny the domain spamme.com, you also deny the domain
you.spamme.com. Rejected recipients receive a failure status in response to the RCPT commands.

Enabling DNS blacklist filters for SMTP connections: To prevent unsolicited commercial e-mail (UCE),
or spam, from entering your system, you can set up Domino to check whether incoming SMTP
connections originate from servers listed in one or more DNS blacklists (DNSBLs). DNSBLs are databases
that keep a record of Internet SMTP hosts that are known sources of spam or permit third-party, open
relaying.

When DNS blacklist filters are enabled, for each incoming SMTP connection Domino performs a DNS
query against the blacklists at the specified sites. If a connecting host is found on the list, Domino reports
the event in a console message and in an entry to the Mail Routing Events view of the Notes Log. Both
the console message and log entry provide the host name and IP address of the server, and the name of
the site where the server was listed.

In addition to logging the event, you can configure Domino to reject messages from hosts on the blacklist
or to add a special Notes item to flag messages accepted from hosts on the list.

Specifying the DNS blacklist sites to check: After you enable the DNS blacklist filters, you can specify the
site or sites the SMTP task uses to determine if a connecting host is a ″known″ open relay or spam
source. Specify sites that support IP-based DNS blacklist queries.

If Domino finds a match for a connecting host in one of the blacklists, it does not continue checking the
lists for the other configured sites.

For performance reasons, it’s best to limit the number of sites because Domino performs a DNS lookup to
each site for each connection.

You can choose from a number of publicly available and private, paid subscription services that maintain
DNS blacklists. When using a public blacklist service, Domino performs DNS queries over the Internet. In
some cases, it may take a significant amount of time to resolve DNS queries submitted to an Internet site.
If the network latency of DNS queries made over the Internet results in slowed performance, consider
contracting with a private service that allows zone transfer, so that Domino can perform the required
DNS lookups to a local host. During a zone transfer, the contents of the DNS zone file at the service
provider are copied to a DNS server in the local network.

Each blacklist service uses its own criteria for adding servers to its list. Blacklist sites use automated tests
and other methods to confirm whether a suspected server is sending out spam or acting as an open relay.
The more restrictive blacklist sites add servers to their list as soon as they fail the automated tests and

Chapter 30. Customizing the Domino Mail System 773

regardless of whether the server is verified as a source of spam. Other less restrictive sites list a server
only if its administrator fails to close the server to third-party relaying after a specified grace period or if
the server plays host to known spammers.

By searching the Internet, you can find Internet sites that provide periodic reports on the number of
entries in various DNS blacklist services.

Hosts that are exempt from DNS blacklist checks: To avoid unnecessary DNS lookups, Domino performs
DNS blacklist checks only on hosts that are subject to relay checks, as specified in the SMTP inbound
relay restrictions. Any host that is authorized to relay is exempt from blacklist checks. For example, by
default, Domino enforces the inbound relay restrictions only for external hosts (Router/SMTP -
Restrictions and Controls - SMTP Inbound Controls - Perform Anti-Relay enforcement for these
connecting hosts). If the default setting is used, internal hosts are not subject to relay controls and thus
are also exempt from blacklist checks.

For more information on configuring relay enforcement, refer to the topic ″Setting inbound relay controls
to prevent unauthorized mail relaying″ earlier in this chapter.

Specifying how Domino handles connections from hosts found in a DNS blacklist: You can configure Domino to
take the following actions when it finds a connecting host on one of the blacklists:
v Log only
v Log and tag message
v Log and reject message

In each case, the server records the following information in the Notes log: the host’s IP address and host
name (if a reverse DNS lookup can determine this information) and the name of the site that listed the
host.

When tagging messages, Domino adds a special Note item to messages received from hosts found on a
blacklist. After Domino determines that a connecting host is on the blacklist, it adds the Note item,
$DNSBLSite, to each message it accepts from the host before depositing the message in MAIL.BOX. The
value of a $DNSBLSite item is the blacklist site in which the host was found. Administrators can use the
$DNSBLSite note item to provide custom handling of messages received from hosts listed in a blacklist.
For example, you can test for the presence of the item through the use of formula language in an agent
or view and provide conditional handling of messages that contain the item, such as moving the
messages to a special database.

When considering what action to take when Domino finds a host on the blacklist, choose an action that’s
consistent with the policies of the DNS blacklist site you use. For instance, if the service you use is very
restrictive, its blacklist may include ″false positives″; that is, it may blacklist hosts that are not known
sources of spam. As a result, if you take the action of rejecting mail from any host found on the blacklist,
it could prevent the receipt of important messages.

Use restraint when taking action, particularly if you use the blacklist of a more restrictive site. The action
you select applies to each of the specified blacklist sites. That is, you cannot configure Domino to deny
connections for hosts found on one site’s list and log the event only for hosts found on another site’s list.

DNS blacklist statistics: The SMTP task maintains statistics that track the total number of connecting hosts
that were found on the combined DNSBL of all sites combined, as well as how many were found on the
DNSBL of each configured site. Because the statistics are maintained by the SMTP task, they are
cumulative for the life of the task only and are lost when the task stops.

You can view the statistics from the Domino Administrator or by using the SHOW STAT SMTP command
from the server console. You can further expand the statistics to learn the number of times a given IP
address is found on one of the configured DNSBLs. To collect the expanded information, you set the

774 Lotus Domino Administrator 7 Help

variable SMTPExpandDNSBLStats in the NOTES.INI file on the server. Because of the large numbers
generated by the expanded set of statistics, Domino does not record the expanded statistics by default.

Note: Domino uses IP version 4 (IPv4) addresses when querying DNS blacklist sites to find out if a
connecting host is listed. If the connecting host has an IP version 6 (IPv6) address, Domino skips the
DNSBL check for that host.

Changing the default error message: When denying a blacklisted host, Domino returns to it a default SMTP
response, which includes the remote host’s IP address and the blacklist site that listed the host. You can
customize this response in the ″Custom error message for denied hosts″ field in the Configuration
Settings document. The text of a customized response can include the string format specifier ″%s″ to
represent a denied host’s IP address and the DNSBL site where the host was found. Refer to the table in
the following procedure for more information.

To enable DNS blacklist filters:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers where you want to enable
DNS blacklist filters, and click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab.
6. Complete the following fields in the DNS Blacklist Filters section, and then click Save & Close:

Field
DNS Blacklist filters
DNS Blacklist sites
Desired action when connecting
host is found in a DNS Blacklist
Enter
Choose one:
v Enabled - When Domino receives an SMTP connection request, it checks
whether the connecting host is listed in the blacklist at the specified sites.
v Disabled - Domino does not check whether a connecting host is on the
blacklist.
If DNS blacklist filters are enabled, specify the DNSBL sites to check when
Domino receives an SMTP connection request.
Choose one:
v Log - When Domino finds that a connecting host is on the blacklist, it accepts
messages from the host and records the host name and IP address of the
connecting server and the name of the site where the server was listed.
v Log and tag message - When Domino finds that a connecting host is on the
blacklist, it accepts messages from the hosts, logs the host name and IP
address of the connecting server, and the name of the site where the server
was listed, and adds the Notes item $DNSBLSite to each accepted message.
v Log and reject message - When Domino finds that a connecting host is on the
blacklist, it rejects the connection and returns a configurable error message to
the host.

Chapter 30. Customizing the Domino Mail System 775

Field Enter
Custom SMTP error response for Enter the text of the error message Domino returns when denying a connection
rejected messages because it found the host in the DNS blacklist. The default error message
indicates that the connection was denied for policy reasons.

You can use the format specifier ″%s″ to specify the IP address of the denied
host and the DNS blacklist site where Domino found the host listed. For
example, if you enter the following:
Your host %s was found in the DNS Blacklist at %s

whenever Domino denies a connection, it returns an error to the host, in which

it replaces the first instance of ″%s″ with the IP address of the host, and the
second instance with the DNS blacklist site name. Thus, if you entered the text
in the preceding example, a denied host receives an error such as:
Your host 127.0.0.2 was found in the DNS Blacklist at blackholes.mail-abuse.org

7. Reload the SMTP task, or update the SMTP configuration to put changes into effect.

Enabling DNS whitelist filters for SMTP connections: Use DNS whitelist filters as a means to help
identify legitimate email. When DNS whitelist filters are enabled, the SMTP listener task determines
whether a connecting host is a member of a DNS whitelist by relying on the results of a DNS query of a
DNS blacklist-style host name. If the query returns an IP address, the host is added to the whitelist and
the remaining DNS whitelists are not searched. If the host is not found in the DNS whitelist , processing
continues with DNS blacklist filters. If the query returns an error indicating that the host name is not
valid, the host is not added to the whitelist and may be subject to blacklist filtering if that is enabled.

Note: DNS whitelists can be used independently of blacklists but private blacklists override DNS
whitelists.

Enabling the use of DNS whitelist filters: This procedure assumes you have previously set up a
Configuration Settings document for the server on which you are enabling DNS whitelist filters.
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the server on which you are enabling DNS whitelist
filters.
4. Click Router / SMTP - Restrictions and Controls - SMTP Inbound Controls.
5. Complete these fields in the DNS Whitelist Filters section and then click Save and Close.

Field Action
DNS Whitelist Filters Note: DNS whitelist filtering applies only to hosts
subject to inbound relay enforcement.

Choose ″Enabled″ to allow the SMTP listener task to

perform DNS queries against whitelist sites that you
enter in the ″DNS Whitelist filters″ field.

By default this setting is disabled.

DNS Whitelist sites Specify the DNS whitelist sites against which the SMTP
listener task will perform DNS queries. The queries are
performed when Domino receives an SMTP connection
request.

776 Lotus Domino Administrator 7 Help

Field Action
Desired action when a connecting host is found in a DNS When the connecting host is found in a DNS Whitelist,
whitelist choose one of the options here:
v Silently skip blacklist filters -- All whitelist actions skip
blacklist filters. Performs no logging.
v Log only -- Records the host name and IP address of
the connecting server, as well as the name of the site
where the server was listed.
v Log and tag message -- Adds the Note item,
$DNSWLSite, to messages accepted from whitelisted
hosts. Records the host name and IP address of the
connecting server, as well as the name of the site
where the server was listed.

DNS whitelist statistic: The SMTP listener task maintains a statistic to keep a cumulative count of the
number of connections accepted from DNS whitelisted hosts. The statistic, SMTP.DNSWL.TotalHits, can
be viewed using the Domino Administrator client, or by issuing this command from the server console:
show stat SMTP

To determine the number of times a particular IP address is listed in one of the configured DNS
whitelists, expand the statistic as shown:

SMTP.DNSWL.<WhitelistSite>.IP address.Hits

To collect the expanded information, set the NOTES.INI variable SMTPExpandDNSWLStats =1.

Enabling private blacklist filters for SMTP connections: Use private blacklists to specify hosts and/or
domains responsible for sending unnecessary, unwanted mail to your Internet domain. For consistency,
Domino’s private blacklists follow the model currently used by existing anit-spam functionality. Private
blacklists are stored in the Domino Directory to simplify the process of maintaining and distributing
blacklist information between servers.

When private blacklists are enabled, the SMTP listener task compares the names of hosts that may be
subject to relay enforcement against the private blacklist prior to performing DNS blacklist queries. This
prevents unnecessary DNS lookups. If the host is found in the private blacklist, the action specified in the
field ″Desired action when a connecting host is found in a private blacklist″ in the Private Blacklist Filters
section of the Configuration Settings document applies. If the host is not found in the private blacklists,
processing continues with DNS whitelist filters and then DNS blacklist filters.

Enabling the use of private blacklist filters: This procedure assumes you have previously set up a
Configuration Settings document for the server.
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the server on which you are enabling the private
blacklist filters.
4. Click Router / SMTP - Restrictions and Controls - SMTP Inbound Controls.

Chapter 30. Customizing the Domino Mail System 777

5. Complete these fields in the Private Blacklist Filters section and then click Save and Close.

Field Action
Private Blacklist filter Note: Private blacklist filters apply only to hosts that are
subject to inbound relay enforcement.

Choose ″Enabled″ to allow the SMTP listener task to

determine if connecting hosts have been blacklisted, that
is, if connecting hosts have been entered in the field
″Blacklist the following hosts″.

By default, this setting is disabled.

Blacklist the following hosts Enter IP addresses or host names of the systems to
blacklist.

IP ranges and masks are supported. Wildcards can be

Desired action when a connecting host is found in the
private blacklist
Custom SMTP error response for rejected messages
used except within ranges.
Choose one:
v Log only -- Records the host name and IP address of
the connecting server found in the private blacklist.
This is the default setting.
v Log and tag message -- Logging occurs in the same
manner as in the Log only option. Tags the message
by adding the Note item, $DNSBLSite, to messages
accepted from blacklisted hosts. The value of
$DNSBLSite will be PrivateBlacklist.
v Log and reject message -- Logging occurs in the same
manner as in the Log only option. Rejects messages by
returning an error response to the blacklisted host.
Enter the custom error message text to be sent when the
connecting host’s name is found in the private blacklist.

The format specifier ’%s’ can be used to insert the IP

address of the connecting host. For example, enter the
following text: Your host %s was blacklisted. When
Domino rejects a message from the blacklisted host
127.0.0.1, the following error message appears: Your host
127.0.0.1 was blacklisted.

Private blacklist statistic: The SMTP listener task maintains a cumulative count of the number of
connections accepted from blacklisted hosts, and stores that count in the SMTP.PrivateBL.TotalHits
statistic. The SMTP.PrivateBL.TotalHits statistic is part of the SMTP statistics package and can be viewed
using the Domino Administrator client or from the server console by entering the following command:
show stat SMTP

Enabling private whitelist filters for SMTP connections: Use Domino’s private whitelist filters to
specify exceptions to blacklist filters.

Prior to the introduction of private whitelist filters, to exclude a host from blacklist filter processing, you
had to either define the client’s mail server as a relay exception -- which creates a security risk, or disable
the DNS blacklists filters. Now you can use private whitelist filters to specify the hosts and/or domains
to exclude from blacklist processing. Hosts that are specified in private whitelists are exempt from
blacklist checks. Whitelisted hosts bypass blacklist filter checks but there are other controls which may
prevent the message from being accepted. Members of the private whitelist are still subjected to
connection, relay, sender, and recipient controls. Being whitelisted does not guarantee that the message
will be delivered to the recipient.

778 Lotus Domino Administrator 7 Help

Whitelists can be used independently of blacklists.

When private whitelists are enabled, the SMTP listener task compares hosts that may be subject to relay
enforcement against the defined private whitelist. If there is a match, the private blacklist, DNS whitelists,
and DNS blacklists are skipped. Otherwise, processing continues beginning with the private blacklist.

Setting up private whitelist filters: This procedure assumes you have previously set up a Configuration
Settings document for the server.
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the server on which you are enabling private whitelist
filters.
4. Click Router / SMTP - Restrictions and Controls - SMTP Inbound Controls.
5. Complete these fields in the Private Whitelist Filters section and then click Save and Close.

Field Action
Private Whitelist Filters Note: Private whitelist filtering applies only to hosts
subject to inbound relay enforcement.

Choose ″Enabled″ to allow the SMTP listener task to

determine if connecting hosts have been whitelisted, that
is, to determine whether they have been entered in the
field ″Whitelist the following hosts.″

By default this setting is disabled.

Whitelist the following hosts Enter IP addresses or host names of the systems to add
to the whitelist.

IP ranges and masks are supported. Wildcards can be

Desired action when a connecting host is found in the
private whitelist
used except within ranges.
Choose one of these:
v Silently skip blacklist filters -- All actions skip blacklist
filter checks. No logging occurs and all actions skip
blacklist filters. This is the default setting.
v Log only -- Records the host name and IP address of
the connecting server found in the private whitelist.
v Log and tag message -- Logging occurs in the same
manner as in the Log only option. Tags the message
by adding the Note item, $DNSWLSite, to messages
accepted from whitelisted hosts. The value of
$DNSWLSite will be PrivateWhitelist.

Private whitelist statistic: The SMTP listener task maintains a statistic to keep a cumulative count of the
number of connections accepted from whitelisted hosts. The statistic, SMTP.PrivateWL.TotalHits, can be
viewed using the Domino Administrator client, or by issuing this command from the server console:
show stat SMTP

Restricting who can send Internet mail to your users: Unsolicited commercial e-mail (UCE) can flood
your server with numerous copies of the same message. Accepting UCE reduces performance and
consumes system resources. You can specify restrictions to prevent UCE from being routed to or relayed
through your server. Specifying restrictions prevents malicious users from using your system to spoof
addresses or send UCE.

To save system resources, before it accepts a message, the Domino SMTP listener checks the Mail From
address specified in the message envelope during the SMTP transaction. If you set the Domino server to

Chapter 30. Customizing the Domino Mail System 779

deny mail from a particular source, Domino denies it whenever that source is encountered -- for example,
if users from a denied domain send mail through a relay, Domino denies it based on its origin from that
domain. Domino creates an entry in the log file (LOG.NSF) whenever a message is rejected.

Note: SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or
modify the SMTP and Router settings in the Configuration Settings document, be sure to enter group
names that have a group type of Mail-only or Multi-purpose. These groups must be in the primary
directory. This applies to settings on the Restrictions tab, the SMTP Inbound Controls tab, and the SMTP
Outbound Controls tab.

To restrict who can send Internet mail to your users:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to restrict mail on,
and click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab.
6. Complete these fields in the Inbound Sender Controls section, and then click Save & Close:

Inbound Sender Controls

Field Enter
Verify sender’s domain in DNS Choose one:
v Enabled - Domino verifies that the sender’s domain exists, by checking the
DNS for an MX, CNAME, or A record that matches the domain part of the
address in the MAIL FROM command received from the sending host. If no
match is found, Domino rejects inbound mail from the host.
Note: This can result in Domino rejecting mail from legitimate hosts that do
not have these records in their DNS entries.
v Disabled - (default) Domino does not check DNS to verify that the sender’s
domain exists.
Allow messages only from the Internet addresses from which the server accepts messages. If you enter
following Internet addresses in this field, only messages with senders matching those addresses
addresses/domains can send Internet mail to users in your local Internet domain. Mail from all
other addresses is denied.

During the SMTP conversation, the Domino SMTP listener compares the
address in the MAIL FROM command received from the connecting host with
the entries in this field.

For example, if you enter lotus.com in the field, Domino accepts incoming mail
only if the address in the MAIL FROM command ends in lotus.com. Domino
denies messages from all other Internet addresses.

You can create a Notes group containing a list of addresses from which to
allow messages and enter the group name in this field. A group entry is valid
only if it does not contain a domain part or dot (″.″). For example, the group
with the name group1 is valid, but the groups named iris.com or group2@iris
are not.

780 Lotus Domino Administrator 7 Help

Inbound Sender Controls
Deny messages from the following
Internet addresses/domains
Internet addresses from which the server does not accept messages.
During the SMTP conversation, the Domino SMTP listener compares the
address in the MAIL FROM command received from the connecting host with
the entries in this field.

If you enter addresses in this field, all messages except those matching
addresses listed in this field can route to your users. Mail is denied only from
addresses matching the entries in this field.

For example, if you enter lotus.com in the field, Domino accepts messages
from all Internet addresses and domains except those ending in lotus.com.
Domino denies messages from senders whose addresses end in lotus.com.

You can create a Notes group containing a list of addresses from which to
deny messages and enter the group name in this field. A group entry is valid
only if it does not contain a domain part or dot (″.″). For example, the group
with the name group1 is valid, but the groups named iris.com or group2@iris
are not.

7. Reload the SMTP task, or update the SMTP configuration to put changes into effect.

Note: Be careful not to specify the same entry in an Allow field and a Deny field because Domino will
deny messages for that entry. The Deny setting takes precedence for security reasons.

Restricting users from receiving Internet mail: Domino provides SMTP intended recipient filters that
let you control the users for whom the server accepts mail sent over SMTP connections. One filter
triggers a directory lookup that enables the server to verify that an intended recipient exists before
accepting a message. The other two filters let you explicitly specify the Internet addresses that can and
cannot receive mail. To ensure that you don’t unintentionally block desirable mail, use discretion when
applying these settings.

During the SMTP conversation, the connecting host sends the Domino SMTP listener a RCPT TO
command, which specifies the recipient’s Internet address. Each of the Inbound Intended Recipient
Controls works by examining the addresses specified as arguments to the RCPT TO command. For
example, if you enable directory verification and the address specified in the RCPT TO command is in
the local Internet domain, the SMTP listener refers to the Domino Directory to determine whether the
address is valid. Messages for invalid addresses are rejected, preventing them from becoming ″dead″
messages in MAIL.BOX.

Note: Because enabling this setting results in messages for recipients not found in the directory being
rejected, do not use this setting in environments that require mail to be forwarded to a smart host for
further processing.

The ″Allow messages″ setting lets you list Internet addresses that are allowed to receive mail. If the RCPT
TO command contains one of the specified addresses, the SMTP listener accepts the message; messages
for all other recipients are rejected. The ″Deny messages″ setting lets you explicitly deny mail to certain
addresses. If the RCPT To command contains a denied address, the SMTP listener rejects the message, but
messages for all other recipients are accepted.

Note: If the server supports Local Part name lookups, users whose addresses are listed in the Deny field
may still receive mail addressed to any alternate Internet addresses configured for them. To ensure
greater control, specify the Internet address in each user’s Person document and allow users to receive
inbound mail destined for their fullname addresses only.

Chapter 30. Customizing the Domino Mail System 781

SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or modify the
SMTP and Router settings in the Configuration Settings document, be sure to enter group names that
have a group type of Mail-only or Multi-purpose. These groups must be in the primary directory. This
applies to settings on the Restrictions tab, the SMTP Inbound Controls tab, and the SMTP Outbound
Controls tab.

For information on restricting how Domino looks up recipient names, see the chapter ″Setting Up Mail
Routing.″
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Inbound Controls tab.
6. Complete these fields in the Inbound Intended Recipients Controls section, and then click Save &
Close:

Field Description
Verify that local domain Specifies whether the SMTP listener checks recipient names specified in RCPT TO
recipients exist in the Domino commands against entries in the Domino Directory
Directory
Choose one:
v Enabled - If the domain part of an address specified in an SMTP RCPT TO
command matches one of the configured local Internet domains, the SMTP listener
checks all configured directories to determine whether the specified recipient is a
valid user. If all lookups complete successfully and no matching user name is
found, the SMTP server returns a 550 permanent failure response indicating that
the user is unknown. For example:

550 bad_user@yourdomain.com ... No such user

Choosing this setting can help prevent messages sent to nonexistent users (for
example, spam messages and messages intended for users who have left the
organization) from accumulating in MAIL.BOX as dead mail.

To avoid messages from being rejected as a result of directory unavailability, Domino

accepts messages when an attempted directory lookup does not complete
successfully.

To avoid unnecessary directory lookups, Domino applies this setting only after
performing all other configured SMTP inbound checks (inbound relay, sender, and
recipient controls).
Note: When this setting is enabled, and there is an entry in the field ″Local Internet
domain smart host″, messages that cannot be resolved are not accepted; therefore,
they will not be forwarded to the smart host. When this setting is enabled, and the
field ″Smart host is used for all local Internet domain recipients″ is enabled, only
those messages sent to recipients that can be resolved are accepted, and these will be
forwarded to the smart host.
v Disabled - (default) The SMTP listener does not check whether local domain
recipients specified in the RCPT TO command are listed in the Domino Directory.

782 Lotus Domino Administrator 7 Help

Field Description
Allow messages intended Internet addresses that are within the local Internet domain and that are allowed to
only for the following receive mail from the Internet. If you enter addresses in this field, only those
Internet addresses recipients can receive Internet mail. Domino denies mail for all other recipients.

You can create a Notes group containing a list of addresses allowed to receive mail
from the Internet and enter the group name in this field. A group entry is valid only
if it does not contain a domain part or dot (″.″). For example, the group with the
name group1 is valid, but the groups named yourdomain.com or
group2@yourdomain are not.
Deny messages intended for Internet addresses within the local Internet domain that are prohibited from
the following Internet receiving mail from the Internet. If you enter addresses in this field, all addresses
addresses except those listed in this field can receive Internet mail. Domino denies mail for
only the addresses in this field.

You can create a Notes group containing a list of addresses that cannot receive mail
from the Internet and enter the group name in this field. A group entry is valid only
if it does not contain a domain part or dot (″.″). For example, the group with the
name group1 is valid, but the groups named yourdomain.com or
group2@yourdomain are not.

Note: The SMTP listener accepts messages addressed to any variant of a user’s name that is not
explicitly denied and that is otherwise acceptable to Domino. For example, if you deny mail to
Kieran.Campion@acme.com, a message addressed to Kcampion@acme.com may be accepted and
delivered to the same user.
7. Reload the SMTP task, or update the SMTP configuration to put changes into effect.

Note: Be careful not to specify the same entry in an Allow field and a Deny field because Domino will
deny messages for that entry. The Deny setting takes precedence for security reasons.

Supporting inbound SMTP extensions: Domino supports a number of extended SMTP (ESMTP)
functions. These include the ability to combine (or ″pipeline″) commands, set the server to check message
size before accepting transfer, create a secure SSL connection with another server, and create delivery
status notifications in MIME format. You enable or disable each of these options in the Configuration
Settings document for the server or servers for which you want to use these extensions.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Advanced - Commands and Extensions tab.
6. Complete these fields in the Inbound SMTP Commands and Extensions section, and then click Save &
Close:

Chapter 30. Customizing the Domino Mail System 783

Field Enter
SIZE extension Choose one:
v Enabled - (default) Domino declares its maximum message size to connecting hosts
and checks the sending host’s estimates of message size before accepting transfer. If the
sender indicates that a message to be transferred is larger than the maximum size,
Domino returns an error indicating that it will not accept the message.
v Disabled - Domino does not advertise its maximum message size or check inbound
message size before transfer.
Note: For information about setting the maximum message size, see the topic
″Restricting mail routing based on message size″ earlier in this chapter.
Pipelining extension Choose one:
v Enabled (default) - Improves performance by allowing Domino to accept multiple
SMTP commands in the same network packet.
v Disabled - Domino does not accept multiple SMTP commands in a single packet.
DSN extension Choose one:
v Enabled - Domino supports incoming requests to return delivery status notifications to
the sender for failed, delayed, delivered, and relayed messages. Domino sends delay
reports for low-priority messages held until the low-priority routing time to the sender
of an SMTP message upon request.
v Disabled - (default) Domino does not return delivery status notifications for SMTP
messages.
8-bit MIME extension Choose one:
v Enabled - Domino accepts 8-bit messages as is, allowing reception of unencoded
multinational characters.
v Disabled (default) - Domino requires inbound messages containing 8-bit characters to
be sent using 7-bit ASCII encoding.
HELP command Choose one:
v Enabled - (default) In response to the Help command, Domino displays a list of
supported commands.
v Disabled - Domino ignores the Help command.
VRFY command Choose one:
v Enabled - Domino accepts inbound requests to verify user names.
v Disabled - (default) Domino denies requests to verify user names.
EXPN command Choose one:
v Enabled - Domino expands mailing lists or groups to show individual recipient names.
v Disabled - (default) Domino does not expand lists and groups.
ETRN command Choose one:
v Enabled - Domino accepts inbound ″pull″ requests from other SMTP hosts to transfer
messages destined for the calling server. Enabling ETRN support allows for more
efficient use of bandwidth resources by allowing a remote SMTP host to request
pending messages at the same time it transfers messages to the Domino server.
v Disabled - (default) Domino does not accept inbound ″pull″ requests from other SMTP
hosts.

784 Lotus Domino Administrator 7 Help

Field Enter
SSL negotiated over Choose one:
TCP/IP port v Enabled - Domino supports the STARTTLS command, allowing it to create an
encrypted SSL channel over the SMTP TCP/IP port.
v Required - Domino accepts inbound SMTP connections over the TCP/IP port only
from hosts that issue the STARTTLS command.
v Disabled (default) - Domino does not allow secure SSL connections over the SMTP
TCP/IP port.
Note: After accepting the STARTTLS command from a remote server, Domino uses
settings for the server’s SSL port to govern authentication for the sessions. For Domino to
authenticate remote hosts that use the SMTP AUTH command, Name & Password
authentication must be enabled for the Domino SSL port.

For more information about the authentication settings required to support STARTTLS, see the topic
″Securing SMTP sessions using the STARTTLS command earlier in this chapter.″
7. Reload the SMTP task, or update the SMTP configuration to put changes into effect.

Note: Enabling VRFY and EXPN allows people outside your organization to expand group names and to
check for valid e-mail addresses in your organization. You may not want to enable these extensions for
security reasons.

To prevent an SMTP server from sending outbound messages that exceed the specified maximum size on
the destination server, set the outbound SMTP SIZE extension.

For information on enabling the outbound SMTP SIZE extension, see the topic ″Supporting outbound
SMTP extensions″ later in this chapter.

Restricting outbound mail routing

You can control outbound messages from your system to external Internet domains by restricting who
can send these messages and by enabling extended SMTP (ESMTP) outbound features. You can set these
restrictions to:
v Restrict who can send mail to the Internet
v Set outbound SMTP extensions

Restricting users from sending Internet mail: You can control the transfer of outbound mail from your
organization to the Internet. Domino provides two methods for restricting outbound Internet mail:
v Outbound sender controls - These controls specify which users in your organization are allowed to
send mail to the Internet.
v Outbound recipient controls - These controls specify the Internet destinations to which users can send
mail.

Setting outbound sender controls: The outbound sender controls let you specify who can and cannot send
mail to the Internet. The controls are implemented in two sets of Allow and Deny lists:
v Internet addresses of users who can/cannot send mail to the Internet
v Notes addresses of users who can/cannot send mail to the Internet

Domino sends a restriction failure message to restricted users who attempt to send outbound mail. You
can customize the text of mail failure messages.

For more information, see the topic ″Customizing the text of mail failure messages″ earlier in this chapter.

Chapter 30. Customizing the Domino Mail System 785

The Outbound sender controls are not intended to restrict SMTP relay access. To configure relay
restrictions, use the Inbound Relay Controls on the Router/SMTP - Restrictions and Controls - SMTP
Inbound Controls tab of the Configuration Settings document.

Note: SMTP can resolve names for group types of Mail-only or Multi-purpose. When you create or
modify the SMTP and Router settings in the Configuration Settings document, be sure to enter group
names that have a group type of Mail-only or Multi-purpose. These groups must be in the primary
directory. This applies to settings on the Restrictions tab, the SMTP Inbound Controls tab, and the SMTP
Outbound Controls tab.

For more information on setting the inbound relay controls, see the topic ″Setting inbound relay controls″
earlier in this chapter.

Note: Because you might unintentionally block desired mail, be careful when you use these fields.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Outbound Controls tab.
6. Complete these fields in the Outbound Sender Controls section, and then click Save & Close:

Outbound Sender Controls

Field
Allow messages only from the
following Internet addresses to be
sent to the Internet
Description
Specifies the RFC 821 Internet addresses of users in the local Internet domain
from whom Domino accepts mail destined for Internet addresses outside the
local Internet domain. If this field contains entries, Domino accepts outbound
Internet mail from the specified Internet addresses only and rejects outbound
Internet mail sent from other addresses. Rejected mail is returned to the
sender.

Enter Internet addresses in the form user@domain.com, or enter the name of a

Notes group containing a list of Internet addresses allowed to send mail to the
Internet. Domino expands entries for groups only if the group name can be
found in the primary Domino Directory.

Wildcards (for example, *acme.com) and isolated Internet domain suffixes (for
example, acme.com) are not acceptable values in this field.

Group entries cannot contain a domain part or dot (’.’). For example, the group
with the name DenyMail is valid, but the groups named Deny.iris.com or
Denymail@iris are not.

786 Lotus Domino Administrator 7 Help

Outbound Sender Controls
Deny messages from the following
Internet addresses to be sent to the
Internet
Specifies the RFC 821 Internet addresses of users in the local Internet domain
from which Domino does not accept mail destined for external Internet
addresses. If this field contains entries, Domino rejects outbound Internet mail
sent from the specified Internet addresses and returns it to the sender. All
other users can send Internet mail.

Enter Internet addresses in the form user@domain.com, or enter the name of a

Notes group listing the Internet addresses from which to deny outbound
Internet mail. Domino expands entries for groups only if the group name can
be found in the primary Domino Directory.

Wildcards (for example, *acme.com) and isolated Internet domain suffixes (for
example, acme.com) are not acceptable values in this field.

Allow messages only from the
following Notes addresses to be
sent to the Internet
Group entries cannot contain a domain part or dot (’.’). For example, the group
with the name DenyMail is valid, but the groups named Deny.iris.com or
Denymail@iris are not.
Specifies the Notes user names from which Domino accepts mail destined for
external Internet addresses. If this field contains entries, Domino accepts
outbound Internet mail from the specified entries only and rejects outbound
Internet mail sent from all other Notes addresses. Rejected mail is returned to
the sender.

Enter fully qualified Notes addresses in the form

Deny messages from the following
Notes addresses to be sent to the
Internet
User/Organizational_unit/Organization, or enter the name of a Notes group
whose members you want to prevent from sending Internet mail. Domino
expands entries for groups only if the group name can be found in the primary
Domino Directory.
Specifies the Notes user names from which Domino does not accept mail
destined for external Internet addresses. If this field contains entries, Domino
rejects outbound Internet mail sent from the specified entries and returns it to
the sender. Domino accepts outbound Internet mail from all other Notes
addresses.

Enter fully qualified Notes addresses in the form

User/Organizational_unit/Organization or the name of a Notes group whose
members you want to prevent from sending Internet mail. Domino expands
entries for groups only if the group name can be found in the primary Domino
Directory.

Note: Group entries cannot contain a domain qualifier (’@’ sign). For example, an entry for a group
with the name DenyMail is valid, but if you add the domain name to the entry, as in
Denymail@acme, Domino does not expand the entry to determine its members. This restriction
applies to nested groups also. That is, if the group DenyMail includes Sales@AcmeWest as a member,
Domino does not expand Sales@AcmeWest to determine its members.
7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″
The outbound sender controls are not intended to control relaying. For information on controlling
message relaying, see the topic ″Setting inbound relay controls″ earlier in this chapter.

Setting outbound recipient controls: The Outbound recipient controls let you specify the Internet domains,
and host names users are allowed to and denied from sending mail to. The controls consist of a set of
pair of lists, one specifying the Internet domains or host names to which users can send mail and another
listing the domains and host names to which users cannot send mail.

Chapter 30. Customizing the Domino Mail System 787

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Restrictions and Controls - SMTP Outbound Controls tab.
6. Complete these fields in the Outbound Recipient Controls section, and then click Save & Close:

Outbound recipient controls

Field
Allow messages only to recipients
in the following Internet domains
or host names
Description
Specifies the Internet domains, such as acme.com, and Internet host names,
such as mailhost.acme.com, to which Domino can send mail. If there are
entries in this field, users can send Internet mail to the specified entries only.
Domino denies mail to all other domains or host names.

Deny messages to recipients in the
following Internet domains or host
names
If you specify an Internet domain, users can send mail to any host or
sub-domain in that domain. Domino matches entries against the last part of
domain names or host names, so entering host.acme.com allows mail to
mail.host.acme.com as well inbound.host.acme.com.
Note: If you list a host name that matches an MX record for a domain,
Domino allows mail to all recipients in that domain. For example, if
mailhost.acme.com exactly matches the name of an MX host in the DNS for the
domain acme.com, entering it in this field allows all mail to that domain.
Specifies the Internet domains, such as acme.com, and Internet host names,
such as mailhost.acme.com, to which Domino cannot send mail. Domino
allows mail to all other domains or host names. Domino matches entries
against the last part of domain names or host names, so entering
host.acme.com denies mail to smtp.host.acme.com as well as
inbound.host.acme.com.
Note: If you enter a host name that matches an MX record for a domain, mail
to all host names / MX records for that domain is denied. Thus, specifying a
host name that matches an MX record for a domain denies all mail to that
domain.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Note: For security reasons, if there is a conflict between the two fields for a given setting, entries in the
Deny field take precedence. For example, if acme.com appears in both the ″Allow messages only to
recipients in the following Internet domains or host names″ field and the corresponding ″Deny messages″
field, Domino denies messages sent to acme.com. Be careful not to have the same entry in an Allow field
and a Deny field for the same setting.

Note: Domino checks each address to see if it is an Internet address or a Notes address. The Router then
applies the restrictions specified for that type of address.

Note: If you are entering multiple names in a field, consider creating a group and entering the group
name in the field. Domino expands the group into a list of members. If you update the group list in this
document or edit the group members in the Domino Directory, changes do not take effect immediately.

Supporting outbound SMTP extensions: Domino supports outbound extended SMTP (ESMTP) features
to interact with other messaging servers. These extensions are controlled in the Configuration Settings
document.

788 Lotus Domino Administrator 7 Help

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Advanced - Commands and Extensions tab.
6. Complete these fields in the Outbound SMTP Commands and Extensions section, and then click Save
& Close:

Field Enter
SIZE extension Choose one:
v Enabled - (default) If the destination SMTP host also supports the SIZE extension,
Domino declares the estimated size of messages before transfer.
v Disabled - Domino does not declare message size before transferring messages to
another SMTP server.
Pipelining extension Choose one:
v Enabled - (default) If the remote SMTP host also supports pipelining, Domino sends
multiple SMTP commands in the same network packet to improve performance.
v Disabled - Domino sends each SMTP command in a separate packet.
DSN extension Choose one:
v Enabled - When sending a message to a server that also supports the DSN extension,
Domino appends a NOTIFY parameter to the SMTP RCPT TO command to request a
particular type of delivery status notification for the message. For messages sent from
Notes clients, Domino uses the Delivery report options specified by the client (Confirm
delivery; Trace entire path; Delivered) to determine the type of DSN requested.
v Disabled - (default) Domino does not send DSN requests.
8-bit MIME extension Choose one:
v Enabled - When sending a message to a remote server that also supports 8-bit MIME,
Domino improves performance by sending messages containing multinational
characters as is, without first encoding them.
v Disabled - (default) Domino encodes messages containing 8-bit characters as 7-bit
ASCII before sending.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Setting up and using message disclaimers

Note: You must be familiar with using Policy documents and policy settings documents to set up and
enable message disclaimers.

Message disclaimers are notices -- usually short text blocks -- that are added to email messages. They are
often used by organizations in an attempt to protect the organization’s legal interests. For example,
message disclaimers can be used to limit an organization’s exposure to vicarious liability, that is, to limit
the organization’s responsibility for the actions of its employees. This type of disclaimer informs the
message recipient that the organization Is not responsible for anything written by the author of the
message. Another commonly used type of message disclaimer consists of a warning stating that the
message may not be intended for the current recipient and that it may contain confidential information.
The disclaimer directs the ″unintended recipient″ to dispose of the message without sharing its contents
with others.

Chapter 30. Customizing the Domino Mail System 789

Enable or disable the use of message disclaimers from the Domino server, Notes client, or both.

To set up and enable message disclaimers on the Notes client, you need to create a Policy document or
use an existing Policy document. You then create a mail policy settings document to define and enable
the message disclaimers. Complete the fields on the mail policy settings document, including those on the
Message Disclaimers tab. Message disclaimers are enabled on the Notes client when you choose Enabled
in the field ″Notes client can add disclaimers.″ The message disclaimer text that is added to electronic
mail messages is derived from the text that you enter in the field ″Disclaimer text.″ Message disclaimers
are written to the mail files of every user to whom the policy applies. The disclaimer is stored in the
Domino Directory.

To set up and enable message disclaimers on the server side, you need to create a Policy document or use
an existing Policy document. You then create a mail policy settings document to define the message
disclaimer text. The message disclaimer text that you enter in the field ″Disclaimer text″ on the mail
policy settings document is the disclaimer that is added to your email messages. You enable and disable
message disclaimers for the server using the server Configuration Settings document - Router/SMTP -
Message Disclaimers tab. When disclaimers are enabled on the server, all messages sent from that server
are disclaimed, regardless of the message source.

The mail policy settings document is applied to all users’ mail files on a given server by the
administration process, using the mail file owner’s hierarchical name to determine the corresponding
Policy document. By default, the administration process runs every twelve hours; therefore, changes do
not take effect until the next time the administration process runs. You can force the administration
process to process new information in the mail policy settings document, by using the server console
command:
tell adminp process mailpolicy

Message disclaimers are not added to incoming SMTP messages; they are only added to outgoing SMTP
messages.

Note: In some cases, all recipients, including local Notes users, receive the disclaimer, but only if all local
Notes users receive MIME messages. Any local Notes users who have the setting Prefers Notes Rich Text
selected in their Person document in the Domino Directory will not receive the disclaimer. This is the
only situation in which the Notes client splits messages: one message for Notes client rich text users, and
one message for all other users.

For information about the mail policy settings document, see the topic Creating a mail policies settings
document.

You need to be aware of the following information regarding enabling and disabling message disclaimers:
v If message disclaimers are enabled for the client and the server, message disclaimers can be added to
mail messages via the server or the client. The server is able to determine whether a disclaimer has
been added by the Notes client. For performance reasons, the client usually adds the disclaimer if
message disclaimers are enabled on both the client and the server.
v If message disclaimers are enabled for the server, but disabled for the client, message disclaimers can
only be added to mail messages from the server.
v If message disclaimers are disabled for the server but enabled for the client, message disclaimers can
only be added from the Notes client.
v If message disclaimers are disabled from both the server and the client, message disclaimers cannot be
added to any mail messages.

You can create one disclaimer and apply it to all messages sent from an organization or organizational
unit, or you can create multiple disclaimers for any combination of messages, or create individual
disclaimers for individual senders. To associate a disclaimer with an individual sender, use the Policy
document to define an Explicit policy that applies to specific individuals or groups. To associate multiple

790 Lotus Domino Administrator 7 Help

disclaimers with combinations of mail messages, you also use policies. For example, use Organizational
polices to create one disclaimer for the Sales organization, another disclaimer for the Accounting
department and so forth.

If multiple disclaimers apply to a given sender, choose the correct disclaimers using a hierarchical
approach with a default disclaimer applying when no other disclaimer applies to the sender. Policies exist
in a hierarchy, ordered from the most specific policy to the least specific. For example, the most specific
policy for an individual is an Explicit policy that applies directly to that person. The next most specific
policy could be an organizational policy defined for all members of that individual’s entire organization.
In this case, using a hierarchical model, the Explicit policy would be used. To ensure that all Internet mail
is assigned a disclaimer, you can also create one general disclaimer to be used if no other disclaimer
applies to the sender’s mail message.

Use the Mail policy settings document to ensure that the correct disclaimer for a given sender is available
on the server for the mail router and is also deployed to the Notes mail client.

For information about the mail policy settings document, see the topic Creating a mail policies settings
document.

Using message disclaimers with S/MIME signed and encrypted messages

You can add disclaimers to all messages, including signed and encrypted messages.

The Message Disclaimers feature is primarily designed for use with Internet-bound messages. While It is
possible to add disclaimers to S/MIME signed and encrypted messages at the mail router, S/MIME
signed and encrypted messages are not handled well by Notes. When an S/MIME signed message has a
disclaimer added and is received by a Notes user, the message body can be viewed, but the signature
cannot be verified. When an S/MIME encrypted message with a disclaimer added to it is received by a
Notes user, the message body can not be viewed and the message can not be decrypted.

Whenever possible, use the Notes client to add disclaimers instead of adding them from the server. Issues
with signed and encrypted messages do not apply to disclaimers added from the Notes client because the
disclaimer is added before the message is signed. Issues with character sets also do not apply to
disclaimers added from the Notes client because the Notes client determines the Internet character set
used for outgoing messaging. Adding disclaimers at the Notes client avoids any potential performance
problems or ″bottlenecks″ at the router.

Enabling message disclaimers from the server

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Router/SMTP - Message Disclaimers tab.
6. Complete these fields on the Message Disclaimers tab:

Field Action
Message disclaimers Choose one:
v Enabled -- Allows message disclaimers to be added by the
server.
v Disabled -- Prevents message disclaimers from being
added from the server.

Chapter 30. Customizing the Domino Mail System 791

Field Action
Add disclaimers to S/MIME signed or encrypted Choose one:
messages v Enabled -- Adds the message disclaimers to S/MIME
signed or encrypted messages, as well as to other
messages.
v Disabled -- Prevents message disclaimers from being
added to S/MIME signed or encrypted messages.
Logging level Choose a logging level to be applied when adding message
disclaimers. The logging level determines the quantity of
information that is logged.

This field appears when you choose Enabled in the Message

disclaimers field.

7. Click Save and Close.

Enabling message disclaimers on the Notes client

Use the Mail policy settings document to enable or disable the use of message disclaimers by the Notes
client.

See the topic Creating a mail policy settings document.

Mail journaling
By default, after the Router processes a message, it does not retain a copy of the message. That is, after
ServerA successfully sends a message to ServerB, the Router on ServerA deletes the message from its
MAIL.BOX database. Likewise, when ServerB successfully transfers or delivers the message to the next
server on the routing path, the Router on ServerB removes the message from its MAIL.BOX database.

To comply with laws or regulations that apply to your business, your organization may be required to
save a copy of every message processed by the local mail system and permanently store or otherwise
process the message copies. For example, government agencies such as the Securities and Exchange
Commission (SEC) require a business to retain all messages related to the transactions they undertake.

Mail journaling enables administrators to capture a copy of specified messages that the Router processes
by the Domino system. Journaling can capture all messages handled by the Router or only messages that
meet specific defined criteria. When mail journaling is enabled, Domino examines messages as they pass
through MAIL.BOX and saves copies of selected messages to a Domino Mail Journaling database
(MAILJRN.NSF) for later retrieval and review. Mail journaling works in conjunction with mail rules, so
that you create a journaling rule to specify the criteria for which messages to journal. For example, you
can journal messages sent to or from specific people, groups, or domains. Before depositing messages in
the Mail Journaling database, the Router encrypts them to ensure that only authorized persons can
examine them. Journaling does not disrupt the normal routing of a message. After the Router copies a
message to the Mail Journaling database, it continues to dispatch the message to its intended recipient.

Domino mail journaling differs from message archiving. Journaling works dynamically, making a copy of
each message as it passes through MAIL.BOX to its destination and placing the copy in the Mail
Journaling database. A copy of the message is retained, even if the recipient, or an agent acting on the
recipient’s mail file, deletes it immediately upon delivery. Archiving is used to reduce the size of an
active mail file database by deleting messages from one location and moving them to an offline database,
usually in another location, for long-term storage. Archiving acts on messages that have already been
delivered. Journaling is performed automatically by the server; while archiving is a manual operation,
performed by end users on their own mail files. End users can search for and retrieve messages from a
mail file archive, but only an authorized administrator can examine a Mail Journaling database.

792 Lotus Domino Administrator 7 Help

You can use Domino mail journaling in conjunction with third-party archiving programs to fulfill
long-term storage needs.

To provide access to certain journaling routines, Domino implements several Extension Manager (EM)
hooks. EM hooks enable an executable program library, such as a dynamic link library or shared object
library, to register a callback routine that will be called before, after, or before and after Domino performs
selected internal operations. Using EM hooks, developers can customize mail processing. For example,
EM hooks to the Journaling task could be used in conjunction with a third-party archiving program to
route certain messages directly to an archive center. For more information about Extension Manager, see
the IBM Lotus C API Toolkit for Notes/Domino 7. The toolkit is available at http://www.lotus.com/capi.

Setting up mail journaling

There are two steps to configure journaling:
v Setting up the Mail Journaling database
v Specifying which messages to journal

Setting up the Mail Journaling database

By default, mail journaling is not enabled. You enable journaling from the Configuration Settings
document. To set up the Mail Journaling database, you specify where to store journaled messages and
then set options for managing the security and size of the database.

After you enable journaling, Domino automatically creates the Mail Journaling database in the specified
location.

To set up the Mail Journaling database:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers where you want to journal
mail, and click Edit Configuration.
5. Click the Router/SMTP - Advanced - Journaling tab.
6. Complete the following fields, and then click Save & Close:

Field Description
Journaling Specifies whether the server supports mail journaling. Choose one:
v Enabled - Domino supports mail journaling on the servers governed by this document. To
journal mail, create a server mail rule with the action ″Journal this message.″
v Disabled - (default) Mail journaling is not supported on the servers governed by this
document.
Field encryption Specifies the names of Notes message fields that Domino does not encrypt when adding
exclusion list messages to the Mail Journaling database. Encrypted fields cannot be displayed in a view. List
any fields you want to display in a view. By default, the following fields are not encrypted:
Form, From, Principal, and PostedDate.
Note: When using a mail-in database for journaling, Domino does not automatically encrypt
messages added to the database. To encrypt messages in a mail-in database use the Mail-in
database document to specify encryption of incoming messages.

Chapter 30. Customizing the Domino Mail System 793

Field Description
Method Specifies the location of the Mail Journaling database. Choose one:
v Copy to local database - (default) The Router copies each journaled message to a database on
the local server. If it does not already exist, Domino creates a local Mail Journaling database
on the server. If the Configuration Settings document applies to multiple servers, Domino
creates a unique Mail Journaling database on each server.
v Send to mail-in database - The Router copies each journaled message and sends it to a
specified mail-in database. The specified database must already exist and must have a Mail-in
database document in the Domino Directory. The mail-in database used for journaling may be
on any Domino server, including the local server. Specify the mail file where journaled
messages are to be sent in the Mail Destination field. When using a mail-in database for
journaling, be sure to encrypt messages when adding them to the database. To encrypt
messages sent to a mail-in database, enable encryption on the Administration tab of the
Mail-in database document.
Database name If you specified ″Copy to local database″ as the journaling method, specify the file name you
want Domino to use when it creates the Mail Journaling database. The default name is
MAILJRN.NSF.
Mail destination If you specified ″Send to mail-in database″ as the journaling method, use this field to enter the
name of the mail-in database to which the Router forwards messages to be journaled.

Click the down-arrow to select the name of the mail-in database from the Domino Directory.
Note: You must create the mail-in database beforehand; Domino does not automatically create
mail-in databases for journaling.
Encrypt on behalf If you specified ″Copy to local database″ as the journaling method, enter the fully qualified
of user Notes Name of the user whose certified public key Domino uses to encrypt messages added to
the database. To ensure privacy, consider creating a special user ID for reviewing journaled
messages, and protect the ID with multiple passwords.

To encrypt messages sent to a mail-in database, enable encryption on the Administration tab of
the Mail-in database document.
Database For local Mail Journaling databases, the entry in this field specifies how Domino controls the
Management - size of the Mail Journaling database. When the database management method in effect calls for
Method Domino to create a new Mail Journaling database, on the day that it creates the new database, it
does so at approximately 12:00 AM. Choose one of the following methods:
v Periodic Rollover - (default) When the current Mail journaling database reaches the age
specified in the Periodicity field, Domino renames the existing Mail Journaling database and
creates a new Mail Journaling database with the original name.
v None - Domino does not automatically control the size of the Mail Journaling database. If you
do not use one of the available methods for controlling database size automatically, be sure to
monitor the database size and use appropriate tools to archive the journal data.
v Purge/Compact - Domino deletes documents from the database after the number of days
specified in the Data Retention field and then compacts the database.
v Size Rollover - When the current database reaches the size specified in the Maximum size
field, Domino renames the database and creates a new Mail Journaling database with the
original name.
Periodicity If you specified Periodic Rollover in the preceding field, Domino displays this field for
specifying the length, in days, of the rollover interval. The default value is 1 day.
Data Retention If you specified Purge/Compact in the Database Management-Method field, Domino displays
this field for specifying the time, in days, that a message remains in the Mail Journaling
database before being deleted.
Maximum size If you specified Size Rollover in the Database Management-Method field, Domino displays this
field for specifying a size limit, in megabytes (MB), for the Mail journaling database. After the
database reaches the specified size, Domino renames it and creates a new one.

794 Lotus Domino Administrator 7 Help

 The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″
For information on Mail-in database documents, see the chapter ″Rolling Out Databases.″
For more information on the different journaling and database management methods, and on securing
the Mail Journaling database, see the topic ″Managing the Mail Journaling database″ later in this
chapter.

Managing the Mail Journaling database

When setting up the Mail Journaling database, you must specify:
v The journaling method
v Security settings
v How to manage database size

Specifying the journaling method: There are two methods available for journaling messages, copying
messages to a local database (local journaling) and forwarding messages to a mail-in database (remote
journaling). In local journaling the Router moves messages from MAIL.BOX to a Mail Journaling database
on the same server. If you enable local journaling on more than one server, each server maintains its own
unique Mail Journaling database. Since local journaling doesn’t require messages to be transferred
between servers to reach the Mail Journaling database, this is the preferred method for minimizing
network traffic.

Remote journaling lets you journal messages from multiple servers to a single location, sending them to
the mail-in database specified in the ″Mail Destination″ field. Domino does not automatically create
mail-in databases for journaling; you must manually create both the destination database and the
necessary Mail-in database document.

Using a mail-in database to journal messages greatly increases mail traffic, since messages must travel
over the network to be deposited in the Mail Journaling database.

For information about using Mail-in databases, see the chapter ″Rolling Out Databases.″

Managing security of the Mail Journaling database: The Mail Journaling database contains private
information about many people. Domino employs two methods to restrict access to the Mail Journaling
database. First, it conceals the database from users. By default, Domino makes the Mail Journaling
database ″invisible″ to users; that is, the database does not appear in the Open database dialog box when
a user opens a new database. To display the database, check ″Show in ’Open Database’ dialog″ on the
Design tab of the Database properties dialog box.

Second, when local journaling is enabled, Domino encrypts the information in the Mail Journaling
database, using the Certified public key of a specified Notes user. To specify the ID to use when
encrypting messages, enter a user name in the field ″Encrypt on behalf of user.″ By default, Domino
exempts certain summary information fields from encryption so that the information they contain can be
used in database views. You can specify other fields to exempt in the field, ″Field encryption exclusion
list.″

Setting up a Mail Journaling user: To maximize security, create and register a special user ID for the
Mail Journaling database and assign multiple passwords to the ID. Distribute passwords in such a way
that no one person knows them all, so that the consent of multiple parties is required to view the
contents of the database.

For information on assigning multiple passwords to an ID, see the chapter ″Protecting and Managing
Notes IDs.″

Chapter 30. Customizing the Domino Mail System 795

Providing access to the Mail Journaling database for users who are not server administrators: Domino
encrypts journaled messages with the user ID specified on the Router/SMTP - Advanced - Journaling tab
of the Configuration Settings document. The ID you specify can be the ID of an existing server
administrator or another user ID. By default the ACL of the Mail Journaling database includes only users
listed in the Administrators field of the Server document’s Security tab. If the ID for encrypting messages
does not belong to a server administrator, you must add this user to the database ACL before the user
can access the database.

The user’s name is preserved in the ACL during daily rollovers and size rollovers, but if you remove the
Mail Journaling database, the next time the server starts, it automatically creates a new database using
the original ACL. Add the ID used for encryption in square brackets [User.ID] to the ACL of the template,
JOURNAL.NTF, to automatically add the user’s name to the ACL of JOURNAL.NSF.

Enabling encryption for remotely journaled messages: By default, mail-in databases do not encrypt
incoming mail. To ensure privacy when sending journaled messages to a mail-in database, enable the
mail-in database to encrypt incoming mail. When enabling encryption for a mail-in database, you select a
user whose Notes certified public key Domino uses to encrypt messages stored in the database.

For more information on setting up a mail-in database, see the chapter ″Rolling Out Databases.″

No encryption of previously encrypted messages: A message that Notes has previously encrypted for
its recipients is not re-encrypted with the certified public key of the specified Journal user. As a result,
when depositing encrypted messages in the Mail Journaling database, Domino preserves the original
encryption, so that the message content cannot be decrypted with the ID of the designated Mail
Journaling user, unless, of course, that user was included in the original recipient list. A Mail Journaling
user who was not on the recipient list can view header information only.

Managing the size of the Mail Journaling database: Depending on how you set up journaling rules, the
size of the Mail Journaling database may increase rapidly. Domino provides several methods for
automatically controlling the database size:

Size management method Description

Periodic Rollover
(Default) Domino creates a new Mail Journaling database at an interval in specified
in days, The default interval is one day. The new database takes its name from the
name of the current database (for example, MAILJRN.NSF) and is created at
approximately 12:00 AM of the specified day. Domino renames the current database
using the format:

MJ<date>.NSF

where <date> is an 8-digit number representing the current date in a format that
standardizes the database name. The name is created using this format:
MJMMDDYYYY.NSF.
Purge/Compact Domino deletes documents from the database after a specified number of days and
then compacts the database to eliminate deletion stubs and white space.

796 Lotus Domino Administrator 7 Help

Size management method Description
Size Rollover Domino creates a new Mail journaling database when the current database reaches
a specified size, renaming the old database using the format:

MJXXXXXX.NSF

where XXXXXX represents a number series starting at 000001 and increasing by 1

with each successive rollover, for example, MJ000001.NSF, followed by
MJ000002.NSF, and so forth. If a database with the next name in the sequence
already exists on the server, Domino uses the next number in the sequence. The
new Mail journaling database uses the original database name (for example,
MAILJRN.NSF). Because Domino may be unable to determine the exact size of any
message attachments before adding a message to the Mail journaling database, the
database may exceed the maximum size after the addition of a new message. If this
happens, the next message added to the database triggers creation of the new
database.

These methods for controlling database size are not available if you use a mail-in database for journaling
messages. If you select this method of journaling, be sure to monitor the database size and use
appropriate tools to archive data to another location.

Specifying messages to journal

After you enable journaling, set mail rules on the Configuration Settings document to specify which
messages to journal.

For information about setting mail rules, see the topic ″Setting server mail rules″ earlier in this chapter.

If you specify All documents and a message is returned as undeliverable, Domino journals the delivery
failure report as well as the original message.

When Domino journals a message, it sets a journal flag on the message before transferring it to the next
server on the route. This ensures that servers later in the routing path do not journal the message again.
When the Router on the destination mail server delivers the message to the user’s mail file it removes the
journal flag so to that the user remains unaware that the message was been journaled.

On servers running the ISpy task, this task sends mail probes in the form of trace messages to test mail
connectivity approximately every five minutes. Under normal use, the ISpy task automatically deletes
these probes from the ISpy mail-in database and the only trace of them are entries in the Routing events
view of the server log file and on the server console. However, if you enable a journaling rule on these
servers and specify the condition ″All documents,″ the Mail Journaling database will capture each trace
message that the ISpy task sends. To prevent the Mail Journaling database from filling up with these
entries, configure a rule exception for messages where the sender includes ″ISpy.″

Retrieving messages from the Mail Journaling database

Administrators can examine the contents of the Mail Journaling database by logging in as the user for
whom Domino encrypts journaled messages. A user who is listed in the database ACL, but who is not
the specified journal user (and thus does not own the correct private decryption key), may be able to
access the Mail Journaling database but will receive the following error when attempting to open
messages in the database:
You cannot access portions of this document because it is encrypted and was not intended for you.

By default, the Mail Journaling database does not appear in the Open database dialog box. You can open
the database by specifying its file name -- for example MAILJRN.NSF -- in the Filename field in the Open
Database dialog box. To list the database in the Open Database dialog box, check ″Show in ’Open
Database’ dialog″ on the Design tab of the Database properties dialog box.

Chapter 30. Customizing the Domino Mail System 797

To facilitate searches and provide quick information about journaled messages, the Mail Journaling
database provides a full-text index and several views. You can create views or customize existing ones to
better determine the characteristics of your mail traffic.

Note: Notes database views do not display encrypted fields. By default, Domino encrypts the subject
field of messages added to the Mail Journaling database, when you open a view of the database, the
Subject column may be blank. To display message subjects, add ″Subject″ to the ″Field encryption
exclusion list.″

For information on how to specify the fields to encrypt when journaling mail, see the topic ″Setting up
the Mail Journaling database″ earlier in this chapter.

View name Description

By Hierarchy Displays messages by the Internet domain hierarchy (for messages received over SMTP) or
Notes organizational certifier hierarchy (for messages received over Notes routing) of the
sender. The Count column displays separate message totals for all messages, for messages
received from each node in the hierarchy, and for messages received from each sender. Expand
entries for each node to view messages in descending order by date and time (most recent
message first). In addition to the date, individual message entries display the size in bytes and
the message subject, if that field is specified in the Field Encryption Exclusion list.
By Sender Displays messages by the name of the sender. Senders may be listed more than once: by their
Internet address for messages received by the server over SMTP routing and by their Notes
address for messages received over Notes routing. The Count column displays the total
number of messages routed and the number of messages from each sender. Expand sender
entries to view messages in descending order by date and time (most recent message first). In
addition to the date, individual message entries display the size in bytes and the message
subject, if that field is specified in the Field Encryption Exclusion list.
By Size Displays messages in descending order by size in bytes. Click the column head to reverse the
order. Individual message entries display the message date, sender (From), and subject, if that
field is specified in the Field Encryption Exclusion list.
By Date (Default) Displays messages in ascending order by date, with the most recent date last. The
Count column displays the number of messages routed on each date. Expand date entries to
view messages sorted in descending order by time, with the most recent message listed first.
Individual message entries display the message time, sender (From), and subject, if that field is
specified in the Field Encryption Exclusion list.
By Form Displays messages in ascending alphabetical order by the name of the Notes message form
used; for example, Delivery report, Memo, Reply, Trace Report, and so forth. Uncategorized
forms are listed last. The Count column displays the number of messages routed for each form
type. Expand form entries to view messages sorted in ascending order by date and time.
Individual message entries display the message date, sender (From), and subject, if that field is
specified in the Field Encryption Exclusion list.
By Attachments Displays messages in ascending order by attachment size in bytes. Column totals provide the
average size in bytes of journaled attachments and the total size of all journaled attachments.
Individual message entries display the attachment name, sender (From), date, and subject, if
that field is specified in the Field Encryption Exclusion list.

Viewing messages that use forms not included in the Mail Journaling database: The Mail Journaling
database does not include all of the form types that can be used to send messages. If a message copied to
the database was sent using a form that is not part of the Mail Journaling database design, the database
substitutes the memo form to display the message. To view the document using the original form type,
copy the form design element into the design of this database.

Setting inbound and outbound MIME and character set options

You can control how servers convert MIME items and international character sets for inbound and
outbound messages by specifying options on the Configuration Settings document.

798 Lotus Domino Administrator 7 Help

You can specify settings for the following:
v Return receipt processing
v Primary and secondary character set groups
v Message conversion options
v Font and message options for international languages
v Advanced inbound MIME options
v Advanced outbound MIME options
v Mapping MIME types to file extensions

Enabling Domino to process return receipts for SMTP messages

When a Notes mail user sends a message to another Notes user and selects the Return Receipt delivery
option, the mail client adds the Notes ReturnReceipt item to the message. The ReturnReceipt item on a
Notes mail message prompts the recipient’s Notes client to generate a notification (the receipt) to the
sender when the recipient opens the message.

By default, Notes return receipts are not compatible with SMTP messages, which use MIME headers to
identify return receipt requests. For return receipts to work seamlessly when a Notes message is
converted to MIME and vice versa, you must set up Domino to translate between the two formats.

Enabling return receipts lets Domino honor return-receipt requests on inbound SMTP mail and add
return-receipt requests to outbound SMTP mail. On inbound messages, Domino converts MIME
return-receipt headers to Notes ″ReadReceipt″ requests before delivering the message. On outbound
Internet mail, Domino maps a Notes return receipt request to the MIME header specified in the Return
Receipt Mapping field.

There are two MIME headers that can be used to request a read receipt. You can specify which header
Domino uses for outbound mail when converting a Notes return-receipt request into a MIME
return-receipt request. The Return-Receipt-To header is the older method; the Disposition-Notification-To
header is the newer, preferred method. Choose the method supported by the majority of the systems to
which your organization sends mail. For return receipts to work, the receiving server and client must
both support the header used. Newer mail clients may not support the older header.

When you disable return receipts, Domino ignores the Return-Receipt-To or Disposition-Notification-To
headers on inbound SMTP mail and does not return the return receipt to the sender. It also does not
convert Notes client requests for return receipts into a corresponding MIME header field.

Note: Disabling return-receipt support affects SMTP messages only. Internal messages sent over Notes
routing continue to process return receipts.

Enabling return receipts in your system does not guarantee that your users will receive return receipts
every time they are requested. The Internet mail specifications do not require servers or clients to honor
return-receipt requests. If the recipient’s server does not honor the request, it is ignored. Generally, large
organizations with LAN-based mail systems that provide their own internal return-receipt features
implement return-receipts over SMTP, while commercial Internet mail systems, such as Web-based mail
systems tend not to.

Requesting Return Receipts from an IMAP or POP client: Disabling return receipts on a server does
not affect non-Notes clients. If users request return receipts for messages sent from an IMAP or POP
client, such as Microsoft Outlook, the client generates the proper MIME header (that is, either a
Return-Receipt-To or Disposition-Notification-To field in the header). Domino does not strip the messages
of the return receipt request. Domino leaves existing MIME headers intact on outbound messages and
sends a MIME message that asks the receiving server to send a receipt when it delivers the message.

To enable return receipts:

Chapter 30. Customizing the Domino Mail System 799

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the MIME - Conversion Options - General tab.
6. Complete these fields, and then Click Save & Close:

Field Description
Return Receipts Choose one:
v Enabled to allow the sender of a message to receive a return receipt.
v Disabled to prevent the sender of a message from receiving a return receipt.
Return Receipt Choose one:
Mapping v Use Disposition-Notification-To - (default) When converting an outbound Notes message
that includes a return receipt request into MIME format, the server converts the Notes
ReturnReceipt item into the MIME header item Disposition-Notification-To.
v Use Return-Receipt-To - When converting an outbound Notes message that includes a return
receipt request into MIME format, the server converts the Notes ReturnReceipt item into the
MIME header item Return-Receipt-To.
Note: This field appears only if you enable Return Receipts.

Note: Domino does not map the Return Receipt request to one of the MIME headers if the address
specified in the Disposition-Notification-To or Return-Receipt-To header does not match the sender’s
address. Domino sends return receipts only to the sender.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Setting the primary and secondary character set groups

In the text parts of a MIME message, character set tags, such as US-ASCII or EUC-KR (Korean), specify
how Domino interprets the text data and renders it into recognizable characters. The value that represents
a character in one character set can represent a different character in another character set.

When converting a MIME message into Notes rich-text, Domino uses the information in the character set
tags to determine the appropriate characters for representing the message text. Similarly, when Domino
converts a Notes rich-text message into MIME, it must determine which MIME character set tag to apply.

On the MIME - Basics tab of the Configuration Settings document, you can define a primary character set
group and one or more secondary character set groups. These primary and secondary choices control,
among other things, how Domino detects character sets to correctly identify ambiguous text data in a
message when converting inbound MIME messages to Notes rich-text and outbound Notes rich-text
message to MIME.

Note: If your organization sends and receives messages that use US-ASCII characters only, there’s no
need to change the default settings.

Domino can interpret text represented in 16 different character set groups (also known as language
groups) including the Unicode standard for encoding character systems (www.unicode.org/ ). A language
group can correspond to a single language (for example, Japanese) or to a region where multiple
languages use more or less the same characters (for example, Central Europe). A language group can also
support multiple character sets.

800 Lotus Domino Administrator 7 Help

For a list of character set groups and the language codes associated with them, see the topic ″Language
codes supported in Notes and Domino″ later in this chapter.

If the MIME messages your organization receives always contained the correct character set information,
there would be no need to change the default settings. However, some mail systems do not provide
character set information when sending mail. For example, older mail systems may not support MIME at
all, and some Web-based systems enable users to create messages in a given language but don’t correctly
generate MIME character set information when sending the message. Thus a user sending mail from a
Web-based mail system might be able to compose and send messages written in Chinese, but in the sent
message, the character set tag US-ASCII is incorrectly applied to the message text. If your SMTP server is
configured to use the default character set group, it would be unable to correctly convert this message.

In such cases, Domino examines incoming messages to determine the byte range used and identify
unique control codes. It then attempts to match patterns in the incoming message to a probable character
set. This process is effective in distinguishing among certain character sets only. For example, it can
correctly distinguish messages in the CJKT languages (Simplified Chinese, Japanese, Korean, and
Traditional Chinese ) from each other and from an English message), but it cannot distinguish between
messages in English or any other Western languages, which tend to use the identical bytes and byte
ranges.

To ensure accurate character set detection for the CJKT languages, configure a priority order among the
languages by specifying a primary and secondary character. For example, if Domino cannot distinguish
whether a MIME message uses EUC-KR (a Korean character set) or GB2312 (a Simplified Chinese
character set), it uses the priority order assigned to the primary and secondary character set groups to
determine which character set to use in converting the message to Notes rich-text. Domino chooses the
primary character set first, then the secondary character set (in an undefined order -- the order of
multiple secondary choices doesn’t matter), then the operating system group (for operating systems
where the locale can be queried).

When converting outbound messages to MIME format, Domino chooses a MIME character set based on
the text of the message. Outbound messages are examined by the Router and the appropriate character
set is selected for the message. For example, messages in Japanese are converted using the ISO-2022-JP
character set; messages in Simplified Chinese, using the GB character set; messages in Traditional
Chinese, using the Big5 character set; and messages in French, using the ISO-8859-1 character set. When
Domino cannot automatically detect which character set to use, as with some European languages, it
refers to the primary, secondary, and operating system groups, in that order, to determine which character
set to use. For example, if all of the characters in a message could be French or Turkish, Domino uses the
information about the primary and secondary character set groups to determine which character set to
use.

To set the primary and secondary character set groups:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Basics tab, and in the field International MIME Settings for this document, select Enabled.
6. Click the MIME - Basics tab.
7. Complete the following fields and click Save & Close:

Field Enter
Primary character set group The character set group for this domain’s primary language. English is the
default value. Choose the language or region appropriate for your organization,
for example, Simplified Chinese.

Chapter 30. Customizing the Domino Mail System 801

Field Enter
Secondary character set groups The character set groups for other languages typically used in this domain. By
default, no secondary character set group is configured. Choose the language or
region(s) appropriate for your organization, for example, Western. You can
specify multiple secondary character set groups.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Language codes supported in Notes and Domino

The following table lists each character set group supported in Notes and Domino 7 together with the
character set language codes and encoding types for that group. Where multiple language codes or
encoding types may be used for a given character set group, the default code and encoding for the group
are listed first. For each character set group, the default character set language code and encoding are the
same for message bodies and headers unless otherwise indicated.

Characters set group Character set language code Header and body encoding
Arabic Windows-1256, ISO-8859-6 Base64, Quoted Printable, None
Baltic Rim Windows-1257 Quoted Printable, Base64, None
Central Europe ISO-8859-2, Windows-1250 Quoted Printable, Base64, None
Cyrillic KO18-R, ISO-8859-5, Windows-1251 Base64, Quoted Printable, None
English US-ASCII None, Base64, Quoted Printable , None
Greek Windows-1253, ISO-8859-7 Base64, Quoted Printable, None
Hebrew Windows-1255, ISO-8859-8, ISO-8859-8-I Base64, Quoted Printable, None
Japanese ISO-2022-JP Header - Base64, Quoted Printable, None

Body - None, Base64, Quoted Printable,

None
Korean Header - EUC-KR, ISO-2022-KR Header - Base64, Quoted Printable, None

Body - ISO-2022-KR, EUC-KR Body - None, Base64, Quoted Printable,

None
Simplified Chinese GB2312, GB18030, HZ-GB2312 Base64, Quoted Printable, None
Thai TIS-620 Base64, Quoted Printable, None
Traditional Chinese Big5, EUC-TW Base64, Quoted Printable, None
Turkish Windows-1254, ISO-8859-9 Quoted Printable, Base64, None
Unicode UTF-8, UTF-7 Base64, Quoted Printable, None
Vietnamese Windows-1258, TCVN3 Quoted Printable, Base64, None
Western ISO-8859-1, ISO-8859-15, Windows-1252 Quoted Printable, Base64, None

Specifying inbound and outbound MIME conversion options

If a server sends or receives messages in MIME format, you can set options to control how Domino:
v Converts outbound Notes rich-text messages into MIME for sending over SMTP
v Converts inbound messages received in MIME format into Notes rich-text messages

802 Lotus Domino Administrator 7 Help

Configuring how Domino converts outbound Notes rich-text messages to MIME format: Outbound
conversion options apply to messages exported from the server. This includes Notes rich-text messages
sent outbound over SMTP to another Domino server or other mail host and messages retrieved by the
IMAP or POP3 service for sending to a client.

Settings in this section do not apply to messages delivered to mail files on the server or messages
transferred over Notes routing. Nor do they apply to messages sent in MIME format from the client --
either messages sent by POP3 or IMAP clients or messages from a Notes client where the Location
document specifies the use of MIME format for messages sent to Internet addresses.

Note: If the Internet mail format specified in the client’s current Location document is set to Notes
rich-text (Mail tab - Format for messages addressed to Internet addresses), the client sends all messages in
Notes rich-text, even if the Internet mail format in the User Preferences dialog box (File - Preferences -
User Preferences - Mail - Internet - Internet Mail Format) is set to send HTML.

Providing the richest content when converting messages on internal servers: By default, when
converting messages in Notes rich-text format to MIME format, Domino generates MIME messages in
plain text format only, resulting in a loss of formatting. This default setting, which is required to ensure
that recipients can read messages that are received by SMTP servers that do not correctly process
multipart MIME messages, is not necessary for internal servers. To enable conversion on internal servers
to generate the richest possible MIME from messages in Notes format, change the default Message
Content setting to ″Convert from Notes to Plain Text and HTML.″

To specify outbound MIME conversion options:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the MIME - Conversion Options - Outbound tab.

Chapter 30. Customizing the Domino Mail System 803

6. Complete the following fields and then click Save & Close:

Field Description
Attachment encoding When a Notes client sends a rich-text message with a file attachment that contains 8-bit
method data -- for example, program, image, sound, video, and application files -- Domino
encodes the attachment data as ASCII text for SMTP transport. Choose the encoding
method best suited to the file types sent and supported by the majority of likely message
recipients.

Choose one of the following:

v Base64 - (default) This is the preferred method for encoding non-text data attachments
when sending messages to recipients who use MIME-compliant mail programs. Domino
adds a MIME tag to describe what type of file was sent. Sending files with MIME
encoding ensures that the recipient receives binary data (non-text) intact. Base64
encoding converts binary data in attachments into a subset of the US-ASCII character
set and is slightly more efficient than UUencode, resulting in a transmitted file
approximately 37% larger than the original.
v Quoted Printable - This method is best suited to sending text-based files to recipients
that use MIME-compliant mail programs. Quoted-Printable (QP) encoding replaces each
special character in the attachment with an equal sign ″=″ followed by two hexadecimal
digits, which represent the 8-bit character code. Printable ASCII characters are left
unencoded. QP provides efficient encoding of text-based files, creating an encoded file
that’s only a fraction larger than the original. However, for non-text files, QP encoding
can result in encoded files that are two to three times the size of the original.
v UUencode - Use UNIX-to-UNIX encoding on servers that send message attachments
primarily to recipients who use UNIX or older PC mail programs. UUencode increases
the size of the encoded file by about 42%.
v BinHex - Use primarily when sending binary data to recipients who use Macintosh mail
programs
Note: This field does not control encoding for messages sent from the Macintosh version
of the Notes client. To configure attachment encoding for messages sent from Macintosh
clients, use the field ″Macintosh attachment conversion″ on the MIME - Advanced -
Advanced Outbound Message Options tab.

804 Lotus Domino Administrator 7 Help

Field Description
Message Content Specifies how Domino structures the MIME content of messages when converting Notes
rich-text messages before sending them over SMTP. Choose one:
v Convert from Notes to plain text - (default) Domino converts the text in a Notes
rich-text document to plain text. If the message contains file attachments or images,
Domino creates a multipart/mixed MIME message with the images and attachments
following the text/plain part. Use this option in organizations that send most of their
outbound SMTP mail to mail systems that are unable to handle MIME messages
containing multiple text parts (for example, messages with a multipart/alternative
structure that includes text/plain and text/html parts).
v Convert from Notes to HTML - Domino converts the text in a Notes rich-text document
to HTML. If the message contains file attachments, Domino creates a multipart/mixed
MIME message and includes the attachment in that part. If the message contains
images, Domino includes the images in the message body by creating a
multipart/related part.
v Convert from Notes to Plain Text and HTML - Select this option on internal server for
Domino to best preserve rich-text content when converting messages from Notes format
to MIME. Domino converts the text in a Notes rich-text document to both plain text and
HTML by creating a multipart/alternative body part that contains both the text/plain
and text/html parts. If the message contains file attachments, Domino creates a
multipart/mixed MIME message and includes the attachment in that part. If the
message contains images, Domino creates a multipart/related part and includes the
image in that part along with the text parts.
v Create multi-part alternative including conversion and encapsulation - Domino converts
Notes rich-text messages and creates an additional file attachment that contains a Notes
database with the original message in it. This option results in a message nearly twice
the size of the original. Use this option only in organizations that send most of their
outbound SMTP mail to recipients using Notes 4.x clients.
Convert tabs to spaces Choose one:
v Yes - Enables the Router to change tabs to spaces when converting outbound messages
to MIME format. Use this option only in organizations that send most of their outbound
SMTP mail to recipients using mail clients that do not recognize tabs.
v No - (default) The Router does not change tabs to spaces when converting outbound
messages to MIME format.
Outbound line length (Default = 75) The maximum line length from left to right for the body of outbound
messages; useful when a message contains long lines of text without spaces -- for example,
URLs.

If there is a table or forwarded mail headers, then the line length default is doubled so no
line break occurs until 150.
Lookup Internet All addresses on messages sent to Internet recipients must be in Internet format (RFC
address for all Notes 821/822 format). A Notes user may send a message to both Notes addresses and Internet
addresses when addresses. To specify how Domino converts the addresses of Notes recipients on messages
Internet address is not sent to the Internet, choose one:
defined in document v Enabled - On outbound Internet messages, if the address of any recipient is in Notes
format, Domino reads the user’s Internet address from the Person document and adds it
to the message before sending.
v Disabled - (default) Domino forms Internet addresses by converting spaces into
underscores and encoding Domino domains with percent signs. For example:
John_Smith%Notes@acme.com

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Chapter 30. Customizing the Domino Mail System 805

Configuring how Domino converts inbound MIME messages to Notes rich-text
Inbound conversion options apply to messages received over SMTP in MIME format, which must be
converted to Notes rich-text format. Conversion to Notes rich-text format is necessary when the storage
preference for the recipient’s mail file is set to Notes rich-text format, or when the route to the destination
mail file includes Domino servers earlier than Release 5.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the MIME - Conversion Options - Inbound tab.
6. Complete the following fields and then click Save & Close:

Field Enter
Use character set Choose one of the following:
auto-detection if message has v Yes - Domino examines the text of inbound messages to determine the character
no character set information set if it is not specified in the message. Select this option if your site routinely
receives non-MIME messages that are encoded in character sets other than ASCII.
Provides the most accurate rendering of the original character information, but
slows performance.
v No - (default) Character set auto-detection is disabled.

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Setting font and message options for international languages

A single Domino SMTP server can handle inbound and outbound messages in any language group or
character set, including double-byte character sets. For each character set group, for example, Simplified
Chinese, Domino provides default settings that control how servers convert messages in that character set
group from Notes rich-text format to MIME and vice-versa. You can change the default settings to
customize conversions for specific languages.

Inbound settings specify font options that control how the text of a MIME message using a given
character set tag displays in Notes. Outbound settings determine the character set tag and encoding to
apply when converting Notes rich-text messages to MIME.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the Basics tab. If it is not already selected, select the field ″International MIME Settings for this
document.″
6. Click the MIME - Settings by Character Set Groups tab.

806 Lotus Domino Administrator 7 Help

7. Complete the following fields and then click Save & Close:

Field Enter
For outbound message options below When unchecked (default), Domino’s Outbound Message Options are set to
use all possible choices (Advanced use the standard character set and encoding method for the language group
users) specified in the field ″MIME settings by character set.″ The options in the
Character Set field are limited to the standard character sets for the
language group.

MIME settings by character set group
Check this box to enable use of nonstandard character set choices in the
header and body of messages in any language group.
Click the drop-down list to choose the language group to configure. You
can accept the default settings or configure specific settings for one or more
language groups.

The language group displayed at the time you save and close the document
is not the only one for which Domino saves settings. After you save the
Configuration Settings document, Domino retains the settings for each
language group that you modified.

These fields allow you to override default values for character sets, fonts, and so on, for individual
character set groups.

Note: If no Server Configuration document exists, Domino uses the default typeface and point size
settings. The default typeface used for HTML text is Default Sans Serif, and the point size is
determined by the sender of the message. The default typeface for Plain Text (US-ASCII) is Default
Monospace with point size of 10.

To set character set options for inbound messages:

1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
4. Click the MIME - Settings by Character Set Groups tab.
5. In the Inbound Message Options - Font Options section, complete the following fields, and then click
Save & Close:

Field Enter
HTML Proportional The typeface style to be used for proportional type in inbound SMTP messages.

(default = Default Serif)

HTML Mono-spaced The typeface to be used for monospaced type in inbound SMTP messages.

(default = Default Monospace)

HTML Size The point size to use for HTML text in inbound SMTP messages.

(default = 12)
Plain text The typeface to be used for plain text in inbound SMTP messages.

(default = Default Monospace)

Plain text size The point size to use for plain text in inbound SMTP messages.

(default = 10)

Chapter 30. Customizing the Domino Mail System 807

 Note: The font list displays every font available to the client system. However, when converting
messages, Domino uses the ″Default″ fonts (Default Serif, Default Sans Serif, Default Monospace, and
Default Multilingual) only. If you select a font other than one of the four ″Default″ fonts, Domino
converts the text in all incoming messages to Default Monospace.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

To set character set options for outbound messages: You can specify the character set and encoding
type for the header and body text of outbound messages. The settings you select do not affect
attachments. For each language (or region) there is a default character set. For example, for Western
Europe the default character set is ISO-8859-1, but other Latin character sets can also be used. You can
indicate the specific character set and encoding to be used for outbound SMTP message headers and
body content. In general, use the same character set for both the headers and the body of outbound
messages. However, because some characters set groups, such as Korean, typically use different character
sets for the headers and body, by default, for these languages, the character set specified for header text
differs from the character set for body text.

For a complete list of character set groups and the default characters sets used in the headers and body
of messages in those groups, see the topic ″Language codes supported in Notes and Domino″ earlier in
this chapter.
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
4. Click the Basics tab and select ″International MIME settings for this document.″
5. Click the MIME - Settings by Character Set Groups tab.
6. In the Outbound Message Options section, complete the following fields, and then click Save & Close:

Field
Header - Character Set
Body - Character Set
Header - Encoding
Choose
The character set Domino uses to display message headers. The default entry depends
on the character set language group currently selected in the field ″MIME settings by
character set group.″ In most cases, the default entry is the best choice for representing
header text for this language group.
The character set used to display message body. The default entry depends on the
character set language group currently selected in the field ″MIME settings by
character set group.″ In most cases, the default entry is the best choice for representing
body text for this language group.
The encoding method for outbound headers. The default entry depends on the
character set language group currently selected in the field ″MIME settings by
character set group.″In most cases, the default entry is the best choice for encoding
header text for this language group.

Choose one:
v Base64
v Quoted Printable
v None

808 Lotus Domino Administrator 7 Help

Field Choose
Body - Encoding The encoding method for outbound body text. The default entry depends on the
character set language group currently selected in the field ″MIME settings by
character set group.″ In most cases, the default entry is best choice for encoding body
text for this language group.

Choose one:
v Base64
v Quoted Printable
v None

7. The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter, ″Setting Up Mail
Routing.″

Setting advanced inbound MIME options

Set advanced inbound MIME options to control how servers process certain address headers and how
servers decipher messages using undefined or incorrectly defined character sets.
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
4. Click the MIME - Advanced - Advanced Inbound Message Options tab.
5. Complete the following fields, and then click Save & Close:

Field Description
Resent headers take Specifies whether Domino uses resent- headers on inbound messages. When
precedence over original forwarding a message, some mail programs add header lines that describe the
headers forwarding sender. These headers begin with the resent- prefix, such as
″Resent-From:″ The received message contains both the resent- headers and headers
describing the original sender, for example:

From: original-sender

Resent-From: forwarding-sender

When generating a reply to a forwarded message, some older mail programs address
the reply to address specified in the resent-from header. However, most modern mail
programs consider resent- headers to be for informational purposes only and do not
normally use them to generate replies. Instead, when forwarding a message, a
MIME-compliant mail program creates a new message and encapsulates the original
message within this message as a MIME body part of content type message.

Choose one:
v Enabled - When receiving a forwarded message over SMTP, Domino places the
value of the Resent-From header in the From header. Select this option only if a
large number of users in your organization find that when replying to Internet
messages that use resent- headers, their replies are incorrectly addressed to the
original sender, rather than the forwarding sender.
v Disabled - (default) Domino ignores resent- headers in inbound messages.

Chapter 30. Customizing the Domino Mail System 809

Field Description
Remove group names from Specifies whether Domino preserves the names of Internet distribution lists in the
headers message headers of inbound messages. RFC 822 specifies use of a group construct to
allow Internet address headers to include distribution lists. Groups are designated
using either of the following formats:
v Groupname:;
v groupname: person1@domain.com, person2@domain.com, person3@domain.com;
Note: This option does not control the use of Notes/Domino group names in
recipient lists.

Choose one:
v Yes - Domino strips RFC 822 group names from address headers on incoming
SMTP messages.
v No - (default) Domino preserves RFC 822 group names in the address headers of
incoming SMTP messages.
If each recipient’s address Choose one:
does not appear in any v Yes - Enables Domino to resolve differences between addresses in the SMTP RCPT
address header, then add TO commands and the RFC 822 message header. If an address is referenced in the
their address to the BCC list SMTP RCPT TO command, but not in the message header, Domino creates a new
copy of the message and places the address in the BCC: field of the new message.
v No - (default) Domino ignores differences between the recipients listed in the RCPT
TO command and the message header.
For non-MIME messages or Specifies the default character set that Domino uses to render messages with 8-bit
MIME messages with an characters if the message does not contain character set information, and automatic
unknown character set, 8-bit character set detection is disabled (on the MIME - Conversion Options - Inbound tab).
character set is assumed to
be
Character set name aliases Enter the substitute name for the equivalent character set to allow MIME to be
converted to native MIME. An alias allows a character set name tag in an inbound
message to be treated as though it were a different character set.

For example, mapping ″ISO-8859-1″ to ″KOI8-R″ would be useful in an environment

where incoming messages are frequently labeled as ISO-8859-1 (Western) when the
data is really KOI8-R (Cyrillic).

The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.
For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″

Setting advanced outbound MIME options

Outbound MIME settings apply to messages sent over SMTP to another host. They do not apply to
messages delivered to local mail files on the server or messages transferred over Notes routing.

Use the advanced outbound MIME options to specify how servers determine the following message
items:
v Encoding for attachments sent from Macintosh clients
v Use of phrases specifying the sender’s user name in the sender’s Reply address
v Sending of Notes mail items that do not have standard MIME equivalents
v Removal of Notes fields from message headers
v Character set to use when converting multilingual messages
v Character set alias to use in place of one that is typically mislabeled in outgoing messages

810 Lotus Domino Administrator 7 Help

To set advanced outbound MIME options:
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
4. Click the MIME - Advanced - Advanced Outbound Message Options tab.
5. Complete the following fields, and then click Save & Close:

Field Enter
Macintosh attachment The format for Macintosh attachments. Choose one:
conversion v AppleDouble [base64 only] - (default) Provides standard MIME encoding for sending
Macintosh files to recipients using newer Macintosh and PC mail programs.
AppleDouble splits the data fork and the resource fork of the file and encodes the
resulting data in Base 64 for transport. PC clients receiving the attachment discard the
resource fork and use the data fork only.

The AppleDouble header is effectively the resource fork and includes the original Mac file
name of the file. If the AppleDouble data part has a recognizable MIME type, Domino
uses it to label the MIME part of the converted message; for example, the data part of a
Microsoft Word attachment is described as application/msword. If the MIME type cannot
be determined, Domino labels the MIME part as application/octet-stream.
v BinHex4.0 - Sends Macintosh attachments with the MIME type application/mac-
binhex40. Use this method for sending Macintosh files to other Macintosh users who do
not use MIME-compliant mail programs. Because few Windows mail programs can
decode BinHex, this method should not be used when sending files to recipients who
use Windows.
RFC822 phrase Specifies how the server handles phrases in an address header. Choose one:
handling v Do not add phrase (default) - Outbound mail displays the sending user’s RFC 821
address. The Router permits user-defined phrases in recipient addresses.
v Use DN as phrase (Use domain name for the phrase) - The Router constructs an RFC
822-style address using a phrase part derived from the person’s hierarchical,
distinguished name; for example, ″John Jones/Sales/ACME″ <JJones@acme.com>. The
Router permits user-defined phrases in recipient addresses.
v Use alt. name if available - otherwise DN (Use the alternative name or domain name) -
If an Alternate name is specified in the user’s Person document, constructs an RFC
822-style address using it as the phrase part; otherwise uses the hierarchical,
distinguished name; for example, ″John Jones/Sales/ACME″ <JJones@acme.com>. The
Router permits user-defined phrases in recipient addresses.
v Remove phrase - Only RFC 821-style addresses allowed. The Router strips user-defined
phrases in recipient addresses.
v Use CN as phrase - Constructs an RFC 822-style address using a phrase part derived
from the person’s common name; for example, ″John Jones″ <JJones@acme.com>. The
Router permits user-defined phrases in recipient addresses.

Chapter 30. Customizing the Domino Mail System 811

Field Enter
Internet mail server Notes private items are header items present in a Notes rich-text message that do not map
sends Notes private to any of the standard header fields for SMTP messages, as defined in RFC 2822. When
items in messages adding private items to the headers of an SMTP message, Domino adds the prefix
″x-notes-item″ to the field name to indicate that it is a nonstandard field.

Choose one:
v Enabled - When converting Notes rich-text messages for SMTP transport or download
by a POP3 or IMAP client, Domino converts all Notes private items in the message to
custom ″x-notes-item″ headers. The resulting ″x-notes-item″ is a structured header with
parameters that reflect the attributes of the original notes item, for example, data type,
value, summary flags, item name, and so on. Because Notes private items are not
generally used in Internet mail, do not select this option unless you have a specific
reason for sending private items.
Note: Items specified in the field ″Notes items to be removed from headers″ are excluded
from the headers of the converted message.
v Disabled - (default) When converting Notes rich-text messages for SMTP transport,
Domino removes nonstandard Notes header items.
Always send the List the Notes header items to always include as RFC 2822 headers in outbound SMTP
following Notes items messages, mapping each specified Notes item to a valid nonstandard RFC 2822 header
in headers item. For example, the Notes item, header-1 would be mapped to the RFC 2822 header,
x-header-1. The header body is the first 255 bytes of the item value, converted to text if
necessary.

Domino sends the items specified in this field even if sending of Notes private items is
disabled. Use this field to send specific items only, while preventing export of all
unspecified Notes private items.
Note: If an item listed in this field is also listed in the field ″Notes items to be removed
from headers,″ the item is not included.
Notes items to be List the Notes header items to exclude from x-headers in outbound SMTP messages.
removed from headers
When converting a Specifies the character set Domino uses when converting a Notes rich-text message with
multilingual message to text content that cannot be represented by a single character set group -- for example, a
MIME message in which part of the content is in French (Western character set group) and part
in Arabic. Choose one:
v Send it in Unicode [UTF8] - (default) Domino converts all the text to an 8-bit encoding
of the Unicode character set. To read the resulting message, recipients’ mail programs
must support Unicode.
v Send it in most representable character set - Domino selects the character set that best
matches the majority of characters in the message. If the message is sent as plain text,
any character that cannot be represented by the selected character set is replaced by a
fallback character -- typically a question mark. If the message is sent as HTML, a
Unicode-enabled mail program is required to decode the message because such a mail
program can replace unrepresentable characters with their Unicode numeric values.
Character set name Specifies the name of a nonstandard character set alias to be used when converting Notes
aliases rich-text messages for outbound SMTP transfer. For example, you can send messages sent
in ISO-8859-1 with the tag ″My-Character-Set.″ It is not recommended that you provide
aliases here because outbound messages will be understood only by similarly configured
mail clients.

Note: These settings apply to messages sent outbound over SMTP to another host, or exported to the
IMAP or POP3 service. They are not applied to messages delivered locally or messages transferred over
Notes routing.
The change takes effect after the next Router configuration update. To put the new setting into effect
immediately, reload the routing configuration.

812 Lotus Domino Administrator 7 Help

 For information on how to reload the routing configuration, see the chapter ″Setting Up Mail
Routing.″
For more information about using the RFC 822 address format, see the topic ″Configuring outbound
Internet mail to use RFC 822 address format (phrase parts)″ later in this chapter.

Examples: How Domino handles Macintosh attachments in inbound messages

For inbound messages, Domino supports AppleSingle, AppleDouble, and BinHex attachment encoding.
Macintosh attachments of any encoding are stored as normal Notes Macintosh attachments; if the data
fork would be meaningful to a PC user, then a Notes user at a PC workstation can launch the attachment
normally.

In the following examples, unless noted otherwise, it is assumed that the application required to open the
attachment is properly installed on the user’s computer. Also, it is assumed that both sender and recipient
are using MIME-compliant mail programs.
v A Macintosh Claris Emailer user sends a Lotus 1-2-3 spreadsheet to two Notes recipients: one uses a
Macintosh, and one uses a PC.
Both recipients receive an intact Lotus 1-2-3 spreadsheet attachment. The Macintosh recipient can
launch it from within Notes or can detach it and double-click to launch -- regardless of the name given
to the attachment.
The PC user can launch it from within Notes or detach it and double-click to launch, only if the file
name ends in WK1, WK3, 123, or some other extension associated with the Lotus 1-2-3 application.
(This is a Windows restriction, not a Notes restriction.)
v A Lotus Notes user sends a Lotus 1-2-3 spreadsheet from a PC to a Macintosh recipient using Claris
Emailer.
The PC user must save the spreadsheet as a 1-2-3 R1 spreadsheet because it is the most recent version
of 1-2-3 available on the Macintosh. The spreadsheet is encoded with the MIME type ″X-Lotus-123R1,″
a private MIME type defined by Lotus. Since this is a private MIME type, by default, it cannot be
launched directly from Claris Emailer. To view the file, the recipient can detach it, launch Lotus 1-2-3,
and then open it using the File - Open command.
As an alternative, Macintosh users can install Internet Config (a widely used free software utility) and
configure a mapping for the ″X-Lotus-123R1″ MIME type. Claris Emailer can then use the file mapping
table in Internet Config to determine the application to use to launch the attachment directly from the
message.

Configuring outbound Internet mail to use RFC 822 address format (phrase parts)
RFC 821 defines the standard convention for naming mailbox addresses as ″user@domain″ or more
broadly, ″Localpart@Domainpart.″ This format has come to be known as RFC 821-style addressing.
Subsequently, RFC 822 specified a format for a more human-readable Internet address, which adds a
phrase part, also known as a friendly name or display name, before the actual address. Phrase-style
addresses use the form ″Phrase″ <localpart@domainpart>; an optional display name indicates the name of
the recipient for display to the user of a mail application, for example, ″John Jones″ <JJones@acme.com>.

You can have Domino add a phrase to the sender’s address on outbound SMTP mail and specify the
name component to use as the address phrase. By default, addresses do not include phrases. If you
choose not to support phrase-style addresses, you can specify that Domino remove any user-added
phrases in the recipient fields of outbound messages.

You configure this address format using the ″RFC822 phrase handling″ field in the Configuration Settings
document, under the MIME - Advanced - Advanced Outbound Message Options tab.

The Router adds phrases to Internet addresses both when taking the address from a Person document in
the Domino Directory and when constructing the address from rules in the Global domain document.

Chapter 30. Customizing the Domino Mail System 813

This setting applies to messages sent over SMTP to another host or exported to the IMAP or POP3
service. It does not apply to messages delivered to mail files on the server or messages transferred over
Notes routing.

The options for this field are as follows:

v Do not add phrase -- (Default setting) Outbound mail displays the sending user’s RFC 821 address.
The Router permits user-defined phrases in recipient addresses.
v Use DN as phrase -- Constructs an RFC 822-style address using a phrase part derived from the
person’s hierarchical, distinguished name; for example, John Jones/Sales/ACME <JJones@acme.com>.
The Router permits user-defined phrases in recipient addresses.
v Use alt. name if available - otherwise DN -- If an Alternate name is specified in the user’s Person
document, constructs an RFC 822-style address using it as the phrase part; otherwise uses the
hierarchical, distinguished name; for example, ″John Jones/Sales/ACME″ <JJones@acme.com>. The
Router permits user-defined phrases in recipient addresses.
v Remove Phrase - The Router strips user-defined phrases in recipient addresses. Only RFC 821-style
addresses are allowed.
v Use CN as phrase -- Constructs an RFC 822-style address using a phrase part derived from the
person’s common name; for example, John Jones <JJones@acme.com>. The Router permits user-defined
phrases in recipient addresses.

Mapping MIME types to file extensions

Domino uses File identification documents in the Domino Directory to associate file types and their file
name extensions with MIME types and subtypes. For example, a File identification document for JPEG
files classifies files with the extension JPG as having the MIME type image and MIME subtype jpeg.
Domino servers and Notes clients use the information in the File Identification documents to map file
types to file extensions and vice versa on inbound and outbound mail.

This ensures that the contents of attached files are correctly interpreted by the recipient’s mail client.
Upon opening the message in a MIME-aware mail program, the recipient can open the attached
document from within the message, provided that the mail program recognizes the MIME type and the
associated application is installed on the recipient’s computer.

You can add, modify, or delete File Identification documents from the Domino Directory. Add new
documents to support additional file types. When adding a new File Identification document, you must
know the MIME type for the application and the file extension associated with the application. Modify a
File Identification document in the event that a default mapping is incorrect or later standards dictate a
change. You might also edit a File Identification document to specify which of multiple MIME types and
subtypes Notes and Domino assign to files with a given file extension when sending outbound mail.

How Domino uses File Identification documents when processing inbound mail: When receiving an
inbound MIME message that includes a file attachment, Domino reads the MIME headers to determine
the name and type of the attached file. If, however, the MIME headers do not specify the name of the
attached file, Domino must assign a name to the file that is both unique within the document and
includes the appropriate file extension. To determine the file extension to use in creating the file name,
Domino refers to the File Identification documents in the Domino Directory.

For example, if Domino receives a message that has a MIME header indicating that it contains a
Microsoft Word attachment (MIME type/subtype of application/ms-word), but neither the content-type
header or content-disposition header specify a file name, the server has to provide a name for the
attachment. To ensure that Domino creates a name using the correct file extension for a file of this type,
the server checks the Domino Directory for a File Identification document for this file type and subtype,
and then checks the ″Extension″ field of the matching document. Because, by default, the only document
that matches files with the MIME type application/ms-word indicates that the file uses the extension
DOC, Domino creates a file name using this extension.

814 Lotus Domino Administrator 7 Help

By default, the File Identifications view of the Domino Directory lists multiple documents for a given
MIME type/subtype alphabetically, by file extension. For example, by default, Domino includes several
File Identification documents for the MIME type/subtype application/vnd.lotus-1-2-3, and the default
view lists these from top to bottom, beginning with the document that specifies the extension 123 and
proceeding through those that specify the extensions unknown, WK2, WK3, WK4, and WKS. This list
order determines how Domino names files when receiving a message containing an unnamed file
attachment with one of these MIME types. When creating the file name, the server uses the information
in the first document that appears alphabetically in the view. Thus, when a server receives an inbound
message that includes an unnamed file attachment with the MIME type/subtype application/vnd.lotus-1-
2-3, Domino names the file using the extension 123, because the File Identification view lists the
document specifying this extension before the other documents that describe the same MIME
type/subtype.

How Domino uses File Identification documents when processing outbound mail: Domino servers
and Notes clients both use File Identification documents when sending MIME messages that include file
attachments. In both cases, information in the document is used to specify the MIME content type of the
message attachment.

Domino servers use File Identification documents when converting messages that include file attachments
from Notes rich-text format to MIME format for sending over SMTP. When converting an outbound
message that includes a file attachment, Domino first searches for a File Identification document that
corresponds to the file extension of the attachment. After locating the correct document, Domino uses the
MIME type and subtype information from the document to construct the MIME Content-type header for
the message part that describes the attachment.

When a Notes client attaches a file to a message it sends in MIME format (for example, when sending to
Internet recipients or to Notes mail recipients whose mail storage preference is set to MIME), the client
first checks the operating system to determine what file associations are defined. Clients running on
Microsoft Windows check the Windows registry, while clients running on the Macintosh check Internet
Config. If the client cannot locate MIME type information from these sources, it then checks the Domino
Directory for a File Identification document that applies to files with the same extension as the attached
file. After locating the correct document, the client places the MIME type and subtype information from
the document in the MIME header describing the attachment.

In the case of both servers and client, if more than one File Identification document applies to a given file
extension, the setting in the ″Outbound″ field of the documents determines which MIME type and
subtype to assign to file attachments with this extension when sending mail.

To create or modify a File Identification document:

1. From the Domino Administrator, click the Configuration tab and expand the Messaging view.
2. Click File Identifications.
3. To add a new File Identification document, click Add File Identification.
To edit an existing File Identification document, select it from the documents listed, and click Edit File
Identification.
4. Complete the following fields:

Field Description
MIME type General MIME category used to describe files of this content type or media; for example,
application, audio, image, or video. When sending attachments in MIME messages, the
information in this field is placed in the MIME Content-type header.

Each MIME type/subtype combination can be mapped to zero or more file extensions.

Chapter 30. Customizing the Domino Mail System 815

Field Description
MIME subtype The specific MIME category that uniquely identifies the application that created files of
this content type, for example, X-Lotus-NSF. When sending attachments in MIME
messages, the information in this field is placed in the MIME Content-type header.

Each MIME type/subtype combination can be mapped to zero or more file extensions.
File extension The Windows or UNIX file name extension associated with files of this type; for example,
JPG, BMP, or NSF.

The Domino Directory can contain multiple File identification documents for a given file
extension.

If the MIME headers of an inbound message do not specify the name of an attached file,
Domino creates a file name for the attachment using this extension.
Description Use this field to specify the type of file or the name of the application used to create and
open the file.
Outbound If the Domino Directory contains multiple File Identification documents for files with this
file extension, this setting determines which MIME type and subtype Notes and Domino
use to send file attachments with this extension.
Note: Notes clients also use settings in the Windows registry or the Macintosh Internet
Config object to determine the MIME type and subtype to associate with a given file
extension.

Choose one:
v Send - When sending outbound messages in MIME format, Domino assigns this MIME
type and subtype specified in this document to attachments that have this file extension.
If there are multiple File Identification documents for a given file extension, select this
option for one document only. If the value in this field is set to Send in multiple File
Identification documents for a given file extension, Domino uses the first document
listed in the File Identifications view to set the MIME information for attachments with
the extension.
v Do not send - When sending outbound messages to MIME format, Domino does not
assign the MIME type and subtype specified in this document to attachments that have
this file extension. If there are multiple documents for a given file extension, specify this
option in the Outbound field in all but one of the documents.

816 Lotus Domino Administrator 7 Help

Chapter 31. Setting Up Shared Mail
This chapter describes setting up and managing shared mail databases.

Shared mail overview

By default, the Domino mail system employs a message-based model for mail storage, delivering a
separate and complete copy of every document to each recipient’s mail file. When a message is small or
is addressed to only a few recipients, creating multiple copies of a message does not consume much
additional disk space. But when a large message is broadcast to thousands of users on a single server,
creating a separate copy of the message for each recipient can consume several gigabytes of disk space.

To use disk space more efficiently, you can set up shared mail on each mail server after you set up the
Domino mail system. Shared mail, sometimes referred to as the Single Copy Object Store (SCOS), offers
an alternative to message-based mail, allowing servers to store a single copy of messages received by
multiple recipients in a special central database, or object store. Every server using shared mail contains
one or more of these object stores, or shared mail databases, to hold all shared messages. After you
enable shared mail on a server, all mail databases on the server automatically use the shared mail
database to store the content of new messages, unless you explicitly exclude a database from using
shared mail. You do not need to configure each user’s mail file individually for shared mail use.

When shared mail is enabled and an incoming message is addressed to multiple local recipients, the
Router divides the message into a message header and message body. The header includes the message’s
To, cc, bcc, Subject, and From fields. The body includes the text and other content, as well as any file
attachments. The Router then writes the message body to a shared mail database and the message header
to each recipient’s mail file. The message body stored in the shared mail database contains an object store
link, which identifies all of the mail files linked to that message. Similarly, the corresponding message
headers stored in each recipient’s mail file each contain a pointer to the object store that contains the
message body.

To keep shared mail databases small, Domino automatically purges the shared portion of a message from
the shared mail database after all recipients delete the message from their mail files. Domino purges the
shared portion of these obsolete messages immediately; you do not have to wait for a task to run before a
message can be removed.

To improve efficiency and support encryption, Domino excludes certain messages from the object store.
Users always receive messages smaller than one kilobyte (1 KB) as complete messages. This guarantees
that message pointers in a mail file never exceed the size of the message body in the shared mail
database. In addition, users always receive complete messages if instructions in their Person documents
specify to encrypt incoming mail.

Using a shared mail database is completely transparent to users. When a recipient opens a message, the
link between the mail file and the shared mail database causes the message to appear in its entirety.
Users can delete, reply to, change the view or folder, edit, save, resend, and perform all the same tasks on
a mail message stored in a shared mail database as they would with the same message stored in their
own mail files. If a users edit and save, or encrypt and save a message, the complete message is then
stored in their personal mail file, with no effect on how the original message appears to other users.

Shared mail works for all messages, regardless of the mail client used to compose the message. That
means that users who use a POP3, IMAP, or Notes mail client and who have a mail file on the Domino
mail server can all use shared mail. However, shared mail is not used if the various recipients have
different format preferences for incoming mail. For example, if a message is sent to four users, half of

817
whom have Notes rich text format specified as their format preference, and half whose format preference
is set to MIME, all of the users receive the complete message.

Using multiple active shared mail databases

To improve scalability and reduce database contention, Domino servers support the use of multiple active
shared mail databases in multiple shared mail directories. The directories can exist on any disk that the
server has access to. An active shared mail database is one that is open for delivery of new messages.
When multiple active shared mail databases are available, the Router evenly distributes incoming mail to
each of them, choosing the destination database at the time of delivery. Each new message that a user
receives may be stored in any one of the currently active shared mail databases. After a message is stored
in a shared mail database, it remains there until all users delete the message from their mail files.

You can configure the server to use as many as ten active shared mail directories at one time. Each
configured shared mail directory can contain as many as 100 shared mail databases, to a maximum of
1000 total shared mail databases per server.

If a server has less than 1000 active databases configured, it can continue to reference a number of
inactive shared mail databases up to the maximum of 1000. Inactive databases no longer receive new
mail, but store previously received messages. A server can support as many as 40 inactive shared mail
directories, As with active shared mail directories, each of these inactive directories can contain a
maximum of 100 shared mail databases. A single shared mail directory can contain both active and
inactive databases.

A shared mail database is automatically set to inactive if the parent directory exceeds the maximum size
you specify for it in the Server document.

When a server has multiple active shared mail databases, user mail files on the server may contain links
to any or all of them, as well as to inactive shared mail databases. If you create additional shared mail
databases, Domino distributes a portion of all new incoming messages to each of them. Previously
received messages continue to reside in the shared mail databases where Domino originally stored them.

Using multiple shared mail databases reduces the amount of shared mail that could be lost or become
temporarily inaccessible as a result of database corruption. You can enable transaction logging for shared
mail databases, so that databases corrupted as the result of a server crash or power outage can be
automatically recovered at server startup. Enabling transaction logging frees you from the need to restore
shared mail databases manually.

If transaction logging for shared mail is not enabled, to protect shared mail databases against data loss,
install a backup utility that can back up and verify open NSF files and back up all shared mail databases
at least once a day. Because security settings on shared mail databases prevent replication, you cannot
replicate shared mail databases to provide backup.

For more information on restoring shared mail databases, see the topic Restoring a shared mail database″
later in this chapter.

How using shared mail affects a user’s mail file quota

When calculating the size of a mail file to determine whether it conforms to configured mail quota or
warning threshold limits, Domino treats shared messages as though each user owned the entirety of the
shared message. Thus, the full size of every message delivered to a mail file that uses shared mail counts
against the mail file quota. Likewise, when a user deletes a message that is linked to a shared mail
database, the full size of the message is removed from the mail file quota.

The actual file size of the mail database that uses shared mail therefore does not necessarily reflect its
logical size. For example, a user’s mail file might exceed its quota limit of 60MB even though the physical
size of the file is only 35MB.

818 Lotus Domino Administrator 7 Help

How Domino maintains the security of a shared mail database
Because a shared mail database contains confidential messages for all users on a server, it must be
secured against unauthorized browsing. These security features ensure that only users who should have
access to a given message actually have access to that message:
v Shared Mail databases are encrypted locally with a random key, which is in turn encrypted using the
public key of the server’s ID.
v The access control list (ACL) of a shared mail database is set so that only the server’s ID can access the
database. The server’s ID has Manager access, and the user type is Server. Even if an unauthorized
user obtains the server ID, the user cannot use the server ID to access a shared mail database from a
Notes workstation and cannot create a replica of the database on another server.
v The shared mail database does not appear in the Open Database dialog box.
v A shared mail database contains no views, and none can be added to it.
v The shared mail database includes links to message headers. When a user reads a message, Domino
verifies that the message header matches the content stored in the shared mail database.
v Messages received by users for whom the ″Encrypt incoming mail″ option in the Person document is
set to ″Yes″ cannot be stored in a shared mail database. Messages delivered to recipients who encrypt
incoming mail are placed in the recipient’s mail file in their entirety.
For more information on mail encryption, see the chapter ″Encryption and Electronic Signatures.″

How shared mail works

1. The Router on a server receives a mail message addressed to two or more recipients whose mail files
are on that server.
2. The Router splits the incoming message into two parts: the header and the content. The header
consists of the message’s To, cc, bcc, Subject, and From fields. The content contains the body of the
message, along with any file attachments.

Note: If the combined size of a message and its attachments is 1KB or less, Domino delivers the
complete message to the recipient’s mail file and does not use the object store.
3. The Router stores a copy of the header in each recipient’s mail file and stores a single copy of the
content in the shared mail database.
4. When a recipient opens the message, the header activates a link to the message content, which is
stored in the shared mail database. The message appears as though the entire message is stored in the
recipient’s mail file.
5. If the recipient deletes a shared message, Domino deletes only the header in the recipient’s mail file.
The content is not affected because it is stored in the shared mail database.
6. After all of the recipients delete the message header from their mail files, Domino automatically
purges the obsolete message, including the content in the shared mail database.
For more information on how Domino removes obsolete message from a shared mail database, see the
topic ″Purging obsolete shared mail messages″ later in this chapter.
v If a user edits and saves a received message, Domino stores the revised message in the user’s mail
file in its entirety and deletes links between the user’s mail file and the message body in the shared
mail database.

Setting up shared mail databases

Before setting up shared mail, decide where to locate your shared mail databases. On each server that
uses shared mail, you specify the directory where you want shared mail databases to reside. When
creating multiple shared mail databases, you can place all of the databases in one directory, or create
multiple directories and have multiple databases in each directory. Servers can have up to 10 active
shared mail directories, each supporting a maximum of 100 shared mail databases. In addition, Domino
recognizes as many as 40 inactive shared mail directories, from which users can continue to access

Chapter 31. Setting Up Shared Mail 819

messages. Inactive directories are directories that no longer appear in the server document, but remain in
the last location specified. Each server can support a combined total of 1000 active and inactive shared
mail databases.

Shared mail directories must reside within the logical directory structure that is controlled by the server
or be referenced by a directory link within that directory structure. To improve performance, you can
place shared mail databases on another file system. When creating shared mail databases in a directory
that is not a subdirectory of the Domino data directory, Domino creates a link to point to the shared mail
directory. If no link exists, Domino cannot locate the shared mail databases.

To create and enable a shared mail database

1. From the Domino Administrator, click the Configuration tab and then expand the Server section.
2. Select the Server document to be edited and then click Edit Server.
3. Click the Shared Mail tab.
4. Enable or disable the use of shared mail by completing the following field:

Field name Enter

Shared Mail Choose one:
v None - The server does not use shared mail.
v Delivery - The server uses shared mail for messages delivered to multiple local
recipients.
v Transfer and delivery - The server always uses shared mail.

5. For each shared mail directory you want to create, complete the following fields and then click Save
& Close:

Field name Enter

Directory The full path to the shared mail directory. For example:

C:\LOTUS\DOMINO\DATA\SHAREDMAIL

If the directory you specify does not exist, Domino creates it for you.

You can configure up to 10 active shared mail directories. In addition, Domino recognizes
as many as 40 inactive shared mail directories, from which users can continue to access
messages. Inactive directories are directories that no longer appear in the server document,
but remain in the last location specified.
Number of files The number of shared mail databases to create in the specified directory. Enter a number
between 1 and 100.
Maximum directory The maximum total size, in megabytes (MB), of all shared mail databases in the directory.
size Enter a number between 1 and 8192. If the directory size exceeds this value, Domino stops
adding new mail to the shared mail databases in the directory.
Delivery status Specifies whether the Router can deliver messages to shared mail databases in the
directory. Choose one:
v Open - (default) The Router can access active shared mail databases in this directory for
delivery. Although the delivery status for the directory is set to Open, individual
databases in the directory may be closed to delivery.
v Closed - The Router does not deliver new messages to shared mail databases in this
directory. Domino closes a directory automatically if it exceeds its size or as the result of
certain error conditions. Select this option if you have a temporary need to shut off
access to the database to prevent directory growth -- for example, if another service that
stores data on the disk needs immediate space -- but you don’t want to change the
configured directory size.

820 Lotus Domino Administrator 7 Help

Field name Enter
Availability Specifies whether the mail system can access shared mail databases in the directory.
Choose one:
v Online - (default) Domino designates shared mail databases in the directory as available
for use. The server periodically checks the directory to ensure that it contains the
number of configured shared mail databases. If the number of databases in the directory
falls below the value specified in the Number of Files field, the server attempts to
recreate the missing databases.
v Offline - Domino designates shared mail databases in the directory as not available. The
server does not check the directory to ensure that it contains the correct number of
shared mail databases. Select this option to prevent access to shared mail databases in
preparation for moving a directory or database. Setting the availability status of a
directory to Offline automatically sets the delivery status to Closed.

6. To put the new configuration into effect, restart the server or enter the following command at the
server console:
Show SCOS
For more information about using the SHOW SCOS command, see the appendix ″Server Commands.″

Using shared mail for delivery only or for transfer and delivery
There are two ways of setting up shared mail. One is for delivery only, and the other is for transfer and
delivery. When shared mail is enabled for delivery only, the Router places the body of an incoming
message in the shared mail database only if there are multiple local recipients. Messages for a single local
user are delivered as complete messages. The server uses its normal transfer mechanism for messages
being routed through the server to another destination; that is, messages in MAIL.BOX that are awaiting
transfer to another server always remain intact.

In contrast, when shared mail is enabled for transfer and delivery, the server splits every message it
receives (that is, the content goes to the shared mail database and the header goes to MAIL.BOX),
regardless of the number of recipients. Then, during delivery, the Router merges the header and content
together, examines the recipient list, and either transfers the message to the next server, or delivers it to
the local recipients (with the content staying in the shared mail database and the header going to the
users’ mail files).

The shared mail setting that you decide to use depends on your situation. In general, use shared mail for
transfer and delivery on servers that have mostly deliveries and few transfers to other servers. Because
most incoming messages are likely to be for local delivery, it’s efficient to have the server automatically
place all incoming messages in the object store. On the other hand, on servers such as hub servers, which
perform mostly transfers and have few local mail file deliveries, use shared mail for delivery only.
Because incoming messages on these servers are likely to be transferred to another server, it’s
counterproductive to have the server absorb the cost of preparing mail for the object store.

In the end, both settings provide similar disk space savings, but because the ″transfer and delivery″
setting always places the message body directly in the object store, rather than in MAIL.BOX, it provides
faster delivery for local users by eliminating the transfer time required to move mail from MAIL.BOX to
the object store.

Specifying the location and size of a shared mail directory

Shared mail databases may become quite large, so be sure to locate shared mail directories on a disk that
has enough free space to accommodate future growth. To manage growth, you can specify a size limit for
the database set contained in each shared mail directory. The size limit applies to the cumulative size of
all shared mail databases in the directory. The size of individual databases may fluctuate as messages are
added and removed, but barring any configuration change, the number of databases remains constant,
and the size of the entire database set never significantly exceeds the specified maximum. Domino
supports a maximum size limit of 8GB (8192MB) for each shared mail directory.

Chapter 31. Setting Up Shared Mail 821

Always set a maximum directory size that is less than the actual amount of available disk space. A
shared mail directory may exceed the specified size limit if the Router adds a large message to the
directory when it is already near the limit.

If a shared mail directory reaches the configured maximum size, Domino automatically deactivates it,
changing the delivery status of the directory to Closed, so that it can no longer receive new mail. Existing
links between users’ mail files and the inactive shared mail database continue to work, so users can read
and otherwise work with these messages. If another shared mail directory is available, the Router places
future messages into the active shared mail databases in that directory. If no shared mail directories are
available, the Router delivers new messages as complete messages to user mail files.

Managing object store growth

As the object store becomes host to a greater number of users and messages, you may need to change the
size limits on existing shared mail directories or add new directories to accommodate the increased
usage. Whether you extend the size of current directories or add new ones depends on the amount of
physical space and the number of concurrent users accessing your current directories.

If there’s still adequate space on the current disk, after the existing shared mail directories reach their size
limit, you can increase the maximum size of the existing directories. If the amount of additional space on
the current disk is limited, create another shared mail directory on a separate disk that has more space.

If database contention (too many users accessing the database at the same time) is affecting performance,
and space allows, increase the number of databases (not the size) within the existing shared mail
directories or create new shared mail directories on the same disk or a separate disk.

Creating shared mail directories outside of the Domino Data directory

If you create a shared mail directory that is not a subdirectory of the Domino data directory, Domino
automatically creates a link file, or directory link, within the Data directory, called SCOS_N.DIR, where N
indicates the sequence order in which the link file was created relative to other shared mail database
links. For example, the directory link Domino creates for the first shared mail directory outside of the
Domino Data directory is named SCOS_1.DIR; the second one is named SCOS_2.DIR; and so forth.
Domino does not create link files for shared mail directories residing within the Domino Data directory.
The link file is a text file containing the path to the shared mail directory so that the server can locate
shared mail databases.

If the server has a drive mapped to another computer, you can place the directory on that drive by
entering its full path. For example:
J:\Shared\SHAREDMAIL

You cannot specify a path in the form of a Universal Naming Convention (UNC) name (that is, using the
format: //hostname/sharepoint).

CAUTION:
If Domino loses access to the remote directory for any reason, users will be unable to access messages
stored in that directory.

Managing a shared mail database

Use these procedures to manage a shared mail database and the user mail files that are linked to it:
v Reconfigure shared mail
v Generate and view shared mail information
v Link, unlink, or relink a user’s mail file
v Include or exclude a user’s mail file
v Enable shared mail for replicas of mail files
v Purge obsolete shared mail messages

822 Lotus Domino Administrator 7 Help

v Restore a shared mail database
v Move mail files between servers that use shared mail
v Delete a shared mail database
v Disable shared mail

Reconfiguring shared mail settings

As the object store becomes host to a greater number of users and messages, you may need to change the
existing settings to accommodate continued growth. You can:
v Increase the number of files in a directory
v Increase the size limits on existing shared mail directories
v Change the delivery status of a directory
v Add new shared mail directories

Whether you extend the size of current directories or add new ones depends on whether physical space
or concurrent usage is the limiting factor.

If your existing shared mail directories reach their size limit, and there’s still adequate space on the
current disk, increase the maximum size of the existing directories. If the amount of additional space on
the current disk is limited, create another shared mail directory on a separate disk that has more space.

If database contention (too many users accessing the database at the same time) is affecting performance,
and space allows, increase the number of databases (not the size) within the existing shared mail
directories or create new shared mail directories on the same disk or a separate disk.

Use the Shared Mail tab on the Server document to change the directory settings. In addition, you can
also use the SET SCOS command to change the status of individual shared mail databases within a
directory. For more information about using the SET SCOS command, see the appendix ″Server
Commands.″

To change directory settings for shared mail:

1. From the Domino Administrator, click the Configuration tab and then expand the Server section.
2. Select the Server document to be edited it and then click Edit Server.
3. Click the Shared Mail tab.
4. To create an additional shared mail directory, complete the following fields:

Field name Enter

Directory The full path to the shared mail directory, For example:

C:\LOTUS\DOMINO\DATA\SHAREDMAIL

If the server can has a drive mapped to another computer, you can place the directory on
that drive by entering its full path. For example:

J:\Shared\SHAREDMAIL
Note: If the server is unable to connect to the remote drive, access to directories on the
drive will be interrupted.

If the directory you specify does not yet exist, Domino creates it for you.

You cannot specify a path in the form of a Universal Naming Convention (UNC) name
(that is, //hostname/sharepoint)
Number of files The number of shared mail databases to create in the specified directory. Enter a number
between 1 and 100.

Chapter 31. Setting Up Shared Mail 823

Field name Enter
Maximum directory The maximum total size, in megabytes (MB), of all shared mail databases in the directory.
size Enter a number between 1 and 8192. If the directory size exceeds this value, Domino stops
adding new mail to the shared mail databases in the directory.
Delivery status Choose one:
v Open - The server can access any active shared mail databases in this directory for
delivery. Individual databases may be closed to delivery.
v Closed - The server cannot access any shared mail databases in this directory.
Availability Specifies whether the mail system can access shared mail databases in the directory.
Choose one:
v Online - (default) Domino designates shared mail databases in the directory as available
for use. The server periodically checks the directory to ensure that it contains the
number of configured shared mail databases. If the number of databases in the directory
falls below the value specified in the Number of Files field, the server attempts to
recreate the missing databases.
v Offline - Domino designates shared mail databases in the directory as not available. The
server does not check the directory to ensure that it contains the correct number of
shared mail databases. Select this option to prevent access to shared mail databases in
preparation for moving a directory or database. Setting the availability status of a
directory to Offline automatically sets the delivery status to Closed.

5. To add more shared mail databases to an existing shared mail directory, increase the value in the
Number of Files field for that directory.
6. To increase the size of an existing shared mail directory, enter a new value in the Maximum directory
size field for that directory. A directory can have a maximum size of 8192MB. If the directory size
exceeds this value, Domino stops adding new mail to the shared mail databases in the directory.
7. At the server console, enter the following command to put the new configuration into effect:
Show SCOS
For more information about using the Show SCOS command, see the appendix ″Server Commands.″

Generating and viewing shared mail statistics

The Object Collect task automatically generates shared mail statistics, such as how many messages in a
shared mail database are shared by a certain number of users. You can view these statistics from the
Shared Mail view on the Messaging-Mail tab of the Domino Administrator, or from the Object Store view
of the server log file (LOG.NSF). The view is populated automatically when the Object Info -Full
command runs by default at 3 AM. You can specify when to run the Object task by editing the
ServerTasks parameter in the NOTES.INI file.

These statistics provide information you need before administering shared mail by showing how shared
mail is currently used on a server. You can see the object store filename, the mail databases that use the
object store, the number of documents referenced in the object store for each mail database, and the total
size of documents in the object store for each mail database. This information can help you determine
how much disk space you would need if you were to unlink the user’s mail file from the shared mail
database. Likewise, you can see the total size of all documents in the shared mail database, so you’d
know how much space you would need if you unlinked the entire shared mail database.

To run the Object Collect task to generate shared mail statistics: Enter the following at the server
console:
Load Object Info -Full SHARED.NSF

where SHARED.NSF is the full pathname of a shared mail directory or a specific shared mail database.

824 Lotus Domino Administrator 7 Help

Note: The Domino Administrator maintains shared mail statistics cumulatively. As a result, if you have
previously populated statistics, duplicate entries appear. To ensure accurate results, clear existing
information before generating new statistics.

To view shared mail statistics:

1. Run the Object Collect task, as described above. To view statistics for all configured shared mail
directories, run the task against each directory.
2. From the Domino Administrator, click the Messaging - Mail tab.
3. Open the Shared Mail view. The view displays each configured shared mail directory and the shared
mail databases within them. The following information appears for the shared mail databases or
directories for which you generate statistics in Step 1:

For each Display

Shared mail v Database name and names of the parent directory and shared mail server
database
v File name and database title of each mail file that references the shared mail database
v Number of messages each mail file references in the shared mail database
v Size (in bytes) of all message bodies a given mail file references in the shared mail database
v Total size (in bytes) of all messages bodies in the shared mail database
Shared mail Total size (in bytes) of the message bodies contained in the included shared mail databases. This
directory value may be less than the true total, if you generated statistics for a subset of the databases in a
directory.
Shared mail Total size (in bytes) of the message bodies contained in the included shared mail directories and
server databases. This value may be less than the true total, if you generated statistics for a subset of the
databases in a directory.

Linking unshared messages in a mail file to the object store

After you set up shared mail on a server, Domino automatically stores all new shared mail messages in
the shared mail database. However, messages that users received before shared mail was enabled, or that
were delivered while shared mail was temporarily disabled, remain in their mail files as complete
messages.

To eliminate redundant copies of messages received by multiple users to save additional space, you may
want to transfer these existing messages to the object store. To store these messages in a shared mail
database, you use the Object Link command to link the user’s mail file to a shared mail directory.

During the linking operation, the Object Store Manager moves the content of each shared message from
the user’s mail file to the shared mail databases in the specified directory. Message headers remain in the
mail file with a link to the shared mail database containing the shared portion. If more than five
messages are moved to the shared mail database, the Object Store Manager automatically compacts the
user’s mail file to reclaim the disk space that was previously occupied by the message content. Linking
does not determine whether the mail file stores future messages it receives as complete messages or uses
the object store. If you disable shared mail on the server, or exclude the mail file from using shared mail,
the messages placed in the object store during the linking process remain there, even if the mail files
receive complete messages in the future.

You can also use the Object Link command to unlink a mail file from all shared mail databases so that
existing messages in the mail file will be stored as compete messages; and unlink a shared mail database
from all mail files.

To link a mail file: The linking operation splits complete messages in a mail file into headers and
content and distributes the content to the shared mail databases on the server. Typically, you would use
linking to process the complete messages in a mail file that is newly replicated to another shared mail
server, or that existed on a server before you enabled shared mail.

Chapter 31. Setting Up Shared Mail 825

Enter this command at the console:
Load Object Link USERMAIL -ALL

where USERMAIL is the name of the directory containing user mail files. Running this command links
messages in the specified user mail files to the configured shared mail databases in a distributed fashion.
You cannot link a mail file to a specific shared mail database.

To link a mail file without compacting it: By default, if linking a mail file results in more than five
messages being moved to the shared mail database, the Object Store Manager compacts the user’s mail
file. To link a mail file without compacting it, use the -Nocompact option.

Enter this command at the console:

Load Object Link -Nocompact USERMAIL
-ALL

where USERMAIL is the name of a single user mail file or a directory containing user mail files.

For example:
Load Object Link -Nocompact Mail\DMalone.NSF

E:\Lotus\Domino\Shared\SCOS1

Unlinking messages in a user’s mail file from the object store: You can restore complete messages to a
user’s mail file by unlinking the mail file from the shared mail databases.

After you unlink existing messages from the shared mail databases, new messages delivered to the mail
file continue to use shared mail as long as shared mail is enabled on the server, unless you explicitly
exclude the mail file from using shared mail.

For information about excluding a mail file from using shared mail, see the topic ″Excluding a mail file
from using shared mail″ later in this chapter.

Note: Unlinking a mail file can result in a significant size increase.

To unlink a mail file: Enter this command at the console:

Load Object Unlink USERMAIL.NSF

where USERMAIL.NSF is the complete path to a user mail file or a directory containing mail files.

To unlink an object store: Enter this command at the console:

Load Object Unlink OBJECTSTORE

where OBJECTSTORE is the name of a shared mail directory or an individual shared mail database.

CAUTION:
Unlinking an object store can significantly increase the size of all mail files that previously linked to
the object store. Before unlinking an object store, confirm that the disk where user mail files reside
includes enough available space to accommodate the resulting increase.

Excluding a mail file from using shared mail

By default, after you enable shared mail on a server, all mail files on the server use shared mail for new
mail. You can disconnect specific mail files from shared mail if you want their owners to use standard,
message-based mail, and you can reconnect previously disconnected mail files to shared mail.

826 Lotus Domino Administrator 7 Help

To determine which mail files use shared mail: If a server contains a mix of some mail files that use
shared mail and some that do not, you can display a list of all mail files that use shared mail. Enter this
command at the console:
Load Object Info
USERMAIL.NSF

where USERMAIL.NSF is the complete path to the user’s mail file or a directory that contains mail files.

For example, to determine the shared mail use of all mail files in a directory, enter:
Load Object Info C:\LOTUS\DOMINO\DATA\MAIL

For each mail database in the directory, the results indicate whether the mail file is set to use shared mail
and currently has links to messages shared in any shared mail databases:
12/06/2001 03:45:03 PM Object Store Manager: mail\gthiers.nsf is not an object store
12/06/2001 03:45:03 PM Object Store Manager: mail\gthiers.nsf contains notes which use an object store
12/06/2001 03:45:03 PM Object Store Manager: mail\gthiers.nsf is set always to use object store (multiple)
12/06/2001 03:45:05 PM Object Store Manager: mail\ewilson.nsf is not an object store
12/06/2001 03:45:05 PM Object Store Manager: mail\ewilson.nsf contains no notes which use an object store
12/06/2001 03:45:05 PM Object Store Manager: mail\ewilson.nsf is set always to use object store (multiple)

To exclude a mail file from using shared mail: Enter this command at the console:
Load Object Set -Never
USERMAIL.NSF

where USERMAIL.NSF is the full path for a mail file or a directory that contains mail files.

For example:
Load Object Set -Never C:\LOTUS\DOMINO\DATA\MAIL\RBOWKER.NSF

sets the mail file RBOWKER.NSF to never use shared mail on the server. The process has no effect on
existing messages.

To include a previously excluded mail file: If you previously excluded a mail file from shared mail and
then want it to use shared mail again, you can re-enable the mail file to use shared mail for new
messages. The process has no effect on existing messages. Enter this command at the console:
Load Object Reset -Never
USERMAIL.NSF

where USERMAIL.NSF is the full path for a mail file or a directory that contains mail files.

For example:
Load Object Reset -Never C:\LOTUS\DOMINO\DATA\MAIL\

resets all mail files in the MAIL directory that were previously excluded from using shared mail so they
use the object store for new mail.

Replicating mail files that use shared mail

By default, when you replicate a primary mail file that uses shared mail to another server, messages in
the new replica are added to the mail file as complete documents, even if shared mail is also enabled on
the destination server. Similarly, all future messages replicated from the primary mail file to the replica
mail file are also added as complete documents. This is necessary, because not only does shared mail
prohibit a mail file on one server from accessing messages in an object store on another server, but the
security settings prevent shared mail databases from replicating between servers.

Chapter 31. Setting Up Shared Mail 827

Enabling shared mail for replica mail files: By default, after you replicate a mail file to a shared mail
server, the new replica does not use shared mail for either existing messages or messages added during
future replications. Enabling shared mail for replicas of mail files increases the available space on servers
that contain mail files that are populated using replication. If a user’s primary mail server is unavailable,
the user can retrieve message content by accessing the replica mail file from the shared mail database on
the secondary server.

To have the replica use shared mail, you can:

v Enable the new replica to use the object store on the new server for messages received from the
primary mail file during future replications
v Enable the new replica to use the object store on the new server for existing messages

Enabling messages added during replication to be placed in the object store: When shared mail is
enabled on a server, mail files hosted on the server automatically use shared mail for new messages
received through the Domino routing process. However, when the replication process, rather than the
Router, adds new mail to a replica mail file, by default, the mail file stores the mail as complete
documents.

To enable messages added during replication to be placed in the object store: To enable messages
added during replication to be placed in the object store, you must set a mail file to always use shared
mail. Enter this command at the console of the server that stores the replica mail files and that uses
shared mail:
Load Object Set -Always USERMAIL.NSF

where USERMAIL.NSF is the name of a replica mail file or a directory that contains replica mail files. For
example,
Load Object Set -Always Dmalone.nsf

causes Domino to store the content of messages replicated to DMALONE.NSF in one of the configured
shared mail databases on the server during future replications.

To split messages that were previously replicated and place the message bodies in a shared mail
database, use the Load Object Link command.

For more information on the Load Object Link command, see the topic ″Linking unshared messages in a
mail file to the object store″ earlier in this chapter.

To enable existing messages in a replica to be placed in the object store: To have a mail file use shared
mail for messages that already existed at the initial replication, link the mail file to the object store on the
second server. For more information on linking a mail file to an object store, see the topic ″Linking
unshared messages in a mail file to the object store″ earlier in this chapter.

To disable shared mail for replica mail files: Enter this command at the console of the server that
stores the replica mail files:
Load Object Reset -Always USERMAIL.NSF

where USERMAIL.NSF is the name of a replica mail file or a directory that contains replica mail files.

Using shared mail with Domino clusters: For a Domino cluster in which some servers have shared
mail enabled, you can create replicas of user mail files, and use cluster replication to increase mail
reliability. Although you cannot use cluster replication to keep shared mail databases synchronized, you
can use cluster replication to replicate information to another mail file replica and then configure that
replica to use shared mail on the local server. Each server in the cluster must have shared mail enabled.

828 Lotus Domino Administrator 7 Help

Use these steps on each cluster member server that hosts replica mail files. Once activated, Domino
clustering (not the Domino Router task) automatically splits any replicated messages into their header
and content portions, saving the headers in the individual mail databases and the content portions in the
shared mail database on the target server.

You can also use this same procedure for mail file replicas located on servers not in a cluster -- that is,
servers kept synchronized by standard Domino replication.

Purging obsolete shared mail messages

Each message in a shared mail database contains object links to the mail files of all recipients of the
message. The number of mail files that a message links to represents the reference or share count for that
message. When a user deletes a message from a personal mail file, Domino immediately removes the
object link to that mail file from the shared mail database.

When all recipients have deleted a message from their mail files, the reference count for the message
reaches zero, and the message becomes obsolete. Domino automatically purges the shared portion of
obsolete messages from the shared mail databases immediately after all users have deleted it from their
mail files.

In earlier releases of Domino, links to user mail files and obsolete messages were not immediately deleted
after users deleted messages from their mail file. Deletions occurred only after the Object Collect task was
run, an expensive process that examines each link in the referencing databases to determine whether the
referring note still exists.

In Domino, the Object Collect task is used to resynchronize mail files with a shared mail database and to
generate shared mail statistics. Synchronization between a shared mail database and the mail files that
use it can become disrupted if a shared mail database is restored from a backup that doesn’t include the
most recently received messages. As a result, these messages are incomplete and cannot be read: the
message headers appear in users’ mail files, but no message body exists in the object store. Running the
Object Collect task resynchronizes a mail file with the object store by purging incomplete messages. The
task checks each mail file that uses the object store and removes those messages that have no message
body in the object store.

If a mail file has replicas on other servers, messages removed during resynchronization can be restored to
the shared mail database when replicated to the mail file on the shared mail server.

Running the Object Collect task to purge messages, automatically generates shared mail statistics. For
information about using the Object Collect task to generate shared mail statistics without purging
messages, see the topic ″Generating and viewing shared mail statistics″ earlier in this chapter.

To preview which messages will be purged: Before purging obsolete messages, enter this command at
the console to determine which documents will be deleted and how much space will become available:
Load Object Collect -Nodelete

To purge messages from the shared mail database: Enter one of these commands at the console:
Load Object Collect SHARED.NSF
Load Object Collect -Force SHARED.NSF

where SHARED.NSF is the name of the shared mail directory or a specific shared mail database. Use the
-Force option after you delete a user’s mail file to reclaim the disk space used by shared messages that
reference the deleted mail file only.

Chapter 31. Setting Up Shared Mail 829

CAUTION:
If you do not indicate a specific database, the Object Collect task purges obsolete messages from all
shared mail databases. Also, before you use the -Force option, ensure that all of the mail files that
store messages in the shared mail database are available. If Domino cannot write to mail file
referenced by the shared mail database -- for example, if the mail file has been moved or cannot
currently accept new mail -- the Object Collect task behaves as though the mail file had been deleted.
As a result, the task deletes messages that should be retained.

To purge messages from a user’s mail file: Enter this command at the console:
Load Object Collect USERMAIL.NSF

where USERMAIL.NSF is the name of the user’s mail file.

Restoring a shared mail database

Data loss is an unusual occurrence, but it can occur. To prevent data loss in a shared mail database,
enable transaction logging, and use a backup utility that supports transaction logs. When you restore
from the backup media, Domino automatically applies any notes that have been added since the backup
was taken. In general, you should perform a complete backup at least once a week, and incremental
backups of the transaction logs every day. Refer to the documentation that came with your backup utility
for specific recommendations.

If you do not use transaction logging, back up the shared mail database at least once a day and use
multiple shared mail databases on the server. Using multiple shared mail databases on different physical
disks can reduce the amount of shared mail data lost in the event of database corruption or disk failure.

If data loss occurs on a server that does not use transaction logging or was not backed up using a utility
that supports transaction logging, you may be unable to restore some messages to the shared mail
database. Therefore, users’ mail files might still contain message headers that reference message content
that was not restored in the shared mail database. These users cannot read these messages because the
shared mail database doesn’t contain the corresponding message content.

To restore a shared mail database when transaction logging is not enabled:

1. Download the most recent backup copy of the shared mail database to a directory that is not part of
the Domino server’s directory structure. The Domino server’s directory structure includes the data
directory, directories that are referenced by directory links, and subdirectories of all of these
directories. The directory can be on a network drive if there is not enough room on the server’s local
disks to store the backup copy of the shared mail database.
2. At the console, enter the Push command to push changes from the backup shared mail database to
the current shared mail database. For example, after downloading the backup copy of the shared mail
database into the directory h:\backup, enter this command at the console:
Push Manufacturing h:\backup\SHARE1.NSF
where Manufacturing is the name of the server and SHARE1.NSF is the name of the shared mail
database.
3. Delete the backup copy of the shared mail database.
4. In the user’s mail file, purge messages that no longer have corresponding message content in the
shared mail file.

Deleting a shared mail database

If your organization decides to stop using shared mail, or a server has several inactive shared mail
databases that only a few mail files still link to, you may need to delete shared mail databases.

Before deleting a shared mail database, unlink all mail files from it. Unlinking mail files from a shared
mail database places a complete copy of each message in the shared mail database in all of the mail files
listed in the message’s object store link. If you delete a shared mail database that is still linked to users’
mail files, those users lose access to message bodies contained in the database.

830 Lotus Domino Administrator 7 Help

Note: Before you unlink a shared mail database, verify the number and size of the messages shared in it
to determine if you have enough disk space available to store complete copies of the shared messages in
each recipient’s mail files.

To delete a shared mail database:

1. Enter this command at the console to generate shared mail statistics that indicate which mail files
have links to the object store:
Load Object Info
-Full OBJECTSTORE
where OBJECTSTORE is the complete path to a shared mail directory or a single shared mail
database.
For more information on generating shared mail statistics, see the topic ″Generating and viewing
shared mail statistics″ earlier in this chapter.
2. View the usage statistics in the Domino Administrator. Use this information to determine if you have
enough disk space available for storing complete copies of the shared messages in the recipients’ mail
files.
3. Enter this command at the console:
Load Object Unlink
SHARED.NSF
where SHARED.NSF is the name of the shared mail database. This unlinks the shared mail database
from all mail files, so that the messages it contained are restored as complete messages to user mail
files.
4. Delete the shared mail database file.

Disabling shared mail

If you decide to return to the use of message-based mail storage, you can disable shared mail on the
server. After you disable shared mail on a server, user mail files that were linked to shared mail remain
linked to the now inactive shared mail databases. Because the shared mail databases still contain the
body portion of previously delivered messages, use caution before moving or removing databases.

To take advantage of the space savings already achieved, you may choose to preserve inactive shared
mail databases in their current state. If you do decide to retain these inactive databases, they must remain
in their current location to allow users to access messages.

To disable shared mail

1. From the Domino Administrator, click the Configuration tab and then expand the Server section.
2. Select the Server document to be edited and then click Edit Server.
3. Click the Shared Mail tab.
4. In the Shared Mail field, choose None.
5. To refresh the shared mail configuration enter the following command at the server console:
SHOW SCOS
For more information about using the Show SCOS command, see the appendix ″Server Commands.″
After you disable shared mail, the Router stops adding new messages to shared mail databases.
However, users whose mail files remain linked to the shared mail database can still access previously
received messages.

Chapter 31. Setting Up Shared Mail 831

832 Lotus Domino Administrator 7 Help
Chapter 32. Setting Up the POP3 Service
This chapter describes how to set up the POP3 service on a Domino server and how to set up POP3
users.

The POP3 service

POP3 (Post Office Protocol Version 3) is an Internet mail protocol that allows a user running a POP3
client -- for example, the Lotus Notes POP3 client, Eudora Pro, or Microsoft Outlook Express -- to retrieve
mail from a server that runs the POP3 service. You can set up a Domino server to run the POP3 service.
The Domino server receives and stores mail for POP3 users, who can then connect to the server to
retrieve their mail.

The Domino POP3 service acts as an intermediary for communications between POP3 mail clients and
the Domino mail server. By default, the Domino POP3 service monitors TCP port 110, where POP3 clients
connect to submit requests to the service to retrieve mail. After receiving a request, the POP3 service
sends mail to the client. POP3 clients let users specify whether to leave a copy of a message on the server
after retrieving it. By default, messages downloaded by the client are deleted from the server.

The POP3 service complies with RFC 1939 - Post Office Protocol Version 3.

Supporting outbound mail service for POP3 clients

POP3 is a mail access protocol only and does not stipulate any method for sending mail. To ensure that
POP3 clients can send outbound mail, you must provide them with access to an SMTP server. The SMTP
server can be the Domino server running the POP3 service, another Domino server, or a non-Domino
SMTP server.

For information about specifying the SMTP server that a POP3 client uses for outbound mail, see the
topic ″Configuring POP3 client software″ later in this chapter.

Authenticating with the server

The Domino server does not check Notes User ID files to verify the identity of users who connect from a
POP3 client. Because the POP3 service does not use ID files to identify users and control access to
servers, a POP3 user does not have to be a registered Notes user. To access mail through the POP3
service, users need a mail file on the server and a Person document (including an Internet password) in
the Domino Directory. Only users who receive encrypted Notes mail or access Domino applications must
be registered Notes users.

To authenticate POP3 users, Domino relies on authentication methods built into the Internet protocols.
The methods available depend on the server ports you configure the POP3 service to use. The POP3
service can use a TCP/IP port, a Secure Sockets Layer (SSL) port, or both the TCP/IP and SSL ports.

If POP3 uses the TCP/IP port only (the default), the server uses basic name-and-password authentication
to identify users. The login names that the server accepts as valid depend on the setting in the Internet
authentication field on the Security tab of the Server document.

For more information on configuring how Domino authenticates Internet clients, see the chapter ″Setting
Up Name-and-Password and Anonymous Access to Domino Servers.″

If the SSL port is enabled, you can specify whether a client certificate is required to authenticate (SSL
authentication), and whether clients must also supply a name and password.

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

Accessing a mail file from the Notes client and a POP3 client
POP3 clients use the standard Domino mail file database. This allows registered Notes users to access
their mail files from both a POP3 client and the Notes mail client.

Setting up the POP3 service

The Domino POP3 service can be run on any Domino server on which a TCP/IP port is configured. The
POP3 protocol provides a mechanism for retrieving mail only; POP3 clients send mail using the SMTP
protocol.

To set up the Domino POP3 service

1. Edit the Server Document to enable the TCP/IP port for POP3.
Optionally, you can configure the POP3 TCP/IP port to run from an alternate port number, and to
accept SSL connections.
For more information on enabling and configuring POP3 ports, see the topic ″Enabling and
configuring the POP3 service port″ later in this chapter.
2. Start the POP3 task on the Domino server.

Starting and stopping the POP3 service

You can load the POP3 service manually or start it automatically when you start the Domino server.

To do this Perform this task

Start the POP3 service manually Enter the following command at the console:

load POP3
Start the POP3 service automatically when you Edit the ServerTasks setting in the NOTES.INI file to include the
start the Domino server command POP3. Domino adds the POP3 task by default to the
NOTES.INI file if you select the POP3 service during installation.
Stop the POP3 service Enter the following command at the console:

tell POP3 quit

Enabling and configuring the POP3 service port

For POP3 clients to access mail files on the server, you must enable a POP3 port on the server. You can
enable the TCP/IP port, the SSL port, or both. By default, the Domino POP3 service uses TCP/IP port
110. A procedure later in this topic explains how to enable and disable the POP3 port, how to set the
POP3 service to use a nonstandard port, and how to change security options for the port.

Configuring POP3 authentication options on servers that use Internet Site documents: On servers that
use Internet Site documents, the POP3 service obtains port authentication settings from the Security tab
of the POP3 Site document, rather than from the Server document. As a result, when Internet Site
documents are used, the TCP/IP and SSL port authentication settings described in the procedures that
follow are not available in the Server document. Settings in the Server document still provide the port
numbers and status for the POP3 TCP/IP and SSL ports, and enable the POP3 ports to honor server
access restrictions.

To determine whether the use of Internet Site documents is enabled for a server, check the value of the
following field on the Basics tab of the Server document: ″Load Internet configurations from
Server\Internet Sites documents.″ If this field is set to ″Enabled,″ the server uses Internet Site documents
to configure all of its Internet protocols (POP3, IMAP, SMTP, and so forth).

834 Lotus Domino Administrator 7 Help

If the server uses Internet Site documents, then you must use Site documents to configure all Internet
protocols on the server. If a POP3 Site document is not present in the Domino Directory, or the
authentication options in a configured POP3 Site document are set to No, users cannot connect to the
POP3 service. In each case, POP3 clients receive the following error when attempting to connect to the
POP3 service:
This site is not enabled on the server.

For information on creating and using Internet Site documents, see the chapter ″Installing and Setting Up
Domino Servers.″

To enable the POP3 TCP/IP port:

1. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the POP3 service.
2. Click the Ports - Internet Ports - Mail tab.
3. To enable the default TCP/IP port, in the Mail (POP) column, change the value of the TCP/IP port
status field to Enabled.
4. Click Save and Close or edit additional settings, as directed in the following procedure.

Note: On servers with multiple TCP/IP ports, by default, the POP3 service uses the port listed first in
the NOTES.INI file as the preferred path. If you want the service to use a port other than the default one,
you can configure it to use a specific port.

For information on configuring an Internet service to bind to a specific TCP/IP port, see the chapter
″Setting Up the Domino Network.″

To configure the POP3 TCP/IP port:

1. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the POP3 service.
2. Click the Ports - Internet Ports - Mail tab.
3. In the Mail (POP) column, complete these fields, and then click Save and Close:

Field Enter
TCP/IP port number Choose 110 (default) to use the industry standard port for POP3 connections over
TCP/IP. You can specify a different port, but 110 works in most situations. When
specifying a nonstandard port, make sure the port is not reserved for another service.
Port numbers can be any number from 1 to 65535.
TCP/IP port status Choose one:
v Enabled (default) - Allows POP3 clients to connect to the Domino server without
using SSL. Users must provide their name and Internet password to connect.
v Disabled - Prevents POP3 clients from connecting to the Domino server, unless they
can connect using SSL.
Enforce server access Choose one:
settings v Yes - Access to the POP3 service is controlled by the server access settings on the
Security tab of the Server document. Users who are not allowed to access the server
cannot access mail through the POP3 service.
v No - (default) The POP3 service ignores the server access settings in the Server
document.

4. Restart the POP3 task to put the new settings into effect.

To enable and configure the POP3 SSL port:

1. Familiarize yourself with the Domino security model and set up SSL on the Domino server.

Chapter 32. Setting Up the POP3 Service 835

2. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the POP3 service.
3. Click the Ports - Internet Ports - Mail tab.
4. In the Mail (POP) column, complete these fields, and then click Save and Close:

Field Enter
SSL port number Choose 995 (default) to use the industry standard port for POP3 connections over SSL.
You can specify a different port, but 995 works in most situations. When specifying a
nonstandard port, make sure the port is not reserved for another service. Port numbers
can be any number from 1 to 65535.
SSL port status Choose one:
v Enabled - Allows POP3 clients to connect to the POP3 service over SSL.
v Disabled - (default) Prevents client connections over SSL.
Authentication options: If ″SSL port status″ is set to Enabled, choose one:
Client certificate v Yes - The POP3 SSL port authenticates POP3 clients that use client certificates. If a
connecting client does not have a certificate, the server reverts to using
name-and-password authentication.
v No - (default) The POP3 SSL port does not support client certificate authentication.
Authentication options: If the ″SSL port status″ field is set to Enabled, choose one:
Name & password v Yes - POP3 clients use name-and-password authentication when connecting to the
POP3 service over SSL.
v No - (default) The POP3 SSL port does not support name-and-password
authentication.

5. Restart the POP3 task to put the new settings into effect.

Performing additional POP3 configuration: In addition to configuring the POP3 service port, you can
customize the operation of the POP3 service by setting variables in the server’s NOTES.INI file. Variables
used to configure the POP3 service begin with the prefix ″POP3.″

For more information on setting variables in the NOTES.INI file, see the appendix ″NOTES.INI File.″

Setting up POP3 users

To set up POP3 users, perform these procedures:
1. Set up the Person document.
2. Create a mail file for the POP3 user.
3. Configure POP3 client software.

Setting up the Person document for a POP3 user

To access mail files on the Domino server, a POP3 user must have a Person document in the Domino
Directory. For users who already have a Person document, edit settings in the existing document as
necessary to provide POP3 support. If a user does not have an existing Person document, you must
create a new one. You can create a Person document manually, or use the Domino registration process to
create the Person document automatically. If you use the Domino registration process, select POP3 in the
″Mail system″ field of the Register Person dialog box.

Note: By default, the Domino registration process generates a Notes ID file (and corresponding Notes
Public Encryption Key in the Domino Directory) for each user in addition to creating the Person
documents and mail files required by a POP3 user. Because users who will access Domino from POP3
clients only do not require a Notes ID, during registration you can deselect the option to ″Create a Notes
ID for this person.″ However, if a new POP3 user also requires access to Domino from a Notes client,
Domino Administrator client, or Domino Designer client, be sure to enable creation of an ID file.

836 Lotus Domino Administrator 7 Help

For more information on using the Domino registration process, see the chapter ″Setting Up and
Managing Notes Users.″

The following procedure specifies the Person document settings required for POP3 users and explains
how to create a Person document manually.

To set up a Person document for a POP3 user:

1. From the Domino Administrator, click the People & Groups tab.
2. Select Domino Directories - Address Book - People.
3. If no Person document exists for this user, click Add Person to create a new Person document.
To display an existing Person document, select the name of the user, and click Edit User.
4. Click the Basics tab, complete these fields, and then click Save & Close:

Field Description
First name The name the client uses to authenticate with the POP3 server must be unique in the
Domino Directory.
Last name
Depending on the level of Internet access security established for the server (Server
User name document - Security tab), the login name or user name configured on the POP3 client
must match an entry in one of these fields. Entries in the User name field are always
accepted as the login name. If Internet authentication is set to allow ″More name
variations with lower security″ entries in the First name and Last name fields may also
be accepted as login names.
Internet password The password that the user enters to access the Domino server from the POP3 client.
POP3 users must have an Internet password that complies with your organization’s
password quality requirements.
Mail system Choose POP or IMAP if the user does not require Notes client access.
Domain The name of the Notes domain to which the server belongs.
Mail server The name of the POP3 user’s Domino mail server.
Mail file The path for the user’s mail file, relative to the Domino data directory -- for example:
MAIL\AJONES.
Forwarding address Leave this blank for users who access mail files on the Domino server from a POP3
client.
Internet address The Internet address at which the user can receive mail within your organization. This
address must match the Internet address specified in the POP3 client.

Chapter 32. Setting Up the POP3 Service 837

Field Description
Format preference for Choose one:
incoming mail v Keep in sender’s format - (default) The mail file may contain messages in either Notes
rich text or MIME format. When delivering messages to the mail file, the local Router
preserves the current message format. Thus messages received at the server in MIME
format are stored in the mail file in MIME format, and messages received at the
server in Notes rich text format are in Notes rich text format. When a POP3 client
requests a message that is stored in Notes rich text format, the POP3 service must
convert the message to MIME before sending it to the client. Because the stored
message remains in Notes rich text format, each time a POP3 client requests the
message, the POP3 service must perform the conversion.
v Prefers MIME - The mail file stores messages in MIME format only. Choose this
option for users who access mail exclusively from a POP3 client. Since POP3 clients
require messages in MIME format, storing mail in MIME format ensures the best
performance for POP3 users, eliminating the need for the POP3 service to convert
messages before passing them to the client.
v Prefers Notes Rich Text - The mail file stores messages in Notes format only. The
Router converts messages received as MIME into Notes rich text before delivery. In
addition, the POP3 task must convert messages to MIME format when sending them
to a POP3 client. To ensure the best performance, do not choose this option for users
who access their Domino mail file primarily from a POP3 client.
When receiving Choose No (default). POP3 clients cannot read encrypted Notes mail.
unencrypted mail, encrypt
before storing in your To ensure that users who read mail exclusively from POP3 clients do not receive
mail file Notes-encrypted mail, remove the POP3 users’ Notes public encryption keys from their
Person documents.
Note: Never remove the Notes public key from the Person document of users who
access Notes databases from a Notes client.

For more information about password quality requirements, refer to the chapter ″Protecting and
Managing Notes IDs.″
5. Complete the procedure ″Creating a mail file for a POP3 user.″

Creating a mail file for a POP3 user

Each POP3 user must have a mail file on the Domino server. You can create the mail file automatically
during user registration, or you can manually create a mail file. If the user is already a registered Notes
user who has an existing Notes mail file and if you set up the Person document to use POP3 as the mail
system, the user can use a POP3 client to access the mail file.

If a user does not have an existing mail file on a Domino server, create a new mail one as described in
the following procedure.

To manually create a mail file:

1. Make sure that you have set up a Person document for the POP3 user.
2. Choose File - Database - New.
3. In the New Database dialog box, enter the following:

Field Enter
Server The Domino mail server that stores the user’s mail file.
Title The name of the client’s mail file -- for example, Alan Jones’ Mail.
File name The full path to the mail file, relative to the Domino data directory -- for example,
MAIL\AJONES.NSF.

4. From the list of template names, select Mail (R6) with the filename MAIL6.NTF, and click OK.

838 Lotus Domino Administrator 7 Help

5. After Domino creates and opens the mail file, determine what level of access is appropriate for both
the user and you, as the administrator. Then, edit the Access Control List (ACL) as follows:
a. Choose File - Database - Access Control.
b. From the Access Control List dialog box, create an ACL entry for the user by clicking Add and
then selecting the user’s name from the Domino Directory.
c. Set the user type to Person and select the level of access. Users require at least Editor with Delete
document access.
d. (Optional) Select your name from the ACL and click Remove. As the administrator, you can
choose to retain Manager access, particularly for users who do not have Notes client access.
e. Click OK to save the entry and close the ACL.
6. Complete the procedure ″Configuring POP3 client software.″

Configuring POP3 client software

After you set up a Domino server to run the POP3 service, users can access their mail files on the
Domino server from any POP3 mail client. The POP3 service supports all POP3-compliant clients -- for
example, the Lotus Notes POP3 client, Microsoft Outlook and Outlook Express, and Qualcomm Eudora.

The requirements for configuring POP3 client software differ for each product. This table presents general
requirements.

Field
Incoming mail (POP3) server
Outgoing mail (SMTP) server
Authentication required to send
outbound mail
Account/Login name
Password
Automatically delete mail
documents from the POP3 server
after the client copies them
locally.
POP3 client should check for
mail no more than every five (5)
minutes.
E-mail address
Description
Fully qualified host name of Domino POP3 server.
The fully qualified host name of a server running SMTP to which the user can
send mail addressed to intranet or Internet recipients. The SMTP server may be
the Domino server running the POP3 service, a different Domino server, or a
non-Domino SMTP server.
Specifies whether the configured SMTP server requires users to provide a name
and password before they can send outgoing messages.
The name by which the user authenticates with the Domino server. Valid user
name values depend on the setting in the Internet authentication field of the
Server document:
v If the server is set to use ″More name variations with lower security,″ users can
enter a login name that matches any entry in the First name, Last name, User
name or Short name/UserID field of the Person document, as long as it is
unique within the Domino Directory, for example, JCorrer.
v If the server uses ″Fewer name variations with higher security,″ a user’s login
name must match an entry in the User name field of the Person document, for
example, Jada Correr/ACME
The Internet password from the user’s Person document.
By default, when downloading messages from the server, most POP3 clients
delete the server copy to conserve disk space. For users who read mail from both
the Notes client and a POP3 client, make sure the POP3 client is set to leave
messages on the server.
Determines how often the POP3 client checks for mail. If the client checks for
mail more frequently, it may affect server performance.
The Internet address specified in the user’s Person document.

For more information on the relationship between security settings and valid login names, see the chapter
″Setting Up Name-and-Password and Anonymous Access to Domino Servers.″

Chapter 32. Setting Up the POP3 Service 839

840 Lotus Domino Administrator 7 Help
Chapter 33. Setting Up the IMAP Service
This chapter describes how to set up a Domino server to use the IMAP service and how to set up IMAP
users.

The IMAP service

The Domino server supports the Internet Mail Access Protocol (IMAP4rev1), defined in RFC 2060, for
reading mail. The Domino IMAP service lets users with IMAP mail clients access mail files on a Domino
server. The IMAP service differs from the POP3 service in that users are not required to download
messages to a local computer to read and manipulate them. Users can work with messages over the
network, while the messages remain on the server.

The Domino IMAP service acts as an intermediary for communications between IMAP mail clients and
the Domino mail server. By default, the IMAP service monitors TCP port 143 for IMAP client requests.
After connecting to the IMAP service, IMAP mail clients can:
v Access messages on the Domino mail server
v Retrieve messages from the Domino mail server and store them locally
v Copy messages for offline use and then later synchronize with mail on the server
v View folders in another user’s mail file or public folders in a shared database (requires a client that
supports the IMAP NAMESPACE extension)

Supporting outbound mail service for IMAP clients

IMAP is a mail access protocol only and does not stipulate any method for sending mail. To ensure that
IMAP users can send outbound mail, you must provide them with access to an SMTP server. The SMTP
server can be the Domino server running the IMAP service, another Domino server, or a non-Domino
SMTP server.

For information about specifying the SMTP server that an IMAP client uses for outbound mail, see the
topic ″Configuring IMAP client software″ later in this chapter.

Authenticating with the server

When a user connects to the IMAP service, rather than verifying the user’s identity by checking a Notes
ID file, the IMAP service uses name-and-password authentication, SSL, or both. Because Notes ID files
are not used, an IMAP user does not have to be a registered Notes user. To access mail through the IMAP
service, users need a mail file on the server and a Person document (including an Internet password) in
the Domino Directory. Only users who receive encrypted Notes mail or access Domino applications must
be registered Notes users. The IMAP service can authenticate users from entries in the primary Domino
Directory or any secondary directory used by the server.

To authenticate IMAP users, Domino relies on authentication methods built into the Internet protocols.
The methods available depend on the server ports you configure the IMAP service to use. The IMAP
service can use a TCP/IP port, or a Secure Sockets Layer (SSL) port, or both the TCP/IP and SSL ports.

If IMAP uses the TCP/IP port only (the default), the server uses basic name-and-password authentication
to identify users. The name under which a user can log in to the IMAP service must match one of several
fields in the user’s Person document. The set of names that the server accepts as valid depends on the
setting in the Internet authentication field on the Security tab of the Server document.

For more information on configuring how Domino authenticates Internet clients, see the chapter ″Setting
Up Name-and-Password and Anonymous Access to Domino Servers.″

841
If the IMAP SSL port is enabled, you can specify whether a client certificate is required to authenticate
(SSL authentication), and whether clients must also supply a name and password.

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

How Domino modifies mail files to support IMAP

IMAP clients use a standard Domino mail file that must be specially enabled for IMAP. If you enable
IMAP access for the mail file of a registered Notes user, the user can access the file from either the Notes
client or from an IMAP client.

A standard Domino mail file stores information about the messages it contains within database items of
the message. Notes clients can read and interpret the information stored in these items, but IMAP clients
cannot. To support IMAP clients and store IMAP-specific information, the Domino mail file requires the
addition of special IMAP database items.

IMAP stores message information within its own set of attributes. For a Domino mail file to be used with
IMAP, Notes/Domino items in the mail file have to be translated into IMAP attributes. In addition, the
mail file must be set up so that all future messages delivered to it store attribute information in IMAP
format.

To enable IMAP clients to access Domino mail files, run the mail conversion utility. The conversion
process places information about each message, such as its message ID and folder location, into the
message’s IMAP attributes, and sets a flag in the mail file that notifies the Router to add these IMAP
attributes when delivering future messages.

You can run the conversion utility manually to convert mail files before users log in to the IMAP service,
or set up the IMAP service so that it converts mail files automatically the first time a user logs in.

Note: To avoid possible conversion delays, run the conversion utility before users log in.

Before running the conversion utility, you may first need to prepare the mail file. For more information,
see the topic ″Preparing a mail file for IMAP access″ later in this chapter.

Additional IMAP attributes for improving client download of message headers

When an IMAP client opens an IMAP-enabled mail file, it issues a FETCH command to the server,
requesting information that enables it to display message headers. To improve performance for IMAP
clients downloading message headers, the Router adds these IMAP attributes to messages delivered to an
IMAP-enabled mail file:
v $Content_Type
v IMAP_BodyStruct
v IMAP_RFC822Size

Note: The Router adds these attributes only if the recipient’s Person document specifies MIME as the
preferred mail storage format. The attributes are not added to messages delivered in MIME format to a
user whose storage preference is set to ″Keep in sender’s format.″

These attributes contain summary information about the MIME content type, structure, and size of a
message. Exactly how the attributes are used depends on the client. Almost all clients request size
information. In addition, some request type and body structure information. If these summary attributes
are present, when the IMAP service returns message headers in response to a client FETCH request, it
uses the attribute information to fulfill the request, rather than opening each message to obtain the
information. As a result, the client displays message headers much more quickly than it can in the
absence of the summary attributes. The improved response time is especially significant for large mail
files with a a high percentage of messages in Notes rich text format.

842 Lotus Domino Administrator 7 Help

Note: The Domino Release 6, and more recent, IMAP service does not use the settings on the Basics tab
of the Configuration Settings document for specifying whether to return the exact size of messages. This
field appears in the Configuration Settings document to provide backward compatibility with earlier
versions of Domino.

After you run the conversion utility to enable a mail file for IMAP use, you have to run the conversion
utility a second time, using the -h option, to add these attributes to messages. The initial mail file
conversion performed to enable a mail file for IMAP use does not add IMAP-specific attributes to
pre-existing messages in the mail file, regardless of whether you run CONVERT manually or let the
IMAP service automatically enable mail files. Thus messages added to a mail file before it is enabled for
IMAP never contain these summary attributes.

After you enable a mail file for IMAP use, the Router automatically adds these IMAP attributes to
messages, if the mail storage preference is set to Prefers MIME in the user’s Person document. However
it does not add them to messages stored in Notes rich text format.

For more information about running the mail conversion utility using the -h option, see the topic ″Using
the conversion utility to add IMAP summary attributes to messages″ later in this chapter

Setting up the IMAP service

The Domino IMAP service can be run on any Domino server on which a TCP/IP port is configured. For
information about configuring TCP/IP, refer to the chapter ″Setting Up the Domino network.″

IMAP provides a mechanism for retrieving mail only; IMAP clients send mail using SMTP. For
information about enabling SMTP, refer to the chapter ″Setting Up Mail Routing.″

To set up the Domino IMAP service

1. Edit the Server Document to enable the TCP/IP port for IMAP
Optionally, you can configure the IMAP TCP/IP port to run from an alternate port number, and to
accept SSL connections.
For more information on enabling and configuring IMAP ports, refer to the topic ″Enabling and
configuring the IMAP service port″ later in this chapter.
2. Start the IMAP task on the Domino server.

Starting and stopping the IMAP task

You can load the IMAP task manually or start it automatically when you start the Domino server.

To do this Perform this task

Start the IMAP service manually Enter the following command at the console:

load imap
Start the IMAP service automatically when you start Edit the ServerTasks setting in the NOTES.INI file to include
the Domino server the command imap. Domino adds the IMAP task by default
to the NOTES.INI file if you select the IMAP service during
installation.
Stop the IMAP service Enter the following command at the console:

tell imap quit

Customizing the IMAP service

You customize the IMAP service by editing the Server document and Configuration Settings document.
You can change the following settings:
v IMAP port configuration

Chapter 33. Setting Up the IMAP Service 843

v IMAP session limits
v Enable IMAP during login
v Access to other users’ and public folders
v Thread use
v Default service greetings

Enabling and configuring the IMAP service port

From the Domino Administrator you can modify the current IMAP port configuration to:
v Enable or disable the IMAP TCP/IP or SSL port
v Change the TCP/IP or SSL port number
v Enable or disable TCP/IP or SSL authentication options

By default, IMAP clients connect to TCP/IP port 143 on the Domino server. You might need to specify a
different port number if there are multiple instances of the IMAP service on the host machine as, for
example, on a partitioned server. You might also change the default port to a nonstandard port number
to ″hide″ it from clients attempting to connect to the default port, or if another application uses the
default port on the server. Disable the port or change the security options to prevent IMAP clients from
accessing the Domino server.

Configuring IMAP authentication options on servers that use Internet Site documents: On servers that
use Internet Site documents, the IMAP service obtains port authentication settings from the Security tab
of the IMAP Site document, rather than from the Server document. As a result, when Internet Site
documents are used, the TCP/IP and SSL port authentication settings described in the procedures that
follow are not available in the Server document. Settings in the Server document still provide the port
numbers and status for the IMAP TCP/IP and SSL ports, and enable the IMAP ports to honor server
access restrictions.

To determine whether the use of Internet Site documents is enabled for a server, check the value of the
following field on the Basics tab of the Server document: ″Load Internet configurations from
Server\Internet Sites documents.″ If this field is set to ″Enabled,″ the server uses Internet Site documents
to configure all of its Internet protocols (IMAP, POP3, SMTP, and so forth).

If the server uses Internet Site documents, and an IMAP Site document is not present in the Domino
Directory, or the authentication options in a configured IMAP Site document are set to No, users cannot
connect to the IMAP service. In each case, IMAP clients receive the following error when attempting to
connect to the IMAP service:
This site is not enabled on the server.

For information on creating and using Internet Site documents, see the chapter ″Installing and Setting Up
Domino Servers.″

To enable the IMAP TCP/IP port:

1. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the IMAP service.
2. Click the Ports - Internet Ports - Mail tab.
3. To enable the default TCP/IP port, in the Mail (IMAP) column, change the value of the TCP/IP port
status field to Enabled.
4. Click Save and Close or edit additional settings, as directed in the following procedure.

Note: On servers with multiple TCP/IP ports, by default, the IMAP service uses the port listed first in
the NOTES.INI file as the preferred path. If you want the service to use a port other than the default one,
you can configure it to use a specific port.

844 Lotus Domino Administrator 7 Help

For information on configuring an Internet service to bind to a specific TCP/IP port, see the chapter
″Setting Up the Domino Network.″

To configure the IMAP TCP/IP port:

1. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the IMAP service.
2. Click the Ports - Internet Ports - Mail tab.
3. In the Mail (IMAP) column, complete these fields, and then click Save & Close:

Field Enter
TCP/IP port number Choose 143 (default) to use the industry standard port for IMAP connections over
TCP/IP. You can specify a different port, but 143 works in most situations. When
specifying a nonstandard port, make sure the port is not reserved for another service.
Port numbers can be any number from 1 to 65535.
TCP/IP port status Choose one:
v Enabled (default) - Allows IMAP clients to connect to the Domino server without
using SSL. Users must provide their name and Internet password to connect.
v Disabled - Prevents IMAP clients from connecting to the Domino server, unless they
can connect using SSL.
v Redirect to SSL - Denies access to clients connecting to the IMAP TCP/IP port, but
returns a message indicating that they must connect over SSL. You can specify the
contents of the message.
Note: To support IMAP clients, either the IMAP TCP/IP port or the IMAP SSL port
must be enabled, and the IMAP task must be running on the server.
Enforce server access Choose one:
settings v Yes - Access to the IMAP service is controlled by the server access settings on the
Security tab of the Server document. Users who are not allowed to access the server
cannot access mail through the IMAP service.
v No - (default) The IMAP service ignores the server access settings in the Server
document.

For information on customizing IMAP service greetings, see the topic ″Specifying the default IMAP
service greetings″ later in this chapter.
For instructions on setting up the IMAP SSL port, refer to the next topic, ″To enable and configure the
IMAP SSL port.″
4. Restart the IMAP task to put the new settings into effect.

To enable and configure the IMAP SSL port:

1. Familiarize yourself with the Domino security model and set up SSL on the Domino server.
2. From the Domino Administrator, click the Configuration tab and then open the Server document for
the server that runs the IMAP service.
3. Click the Ports - Internet Ports - Mail tab.
4. In the Mail (IMAP) column, complete these fields, and then click Save & Close:

Field Enter
SSL port number Choose 993 (default) to use the industry standard port for IMAP connections over SSL.
You can specify a different port, but 993 works in most situations. When specifying a
nonstandard port, make sure the port is not reserved for another service. Port numbers
can be any number from 1 to 65535.
SSL port status Choose one:
v Enabled - Allows IMAP clients to connect to the IMAP service over SSL.
v Disabled - (default) Prevents client connections over SSL.

Chapter 33. Setting Up the IMAP Service 845

Field Enter
Authentication options: If ″SSL port status″ is set to Enabled, choose one of the following:
Client certificate v Yes - Allows IMAP clients to connect using client certificate authentication.
v No - (default) Prevents the IMAP service from using client certificate authentication.
Authentication options: If the ″SSL port status″ field is set to Enabled, choose one of the following:
Name & password v Yes - Allows IMAP clients to use name-and-password authentication when connecting
to the IMAP service over SSL.
v No - (default) Prevents IMAP clients from using name-and-password authentication
over SSL.

5. Restart the IMAP task to put the new settings into effect.

Setting IMAP session limits

You can configure the following IMAP session limits:
v Maximum number of IMAP sessions
v Default timeout value

Specifying the maximum number of IMAP sessions: To maintain a session with a client, Domino
allocates a main session thread, which uses a certain portion of the server’s memory. Each IMAP client
connecting to the server consumes an additional session thread, and thus a certain amount of memory. If
the number of IMAP sessions exceeds the amount of available memory, the server can become unstable.

To ensure that servers can properly support the number of connecting IMAP clients, you can set a limit
on the number of concurrent IMAP sessions allowed. By default, servers do not place limits on the
number of concurrent IMAP sessions.

After the number of sessions reaches the specified limit, the IMAP service rejects additional connection
attempts.

Note: You cannot use the NOTES.INI variable, IMAPMaxSessions, available in Domino 5.0.3, to limit the
number of IMAP sessions on a Domino Release 6, and more recent, server.

Specifying a default IMAP session timeout value: After a user opens a session with the IMAP service,
the service waits for commands from the mail client. If no commands are received, the session is
considered to be idle. Sessions that are idle for a long period may be the result of a user forgetting to log
out after completing their mail processing. Because servers must allocate memory for each IMAP session
and send periodic keep-alive messages to a client to maintain the connection, idle sessions represent a
waste of server resources.

You can limit how long the server continues to maintain client sessions that do not show any activity.
Specify the number of minutes that the IMAP service waits before disconnecting idle IMAP client
sessions. Many IMAP clients poll for new mail every 10 minutes, so it’s best to set the value to greater
than 10 minutes, because the overhead of supporting an idle session is less than the overhead required to
support clients logging in and opening mailboxes.

By default, servers drop idle sessions after 30 minutes.

Note: You cannot use the NOTES.INI variable, IMAP_Session_Timeout, available in earlier versions of
Domino, to configure the IMAP session timeout on a Domino Release 6, and more recent, server.

To set IMAP session limits:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.

846 Lotus Domino Administrator 7 Help

3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to restrict mail on,
and click Edit Configuration.
5. Click the IMAP - Basics tab.
6. Complete the following fields and then click Save & Close:

Field Enter
Maximum number of The maximum number of concurrent IMAP client sessions the server allows. By default,
IMAP sessions no limit is imposed.
IMAP session timeout The time, in minutes, that the IMAP service continues to maintain an idle session. If
there is no client activity by the end of the specified time, Domino closes the session. By
default, servers drop idle sessions after 30 minutes.

Note: These settings apply to Domino Release 6 and more recent. To specify IMAP session limits on a
Domino Release 5 or earlier server, use the IMAPMaxSessions and IMAP_Session_Timeout settings in
the NOTES.INI file.
For more information on these settings, see the appendix ″NOTES.INI File.″

Setting the IMAP service to automatically enable mail files at login

User mail files must be specially enabled for IMAP use. After a mail file is enabled, Domino converts
information about each message in the mail file, such as its message ID and folder location, into a set of
IMAP attributes. IMAP clients use these attributes to organize messages for display. An additional
attribute informs the Router to add IMAP attributes to new messages delivered to the mail file.

Note: When the mail conversion utility enables a mail file for IMAP use, it does not automatically add
IMAP summary attributes, which enable clients to download message headers more efficiently, to
messages that were already in the file before conversion occurred. To add IMAP summary attributes to
preexisting messages, rerun the conversion utility manually, using the -h option.

For information on adding IMAP summary attributes to messages in a user’s mail file, see the topic
″Using the conversion utility to add IMAP summary attributes to messages″ later in this chapter.

By default, the IMAP service is set to automatically enable mail files during login. When the default
setting is used, whenever a user logs in, the IMAP service checks the user’s mail file to see if it is
enabled. If a mail file is not currently enabled, the IMAP service provides a dedicated conversion thread
to enable it. This conversion thread continues to work on this one mail file until it completes the task. If
additional users require conversion services at the same time, the IMAP service provides an additional
conversion thread for each instance.

Each conversion can require several minutes to complete, with conversion times for users with slow
connections typically needing more time. Because the conversion threads are drawn from the same thread
pool responsible for servicing other IMAP requests, a high number of conversions can place a high
demand on the available IMAP resources. This can result in increased response times and service delays
not only for the those whose mail files require conversion, but for other users connecting to the service as
well. The likelihood of delay naturally increases if there are a large number of users accessing the server
for the first time.

To prevent service delays on busy servers where many mail files require conversion, consider disabling
automatic conversion during peak hours, particularly if users typically log in over a phone line or other
slow connection. If you disable automatic conversion, users whose mail files are not enabled for the
Domino Release 6, or more recent, IMAP service cannot access their mail files from an IMAP client and
receive the following error message after each login attempt:
The database has not been enabled for IMAP.

Chapter 33. Setting Up the IMAP Service 847

When automatic conversion is not available, you must convert users’ mail files manually before they can
access mail from IMAP clients. For information on manually converting mail files for IMAP access, see
the topic ″Running the mail conversion utility to enable a mail file for IMAP″ later in this chapter.

To specify whether the IMAP service automatically enables mail files:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to restrict mail on,
and click Edit Configuration.
5. Click the IMAP - Basics tab.
6. Complete the following field and then click Save & Close:

Field Enter
Enable IMAP during login Choose one:
v Enabled - (default) The IMAP service automatically converts mail files to Lotus
Domino Release 6 IMAP format the first time a user logs in from an IMAP client.
v Disabled - Administrators must manually convert mail files for IMAP use before
users can access mail from an IMAP client.

Configuring the IMAP service to allow shared access to mail files

In addition to providing access to a user’s personal mail folders, the IMAP service supports the
NAMESPACE extension, which permits controlled access to shared mail files. By default, when the IMAP
service is installed, NAMESPACE support is enabled so that clients accessing the service can view and
open their personal mail files, as well as any other mail file on the server that they have permission to
use -- for example other users’ personal mail files to which they have been delegated access, and any
public mail files that you set up as IMAP public folders.

As with personal mail files, an IMAP client can access Public and other users’ mail files only if they
reside on the same server as the IMAP service. In addition, the IMAP service must be able to authenticate
the user from an entry in a configured directory on the server.

To configure namespace support on the server, enable NAMESPACE support so that IMAP users can
view other users’ and public mail files to which they’ve been granted access, and then do one or both of
the following:
v Configure IMAP public folders
v Configure IMAP other users’ folders
For information about enabling IMAP namespace support, see the topic ″Enabling the IMAP service to
automatically display all accessible mail folders″ later in this chapter.
For information about delegating access to a mail file, see Lotus Notes 7 Help, which is available from
the Documentation Library at the Lotus Developer Domain at http://www.lotus.com/ldd/doc.

Note: To provide IMAP users with access to other users’ mail files, you must use a Notes client or
Domino Web Access client to delegate mail file access. You can not delegate access by adding names to
the ACL of the mail file. To enable IMAP access to other users’ mail files, the Domino Administration
Process (AdminP) must process an IMAP delegation request, which is only generated in response to a
user setting delegation preferences from a Notes or IMAP mail client.

About IMAP namespaces: Typically, most users have a personal mail file to which they alone have
access. The IMAP service considers messages in a personal mail file to exist in a hierarchy known as the
personal namespace.

848 Lotus Domino Administrator 7 Help

In addition to the personal namespace, messages can also exist in other hierarchies. For example, if a user
is granted access to another user’s mail file, such as when a secretary has been delegated access to a
manager’s mail file, messages in that mail file become available under an additional hierarchy, the other
users’ namespace.

Other mail files for example, mail-in databases that are intended to be shared amongst users, do not exist
within a single user’s namespace at all, but are intended for public access. Messages in these mail files
exist only in the shared or public namespace.

Enabling the IMAP service to automatically display all accessible mail folders
The Domino IMAP service complies with RFC 2342, which defines a method by which the IMAP service
automatically presents a client with a list of all mail files to which the current user has access, including:
v The user’s personal mail file
v Other users’ personal mail files to which the user has been delegated access
v Public mail files, such as mail-in databases, to which the user has access, and which are set up as
IMAP public folders.
For information about delegating access to a mail file, see Lotus Notes 7 Help.

Note: To provide IMAP users with access to other users’ mail files, you must use a Notes client or
Domino Web Access client to delegate mail file access. It is not sufficient to add the names of users to the
ACL of the mail file.

Enabling clients that do not support the NAMESPACE extension to access shared folders: By default,
only IMAP clients that support the NAMESPACE extension can display mail files other than the user’s
personal mail file. However, you can configure the IMAP service so that it presents public and others
users’ folders even if the user’s IMAP client does not have built-in NAMESPACE support. Configured in
this way, the IMAP service always returns to the client the complete range of mail folders to which the
current user has access.

To enable IMAP NAMESPACE support on the server:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the IMAP - Public and Other Users’ Folders tab.
6. In the Basics section, complete the following field and then click Save & Close:

Field Enter
Public and other users’ Choose one:
folders support v Enabled - (default) In addition to presenting an IMAP client with the current user’s
mail folder, the IMAP service also presents any public folders and other users’ mail
files that the current user has access to.
v Disabled - The IMAP service does not present IMAP clients with public and other
users’ mail folders. The IMAP client can access the current user’s personal mail file
only.

Chapter 33. Setting Up the IMAP Service 849

Field Enter
Include all public and Choose one:
other users’ folders when v Enabled - The IMAP service always displays all available folders to the connecting
a folder list is requested client.
v Disabled - (default) The IMAP service displays available folders in the Other users’
and Public namespaces only to clients that request them using the NAMESPACE
command. If a client does not support the NAMESPACE command, the IMAP service
presents to it the current user’s personal mail folder only.
Note: This field is not available if ″Public and other users’ folders support″ is set to
Disabled.

Note: These settings apply to Domino Release 7 and later only.

Changes take effect after the next IMAP update interval. Sessions that begin after the updated settings
take effect use the updated settings. However, existing sessions continue to use the settings that were
in effect when the session started.
7. To force an immediate update, restart the IMAP service.
For information on how to restart the IMAP service, see the topic ″Starting and stopping the IMAP
service″ earlier in this chapter.
For information on setting the NOTES.INI variable IMAP_Config_Update_Interval to control the
IMAP update interval, refer to the appendix ″NOTES.INI.File.″

Configuring IMAP Public folders

To provide IMAP clients with access to a public mail database, you must do the following:
v Use the mail conversion utility to enable the database for IMAP use
v Specify the appropriate level of access for users in the database ACL, including the Maximum Internet
name and password access.
v Designate the database as an IMAP public folder

The IMAP service does not automatically enable databases other than the user’s personal mail file for
IMAP use. To enable a mail-in database for IMAP use, run the mail conversion utility.

Users’ access to a shared database is defined by their entries in the database ACL. Before users can access
a public folder, an administrator must explicitly grant them access to the database by editing the ACL. If
the database ACL does not grant a user access to an IMAP public folder, when the user logs in from an
IMAP client, the client displays the folder, but does not display the folder Inbox.

To designate a Notes database as an IMAP public folder, copy its database link and paste it into the
Configuration Settings document.

Note: To be configured as a public folder, a database must be created from a Notes mail template. The
IMAP service does not support the use of NNTP or discussion databases as IMAP public folders.

To configure Notes databases for use as IMAP public folders:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Notes client or Domino Administrator client, select a database that has been enabled for
IMAP access to be designated as an IMAP public folder and copy it as a database link.
For example, from the Files tab of the Domino Administrator client, double-click the database icon to
open it, and then click Edit - Copy As Link - Database Link to copy the database as a link.
3. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
4. Click Configurations.

850 Lotus Domino Administrator 7 Help

5. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
6. Click the IMAP - Public and Other Users’ Folders tab.
7. Complete the following field and then click Save & Close:

Field Description
Public folder prefix The name of the virtual root folder Domino uses to organize the hierarchy of Notes mail
databases configured as IMAP public folders. When an IMAP client connects to the server
it displays the public folders available to the user as subfolders of this folder.

Unless you have a specific reason to change the folder prefix, accept the default name to
ensure IMAP clients can access public folders on the server.
Public folder database Database links for IMAP-enabled Notes mail databases you want to designate as IMAP
links public folders. Paste the database link copied in Step 2 into this field.

For example, insert the cursor in the field and click Edit - Paste. The Notes database
represented by the link is now designated as an IMAP public folder. Users with the
appropriate access privileges can open the database from an IMAP client.

Note: These settings apply to Domino Release 7 and later only.

Configuring IMAP Other Users’ folders

If NAMESPACE support is enabled on the server, in addition to displaying the current user’s primary
personal mail folders, an IMAP client displays the personal namespaces of other users who have
explicitly granted access to their personal mail files to the currently authenticated user.

The default configuration for the Other Users’ namespace on the server will support most installations. If
necessary you can customize the Other Users’ namespace on the server, by doing the following:
v Changing the default folder prefix
v Changing the default domain delimiter the IMAP service uses to display user mail file names
v Specifying IMAP users who can change other users’ unread marks

Changing the default folder prefix: To enable IMAP users to view other personal mail files to which
they have access, the IMAP service maintains a virtual list, or collection, of those mail files on the server
whose owners have granted access privileges to one or more secondary users. This collection of other
users’ mail files represents the hierarchy, in addition to a user’s own mail folders hierarchy and the
hierarchy of publicly-accessible mail files, in which a message may exist.

Specifying IMAP users who can change other users’ unread marks: By default, the only user allowed
to change unread marks in a mail file is the Notes user with primary access to the file. If a secondary
user accesses the mail file, any documents opened are marked as read for the secondary user, but not for
the primary user. This is similar to what happens in a discussion database, where multiple users can read
documents and each maintain their own set of unread marks.

Some organizations employ third-party messaging services that run in conjunction with the Domino
IMAP service to provide users with alternate means for accessing their mail files. For example, a unified
messaging service might connect to the IMAP service to access the Domino mail server, acting, in effect,
as an IMAP client. Users connecting to the third-party service can open, read, send, and forward mail. To
ensure that the unread marks in users’ mail files are properly maintained, the third-party service must
have the ability to change unread marks on the user’s behalf, as if it were the mail file owner.

To provide a third-party application with access to a mail file, at minimum, the mail file ACL must grant
the application Designer access.

To configure IMAP support for access to Other Users’ folders:

Chapter 33. Setting Up the IMAP Service 851

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the IMAP - Public and Other Users’ Folders tab.
6. In the Other Users’ Folders section, complete the following field and then click Save & Close:

Field Enter
Other users’ folder prefix The name of the virtual root folder which contains Notes mail databases whose owners
delegated access to other users. When an IMAP client connects to the server it displays
the other users’ folders to whom the user has access as subfolders of this folder.

Unless you have a specific reason to change the folder prefix, accept the default name to
ensure IMAP clients can access other users’ folders on the server.
Other users’ domain The character that Domino uses to separate the common name, organizational unit(s),
delimiter and organization name in a users’ Notes hierarchical names when displaying the user’s
mail file to an IMAP client as part of the Other users’ folder list. Default is forward
slash ( / ). For IMAP clients that cannot display hierarchical names that contain the
default separator character, specify a different character, for instance a dot (″.″) or pipe
character ( ″|″).

For example, if you enter the pipe character, Domino sends the mail folder of a user
named Jada Mendez/Sales/Acme to IMAP clients as Jada Mendez|Sales|Acme.
IMAP users who can The fully-qualified Notes names of users who are permitted to change the unread status
change other users’ of messages in other users’ mail files. You can also enter the name of a Notes group.
unread marks

The change takes effect after the next IMAP service update. You can restart the IMAP service to force
an immediate update to the IMAP service configuration.
7. To provide other another user with access to a personal mail file, instruct the mail file owner to
delegate access from a Notes client.
For information about delegating access to a mail file from a Notes client, see the topic ″Delegating
mail access″ if you have installed Lotus Notes 7 Help. Or, visit the Documentation Library in the
Lotus Developer Domain at http://www.lotus.com/ldd/doc to download or view Lotus Notes 7
Help.

Note: To provide IMAP users with access to other users’ mail files, you must use a Notes client or
Domino Web Access client to delegate mail file access. It is not sufficient to add the names of users to
the ACL of the mail file.

Configuring IMAP internal thread use

The IMAP service acts as an intermediary between IMAP clients attempting to retrieve messages and the
Domino mail server. IMAP clients do not have direct access to mail files on the Domino server; instead,
the IMAP service acts as a proxy, relaying each client’s request to retrieve messages to the mail server. To
return message data to the client, Domino opens the mail database and passes on the requested
information to the IMAP service. The IMAP service then sends the requested message information to the
client.

An IMAP session begins when a user at an IMAP client logs in to the Domino IMAP service. Domino
allocates each IMAP session its own session thread from the server’s main thread pool. This session
thread becomes the sole channel for all communications between the client and the IMAP service. When
the session ends, Domino returns the thread to the pool for use by another client.

852 Lotus Domino Administrator 7 Help

The session thread communicates directly with the server’s IMAP port to receive client input, validate the
syntax of received requests, queue requests to the IMAP service, and send responses from the service
back to the client. If the IMAP service is slow to respond, the main thread also sends periodic keep-alive
messages to the client so that it does not close the connection.

A Domino server can interact with multiple clients simultaneously because it allocates a new thread to
service each client session. Clients connect to a port and exchange all input and output through that port.
Threads require memory and CPU time. The thread pool contains a limited number of physical threads,
but thread use is virtualized so that a single thread works on different tasks. Thus in a fraction of a
second, a single thread that is idled by one task as it waits for information, can switch to another task.
This allows Domino to maximize processor use and minimize memory.

By avoiding the need to create a new physical thread for each requested connection, Domino makes the
best use of available memory. However, a high number of IMAP sessions can place a strain on the server.
If clients experience slow response during times of peak usage, consider limiting the number of IMAP
sessions.

The internal IMAP thread pool: The Domino IMAP service provides an internal IMAP thread pool that
is independent of the thread pool that Domino uses to create client sessions. The default number of
available threads is based on the amount of physical memory the server has. The service has a minimum
of 50 threads available and a maximum of 400 threads. To ensure that the IMAP service continues to
function properly, it’s best to use the default thread pool settings and modify these settings only at the
direction of a qualified IBM support representative.

The IMAP thread pool consists of three types of worker threads as shown in the following table:

Thread type Description Default maximum value

FETCH thread
FETCH response thread
LOGIN conversion thread
Accepts validated FETCH commands 80% of pool total
from the client and transmits them to
the Domino mail service
Transmits message data from the 80% of pool total
Domino mail service to fulfill client
FETCH requests
Converts mail files to IMAP format None

Available threads become active when the main session thread queues a request.

To specify IMAP thread use:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to restrict mail on,
and click Edit Configuration.
5. Click the IMAP - Advanced tab.
6. In the Worker thread pool section, complete the following:

Field Description
Maximum number of IMAP The total number of threads available in the IMAP service’s thread pool, including
worker threads Login conversion threads for upgrading mail files to Domino Release 6 IMAP format;
FETCH threads for transmitting validated client requests to the Domino mail server;
and FETCH response threads for transmitting message data from the mail server in
response to client FETCH requests.

Chapter 33. Setting Up the IMAP Service 853

Field Description
Maximum number of The number of threads available to transmit message data to fulfill a given FETCH
response threads per FETCH request (default is 4).
Maximum number of The Number of concurrent threads the IMAP service can use to transmit client
FETCH threads allowed requests to FETCH message data to the Domino mail server
Maximum number of The number of threads the IMAP service can use to return message data from the
FETCH response threads Domino mail server in response to FETCH requests received from all active IMAP
allowed sessions.

Note: These settings apply to Domino Release 7 and later only.

Specifying the default IMAP service greetings

On the Server document, you can configure the ports that IMAP clients can use to connect to the IMAP
service. IMAP clients can connect over a TCP/IP port or an SSL port. If you have SSL set up on the
server, you can configure the TCP/IP port so that it redirects connections to the SSL port.

When a client connects, the IMAP service responds by sending the client the greeting that is associated
with the port the client uses to connect. On the Configuration Settings document, you can customize the
greetings that the IMAP service returns to clients connecting over each port.

The IMAP service checks for new settings at the specified update configuration interval. If you change
the greeting text, sessions that begin after the new configuration takes effect will receive the updated
greeting.

To modify the default IMAP service greetings:

1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. Click the IMAP - Advanced tab.
6. In the Greeting section, enter the text for the IMAP service to display to connecting clients and the
click Save & Close:

Field Enter Default

IMAP server The greeting the By default, the service sends a greeting that includes the server name,
greeting IMAP service sends to Domino release number, and the current date and time.
clients connecting
over TCP/IP. For example:

*OK Domino IMAP4 Server Release 6 ready Wed, 17 April 2002 17:57:13
-0400
IMAP SSL The greeting the By default the service sends a greeting that includes the server name, Notes
greeting IMAP service sends to release number, and the current date and time.
clients connecting
over SSL. For example:

*OK Domino IMAP4 Server Release 6 ready Wed, 17 April 2002 17:57:13
-0400

854 Lotus Domino Administrator 7 Help

Field Enter Default
IMAP SSL The greeting the By default, the service sends the following greeting:
redirect IMAP service sends to
greeting clients when the *IMAP Server configured for SSL Connections only. Please reconnect using
TCP/IP port is the SSL Port portnumber
configured to redirect
connections to SSL. Where portnumber is the number of the configured SSL port.

Note: To specify IMAP greetings for Domino Release 6, and more recent servers, you must use the
Configuration Settings document. However, you cannot use the Configuration Settings document to
specify service greetings for Domino Release 5 and earlier. To configure IMAP service greetings on earlier
Domino release, use the settings IMAPGreeting, IMAPRedirectSSLGreeting, and IMAPSSLGreeting in the
NOTES.INI file.

For more information on these settings, see the appendix ″NOTES.INI File.″

Setting up IMAP users

To set up IMAP users, perform these procedures:
1. Set up the users’ Person documents.
2. Create a mail file for the IMAP user.
3. Enable the mail file for IMAP access.
4. Configure IMAP client software.
5. (Optional) Create a full-text index of the mail file so the IMAP user can search for information in the
file. When you create the index, choose the ″Index attachments″ option to allow the user to search for
information in attachments that are in MIME format.
For more information on creating a full-text index, see the chapter ″Setting Up and Managing Full-text
Indexes.″
If you use the Domino registration process to create a new IMAP user, Domino automatically creates
the Person document and mail file and lets you specify registration options to create a full-text index
for the mail file and enable the mail file for IMAP use.

Setting up the Person document for an IMAP user

To access mail files on the Domino server, an IMAP user must have a Person document in the Domino
Directory. For users who already have Person document, edit settings in the existing document as
necessary to provide IMAP support. If a user does not have an existing Person document, you must
create a new one. You can create a Person document manually, or use the Domino registration process to
create the Person document automatically. If you use the Domino registration process, select IMAP in the
″Mail system″ field of the Register Person dialog box.

Note: By default, the Domino registration process generates a Notes ID file (and corresponding Notes
public encryption key in the Domino Directory) for each user in addition to creating the Person
documents and mail files required by an IMAP user. Because users who will access Domino from IMAP
clients only do not require a Notes ID, when registering these users, deselect the option to ″Create a
Notes ID for this person.″ However, if a new IMAP user also requires access to Domino from a Notes
client, Domino Administrator client, or Domino Designer client, be sure to enable creation of an ID file.

For more information on using the Domino registration process, see the chapter ″Setting Up and
Managing Notes Users.″

The following procedure specifies the Person document settings required for IMAP users and explains
how to create a Person document manually.

To set up a Person document for an IMAP user:

Chapter 33. Setting Up the IMAP Service 855

1. From the Domino Administrator, click the People & Groups tab.
2. Select Domino Directories - Address Book - People.
3. If no Person document exists for this user, click Add Person to create a new Person document.
To display an existing Person document, select the name of the user, and click Edit User.
4. Click the Basics tab, complete these fields, and then click Save & Close:

Field Enter
First name The login name a client uses to authenticate with the IMAP server must be unique in
the Domino Directory.
Last name
Depending on the level of Internet access security established for the server (Server
User name document - Security tab), the login name or user name configured on the IMAP client
must match an entry in one of these fields. Entries in the User name field are always
accepted as the login name. If Internet authentication is set to allow ″More name
variations with lower security″ entries in the First name and Last name fields may also
be accepted as login names.
Internet password The password that the user enters to access the Domino server from the IMAP client.
IMAP users must have an Internet password that complies with your organization’s
password quality requirements.
Mail system Choose IMAP if the user does not require Notes client access.
Domain The name of the Notes domain to which the server belongs.
Mail server The name of the IMAP user’s Domino mail server.
Mail file The path for the user’s mail file, relative to the Domino data directory -- for example,
MAIL\AJONES.
Forwarding address Leave this blank for users who access mail files on the Domino server from an IMAP
client.
Internet address The Internet address at which the user can receive mail within your organization. This
address must match the Internet address specified in the IMAP client.
Format preference for Choose one:
incoming mail v Keep in sender’s format - (default) The mail file may contain messages in either Notes
rich text or MIME format. When delivering messages to the mail file, the local Router
preserves the current message format. Thus messages received at the server in MIME
format are stored in the mail file in MIME format, and messages received at the
server in Notes rich text format are in Notes rich text format. When an IMAP client
requests a message that is stored in Notes rich text format, the IMAP service must
convert the message to MIME before sending it to the client. Because the stored
message remains in Notes rich text format, each time an IMAP client requests the
message, the IMAP service must perform the conversion.
v Prefers MIME - The mail file stores messages in MIME format only. Choose this
option for users who access mail exclusively from an IMAP client. Since IMAP clients
require messages in MIME format, storing mail in MIME format ensures the best
performance for IMAP users, eliminating the need for the IMAP service to convert
messages before passing them to the client. In addition, using MIME storage allows
the Router to add special IMAP attributes to the messages it delivers.
v Prefers Notes Rich Text - The mail file stores messages in Notes format only. The
Router converts messages received as MIME into Notes rich text before delivery. In
addition, the IMAP task must convert messages to MIME format when sending them
to an IMAP client. To ensure the best performance, do not choose this option for
users who access their Domino mail file primarily from an IMAP client.

856 Lotus Domino Administrator 7 Help

Field Enter
When receiving Choose No (default); IMAP clients cannot read encrypted Notes mail.
unencrypted mail, encrypt
before storing in your To ensure that users who read mail exclusively from IMAP clients do not receive
mail file Notes-encrypted mail, remove the IMAP users’ Notes public encryption keys from their
Person documents.
Note: Never remove the Notes public key from the Person document of users who
access Notes databases from a Notes client.

For more information about password quality requirements, refer to the chapter ″Protecting and
Managing IDs.″
5. Complete the procedure ″Creating a mail file for an IMAP user.″

Creating a mail file for an IMAP user

Each IMAP user must have a mail file on the Domino server. You can create the mail file automatically
during user registration, or you can manually create a mail file. If the user is already a registered Notes
user who has an existing Domino mail file and if you set up the user’s Person document for IMAP
access, the user can access the mail file from an IMAP client.

If a user does not have an existing mail file on a Domino server, create a new mail one as described in
the following procedure.

To manually create a mail file:

1. Make sure that you have set up the Person document for the IMAP user.
2. Choose File - Database - New.
3. In the New Database dialog box, enter the following:

Field Enter
Server The Domino mail server that stores the user’s mail file.
Title The name of the client’s mail file -- for example, Alan Jones’ Mail.
File name The full path to the mail file, relative to the Domino data directory -- for example,
MAIL\AJONES.NSF.

4. From the list of template names, select Mail (R6) with the filename MAIL6.NTF, and click OK.
5. After Domino creates and opens the mail file, determine what level of access is appropriate for both
the user and you, as the administrator. Then, edit the Access Control List (ACL) as follows:
a. Choose File - Database - Access Control.
b. From the Access Control List dialog box, create an ACL entry for the user by clicking Add and
then selecting the user’s name from the Domino Directory.
c. Set the user type to Person and select the level of access. Users require at least Editor with Delete
document access.
d. (Optional) Select your name from the ACL and click Remove. As the administrator, you can
choose to retain Manager access, particularly for users who do not have Notes client access.
e. Click OK to save the entry and close the ACL.
6. Complete the procedure ″Preparing a mail file for IMAP access.″

Preparing a mail file for IMAP access

To support access from IMAP clients, mail files must be specially modified to store IMAP folder and
message attributes as database items. If you used the Domino registration process to create a user, and set
the user’s mail system type to IMAP, Domino automatically performs the steps required to prepare the
mail file for IMAP use. Otherwise, you must complete several tasks to prepare a mail file to support
IMAP access.

Chapter 33. Setting Up the IMAP Service 857

To prepare a mail file for IMAP access:
1. Verify that you have:
v Set up the Person document for the IMAP user.
v Created a mail file for the IMAP user.
2. If you are upgrading a mail file, run Compact on the mail file to ensure that it uses the Notes ODS
(on-disk structure) version 41 or greater.
You do not have to run Compact on newly created mail files that are based on a Lotus Domino
Release 5 or later mail template. For new mail files, skip to Step 4.
3. Run the Fixup task on the mail file.
4. Run the mail conversion utility on the mail file to enable it for IMAP access.
5. If this is not a new mail file, run the mail conversion utility with the -h option to increase the speed
of header downloads when clients log in.

The IMAP service does not rely on template views to store IMAP folder and message data; you can
enable mail files created from any mail template.

For users with multiple mail file replicas -- for example, users with mail files on clustered servers -- you
must independently enable each replica for IMAP access. Because Domino does not replicate IMAP
database items between databases, by default, when you create a new replica of an IMAP-enabled mail
file, it is not enabled for IMAP use.

Differences when viewing mail files from IMAP clients and Notes client: Some aspects of a mail file
are structured in template items that are visible only to a Notes client, and as such are not available to
IMAP clients. As a result, IMAP clients display certain folders and views in a mail file differently from
Notes clients. For instance, from an IMAP client, the Inbox and Trash folders, and any public folders,
appear as IMAP mailboxes. Also, hidden and private folders are not visible to IMAP clients. And finally,
IMAP clients do not display views that are part of the Notes mail file template, such as the Draft and
Sent view.

The Domino IMAP service does not support renaming of the Inbox folder in a Notes mail file from an
IMAP client.

For users who access their mail files from both an IMAP client and a Notes client, Domino synchronizes
unread message marks between the two. Thus, a message marked as read in Notes is also marked as
read for an IMAP client, and vice versa.

IMAP clients cannot read messages that use Notes encryption. IMAP clients do not have access to the
Notes private key needed to decrypt messages encrypted with a user’s Notes public key certificate. As a
result, when a user opens an encrypted Notes message from an IMAP client, only the unencrypted
header information is available. The server replaces the blank message body with the following text:
[Portions of this MIME document are encrypted with a Notes certificate and cannot be read.]

Running Compact to update the ODS version of a mail file: To be enabled for IMAP, a mail file must
use the Domino Release 5 or later file format, Notes ODS (on-disk structure) version 41 or greater. If a
mail file is at a previous ODS version, you must run Compact on it to update the ODS version. It is not
necessary to run Compact to enable newly mail files that are based on either the MAIL6.NTF or
MAIL50.NTF mail templates.

The ODS version of a mail file database is listed on the Info tab of the Database properties dialog box.
For information on how to determine the file format of a database, see the chapter ″Improving Database
Performance.″

To run Compact using a console command: Compacting converts Release 4 databases to the Lotus Domino 6
file format or ODS 43.

858 Lotus Domino Administrator 7 Help

1. From the Domino Administrator, on the Server pane on the left, select the server on which to run
Compact. To expand the pane, click the servers icon.
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 compact databasepath
Enter the database path relative to the Domino data directory. To compact a specific mail file in the
MAIL directory, enter the name of the MAIL directory followed by the name of the mail file, for
example:
Load compact MAIL\USER.NSF
To compact all mail files in the MAIL directory, enter the name of the MAIL directory as the database
path, for example:
Load compact MAIL

Note: You can also enter Step 4 directly at the console on a server.

After you run compact on the mail file, continue preparing the file for IMAP users by running Fixup.

Running Fixup to prepare a mail file for IMAP use: You do not need to run Fixup on newly created
mail files that are based on a Lotus Domino Release 5 or later mail template.

After you run Compact on a user’s mail file to ensure that it uses the correct file format, run the Fixup
task on the mail file.

Because the Fixup task requires exclusive access to the mail file database, you must shut down the server
before running Fixup.

To run Fixup:
1. Shut down the server.
2. From the Windows NT command prompt, change to the Domino program directory. For example, if
you installed Domino in the default location, enter:
cd c:\lotus\domino
3. To run Fixup on a specific mail file, enter:
nFixup path\mailfile
where path is the database path relative to the Domino data directory and mailfile is the name of the
mail file database. For example, to run Fixup on the mail file database USER.NSF in the DATA\MAIL
folder, enter:
nFixup mail\user.nsf

Note: If transaction logging is enabled on the server, run Fixup with the -j switch, for example:
nFixup -j mail\user.nsf

Running the mail conversion utility to enable a mail file for IMAP:

Note: If you used the Domino registration process to add a user account, and set the user’s mail system
type to IMAP, Domino automatically enables the mail file for IMAP use.

After you run Fixup on the mail file, run the mail conversion utility (the Convert task) to enable
IMAP-specific features in the mail file. The conversion utility sets an option bit in the database indicating
that this database is IMAP enabled. After you enable a mail file for which the format preference is set to
MIME, the Router automatically adds special IMAP attributes to new messages delivered to the database.
These attributes provide IMAP clients with summary information which enables them to download

Chapter 33. Setting Up the IMAP Service 859

message headers more efficiently. To ensure the best performance, after the initial conversion completes
run the conversion utility a second time, using the -h option to add these attributes to messages that were
already in the mail file at the time of the initial conversion.

For users with multiple mail file replicas -- for example, users with mail files on clustered servers -- you
must independently enable each replica for IMAP access. Because Domino does not replicate IMAP
database items between databases, by default, when you create a new replica of an IMAP-enabled mail
file, it is not enabled for IMAP use.

After the conversion utility enables a mail file for IMAP, the following information is added to the
bottom of the Information tab of the mail file’s Database Properties dialog box:
Database is IMAP enabled

Deciding whether to convert mail files manually or automatically: By default, when a user connects to the
IMAP service, the service checks whether the user’s mail file is currently enabled for IMAP. If the mail
file is not already enabled, the IMAP service automatically launches the conversion utility to format it for
use with IMAP. To prevent conversions from occurring during login, change the default configuration by
disabling automatic conversion.

For information on enabling and disabling automatic conversion, see the topic ″Setting the IMAP service
to automatically enable mail files at login″ earlier in this chapter.

Although the IMAP service can automatically convert mail files, consider manually converting them
before users first log in to the IMAP server to ensure that mail files are properly converted. By
performing conversions ahead of time, you can ensure that users are not confronted with conversion
errors that they are unable to recover from. For example, because the conversion utility requires that a
mail file be at least at ODS version 41, for mail files that use an earlier ODS version you must run
Compact before converting the mail file; using automatic conversion would fail. Similarly, in databases
where some type of internal corruption has occurred (for example, an invalid note, or corrupt meta data),
you must run Fixup against the mail file before running the conversion utility.

You might also choose to run the conversion utility manually if many of your first-time IMAP users
access the server over slow modem connections, particularly if a large proportion of them would be
logging in at the same time. The reason for this is related to the way the IMAP service allocates threads
to perform automatic conversions. The IMAP service dedicates a single conversion thread for each
conversion and it draws this conversion thread from the same thread pool that provides the threads
responsible for servicing other IMAP client requests, such as logging in users or retrieving messages.
Because mail file conversions can require a significant amount of time, with conversion times increasing
as connection speeds decrease, a conversion thread typically remains busy longer than other thread types.
As a result, an IMAP service flooded with conversion requests can experience a thread shortage. This
shortage affects not only the users awaiting conversion, but current IMAP users, too, who encounter
unexpected delays attempting to log in and retrieve messages. When the conversion utility is run
manually on the mail server, the operation completes in a very short time, even if the mail file is
relatively large.

Finally, you must run conversions manually to enable mail files in the other users’ and public folders
namespaces. Automatic mail file conversion can occur only for the personal mail file of the currently
authenticated user.

To manually convert mail files for use with IMAP: You can run the mail conversion utility on a single mail
file or on all mail files in a directory.
1. At the server console of the Domino server on which you want to enable mail files, shut down the
Router by entering:
tell router quit

860 Lotus Domino Administrator 7 Help

 This prevents Domino from routing mail to the mail files while they are being converted. Mail is
stored in MAIL.BOX while you upgrade the mail files. After you have converted the mail files and
loaded the Router task again, the Router processes and delivers the mail in MAIL.BOX.
2. Load the mail conversion utility by entering the following command:
load convert -e maildirectory\mailfilename
where maildirectory names the path to the mail subdirectory that contains the user’s mail file and
mailfilename is the filename of the user’s mail file. The maildirectory path describes the path relative to
the server’s Domino data directory. For example, to convert the mail database USER.NSF in the
\MAIL subdirectory of the Domino data directory enter:
load convert -e mail\user.nsf

Note: On UNIX systems, use a forward slash (/) as the hierarchy separator, rather than a backslash
(\). For example, enter:
load convert -e mail/user.nsf
To specify all files in a directory, make sure the directory contains only mail files and that they are the
mail files you want to convert. For example, to enable IMAP for all mail files in the \MAIL
subdirectory, enter:
load convert -e mail\*.nsf
3. After you finish enabling mail files for IMAP on this server, load the Router by entering:
load router
4. Configure IMAP client software.
For information on configuring IMAP client software, see the topic ″Configuring IMAP client
software″ later in this chapter.
For information about disabling IMAP access to a mail file, see the topic ″Disabling an IMAP mail
file″ later in this chapter.

Convert utility options:

Note: The convert -d option can be used to convert non-mail databases.

Option Use
-e Enables mail files for IMAP use.
-h To enable clients to download message headers more efficiently, the Convert task processes
all messages in the mail file in the order in which they are listed in the mail file’s ″All
Documents″ view and adds the special IMAP attributes ($Content_Type, IMAP_BodyStruct,
and IMAP_RFC822Size) to messages that don’t have them.

Because the Convert task is single-threaded, and this option requires the Convert task to
process every message in the mail file, it is resource-intensive and can take a long time,
especially for mail files where messages must also be converted from Notes rich text to
MIME format.

You cannot use this option in combination with the -e switch.

-o Removes from messages the IMAP items used to provide more efficient header retrieval.
You may use this option in combination with the -h option, but not with the -e option.
-e- Disables IMAP access to mail files.

How the conversion utility handles unread marks: In previous versions of Notes and Domino, mail
files maintained separate sets of unread marks for IMAP clients and Notes clients, with IMAP-enabled
mail files relying on special template views to indicate that a message was read. With the introduction of
native IMAP in Domino Release 6, a mail file enabled for IMAP displays a consistent set of unread marks
to the IMAP and Notes clients opening the file.

Chapter 33. Setting Up the IMAP Service 861

If you used IMAP in an earlier release of Domino, and are upgrading a mail file to Domino Release 6
IMAP format, the conversion utility will mark a message as read in the converted mail file if either the
IMAP or Notes items in the unconverted mail file indicate that the message was read.

Preserving folder references during upgrade of IMAP mail files: In earlier releases of Domino, the
IMAP service used hidden folder reference views in the mail template to retrieve IMAP folder and
message data. By contrast, the Domino Release 6 IMAP service doesn’t use folder references. Instead, it
enables native storage of IMAP folder and message attributes in the mail file, thus eliminating the need
for hidden views in the mail template.

By default, when you convert mail files to Lotus Domino 6 IMAP format, the conversion utility disables
folder references in the mail file. In most environments, use the default and disable folder references to
ensure the best performance.

If your environment uses Domino applications that rely on folder references in user mail files to gather
information, you may need to preserve folder references. To preserve folder references during conversion,
you can set the variable IMAP_CONVERT_NODISABLE_FOLDER_REFS in a server’s NOTES.INI file.
When this variable is set, folder references are preserved during all mail file conversions, whether
performed manually from the server console, or automatically as the result of an IMAP user logging in to
the IMAP service for the first time.

Immediately following conversion, the folder and message information stored in the folder references
matches the information stored in the mail file’s IMAP attributes. However, because Domino does not
continue to update folder references after the initial conversion, over time, as a user receives, moves, and
sends messages, folder reference information will no longer be synchronized with the information stored
in the mail file attributes.

Using the conversion utility to add IMAP summary attributes to messages: The IMAP service uses
special IMAP summary attributes ($Content_Type, IMAP_BodyStruct, and IMAP_RFC822Size) in
messages to facilitate the process of sending message headers in response to client requests. After you
convert a mail file for IMAP use, for users who receive messages in MIME format, the Router
automatically adds these items to new messages it delivers.

However, these items might not be added to all messages in a mail file. Messages delivered in Notes rich
text format do not contain the items. And Domino does not automatically add these items to messages
delivered before conversion occurred.

Although an IMAP client can read messages that do not contain IMAP summary attributes, the client
must first download each message in its entirety before it can display headers. To enable faster header
fetching, run the mail conversion utility with the -h switch to add IMAP summary attributes to messages
that don’t have them.

Updating IMAP attributes following mail file changes: Changing a message that contains the
IMAP_RFC822Size attribute, might affect a user’s ability to access the message. When the size value of
the IMAP attribute no longer matches the actual message size, IMAP clients might have difficulty
downloading the message. If the actual message size is larger than the size indicated by the attribute, the
IMAP client might not download the entire message. If the actual size is smaller than the size indicated
by the attribute, the IMAP client can hang as it attempts to download the remaining expected message
data.

Message size might change inadvertently as a consequence of an agent running after a message is
delivered or of changes to certain server configuration options, such as the settings governing outbound
MIME conversion options. Although the outbound MIME conversion options apply primarily to
messages sent outbound over SMTP, they also affect any message exported from the server, including
messages retrieved by the IMAP service for sending to a client. For example, if you change the setting for

862 Lotus Domino Administrator 7 Help

adding RFC 822 phrases to users’ Internet return addresses, this changes message size, because the
Internet return address in each message an IMAP client retrieves is altered to comply with the new
setting.

To prevent changes to the server configuration from contributing to download errors, update IMAP
attributes to reflect the new settings. To update IMAP message attributes and refresh the mail file’s MIME
directory, you must remove the existing attributes and then add them again. Because IMAP clients cache
header information, users must also recreate their IMAP accounts to download messages successfully.

Note: A similar problem occurs for IMAP users whose Person documents specify Notes rich text as the
mail storage preference. In this case, the Router does not add IMAP attributes to messages delivered to
mail files, but the IMAP client still caches size information. When you modify the server’s configuration,
for example, by setting the server to export message content as HTML rather than plain text when
converting messages to MIME, this changes message size. Because the client expects the size of existing
messages to match their cached size, user can no longer retrieve these existing messages from an IMAP
client. To remove the header information cached by the IMAP client, the user must recreate the IMAP
account.

To run the mail conversion utility to add or update IMAP attributes.:

1. Shut down the Router on the server containing the mail files to convert, by entering the following
command at the console:
tell router quit
This prevents Domino from routing mail to the mail files while they are being converted. Mail is
stored in MAIL.BOX while you upgrade the mail files. After you have converted the mail files and
loaded the Router task again, the Router processes and delivers the mail in MAIL.BOX.
2. Load the mail conversion utility by entering the following command:
load convert [-h /-o] maildirectory\mailfilename
where maildirectory names the path to the mail subdirectory that contains the user’s mail file and
mailfilename is the filename of the user’s mail file. The maildirectory path describes the path relative to
the server’s Domino data directory. For example, to add IMAP attributes to the mail database
USER.NSF in the \MAIL subdirectory of the Domino data directory, enter:
load convert -h mail\user.nsf

Note: On UNIX systems, use a forward slash (/) as the hierarchy separator, rather than a backslash
(\). For example, enter:
load convert -h mail/user.nsf
To specify all files in a directory, make sure the directory only contains mail files and that they are the
mail files you want to convert. For example, to add IMAP attributes to all mail files in the \MAIL
subdirectory, enter:
load convert -h mail\*.nsf

CAUTION:
When the conversion utility is run with the -h option, the conversion operation can take a long
time to complete. The exact time depends on server processing speed and memory, as well as on
the size and composition of the mail file. To ensure that you can complete conversions in the
available time, run a test with a single mail file before using a wildcard to run multiple
conversions.
3. After you finish enabling mail files for IMAP on this server, load the Router by entering:
load router

Re-enabling a corrupted IMAP mail file

If an IMAP-enabled mail file becomes corrupted, you can repair it by performing the following tasks:
1. Run Fixup.

Chapter 33. Setting Up the IMAP Service 863

2. Disable the mail file for IMAP use.
3. Re-enable mail file for IMAP use.

If you are unable to repair the mail file, contact Lotus Support Services for assistance.

Running Fixup to repair a corrupted IMAP mail file: To repair a corrupted IMAP mail file, the Fixup
task requires exclusive access to the mail file database. Before running Fixup, you must shut down the
server. After the server is shut down, run Fixup as described below:

To run Fixup:
1. From a command prompt, change to the Domino program directory. For example, if you installed
Domino in the default location, enter:
cd c:\lotus\domino
2. To run Fixup on a specific mail file in the MAIL directory, enter:
nFixup path\mail file
where path is the database path relative to the Domino Data directory. For example, to run Fixup on
the database USER.NSF in the DATA\MAIL folder, enter:
nFixup mail\user.nsf

Note: If transaction logging is on, run Fixup with the -j switch, for example:
nFixup -j mail\user.nsf

Disabling an IMAP mail file: If you need to disable IMAP-specific features in a mail file, run the mail
conversion utility with the -e- option file. The example below removes the IMAP capability of the mail
database USER.NSF in the \MAIL subdirectory of the Notes data directory:
load convert -e- mail\user.nsf

Note: On UNIX systems, use a forward slash (/) as the hierarchy separator, rather than a backslash (\).
For example, enter:
load convert -e- mail/user.nsf

Re-enabling a mail file for IMAP: After disabling the mail file as described in the preceding section,
you can re-enable it. For more information on enabling a mail file, see the topic ″Running the mail
conversion utility to enable a mail file for IMAP″ earlier in this chapter.

Configuring IMAP client software

After you set up a Domino server to run the IMAP service, users can access their mail files on the
Domino server from any IMAP mail client. The IMAP service supports all IMAP-compliant clients -- for
example, Microsoft Outlook and Outlook Express, Qualcomm Eudora, Cyrusoft Mulberry, and PC-Pine.

IMAP clients display Notes folders as IMAP mailboxes. When users receive or delete documents in an
IMAP mailbox, the changes also occur in the Notes folder, and vice versa.

Users can access their mail files from both an IMAP client and the Notes mail client. Domino IMAP
clients can send mail to other Notes users and to IMAP and POP3 clients on the Domino mail system or
other mail systems.

For a complete list of IMAP clients and for more information on IMAP, visit the Web site
http://www.imap.org.

The specifics of configuring IMAP client software differ for each product. This table presents some
general requirements.

864 Lotus Domino Administrator 7 Help

Field
Incoming mail (IMAP)
server
Outgoing mail (SMTP)
server
Authentication required to
send outbound mail
Account/Login name
Password
E-mail address
Check for messages every
(x) minutes.
Folder namespace prefixes
Description
The fully qualified host name of the Domino server running the IMAP service.
The fully qualified host name of a server running SMTP to which the user can send
mail addressed to intranet or Internet recipients. The SMTP server may be the
Domino server running the IMAP service, a different Domino server, or a
non-Domino SMTP server.
Specifies whether the configured SMTP server requires users to provide a name and
password before they can send outgoing messages.
The name by which the user authenticates with the Domino server. Valid user name
values depend on the setting in the Internet authentication field of the Server
document.
The Internet password from the user’s Person document.
The Internet address specified in the user’s Person document.
Determines how often the client checks for mail. If the client checks for mail more
frequently, it may affect server performance.
The root folder path required by some IMAP clients. Most IMAP clients do not need
to specify folder prefixes when using the Domino IMAP service to connect to mail
files.

For more information on determining the login names that a server will accept, see the chapter ″Setting
Up Name-and-Password and Anonymous Access to Domino Servers.″

Example of configuring PC-Pine folder prefixes:

Syntax Example
INBOX-PATH {fully qualified domain name of IMAP INBOX-PATH {East.Acme.com}INBOX
server}INBOX
Folder collections {fully qualified domain name of IMAP Folder collections {East.Acme.com}
server}

Example of configuring other IMAP client software folder prefixes:

IMAP client Folder configuration

Outlook Express Mail (Microsoft Internet Explorer 5.0) Root Folder Path

Chapter 33. Setting Up the IMAP Service 865

866 Lotus Domino Administrator 7 Help
Chapter 34. Setting Up Domino Web Access
This chapter describes how to set up Domino Web Access so that Notes client users can use a Web
browser to access their Lotus Notes mail and calendar. It provides configuration document settings and
NOTES.INI settings to control and customize Domino Web Access for users. In addition, this chapter
describes how Domino Web Access works with IBM Lotus Sametime and Domino Off-Line Services to
provide users with an instant messaging capability and the ability to work offline.

Domino Web Access

Domino Web Access (previously iNotes Web Access) provides Notes users with browser-based access to
Notes mail and to Notes calendar and scheduling features. Domino Web Access users can send and
receive mail, view their calendars, invite people to meetings, create to do lists, keep a notebook, and
work offline. After being set up for Domino Web Access, a user can use both the standard Notes client
and a Web browser to access their mail files. Because both the Notes client and Domino Web Access
operate on the same underlying user mail file, read and unread marks remain up-to-date, regardless of
which client the user uses to read the mail. Users can also synchronize contact information in their
Personal Address Book with information in their Contact List in Domino Web Access.

While users simply need a name and Internet password to log on and use Domino Web Access, a Notes
ID is required if a user wants to work offline. Be sure to create a Notes ID for each user when registering
new users with the Domino Web Access template.

Security
Domino Web Access requires user log-on and logout security. When a user logs onto Domino Web
Access, they must enter their name and Internet password, as specified in their Person document. The
login names that the server accepts as valid depend on the setting in the ″Internet authentication″ field
on the Security tab of the Server document.

When the user logs out, Domino Web Access closes the browser and removes the user’s log-on
credentials and private data from the browser’s cache. By deleting this data, Domino Web Access
prevents an unauthorized user from using cached information to access the user’s mail file. In Internet
Explorer, you can use Browser Cache Management to improve the client side performance and security of
Domino Web Access sessions by controlling which entries are stored in the cache and which are removed
when the Domino Web Access session ends. The removal of private data from the browser’s cache and
more secure data clearing capabilities are available only if the user accepts the Domino Web Access
control.

Domino Web Access will not remove some personal data unless the user explicitly selects ″Logout for
Shared PCs or Kiosk Users.″ With this selection, users can choose one of two secure logouts:
v Secure - This option deletes all traces of the user’s personal use of Domino Web Access and any Web
pages that they may have browsed, but keeps Domino Web Access program elements (this boosts
performance when the next person logs on).
v More secure - This option deletes all traces of Domino Web Access and all other Web pages in the
temporary Internet files folder.

You can also redirect users to a specific Web page after they logout.

Integration with DOLS and Sametime

To provide users with the ability to work offline and use Sametime, you can integrate Domino Web
Access with Domino Off-Line Services (DOLS) and IBM Lotus Sametime (instant messaging). DOLS

867
enables users to work offline, disconnected from the network, and provides many replication features that
Notes users expect when working in the Notes client. Sametime provides integrated, real-time chat
features for Domino Web Access users. Neither DOLS nor Sametime are required for Domino Web Access
use.

Registering Domino Web Access users

When registering users, choose ″Domino Web Access″ as the mail system. By default, the Domino Web
Access (7) mail template (DWA7.NTF) should be selected. If it is not, select it. This template contains mail
template support for the Domino Web Access client and the Notes client.

Follow the instructions for registering new users, and keep the following information in mind:
v The mail system, ″Domino Web Access,″ does not automatically create a Notes ID for the person. You
must select ″Create a Notes ID for this person.″
v When deploying Domino Web Access to a large number of users, make any hierarchical or name
changes before registering new users.
v To enable the mail usage indicator for users, set a mail quota.

Enabling the mail usage indicator

Domino Web Access provides a mail file usage indicator so that users can view what percentage of their
mail database is in use. To enable this feature, you set a database quota when registering users. You can
also set a warning threshold so that users are notified when their mail database is reaching its quota.

Follow the instructions for registering new users, and make sure to check the following options on the
Mail tab, visible when using Advanced registration:
v Set database quota -- Click to enable, and then specify a size limit (maximum of 10GB) for a user’s
mail database.
v Set warning threshold -- Click to generate a warning when the user’s mail database reaches a certain
size, and then enter the warning size (maximum of 10GB).

Note: If you are using Policies, set these options in the Registration Policy Settings document.

Providing a log-on URL for Domino Web Access users

After you register new Domino Web Access users, they will need three things to access their mail files:
v User name
v Internet password
v Default log-on URL (http://servername.com/mail/username.nsf)

The default URL displays the Welcome Page. However, you can give users a URL that will initially
display other views. Appending the following text to the URL with a specific keyword (see following
table) will cause Domino Web Access to initially display a different view:
.../username.nsf/inotes/keyword/?OpenDocument&ui=inotes

To display Use URL keyword

Mail Inbox mail
Calendar calendar
To Do List todo
Contact List contacts
Notebook notebook

868 Lotus Domino Administrator 7 Help

Creating Portal URLs
A portal is a Web site that aggregates information from a variety of sources onto one page. You can
provide a Web portal showing only one view of Domino Web Access, or one showing several views.
Domino Web Access supports special URLs that allow a particular Domino Web Access functional area to
be displayed within an IFRAME (or a full browser window). This view takes up very little screen real
estate and limits access to other functional areas.

An individual Domino Web Access portal view is limited to one of the following:
v Inbox
v Calendar
v To Do List
v Notebook
v Contact List

The URL syntax for a Domino Web Access portal showing just the mail Inbox is, for example:
.../username.nsf/inotes/mail/?OpenDocument&ui=portal

To place all of Domino Web Access within a portal page, use the normal Domino Web Access URL
without the &ui=portal parameter.

Note: See the NOTES.INI setting iNotes_WA_PortalOffline for information on including offline and local
archive options in a portal.

Secure mail for Domino Web Access

To allow Domino Web Access users to encrypt and digitally sign e-mail messages, you must enable both
the ″Encrypted mail support″ and the ″Name Resolution and Validation″ field on the Domino Web Access
tab of the server’s Configuration Settings document.

If SSL connection is required for either the client or both the client and server, Domino Web Access users
cannot read or send encrypted messages when connected via HTTP. If the user is connected via HTTP,
they must switch to HTTPS when accessing the encrypted message on the server. This switch occurs
automatically when sending encrypted mail. The user will be prompted to switch when reading
encrypted mail.

S/MIME is supported in Domino Web Access. Users can verify an S/MIME signature on a received
message. Users who have an X.509 certificate in their mail file-based Notes ID can decrypt received
S/MIME messages as well as S/MIME sign messages they send. Outgoing messages can be S/MIME
encrypted for recipients who have an X.509 certificate in the Domino Directory or in Domino Web Access
contacts. Note that for an X.509 certificate to be used by Domino Web Access, an Internet cross-certificate
must be issued from the user’s organizational certifier to the certificate authority that issued the X.509
certificate. This Internet cross-certificate must be present in the Domino Directory.

When both Notes and S/MIME sign and encryption are possible, Domino Web Access uses S/MIME sign
and encryption by default. This could cause problems in a mixed environment that includes both Domino
7 and pre-Domino 7 servers. Pre-Domino 7 servers do not support S/MIME, so messages sent S/MIME
signed and encrypted could not be verified or decrypted. Use the NOTES.INI setting
iNotes_wa_SecMailPreferNotes to turn on Notes sign and encryption when both S/MIME and Notes sign
and encryption are possible. This setting is not supported offline.

Deployment differences between Notes and Domino Web Access

v Recovery authority -- Domino Web Access does not support recovery authority unless it is already in
the ID mailed to the user.
v Imported Notes IDs -- Notes IDs cannot be Smartcard enabled.

Chapter 34. Setting Up Domino Web Access 869

v Certificates -- Domino Web Access looks for certificates first in the Domino Directory and then in the
contacts.
v Cross certificates -- Domino Web Access looks for cross certificates only in the Domino Directory. If you
are using Domino Web Access, you must create any required cross certificates in the Domino Directory.
v Multiple domains -- If you are administering multiple domains, use Directory Assistance for an
Extended Directory Catalog on the server. Do not use a Condensed Directory Catalog (CDC) on the
server.
v Offline -- If you are using a directory catalog, you must enable it for encrypted mail.

Using realm documents in Domino Web Access

When Anonymous access is disallowed on the Domino server, and basic authentication by user name and
password is enabled, users will be challenged to authenticate for both the /mail and the /iNotes realms.
To resolve this issue of having multiple login requests, create realm documents to map access from other
paths to the root path.

On Windows, create a realm document to map your Domino data directory, for example c:\domino\data
(or wherever your Domino data directory is located), to return a realm of ″/″.

On UNIX, create a realm document that specifies a Domino data directory of /local/domino_data (or
wherever your Domino directory is located).

Renaming a Domino Web Access user

You rename a Domino Web Access user who has a Notes ID (and a Notes certified public key located in
their Person Document in the Domino Directory) the same way you rename a Notes user. However, in
Domino Web Access, after a rename has been initiated, Domino Web Access users must access their Notes
IDs to complete the process. Depending on whether the user’s mail file has an imported copy of their
Notes ID, users can do one of two things to access their Notes ID, which will then complete the rename
process:
v User mail file has imported copy of Notes ID -- If the user’s Domino Web Access mail file contains an
imported copy of their Notes ID, the user can either decrypt an encrypted message, or send an
encrypted message to complete the rename process.
v User mail file does not have an imported copy of Notes ID -- If the user’s Domino Web Access mail file
does not contain an imported copy of their Notes ID, the user can either import one, which is required
for using Domino Web Access secure mail features, or can access the Notes ID using a Notes client.
Doing either of these things completes the rename process.

Monitoring Domino Web Access activity

You can determine the number of active Domino Web Access users on a system and log Domino Web
Access request information. To monitor Domino Web Access activity, you set up activity logging to
include Domino Web Access.
1. From the Domino Administrator, open the Configuration Settings document for the Domino server.
2. Click the Activity Logging tab.
3. For the field ″Activity Logging is Enabled,″ check Yes.
4. Under Server Activity Logging Configuration, check Domino.DWA.Request.

Activity Log Information

Domino Web Access activity logging records include such information as the name of the Domino Web
Access server, the name of the user accessing the server, the Domino Web Access request, the number of
bytes returned as a result of the request, the amount of time it took to process the request, and the date
on which the request occurred.

To analyze Domino Web Access activity:

870 Lotus Domino Administrator 7 Help

1. From the Domino Administrator, click Analyze Server Activity.
2. Under Analysis, click Analyze - Activity.
3. Under Server activity types to search for, select Domino - DWA - request, and then click add.

Customizing the look of Domino Web Access

You can customize the look of Domino Web Access. Using Domino Designer, you can add action buttons
to views or dialog boxes, provide additional choices for the Welcome Page, and replace the Domino Web
Access logo with a corporate logo. You can modify the following forms and subforms in the Domino Web
Access FORMS7.NSF file:
v Custom_JS -- to add custom action buttons for any view or dialog
v Custom_WelcomePage -- to add more choices for the end user’s Welcome Page
v Custom_Banner -- to replace the Domino Web Access logo

For example, you may want to add choices to the list of Web sites that can be displayed in the Welcome
Page. To do this, you modify the Custom_WelcomePage form. There are two arrays that can be modified.
One array is for the title of the web site, the other array is for the URL of the web site. The template uses
JavaScript, so it is possible to ″calculate″ a web site, for example, one based on the user’s name or current
mail database. You can write code in the Scene_PreSubmit function (inside the Custom_JS form) to
validate the new field. Note that the Welcome Page in this example uses the monthly calendar view.
var gWelcomePageChoices = {
titles:[
"Yellow Pages"
,"CNN"
,"IBM"
,"My monthly calendar"
],
urls:[
"http://www.superpages.com/"
,"http://www.cnn.com/"
,"http://www.ibm.com/"
, "../../inotes/calendar/?opendocument&ui=portal&presetfields=s_CalView;M"
]
};

Example of modifying Domino Web Access common forms database:

You can use this process to modify the FORMS7.NSF file.
1. Copy FORMS7.NSF to a temporary directory.
2. Make changes to the forms as desired.
3. Test the changes to the forms.
4. Stop the HTTP process on the Domino server using the tell http quit server command.
5. Flush the database cache using the dbc f server command.
6. Copy the new Forms7 database to the Domino Web Access directory under the Domino Data
directory.
7. Start the HTTP process using the load http server command.

Note: If you modify the default CalendarProfile values, the new values affect only new user registrations.
Default values for existing users are not changed.

Chapter 34. Setting Up Domino Web Access 871

Using Domino Web Access agents
You can use agents to process or manipulate data on forms or subforms in Domino Web Access. There
are two Domino Web Access agents, QueryOpen and QuerySave, which are the equivalent of the Web
agents WebQuerySave and WebQueryOpen.

When determining which forms to customize using Domino Web Access agents, keep in mind how often
the form is used. Design your agents to run only on the specific page you want to act on. An agent that
acts on a form or subform that runs constantly may impact performance adversely.

Create the agents

You create Domino Web Access agents in Domino Designer by adding two NOTESVARS to the dictionary
for the form you want to customize. The NOTESVARS specify the names of the QueryOpen and
QuerySave agents (in the user’s mail file or in the Domino Web Access template, DWA7.NTF). In Domino
Designer, edit the form or subform you want the agents to act on, adding the following lines between the
<NotesDictionary> tags:
<NOTESVAR NAME={$$QueryOpenAgent} VALUE={’(agentname)’}>
<NOTESVAR NAME={$$QuerySaveAgent} VALUE={’(agentname)’}>

Example
To add QueryOpen and QuerySave agents to the Memo, Reply, and Reply with History forms, open
FORMS7.NSF and add $$QueryOpenAgent and $$QuerySaveAgent NOTESVARS to the
s_mailMemoDictionary subform. Using the names testopen and testsave, for example, the edited subform
would look like this:
<NotesDictionary><NOTESFIELD NAME={MailOptions}>
<NOTESFIELD NAME={Form}>
<notesvar name="CalendarOwner"
Initialvalue={@Name([Canonicalize];@DbCommand("Haiku";
"h_GetProfileField"; "calendarprofile"; "Owner"))}>
.
.
.
<NOTESVAR NAME={$$QueryOpenAgent} VALUE={’(testopen)’}>
<NOTESVAR NAME={$$QuerySaveAgent} VALUE={’(testsave)’}>
</NotesDictionary>

For information about creating and using Web agents, see the section on Programming Domino for Web
Applications in the Domino Designer help. If you have not installed Lotus Domino Designer 7 Help, go
to http://www.lotus.com/ldd/doc to download or view Designer Help.

Configuring Domino Web Access for users

This section describes Domino Web Access settings in the Configuration Settings document and
NOTES.INI settings you can use to configure Domino Web Access for users.

Editing the Configuration Settings document for Domino Web Access

1. From the Domino Administrator, click the Configuration tab and expand the Server or Messaging
section.
2. Click Configurations.
3. Select the Configuration Settings document for the Domino Web Access mail server(s) and click Edit
Configuration.
4. Select the Domino Web Access tab.
5. Change any of the configuration settings.

872 Lotus Domino Administrator 7 Help

6. Save the document and restart the Domino server.

Setting Action
Welcome Page Setup
Default Welcome Page Click View/Modify to set Welcome Page settings.
v Default Page -- Lets users customize the Welcome Page.
v Selected Web Page -- Forces users to use a specific Web page
as the Welcome page. Enter the URL and title.
v Custom Layout -- Choose from six custom layouts to specify
new mail, calendar schedule, Web links, and other options
to appear in a layout.
Allow user to edit the Welcome page Enable (default) to allow users to create custom Welcome
pages and override any settings on the server.

Disable to prevent users from changing the

administrator-prescribed Welcome page.
Alarms
Alarms Enable (default) to allow users to set alarms for appointments,
meetings, events, and task deadlines.

Disable to prevent users from setting alarms that may slow

Minimum alarm polling time
Mail
Minimum mail polling time
When sending mail, set format to:
Name resolution and validation
Maximum attachment size (kb)
Mail Threads
Mail Encryption
server performance.
Enter a number to specify how often, in minutes, the Domino
Web Access client checks the server for alarms. Default is 5
minutes. Increase this number to improve server performance.
Enter a number to specify how often, in minutes, the Domino
Web Access client checks the server for new mail. Default is 5
minutes. Increase this number to improve server performance.
Choose Plain text, or Let user decide. This setting allows you
to restrict outgoing mail to plain text only. Plain text messages
can be read by most legacy mail applications. Allowing the
user to decide lets the user pick the format for every outgoing
mail message.
Enable to allow alternate name lookups, similar to
″type-ahead″ in Notes. Lets user resolve ambiguous names and
use alternate names by checking names against a contact list or
Domino Directory.
Note: This must be enabled for the Domino Web Access secure
mail feature.
Set the maximum size in kilobytes for attachments. Default is
50,000K (50MB).
Note: You must also set the value of two Server (or Web Site)
document fields to a value higher than this setting. Otherwise,
attachments larger than (10MB) will generate a server error.
The fields are:
v Internet Protocols - HTTP - Maximum Size of Request
v Internet Protocols - Domino Web Engine - Maximum Post
data
Enable (default) to allow users to set a Domino Web Access
user preference to view mail threads.

Chapter 34. Setting Up Domino Web Access 873

Setting
Encrypted mail support
Allow user to delete their Notes ID from their mail Enable to allow users to delete their Notes ID from their mail
database
Allow user to export their Notes ID
Require SSL when reading encrypted mail
Use JavaScript for SSL-redirection
Allow untrusted Internet certificates to be used for
S/MIME encryption
Instant Messaging
Instant Messaging features
Online awareness
Allow secrets and tokens authentication
Set an Instant Messaging server hostname for all
DWA users (useful for clustered configurations)
Loading \stlinks from Domino application server
Prefer ″Sametime Connect for browsers″
Pass the Organization name (commonly used when For xSPs only. The default is disabled.
Domino is configured for xSP)
Enable to include the user’s Organization as part of the name
format. For example:
874 Lotus Domino Administrator 7 Help
Action
Enable (default) to allow users to use a stored Notes ID to
read encrypted mail. The user’s ID must be stored in the mail
database.
database. Default is disabled.
Enable to allow users to export and save their ID in a separate
file. Default is disabled.
Select one to set SSL requirement:
v No -- To treat encrypted mail the same as unencrypted mail
v Client -- (default) To require the browser client to use SSL,
but not the server.
v Both -- To require both the browser client and the server to
use SSL.
Enable (default) to use JavaScript to redirect SSL.
Note: Some reverse-proxy servers do not properly fixup 302
redirects. If so, enabling this option may help. Do not enable
this option unless necessary.
Enable to allow users to use an untrusted Internet certificate
for S/MIME encryption. Default is disabled.
Enable (default) to turn on instant messaging and live names
(awareness) for users who have secrets and token or
Lightweight Third Party Authentication (LTPA) token, and a
Sametime server assigned.
Enable (default) to turn on live names for any user who has
also enabled awareness via a user preference.
v Enable (default) -- to use and prefer secrets and tokens
authentication if available.
v Disable -- if an LTPA token is present, disable this field to
use the LTPA token instead.
Type the name of the Sametime server to set an instant
messaging hostname (messaging.ibm.com for example) for all
Domino Web Access users. Eliminates the need to populate the
Sametime server field value within every user’s Person
document.
v Enable (default) -- to load \stlinks from the Domino
application server.
v Disable -- to load the \stlinks directory from the the
Sametime server defined in the user’s Person document.
Useful if running different versions of Sametime servers
within your organization and using a version of Domino
prior to 6.5.2.
v Enable (default) -- to load the Sametime Connect for
browsers (6.5.1 or later) as the Chat client.
v Disable -- to use the Domino Web Access Chat client.
CN=John Doe/O=Acme
Setting
Directory type used by IBM Lotus Instant
Messaging and Web Conferencing
Disclaimer Text
Add disclaimer notice to mail memo
Disclaimer text or HTML
Offline
Encrypt offline mail databases
Offline database encryption level
Allow user to choose an encryption level
Allow user to go offline
Only sync documents modified in the last x days.
Action
v Domino Directory (or leave blank) -- if the Sametime server
and Domino Web Access server both use the Domino
Directory.
v Domino LDAP -- if the Sametime server uses the Domino
LDAP directory and the Domino Web Access server uses the
Domino Directory.
v Domino LDAP for xSP --(xSP servers only) If the Domino
Web Access xSP server uses the Domino Directory and the
Sametime server uses the Domino LDAP server.
v Non-Domino LDAP-- if the Sametime server and the
Domino Web Access server both use an LDAP directory
other than Domino LDAP.
Note: You can further refine the way the name format is
passed to the Sametime server for login and awareness using
the NOTES.INI setting iNotes_WA_SametimeNameFormat,
which will then override this configuration setting.
Select one:
v Disabled -- No disclaimer text will display
v At the top -- To display disclaimer text at the top of Domino
Web Access mail messages
v At the bottom -- (default) To display disclaimer text at the
bottom of Domino Web Access mail messages
Type the disclaimer text you want to display (in HTML
format) on all Domino Web Access mail messages.
Enable to allow users to encrypt their offline mail databases
for security. If you enable encryption, complete the next two
fields to set the encryption level. Default is disabled.
Choose one:
v Simple -- provides protection against casual snooping.
v Medium -- provides the right balance among security,
strength, and fast database access. Probably the right choice
for most users.
v Strong -- when security requirements are paramount, and
the resulting database access performance is acceptable.
This setting, when enabled, overrides the administrator-
specified encryption level and allows users to choose their
own encryption level.
Enable (default) to turn on the ″Work Offline″ feature in the
Domino Web Access client. Disable this option to prevent users
from using Domino Web Access offline, disconnected from the
network.
Enable and then enter a number to set how many days worth
of documents to replicate (default is 90). Documents older than
those specified are removed from the local replica. Users can
reset this for each offline subscription file using the Domino
Sync Manager. Default is disabled.
Chapter 34. Setting Up Domino Web Access 875
Setting Action
Limit document attachments during sync Enable this setting to limit the size of attachments during sync.
When set, attachments greater than 100 KB are truncated
(stripped from the document) during replication. Default is
disabled.
Security Settings Enable this setting so that the user’s offline Internet password
remains synchronized with their online Internet password.
This setting works only when the Online Configuration
document Security Settings field ″Keep Internet Password
Synchronized″ is enabled.
International
Alternate name support Enable (default) to allow Domino Web Access users to display
alternate names in a native language.

Disable to prevent Domino Web Access from displaying

alternate user names in a native language. When disabled,
users see alternate names in English only.
Preferred alternate name language This setting overrides the preferred language for an alternate
name in user Preferences.

Pick from a list to select the default alternate name language.

Default is English.
Allow user to choose alternate name display Enable to let users choose the preferred language for an
alternate name.

Disable (default) to prevent users from controlling alternate

Start Up View
Allow user to select default active view
When opening Domino Web Access, open to
Browser Cache Management
Browser Cache Management
Automatically install Browser Cache Management
name support.
Enable (default) to allow users to select a default active view.
Select the view that displays when the user logs on to Domino
Web Access.
Enable (default) to install Browser Cache Management.
Enable to automatically install Browser Cache Management the
first time a user accesses Domino Web Access from a machine
that does not have it installed. If not set, the user can install it
on their own from Preferences, but is not required to install it.
Default is disabled.

876 Lotus Domino Administrator 7 Help

Setting
Default cache scrubbing level
Clear history when browser window is closed
Disallow attachments if not installed
Maintain static code archive between sessions
Other Settings
Archiving on server
Full-text indexing
Modification of Internet password
Calendar printing
Action
Set the automatic cache clearing level for the Domino Web
Access server. Type a number from 1-5 where:
0 -- Deletes the caches including personal information related
to the mail database.
1 -- Deletes all URLs that begin with the mail file path.
2 -- Deletes all URLs in the cache that originate from the server
hostname, except for URLs that contain /iNotes/Forms7.nsf,
the current forms file (or /iNotes/Forms6.nsf).
3 -- Deletes all URLs in the cache that originate from the server
hostname.
4 -- Deletes all URL s in the cache except for URLs that contain
/iNotes/Forms7.nsf, the current forms file (or
/iNotes/Forms6.nsf).
5 -- Deletes all URL s in the cache.
Enable to clear the browser’ history when the window is
closed. Prevents access to previously displayed pages by
unauthorized users. Default is disabled.
Enable to prevent users from adding or accessing attachments
in e-mail if Browser Cache Management is not installed.
Default is disabled.
Using this setting prevents users who have not installed
Browser Cache Management from accessing or copying
sensitive information in an attachment at an unsecured
workstation.
Enable (default) to move static Domino Web Access design
entries from the cache to a local folder on the machine so that
they can be restored to the browser cache when the browser is
started again.
Enable (default) to allow users to create archives of their mail
files on the server.
Disable to prevent creation of mail archives and save disk
space on the server.
Enable (default) to allow users to create a full-text index of
their mail, calendar, and task entries on the server.
Disable to prevent creation of full-text indexes to save disk
space on the server and improve performance.
Enable (default) to allow users to change their Internet
password.
Enable (default) to allow users to print various calendar
formats, including DayRunner, Franklin Planner, and Trifold.
Calendar printing uses the PDF format from Adobe Acrobat.
Disable to prevent users from printing Calendar formats using
PDF.
Chapter 34. Setting Up Domino Web Access 877
Setting Action
Domino Web Access ActiveX file attachment utility Enable (default) to allow users to use the custom file upload
utility to drag-and-drop file attachments, select files easily, and
have multiple file views.

Disable to allow users to use the standard browser file upload

utility.
Compress HTTP response data Enable (default) to turn on GZIP compression.

Disable if the browser used does not support GZIP

compression.
Rooms and Resources Enable (default) to allow access to room and resource database
when scheduling meetings.
Reuse Child Windows Enable to enforce this feature globally for all users. If disabled
(the default) users can enable this feature via user preferences.
Local Archiving Enable to allow users to archive locally to their own system.

Note: The Instant Messaging settings and the Local Archiving setting (under Other Settings) on this tab
in the Configuration Settings document apply to users whose mail file is based on the DWA7 mail
template. In a mixed environment, for users whose mail file is based on iNotes6, you must use the
equivalent NOTES.INI settings. For information on those settings, see the topic Using NOTES.INI settings
in a mixed environment.

Adding a disclaimer to outgoing messages

You can add a disclaimer to the bottom of outgoing mail messages in Domino Web Access. A disclaimer
is a denial or a disavowal of legal responsibility for the contents of the message. In some countries, not
having a proper disclaimer on messages may result in fines leveled by regulatory agencies.

To add a disclaimer to an e-mail message, edit the mail server’s Configuration Settings document and
complete the fields under Disclaimer Text.

Using Browser Cache Management

Use Browser Cache Management to improve client side performance and security of Domino Web Access
sessions on Internet Explorer by controlling which entries are stored in the cache and which are removed
when the Domino Web Access session ends. Many organizations restrict files that are left in the browser
cache for security reasons but for lower end machines, loading the Domino Web Access for each session
may adversely impact performance. So, for example, you may want to leave Domino Web Access design
elements in the cache for performance reasons, but remove everything retrieved from mail databases for
security reasons.

You can set the cache scrubbing level to remove all cache entries or only those related to the user’s mail
database. Browser Cache Management improves client side performance, for example, by archiving static
design elements of Domino Web Access locally, and then restoring them to the cache the next time the
browser is accessed. This is particularly useful when Domino Web Access is accessed via a lower
bandwidth connection.

Setting up Browser Cache Management: You set up Browser Cache Management in the Domino Web
Access server’s Configuration Settings document. Once you have enabled this feature, you can choose
whether to install it on Domino Web Access clients automatically, or to give users the option of installing
it. If you install it automatically, the first time a user accesses Domino Web Access, a Browser Cache
Management system confirmation displays, prompting the user to close all browser windows for Browser
Cache Management to take effect.

If you enable Browser Cache Management but do not install it automatically, users can install (and
uninstall) it using a Domino Web Access preference (Preferences - Logout). If you have not enabled
878 Lotus Domino Administrator 7 Help
Browser Cache Management, this preference is not visible. As an additional security measure, you can
prevent users who have not installed Browser Cache Management from adding or accessing e-mail
attachments.

Once the Browser Cache Management feature has been installed on a user’s system, the cache cleanup
occurs based on the cache scrubbing level set in the server’s Configuration Settings document. The user
cannot change this. However, if it has not been installed, users can manually clear the cache at logout by
clearing the history, and selecting one of these logout options:
v Secure -- deletes all entries in the cache except Domino Web Access design elements, which are
archived locally when the last instance of Internet Explorer is closed, and restored back into the
browser cache when the next instance of Internet Explorer is opened.
v More Secure -- deletes all entries in the cache.

Configuring alternate name support in Domino Web Access

An alternate name is helpful when a user wants to use his or her native language and character set to
type, display, and look up names. For example, users can type a name in a native language and character
set when sending mail. A user’s primary name is recognizable to an international audience; an alternate
name is recognizable to the user’s native language.

By default, Domino Web Access allows users to view alternate names but not in any language other than
English. You can change Domino Web Access to allow users to send and view alternate names in their
own native language.

Note: Before a user can use an alternate name for a primary name, you must register and certify the
alternate name.

To allow users to display alternate names in the language of their choice: Complete this procedure so
that the ″Display alternate names″ option appears in the Domino Web Access Basic Preferences. Users
will be able to display alternate names in the language of their choice.
1. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
2. Click Configurations.
3. Select the Configuration Settings document for the Domino Web Access mail server(s) and click Edit
Configuration.
4. Select the Domino Web Access tab.
5. Under Mail, enable ″Name resolution and validation.″
6. Under International, enable ″Alternate name support.″
7. Under International, enable ″Allow user to choose the alternate name display.″
8. Save the document and restart the Domino server.

To allow users to view alternate names in the languages set by the server: Complete this procedure so
that the ″Display alternate names″ option appears in the Domino Web Access Basic Preferences. Users
will be able to display alternate names in the languages set by you on the server.
1. Perform steps 1 through 6 in the preceding procedure.
2. Disable ″Allow user to choose alternate name display.″
3. In the field ″Preferred Alternate name languages,″ choose languages from the list.
4. Save the document and restart the Domino server.

Reusing child windows

Domino Web Access can reuse windows that are already open, thereby reducing the time it takes to
perform certain actions. When this feature is set, Domino Web Access caches, and then reuses portions of
the Mail and Calendar forms that do not change. By reusing the Read Message, New Message, and New
Calendar Entry windows, the performance time is improved for some of the most frequently used
actions: reading and creating e-mail messages, and creating Calendar entries.

Chapter 34. Setting Up Domino Web Access 879

For example, when a user opens a message, the Read Message window opens. The Read Message form is
also cached, without the message text. The form is then used to display any additional messages that the
user opens in the same window. This eliminates the time it takes to close the first window and open a
subsequent message in a new one.

You can enable this feature globally, which enforces it for all users. If you do not enable it globally, end
users can still enable it on an individual basis by setting a Domino Web Access preference.

To enable reuse child windows globally, edit the mail server’s Configuration Settings document and check
″Reuse Child Windows″ under Other Settings.

To disable reuse child windows globally so that the end user preference ″Reuse child windows″ does not
appear in the client preferences, use the NOTES.INI setting iNotes_WA_DisableReuseChildWindows=1.

Using Domino Web Access Redirect to access mail in Domino Web Access
Domino Web Access users can access their mail files using Domino Web Access Redirect. With Domino
Web Access Redirect, users do not need to know the name of their mail file and mail server, they need
only know the name of the Domino Web Access Redirect server. Domino Web Access Redirect uses
Domino authentication methods to redirect a user’s browser to their mail file based on their user name
and password.

During setup, you can enforce SSL security for anyone using DWA Redirect to open their mail file in one
of two ways. You can enforce SSL for the entire session, or enforce SSL only for authentication, after
which the user is switched back to non-SSL. You can change the SSL port number, if it is not the default
443.

Setting up Domino Web Access Redirect: The Domino Web Access Redirect template (IWAREDIR.NTF)
is in the Domino data directory. To set up Domino Web Access Redirect:
1. Create a database from the IWAREDIR.NTF template.
2. In the Notes client, open the database that you created.
3. Click Setup and follow the prompts to set up Domino Web Access Redirect.

Note: If you select ″MailServer″ as the Redirection Type under Server Settings, the common name of the
Domino mail server must be the same as its fully-qualified TCP/IP domain name. For example, if the
mail server field in the Person document is set to serverA/domainA, the server’s TCP/IP fully-qualified
domain name must be serverA.lotus.com.

Using Domino Web Access Redirect with portal views: If you have enabled Personal Options for users
to display Domino Web Access in portal views, you should also use the following NOTES.INI variables
so that the Logout and the Offline buttons display in portal views. Also note that offline is required for
local archiving in portals.
iNotes_WA_PortalLogout=1
iNotes_WA_PortalOffline=1

Using Domino Web Access Redirect: To use the Domino Web Access Redirect:
1. Launch the browser.
2. Enter the URL of the Domino Web Access Redirect server (for example server.acme.com).
3. When prompted, enter your user name and password.

Using the new DWALoginForm: To use the new DWALoginForm, you must have created a Domino
Web Server Configuration database.
1. Open the Domino Web Server Configuration database (DOMCFG.NSF).
2. Click Add Mapping.
3. Change the Target Database to your Domino Web Access Redirect database.

880 Lotus Domino Administrator 7 Help

4. Change the Target Form to DWALoginForm.
5. Save & Close.

You are now ready to use the new DWALoginForm.

Making document links work

Domino Web Access supports document links to any server, including servers other than the user’s home
mail server. Document links work as long as the user has access to the database to which the link
connects. The database must also be on a Domino server in the local area network.

To configure the server for document links:

1. From the Domino Administrator, click the Configuration tab.
2. Select the Server view and open the Current Server Document.
3. Click Edit Server.
4. Choose the Internet Protocols tab, then Domino Web Engine tab.
5. Set the field, ″Redirect to resolve external links″ to ″By Server.″
6. Click Save & Close.

Making calendar details available to all users

By default, Domino Web Access users can view free and busy times of other users when creating group
calendar entries or meeting invitations, but they cannot view details for each time slot. It may be helpful
for users to see detailed information, such as what kind of appointments are scheduled for a particular
time slot, when they schedule meetings.

To make calendar details available to all users:

1. From the Domino Administrator, open the Domino Web Access server Configuration Settings
document.
2. On the Basics tab, for the field ″Use these settings as the default settings for all servers,″ click Yes.
3. Enable the field ″Extract calendar details.″

Note: This field will not display unless you perform step 2.

For information on how to enable this feature see Collecting detailed information from user calendars.

Setting a maximum attachment size

By default Domino Web Access allows a maximum attachment size of 50,000K (50MB). You can increase
this amount by setting the ″Maximum attachment size (kb)″ field in the Domino server Configuration
Settings document - Domino Web Access tab. However, attachment size is based on two parameters that
default to a 10,000K (10MB) limit independent of this setting. So even though Domino Web Access allows
for a larger attachment, the following two settings must be increased to a value larger than the Domino
Web Access maximum attachment setting for users to be able to add attachments larger than 10MB.

In the Server or Web Site document, set these settings higher than the Domino Web Access ″Maximum
attachment size″ field:
v In the Server document -- Internet Protocols - HTTP - Maximum Size of Request
v In the Server or Web Site document -- Internet Protocols - Domino Web Engine - Maximum Post data

Allowing users to take the Domino directory offline

You can use a NOTES.INI variable, $DOLSDirectoryCatalog, to set the name of a Domino directory that
the user may take offline. This setting makes a part of the interface visible in the user’s preferences,
giving users the option of taking the server’s directory catalog or Domino directory offline.

Chapter 34. Setting Up Domino Web Access 881

For example, if NOTES.INI contains $DolsDirectoryCatalog=dc.nsf, the user sees a new preference setting,
″Include server’s Name and Address Book″. If the user enables this setting, the server’s directory catalog
will be included among the files when the user goes offline.

Taking the directory catalog rather than the Domino directory offline improves performance and saves
space on the user’s disk drive.

Disabling the Active Content Filter

Use the NOTES.INI variable, iNotes_WA_DisableActCntSecurity, to disable the Active Content Filter. A
setting of 1 disables the filter. Setting this variable to 0 (or omitting it from the server’s NOTES.INI file)
enables the filter.

The Active Content Filter is intended to remove potentially harmful active content (JavaScript, Java,
ActiveX) from HTML in mail messages prior to display in a browser. Active content filtering can reduce
server performance because it requires a full parse of HTML content and a rewrite of the content.

Setting the level of automatic cache clearing

If you choose not to enable Browser Cache Management for the Domino server (Domino Web Access tab
of the Configuration Settings document), you can set the level of automatic cache clearing using the
NOTES.INI variable iNotes_WA_LogoutScrubType.

The format is:

iNotes_WA_LogoutScrubType=value

Redirecting users to a Web page after logout

Use the NOTES.INI variable, iNotes_WA_LogoutRedirect, to specify a URL to redirect users to a Web
page after logging out from server. The setting provides normal cache clearing with the Domino Web
Access control, and clearing of browser credentials. This variable allows sites which have additional
actions that need to happen on a logout (such as logging out of a reverse proxy server) to specify a URL
to do this additional activity. Or you can use this variable to return people to an initial login page.

For instance:
iNotes_WA_LogoutRedirect=http://www.ibm.com

Specifying the number of names to return

Use the NOTES.INI setting, iNotes_WA_NameLookupMaxNumMatch, to specify the maximum number
of names to return on name lookups. The default is 200. You can reduce this number to improve server
performance.

Using GZIP to improve Domino Web Access performance

By default, Domino Web Access uses compression (GZIP format) to reduce network bandwidth
consumption and provide better performance, particularly for users with slow network connections. You
can use the following NOTES.INI settings to turn GZIP compression on and off, and to specify the types
of content to compress.

After compression, Domino Web Access generated pages are cached in the web server’s page cache,
which also improves server performance.

iNotes_wa_GZIP_Disable: Use this setting to turn compression on and off. The default is 0 (on). For
example to turn off compression:
iNotes_wa_GZIP_Disable=1

iNotes_wa_GZIP_Content_Types_Included: Use this setting to define which types of content you want
to compress. The default is:
"text/*;application/*"

882 Lotus Domino Administrator 7 Help

For example, to compress all text:
iNotes_wa_GZIP_Content_Types_Included="text/*"

iNotes_wa_GZIP_Content_Types_Excluded: Use this setting to define which types of content you do

not want compress. The default is:
"image/*;application/pdf"

For example to exclude XML data so that it will not be compressed:

iNotes_wa_GZIP_Content_Types_Excluded="image/*;text/xml"

Note: You can also disable GZIP compression using the ″Compress HTTP response data″ setting on the
Domino Web Access tab of the Configuration Settings document.

Additional NOTES.INI settings for Domino Web Access

You can use the following NOTES.INI settings to further customize your Domino Web Access sessions.

Set this to the name of an authentication token cookie if you are

iNotes_WA_AuthTokenName
iNotes_WA_AutoUseWebmail
iNotes_WA_DefaultFormatPlainText
iNotes_WA_DisableBothFormats
iNotes_WA_DisableRecodeMIMECharset
iNotes_WA_DisableReuseChildWindows
GuessMIMEBodyLang
iNotes_WA_MaxRowsPerLine
iNotes_WA_NamePickerSearchAccentInsensitive Use this variable to make the Name Picker search accent sensitive.
For example, when this is enabled, search recognizes Muller and
Müller as two different name.
iNotes_WA_NoWebmail
iNotes_WA_OpenElementNoStore
iNotes_WA_PortalOffline
iNotes_WA_PortalSkipEndIESession
iNotes_WA_PrintUserStyleSheet
iNotes_WA_Query Agents
using something other than an LTPA token.
Use this setting to automatically go to Webmail, in instances where
Domino Web Access is not supported by the browser.
Use this setting to set the default format for messages to plain text
for new users.
Use this setting to turn off a user’s ability to send a message in
both plain text and HTML format.
Use this setting to turn off recoding of charsets for any text parts in
which their charset is not the default for the charset group.
Use this setting to globally disable the reuse child windows feature
in Domino Web Access clients.
Use this setting so that Domino Web Access will determine which
character set group to use based on the language used in the body
of e-mail messages.
Use this setting to specify the maximum number of lines per entry
in a view.
Use this setting if you do not want to offer Webmail as an option
when Domino Web Access is not supported by the browser.
By default (or if not set), this setting prevents documents from a
user’s mail file from being cached and left behind even if a user
fails to logout after a Domino Web Access session.
When accessing Domino Web Access via a portal, use this setting to
include the Offline and Archive options.
Use this setting to avoid logging out of other Web applications
when logging out of Domino Web Access during a portal session
(that is, when using &ui=portal).
Use this variable so that you can specify a special user-defined
style sheet to control font sizes when printing.
Use this setting to invoke QueryOpen and QuerySave agents when
accessing Domino Web Access documents.

Chapter 34. Setting Up Domino Web Access 883


iNotes_WA_AuthTokenName
iNotes_WA_SametimeNameFormat
iNotes_WA_SametimeProtocol
iNotes_WA_SecMailPreferNotes
iNotes_WA_SkipEndIESession
iNotes_WA_UseInternetAddrForXsp
Set this to the name of an authentication token cookie if you are
using something other than an LTPA token.
Use to specify the format of the name that is passed to Sametime
for login, awareness checking, or to pass the RFC821 address.
Note: This setting overrides the Configuration Settings document
setting ″Directory type used by IBM Lotus Instant Messaging.″
Use this setting to access the Sametime server using a protocol that
is different from the current Web page’s protocol.
Use this setting to turn on Notes sign and encryption when both
S/MIME and Notes sign and encryption are possible.
Use this setting to avoid issues with other open Web pages being
negatively impacted by a Domino Web Access logout.
For xSP server environments, use this to force the From and
Principal fields to use the ″Internet address″ format when sending
e-mail.

Using NOTES.INI settings in a mixed environment

The following NOTES.INI settings have been replaced by Configuration Settings document settings in
Domino 7. To configure users with the DWA7 mail template, use the appropriate settings on the Domino
Web Access tab of the Configuration Settings document instead of these variables.

Although you cannot use these NOTES.INI settings for Domino 7, they have not been removed, and are
still valid for users who have the iNotes6 mail template. In a mixed environment with both iNotes6 and
DWA7 users, the NOTES.INI setting will apply to iNotes6 users, but the corresponding Configuration
Settings will override these NOTES.INI settings for DWA7 users.

NOTES.INI Setting Configuration Settings document field

iNotes_WA_Chat
iNotes_WA_LiveNames
iNotes_WA_SametimeJavaConnect
iNotes_WA_NoLocalArchive
iNotes_WA_SametimeServer
iNotes_WA_SametimeToken
iNotes_WA_STLinksLocal
Instant Messaging features
Online awareness
Prefer Sametime Java Connect for browsers
Local Archiving
Set an Instant Messaging server hostname for all DWA users
Allow secrets and tokens authentication
Loading \stlinks from Domino application server

For information on these NOTES.INI settings, see the Domino 6.5 Administrator help, available on on
www.Lotus.com/ldd/doc.

Domino Access for Microsoft Outlook

IBM Lotus Domino Access for Microsoft Outlook provides access to Domino mail file databases from the
Microsoft Outlook Client. This product brings most of the Domino messaging features to Microsoft
Outlook users, allowing users familiar with Microsoft Outlook to work effectively with Domino.

Domino Access for Microsoft Outlook (DAMO) includes out of office and change password features, and
the ability to import and export Internet certificates. Users can set Domino Preferences including mail file
preferences, setting up free time and busy hours, autoprocessing, and customizing replication settings.
Replication synchronizes the Outlook client with Domino so that the Outlook .PST file is identical to the

884 Lotus Domino Administrator 7 Help

mail database. For users who access their mail using both Notes and Outlook, users need only to make a
change one time, and the changes appear in both places for Mail, Calendar, Tasks, and Contacts. Users
can also work offline, using a local address book.

If more than one person shares a single workstation, they can share a DAMO installation, by using the
multi-user installation option. In a multi-user installation, each individual user can have a private folder
hierarchy as their data directory (for example, C:\Documents and Settings\<user>\DAMO_Data). This
provides a certain level of privacy. However, for security users also need to assign a password to their
local mail database (*.PST file), because with DAMO, all files are local on the workstation. (Typically, in
both a standard Notes environment and a standard Outlook environment, this is not necessary because
the mail database is on the server, and the server controls access.)

Note: Microsoft Outlook 2000, Outlook XP, and Outlook 2003 each have a different method of assigning a
password to the local data file. Users should refer to the on-line help for their release of Outlook.

Before installing Domino access for Microsoft Outlook, you must set up users for installation.

If you are upgrading from 6.5.x to 7.0, see the topic Upgrading Domino Access for Microsoft Outlook
from 6.5.x to 7.0.

Setting up users for installation

Before users install this program, you must create the Domino user and Notes ID for them. You also need
to supply this information to the user, for use during install. If you plan for end users to install DAMO,
you should distribute the installation instructions in the topic End user installation. This information is
also available to users in the ″Lotus Domino Access for Microsoft Outlook Installation and Setup Guide″
on www.Lotus.com/ldd/doc.

End users must have Microsoft Outlook 2000, 2003, or XP installed on their systems. The Microsoft
Outlook client must be a Corporate or Workgroup client. Users can install Domino Access for Microsoft
Outlook using a standard Windows MSI installer. The setup program used during installation is similar
to the setup that is used for the Notes client. It prompts the user for a minimum amount of information
and, based on this information, sets up the Location documents, Connection documents, and NOTES.INI
settings needed for Outlook to access the server.

End users need the following information to install Microsoft Outlook for Domino Access:
v The name of their mail server and domain for their mail database
v Their Notes user name and password
v Information regarding their Internet certificate (if applicable)
v A copy of the installation instructions

Registering Users as Domino Access for Microsoft Outlook clients

Although DAMO is for Microsoft Outlook users connected to Domino, access through any client
connected to Domino is also available. When registering users, you can choose MAIL7.NTF,
MAIL7EX.NTF or DWA7.NTF as the mail template. If you do not plan to use any Web access for mail,
then you can use the standard MAIL7.NTF template, which is slightly smaller than the other templates.
Users that use the Domino for Web Access 7 (DWA7.NTF) template can connect to their mail file on the
Domino server using a browser, Domino Access For Microsoft Outlook, or a Notes client.

To register DAMO clients, follow the instructions for registering new users keeping the following
information in mind:
v A Notes ID is not automatically created during registration. You must select ″Create a Notes ID for this
person.″
v When deploying Domino Access for Microsoft Outlook to a large number of users, it is recommended
that you make any hierarchical or name changes before registering new users.

Chapter 34. Setting Up Domino Web Access 885

Setting up Condensed Directory Catalogs for Offline
Domino Access for Microsoft Outlook users can create a local replica of an address book to use when
working offline, disconnected from the network. Using Domino Preferences in Microsoft Outlook, users
can select an address book to take offline. It is strongly recommended that a condensed directory catalog
is available for users to conserve space and improve the time it takes to replicate.

Upgrading Domino Access for Microsoft Outlook from 6.5.x to 7.0

Users can upgrade from Domino Access for Microsoft Outlook 6.5.x to release 7.0. However, when
upgrading from 6.5.3 or earlier, the upgrade will continue to use a single data directory, in which
multiple users have profiles that share one directory. To take advantage of the multi-user installation
capabilities, in which each user can have his or her own data directory, users must first uninstall DAMO
6.5.x, and then install DAMO 7.0. Before doing this, users should back up the existing *.NSF, *.PST and
*.OST. files as a precaution. The initialization process of the new installation will recreate the mail files
locally.

During the upgrade users will be asked if they want to create a profile at the end of the upgrade process.
If they choose not to, they can create new profiles at anytime in the future by choosing ″Create New
MAPI Profile″ from the Start - Programs - IBM Lotus Domino Access for Microsoft Outlook shortcut.

Users cannot create a DAMO profile using the Outlook Setup Wizard. They must use the ″Create New
MAPI Profile″ on the start menu.

Installing Domino Access for Microsoft Outlook

The Domino Access for Microsoft Outlook setup program is designed to be installed on a client system.
You can install Domino Access for Microsoft Outlook for end users without their involvement or end
users can install it themselves on their workstations. The Domino Access for Microsoft Outlook setup is
located in the Domino server’s data directory. You can make the setup program available to end users on
the network:
<NOTESDATADIR>\domino\html\DAO\setup.exe

Choose how you want to install Domino Access for Microsoft Outlook:
v Administrator installation
v End user installation

Note: Domino Access for Microsoft Outlook on Outlook 2000 does not support ″Internet Mail Only″
clients. Previous versions of this product used Open Standards (IMAP and ICAL) to access Domino. The
current release, however, uses the Notes remote procedure call (NRPC) service, which allows a more
accurate matching between Notes features and Outlook. Internet mail clients can still access their mail
using POP3 and SMTP, but without the full functionality that Notes or Outlook provides.

If you installed an earlier version of this product, see the topic Upgrading from 6.5.x to 7.0.

For additional information about system requirements and the most current installation information, see
the release notes that shipped with this product, or view them on http://www.Lotus.com/ldd/doc.

Administrator installation
If you are installing Domino Access for Microsoft Outlook on a workstation for an end user(s), Windows
security requires that you assume the identity of the user for whom you are creating the DAMO user
profile. Creating a profile in any other way will hide that profile from the intended user.

There are two ways to create user profiles:

v The simplest method of creating user profiles is to log on to the Windows workstation as the intended
DAMO user. In this way, using the steps below, you can create the data directory in the user’s private
folder (for example, C:\Documents and Settings\<user>).

886 Lotus Domino Administrator 7 Help

v An alternative method is to use the Windows RunAs functionality where a Windows administrator can
assume the identity of each user to create a DAMO profile.

Note: For a multi-user installation, each registered user on the workstation must be a member of the
Power Users group to be able to select their profile when DAMO starts.

Silent install: Use the silent installation to install Domino Access for Microsoft Outlook and create a
profile without end user involvement. This process uses the inherent InstallShield capabilities that call a
setup file containing the user’s connection information to the Domino server.

For example, to set up Domino Access for Microsoft Outlook for multiple users on one workstation, you
can run Silent Install and assume the users’ logon rights with the RunAs capability for each user.

There is one setup file for each user. The setup file is a text file that contains the following connection
information:
-u <User Name> -s <Server IP address> -f <Full path to ID file> -p <id file Password>

For example:
-u John Smith -s 1.11.11.111 -f c:\lotus\notes\data\john.id -p 123456

The DAMO setup executable is called using the following syntax:

setup.exe /s /v"/qn SETUPFILE=<complete path to setup file>"

For example:
setup.exe /s /v"/qn SETUPFILE=C:\user\info.txt"

Note: The syntax must be exact. Notice that after /v there is no space before the quotation mark (″).
Also, there is a closing quotation mark (″) at the end of the line.

Using RunAs on Windows XP:

Option 1 - Using the installation wizard:

1. As the Windows administrator, run setup choosing the desired options, including either the Single
User or the Multi-User install options.
2. Choose to not create a profile.
3. Click Start - Programs - IBM Lotus Domino Access for Microsoft Outlook, and then right click on
″Create New MAPI Profile.″
4. Choose ″Run As...″
5. In the Run As dialog, select ″The following user:″
6. Enter the user’s domain, user name, and password.
7. Enter the connection information as described in Create a User Profile for DAMO section in the End
user installation topic.

Option 2 - Using the silent install:

1. Open a DOS window (cmd.exe) by clicking Start - Programs - Accessories, and then right-click
Command Prompt.
2. Choose Run As ...
3. In the Run As dialog, select ″The following user:″
4. Enter the user’s domain, user name, and password.
5. At the DOS prompt, enter the setup syntax as described in the ″Silent install″ section above.

Using RunAs on Windows 2000:

Chapter 34. Setting Up Domino Web Access 887

Option 1 - Using the installation wizard:
1. As the Windows administrator, run setup choosing the desired options, including either the Single
User or the Multi-User install options.
2. Choose to not create a profile.
3. Open a command prompt (Start - Programs - Accessories - Command Prompt).
4. Change to the program directory for Domino Access for Microsoft Outlook.
5. Run the executable file, dfosetup.exe, as the intended DAMO user using the following syntax:
C:\> RunAs /USER:"WinDomain\<DAMO User>" dfosetup.exe
6. Create the user profile.
For information on creating a profile, see the topic ″End user installation″ later in this chapter.

Option 2 - Using the silent install:

1. Open a DOS window (cmd.exe) by clicking Start - Programs - Accessories - Command Prompt.
2. Use the RunAs command to open another DOS window so that anything run in that window will be
run with rights of the user who opened that DOS window.
C:\> RunAs /USER:"WinDomain\<DAMO User>" cmd.exe
3. From that new window run the install as that user:
setup.exe /s /v"/qn SETUPFILE=<complete path to setup file>"
4. Although it is more complicated, the RunAs command can be used without the need to open a new
DOS window. Use the following syntax, which is a combination of the Windows RunAs syntax
(RunAs /?) and the silent install capability.
C:\> RunAs /USER:"WinDomain\<DAMO User>" <path to DAMO setup.exe> /s /v\" /qn SETUPFILE=<path to setup file>\""
for example:
C:\> RunAs /USER:"ADomain\John Smith" "C:\Temp\setup.exe> /s /v\" /qn SETUPFILE=C:\User\info.txt\""

Note: Because of the possible need for nested quotes, you may need to use an escape character (\) if
spaces are involved.

End user installation

To install Domino Access For Microsoft Outlook (DAMO), you need to know the following:
v Your Notes user name (such as john smith)
v The IP address of your mail server
v The location of your Notes ID

If you are a member of the Windows Administrator group, you can choose whether to do a single user or
a multi-user installation on a workstation. If you are not a member of this group, the installation is a
single user install by default.
v Single user install -- Use this method if only one person uses DAMO on the workstation. This type of
install creates only one data directory.
v Multi-user install -- Use this method if more than one person uses DAMO on the workstation. This
type of install allows the creation of data directories specific to each user. This means that each user
can have their own local files, that can provide some measure of security.

There are three parts to installing DAMO:

1. Configure Microsoft Outlook (assumes you already have Microsoft Outlook installed).
2. Install Domino Access for Microsoft Outlook.
3. Create a user profile (you need to create a DAMO profile, even if you already have one in place for
Outlook).

888 Lotus Domino Administrator 7 Help

Part 1 -- Configure Microsoft Outlook: You must Configure Outlook using these steps or Domino
Access for Microsoft Outlook will not install properly.

Outlook 2000 users -- if you configured Outlook for Internet Only support, you must reconfigure
Outlook for Corporate or Workgroup. To reconfigure Outlook, run Outlook and select Options - Mail
Services - Reconfigure Mail Support. You may be required to supply your Microsoft Office install CD for
this operation.
1. Set Microsoft Outlook as the default mail program. For example, open the Control Panel and choose
Internet Options. Select the Programs Tab - E-mail Option, and then select Microsoft Outlook. (This
path may vary slightly depending on which Windows OS you are using and how you have your
system set up.)
2. If this is a new installation of Microsoft Outlook, you must launch the client to complete the
installation process of Microsoft Outlook. From the Start menu, select Microsoft Outlook and accept
the user name. Then do one of the following:
v Outlook 2k -- Choose ″Manually configure.″ Make no other selections, and then click Finish.
v Outlook XP (2002) and Outlook 2003 -- To the question ″Would you like to configure an E-mail
account?″ choose No. Click Finish.
3. While Outlook is open, select Tools - Options - Mail Services and select the option ″Prompt for a
profile to be used.″

Part 2 -- Install DAMO:

1. Execute the Setup Program.
2. If you are a member of the Windows Administrator group, choose whether to do a single user or a
multi-user install on a workstation. If you are not a member of this group, the installation will be a
single user install.
v Single User Install -- Choose this option if you are the only one who uses the workstation. In single
user installs, the program and data files are in the same directory.
v Multi-User Install -- Choose the Multi-User Install option if more than one person uses the
workstation. Note that each person who uses the workstation must be a member of the Power
Users group or higher to be able to select their profile when DAMO starts.
3. (Optional) Select the Single Logon Feature to synchronize your Notes ID password with your
Windows password. When passwords are synchronized, you can change either password and the
change will be made to both passwords.

Part 3 -- Create a user profile for DAMO: You cannot create a DAMO profile using the Outlook Setup
Wizard. You must use the following procedure.
1. From the Start menu, choose Programs - IBM Lotus Domino Access for Microsoft Outlook - Create
New MAPI Profile.
2. For ″Your Name,″ enter your Domino common user name. For example, John Smith not
jsmith/sales/acme.
3. For ″Domino server name,″ enter the name or the IP address of your mail server.
4. If you installed a multi-user version, and you want your Data directory to be in a different directory
than your program files, enter a path for your mail files in the ″Data Directory″ field. For example,
C:\Documents and Settings\jsmith\DAMOData or C:\DAMO jsmith.

Tip: You can use Windows folder security settings, to protect these folders as necessary.
5. If DAMO does not find your Notes ID in your Person Document on the Domino server, you will be
prompted for one. Type the path or browse to locate your Notes ID.
6. (Optional) Copy your Notes ID file to your Data directory. (It is always good to have a backup copy
of your ID file.)
7. Your DAMO profile will be created.

Chapter 34. Setting Up Domino Web Access 889

After the installation process is complete, you can launch the Outlook client. Select the profile that refers
to the user name just configured during setup. If the mail file contains significant amounts of data, it may
take a while to make this data available within Outlook.

For the most current installation information, and for information on the differences between Microsoft
Outlook and Domino Access for Microsoft Outlook, known problems, and migration issues, users can
view the installation and setup guide (which includes the release notes) on
http://www.Lotus.com/ldd/doc.

Working with Domino Access for Microsoft Outlook

IBM Lotus Domino Access for Microsoft Outlook provides most of the features and services that
Microsoft Outlook does. However, users should be aware of the differences listed here.

Making a change to an instance of a repeat meeting

In Microsoft Outlook, the chair is limited by how changes to repeat meetings are made. The chair can
make the change to all meetings or to one instance of a repeat meeting. In Domino, however, you can
modify any grouping of multiple instances. For example, if a weekly repeat meeting has been created for
the next 6 weeks, and an invitee must be added at the third week of the meeting, using Domino, the
chair can add the invitee to the appropriate instance of the repeat set, and then specify ″this and all
future.″

The feature ″this and all future″ is not provided in Microsoft Outlook. If the chair is using Lotus Notes
and the invitee is using Microsoft Outlook, selecting this option generates an invitation to each of the
subsequent occurrences of the meeting. To maintain compatibility between Microsoft Outlook and Lotus
Notes, an invitee that is added to an existing repeat meeting receives instance updates for the entire
repeat set. If you anticipate there will be significant changes to the repeat meeting invitee list, you may
want to keep the number of meeting instances to a minimum. That way there will not be too many
meeting notices arriving in an invitee’s mailbox. This is also the case for rescheduled meetings and other
meeting updates.

Repeat meetings with no end dates

Repeat meetings without an ending date are not supported in Domino Access to Microsoft Outlook. If
repeat meetings are created and no end date is supplied, a default end date is imposed on the repeat set.
The following maximums are applied to all repeating entries (such as meetings or anniversaries) by
default:
v Daily repeating -- 365 Days
v Weekly repeating -- 52 Weeks
v Monthly repeating -- 12 Months
v Yearly repeating -- 10 years

Delegation to multiple users

In Microsoft Outlook, a user can delegate one or more users to attend on his or her behalf. If both the
chair and the invitee are using Microsoft Outlook, this feature is fully support by Domino Access for
Microsoft Outlook. However, if the chair is using Lotus Notes and Domino, but the invitee is using
Microsoft Outlook, the chair will be notified of the additional invitees, but no additional invitations will
be sent to the invitees themselves. If you want more than one user to attend a meeting on your behalf,
you must contact the meeting chair so that an invitation can be issued.

All Day event invitations

In Microsoft Outlook it possible to invite users to ″All Day″ events. This feature is not provided by
Domino. When using this feature, the All Day Event is converted to a 4:00 a.m. to 8:00 p.m. meeting.

Note: For additional information about known problems and limitations, see the release notes that
shipped with this product.

890 Lotus Domino Administrator 7 Help

Chapter 35. Monitoring Mail
This chapter describes how to track messages to determine if they reached the recipients and how to
generate mail usage reports

Tools for mail monitoring

Domino provides three tools that you can use to monitor mail. Message tracking allows you to track
specific mail messages to determine if the intended recipients received them. Mail usage reports provide
the information you need to resolve mail problems and improve the efficiency of your mail network. Mail
probes test and gather statistics on mail routes.

Tracking mail messages

Both users and Domino administrators can track mail. Users can track only messages that they
themselves sent. Administrators can track mail sent by any user.

When you configure mail tracking, you can specify which types of information Domino records. For
example, you can specify that Domino not record message-tracking information for certain users, or you
can choose not to record the subject line of messages sent by specific users.

The Mail Tracker Collector task (MTC) reads special mail tracker log files (MTC files) produced by the
Router and copies certain messaging information from them to the MailTracker Store database
(MTSTORE.NSF). The MailTracker Store database is created automatically when you enable mail tracking
on the server. When an administrator or user searches for a particular message, either a message tracking
request or a mail report, Domino searches the MailTracker Store database to find the information.

Note: The Mail Tracker Collector differs from the Statistics Collector (Collect task), which is responsible
for gathering statistical information about servers.

How mail tracking works

1. From a Notes client or Domino Administrator client, a user creates a query to determine whether a
specific message arrived at its intended destination or to determine how far it got if delivery failed.
2. The mail tracking program begins to trace the routing path from the server where the message
originated. If the message is not found on the originating server, tracking automatically continues at
the next server on the route.
3. Step 2 is repeated on each ″next server″ until the route ends. Detailed information is provided about
the processing of the message on each server.
4. After the tracking query completes, the user can select messages from the results and check their
delivery status. The following table displays the possible values for the delivery status:

Delivery Status Meaning

Delivered The message was delivered to a mailbox on the server. The mail file status indicates
whether the message was read, unread, or deleted. If the mail file status is not read,
unread, or deleted, it appears as unknown.
Delivery failed The server attempted to deliver the message to a mail file but was unsuccessful. The
recipient may not exist, or the server’s disk may be full.
In queue The Router is processing the message.
Transferred The Router successfully sent the message to the server identified in the next hop field.
Transfer failed The Router attempted to transfer the message to another server and failed.

891
Delivery Status Meaning
Group expanded The message was addressed to a group, and the group was expanded on this server.
Unknown The status of the message on the server cannot be determined.

Generating mail usage reports

Over time, the Domino MailTracker Store database (MTSTORE.NSF) accumulates valuable data about
message routing patterns on the server. It may be useful to generate mail usage reports from this data.
For example, you can generate reports of recent messaging activity, message volume, individual usage
levels, and heavily traveled message routes. You can use the Reports database (REPORTS.NSF) to
generate and store mail usage reports. Typically, the Reports database is created automatically when you
set up the server.

Mail usage reports provide important information that you can use to resolve problems and improve the
efficiency of the mail network. In addition, this information is valuable when you plan changes or
expansions to the mail network. For example, you can generate reports that show the 25 users who
received the most mail over a given period of time (a day, a week, a month, and so forth), or the volume
of mail sent by a specified user over some interval. With this information, you can identify users who
might be misusing the mail system. Other reports show the most frequently used next and previous hops,
enabling you to assess compliance with mail use policies.

Agents stored in the Reports database let administrators schedule reports on a one-time, daily, weekly,
and monthly basis. By default, Domino generates scheduled reports at midnight at the interval you
specify -- daily, weekly, or monthly. When a report query is run, the active report agent examines the data
collected in the Domino MailTracker Store database to generate the resulting report. You can configure a
report to save results in the Reports database or mail results to one or more administrators. Saved reports
are organized in the Reports database under several different views. Reports that are mailed, but not
saved, are not added to the Reports database.

You can use the Reports database to analyze server mail usage. Views in the database display previously
saved reports according to date, schedule, report type, and user. In addition, a view displays all
scheduled reports by interval.

Mail routing event generators

To monitor a mail network, you can configure mail routing event generators to test and gather statistics
on mail routes.

For more information on mail routing event generators, see the chapter ″Monitoring the Domino Server.″

Setting up mail monitoring

To set up mail monitoring, you must complete these procedures:
1. Start mail tracking (the MTC task) on the server.
2. Configure the server for message tracking.
3. Set up the Reports database (REPORTS.NSF).

Setting up the Reports database

After you set up the Domino MailTracker Store database, you can use the Reports database
(REPORTS.NSF) to generate and store mail usage reports. Although the Reports database is created
automatically when you set up the server, before you can generate mail usage reports, you must set up
security for the database.

892 Lotus Domino Administrator 7 Help

To create the Reports database
1. From the Domino Administrator, Notes client, or Domino Designer client, choose File - Database -
New.
2. At the bottom of the New Database dialog box, click Show advanced templates.
3. Complete these fields and click OK:

Field Enter
Server The name of the server that stores the Mail Tracking Store database (MTSTORE.NSF)
Title Reports
File name Reports.nsf
Template server The name of the server entered in the Server field
Template Reports.ntf

To set up security for the Reports database

Note: Step 4 of this procedure requires use of the Domino Designer client.
1. Open the Reports database and choose File - Database - Access control to open the database ACL.
2. Verify that the server and the server administrator have Manager access, then click OK.
3. With the Reports database active in your client, choose View - Agents.
4. Verify that the scheduled agents (Daily, Monthly, and Weekly Report Agents, and the Housecleaning
agents) are enabled. Enable agents as necessary by selecting the agent and clicking Enable; then close
the Domino Designer.
5. From the Domino Administrator, click the Configuration tab, open the Server document for the server
where you created the Reports database and click the Security tab.
6. In the Programmability Restrictions - Run unrestricted methods and operations field, enter the names
of administrators who need access to the Reports database, and then click Save & Close.

Controlling the Mail Tracking Collector

After you enable message tracking on the server, the Mail Tracking Collector (MT Collector or MTC task)
automatically creates the Domino MailTracker Store database (MTSTORE.NSF) in the MTDATA
subdirectory of the Domino data directory. The MTC task periodically collects messaging information
from raw data accumulated in special mail tracker log files (MTC files) produced by the Router. After
collecting this message summary information -- information about the originators, recipients, arrival
times, and delivery status of the messages processed by the server -- it adds it to the Domino MailTracker
Store database. Mail users and administrators use the information stored in the Domino MailTracker Store
to complete mail tracking requests and to generate mail usage reports.

CAUTION:
Do not edit the Mail Tracking Store database directly.

In addition to collecting message data, the MTC task performs several maintenance operations on the
Domino MailTracker Store database. You can enter commands at the server console to instruct the MTC
task to perform these operations. The following table lists the commands for performing various MTC
operations:

MTC operation Description and Command

Start mail tracking When mail tracking is enabled in the Configuration Settings document, tracking
automatically starts when the Router starts. If you stop the MTC task, you can restart
it by entering the following command at the server console:

load mtc

Chapter 35. Monitoring Mail 893

MTC operation Description and Command
Stop mail tracking By default, the MTC task automatically stops when the Router stops. To stop the task
without stopping the Router, enter the following command at the server console:

tell mtc quit

Collect new data from mail If mail tracking is enabled on the Router/SMTP - Mail Tracking tab of the
tracking logs Configuration Settings document, the MTC task collects data from mail tracking log
files at the interval specified in the ″Message tracking collection interval″ field. If there
is new data to report, it creates an entry in the MailTracker Store database. To instruct
the MTC task to collect data immediately, enter the following command at the server
console:

tell mtc process

Performing a manual collection resets the automatic collection interval to its full value.
For example, if the collection interval is set to 15 minutes (900 seconds), after you run
the collection manually, the next automatic collection occurs in 15 minutes.

Establish a different
collection interval
To check the collection interval that is currently in effect, as well as the time remaining
to the next collection, enter the Show Tasks command at the console.
If mail tracking is enabled on the Router/SMTP - Mail Tracking tab of the
Configuration Settings document, the MTC task collects data from mail tracking log
files at the interval specified in the ″Message tracking collection interval″ field. If there
is new data to report, it creates an entry in the MailTracker Store database. To specify a
different interval, enter the following command at the server console:

tell mtc interval value

where value is the desired interval, in seconds.

The specified value remains in effect until the next Router restart. At that time the
value specified in the Configuration Settings document again goes into effect.

To check the collection interval that is currently in effect, as well as the time remaining
to the next collection, enter the Show Tasks command at the console.
Compact the MailTracker By default, the MTC task compacts the Domino MailTracker Store nightly at 2 am. To
Store database compact the database immediately, enter the following command at the server console:

tell mtc compact

Reindex the MailTracker
Store database
You can also change the default time for compacting the database, by setting the
variable MTCDailyTasksHour in the server’s NOTES.INI file.
The Message Tracking Store must be full-text indexed by the MTC task only.
For a one time reindex of the database by MTC, enter the following command at the
server console:

tell mtc reindex

To improve performance of the full text index, the index should be periodically rebuilt.
If the admin believes a daily reindex is necessary they may set the following INI:

MTCCompactReIndex=1

If a different schedule is needed, an admin can periodically schedule a Program

document to reindex by executing a Tell command as shown here:

-c tell mtc reindex

894 Lotus Domino Administrator 7 Help

MTC operation Description and Command
Purge old entries from the Documents are purged from the MailTracker Store database based on the Remove
MailTracker Store database documents not modified in the last x days replication setting. For a one time purge of
documents from the database, enter the following command at the server console:

tell mtc purge value

where value is the maximum number of days to retain documents in the Mail Tracker
Store database. The MTC task removes all documents older than value from the
database.

For information about replication settings, see the topic Table of replication settings.

For more information about the MTCDailyTasksHour setting, see the appendix ″NOTES.INI File.″

Configuring the server for message tracking

This process allows you to customize the type of information you want to collect and store in the Mail
Tracking Store database (MTSTORE.NSF). For example, you can exclude certain users’ mail from being
collected, or you can restrict messages from being tracked by message subject.
1. Make sure you already have a Configuration Settings document for the server(s) to be configured.
2. From the Domino Administrator, click the Configuration tab and expand the Messaging section.
3. Click Configurations.
4. Select the Configuration Settings document for the mail server or servers you want to administer, and
click Edit Configuration.
5. In the Configuration Settings document, click the Router/SMTP - Message Tracking tab.
6. Complete these fields, and then click Save & Close:

Field Enter
Message tracking Choose one:
v Enabled to log message-handling activity information in the Mail Tracking
Store database.
v Disabled (default) to not log any message-handling information.
Don’t track messages for The names of users and/or groups whose messages will not be logged and,
therefore, cannot be tracked. This field applies only to messages sent by the
specified person or group.

For example, to prevent administrators from tracking messages sent by the

Manager of Human Resources, enter the manager’s name in this field.

If you leave this field blank (default), authorized administrators can track
messages for all users and groups on all servers that are enabled for mail
tracking.

Log message subjects
On servers running the ISpy task to test mail connectivity, this task sends trace
messages at 5-minute intervals. To prevent the Domino MailTracker Store
database from filling up with entries for these trace messages, enter the name of
the ISpy mail-in database on the server in this field, for example, ISpy on
MailHub1.
Choose one:
v Yes - The server records the subject of each message in the MailTracker Store
database.
v No - (default) The server does not log message subjects.

Chapter 35. Monitoring Mail 895

Field
Don’t log subjects for
Message tracking collection
interval
Allowed to track messages
Enter
The names of users and/or groups whose message subjects will not be logged
and, therefore, cannot be tracked. This field applies only to messages sent by
the specified person or group. The default is none.
A number that represents how often, in minutes, you want to log message
tracking activity in the Mail Tracking Store database.
Note: This number may affect server performance. Enter a number appropriate
to the size and speed of your system. The default 15 minutes is recommended.
The names of servers and/or users allowed to track messages on this server.

Allowed to track subjects
If you leave this field blank (default), only members of the LocalDomainServers
group are authorized to track messages on this server. If you add any entries to
this field, you must list all servers and/or users that are allowed to track
messages on this server.
The names of servers and/or users allowed to track messages by subject on this
server.

If you leave this field blank (default), only members of the LocalDomainServers
group are authorized to track messages by subject on this server. If you add any
entries to this field, you must list all servers and/or users allowed to track
subjects on this server.
Note: If you list servers and/or users in this field, you do not have to list them
in the ″Allowed to track messages″ field.

If disk storage space is a concern, use database replication settings to control how many days’ worth of
information the Mail Tracking Store database retains. The number of days restricts how far back in time
messages can be tracked, so choose a value that balances tracking needs and available disk storage.

For information on replication settings, see the chapter ″Creating Replicas and Scheduling Replication.″

Tracking a mail message

If you track a mail message and the search finds no messages, adjust the search criteria and then perform
the search again.
1. Make sure that you set up mail monitoring.
2. From the Domino Administrator, click the Messaging - Tracking Center tab.
3. In the Maximum results field, specify the maximum number of search results to display for the
tracking request.
4. Complete any of these fields to describe the message that you want to track, and then click OK:

Field Enter
From The user name of the sender.
Note: You can also select the name from the Domino Directory.
To The user name of the recipient.
Note: You can also select the name from the Domino Directory.

896 Lotus Domino Administrator 7 Help

Field Enter
Sent Choose one:
v Today
v Yesterday
v Last week
v Last 2 weeks
v Last month
v All times
Note: To increase the likelihood of finding messages, choose a long time period.
Start Choose one:
v Sender’s home server - (default) Select this option if you know the sender of the
message.
v Current server - Select this option if you don’t know the sender of the message and
you leave the From field blank.

If you manage multiple servers, you can select a different server by clicking its name
from the Servers bookmark to the left of the Domino Administrator.
Subject The subject of the message that you want to track.
Message ID The message ID of the message you want to track.

For more information on enabling tracking by message subject, see the topic ″Configuring the server
for message tracking″ earlier in this chapter.
Domino displays summary results that include the sender’s name, recipient, delivery time and
message subject, if subject tracking is allowed.
5. From the Messages Found pane, select a message and then click Track Selected Message.
6. Expand the Message tracking results folder, and select a server to view more information about what
happened to the message on that server. Domino displays the following information:

Field Description
Delivery status Indicates whether the Router deposited the message in the recipient’s mail file or
transferred it to another server.
Mailbox status Indicates whether the message is unread, read, deleted, or unknown.
This server The name of the current server.
Previous server The name of the server that delivered the message to the current server in the message
path being examined. For messages originating outside the Domino network and
transferred over SMTP, this is the server from which Domino received the message.
Next server If the current server is not the final destination, the next server on the routing path.
Msg priority Indicates whether the message priority is high, normal, low, or unknown.
Unique message ID A value that uniquely identifies the message on the current server.
Inbound message ID The message ID of the message when it arrived on the server.
Outbound message ID The message ID of the message when it left the server.

In some cases, the SMTP Router changes the ID of the message before transferring it.
Inbound originator The sender’s e-mail address as it appeared in the message headers when the message
arrived at the current server.
Outbound originator The sender’s e-mail address as it appeared in the message headers after transfer from the
current server to the next hop server.
Inbound recipient The recipient’s e-mail address as it appeared in the message headers when the message
arrived at the current server.

Chapter 35. Monitoring Mail 897

Field Description
Outbound recipient The recipient’s e-mail address as it appeared in the message headers after transfer from
the current server to the next hop server.
Subject The content of the message’s subject header.
Disposition time Indicates the time when the Router changed the status of the message to the value in the
Delivery status field. There can be a delay between the arrival of a message and when the
Router processes it.
Message arrival time The time when the current server received the message.
Message size (bytes) The size of the message, including any attachments.

Generating a mail usage report

If mail tracking is enabled on a server, the Mail Tracking Store database (MTSTORE.NSF) contains data
about mail usage. You can generate a usage report of the data.
1. Make sure that you set up mail monitoring.
2. From the Domino Administrator, click the Messaging - Mail tab.
3. Expand the Reports for Servername view and open the Report Results or Scheduled Reports folder.
4. Select a report view; for example, select By Type in the Report Results folder or Daily in the
Scheduled Reports folder.
5. Click New Report.
6. Complete these fields, and then click OK:

Field Description
Description Required text to identify the report.
Report Type Specifies the type of report to create. Choose one:
v Top 25 Users by Count
v Top 25 Users by Size
v Top 25 Senders by Count
v Top 25 Senders by Size
v Top 25 Receivers by Count
v Top 25 Receivers by Size
v Top 25 Most Popular ″Next Hops″
v Top 25 Most Popular ″Previous Hops″
v Top 25 Largest Messages
v Message Volume Summary
v Message Status Summary
Time Range Choose one:
v Today
v Yesterday
v Over the last week (default)
v Over the last two weeks
v Over the last month
v All available information
Note: Each choice refers to the specified time period up to the current day. For example,
if you choose ″Yesterday,″ the report includes information from yesterday and today.

898 Lotus Domino Administrator 7 Help

Field Description
Run this report Specifies the execution interval for the report. Choose one:
v Once - Generates a report immediately (default)
v Daily - Generates a report at midnight every day
v Weekly - Generates a report at midnight on Saturdays
v Monthly - Generates a report on midnight on the first day of every month
Report should be Specifies where the server places report results. Choose one:
v Saved (default)
v Mailed
v Saved & Mailed
Mail Recipient If you chose Mailed or Saved & Mailed in the ″Report should be″ field, enter the user
name of the person who should receive the report or select the user name from the
Domino Directory. The default is the name of the administrator running the report.

Note: The Earliest Message Found and Latest Message Found fields are filled in automatically when
you run the report. They display the date and time of the earliest and latest message found.
7. (Optional) To narrow the scope of a report, complete any of these fields:

Field Enter
Sender’s Name A text string for the sender’s name, and then choose whether the name should contain the
text string or exactly match the text string.
Recipient’s Name A text string for the recipient’s name, and then choose whether the string should contain
the string or exactly match the string.
Delivery Status Choose one:
v Is - Delivered (all messages that were delivered)
v Other than - Delivered (all messages that encountered delivery failures or are still being
processed)
v Is - Not Delivered (all messages that encountered delivery failures)
v Other than - Not Delivered (all messages that were either delivered or are still being
processed)
v Is - Being Processed (all messages that are still being processed)
v Other than - Being Processed (all messages that were delivered or encountered delivery
failures)
Note: The delivery status corresponds to the message tracking delivery status. ″Delivered″
refers to messages that were delivered, transferred, or ″group expanded″ (that is, the
message was addressed to a group, and the group was expanded to its member list on the
server). ″Not delivered″ refers to messages that were not delivered, not transferred, or
whose status is unknown.
Message Size The maximum or minimum message size (in bytes) to include in the report.

8. Reports are saved as Notes documents. Double-click the document to view it.

Editing a scheduled report

Edit a scheduled report to change its execution interval (for instance, daily to weekly) or the method of
recording data (saved or mailed).
1. From the Domino Administrator, click the Messaging - Mail tab.
2. Expand the view Reports for Servername and open the Scheduled Reports folder.
3. Select the report view containing the scheduled report you want to edit; for example, Daily or Weekly.
4. Select the report to edit and click Edit Report.

Chapter 35. Monitoring Mail 899

5. Edit the report settings as needed and click OK.

Changing the default time for generating a scheduled report

Domino generates any scheduled report at the default time for that type of report. For example, daily
reports run at midnight every day, and weekly reports at midnight every Saturday. If the default schedule
conflicts with other operations on the server, you can reschedule the report agent to run when the server
is less busy. Changes apply to all reports scheduled to run at that time; that is, if you change the default
time for running weekly reports, the server runs all weekly reports at the new time.

The following procedure requires you to have Domino Designer installed on the administrative
workstation.

To change when the server generates a scheduled report

1. From the Domino Administrator, click the Messaging - Mail tab.
2. Expand the Reports for Servername view and open the Scheduled Reports folder.
3. Select the report view containing the scheduled report you want to edit; for example, Daily or Weekly.
4. From the View menu, select Agents to launch Domino Designer. If Designer does not open
automatically, launch the program manually and then open the Reports database (REPORTS.NSF)
from the server.
5. Double-click the report agent you want to reschedule.
6. Click Schedule.
7. Specify the time to generate the report.
8. Click OK.

Enabling and disabling a scheduled report

By default, Domino enables a scheduled report immediately after you create it, so that the server runs the
report at the next execution interval -- for example, a new daily report runs at midnight following the
day you create it. You can disable any scheduled report and enable scheduled reports that are currently
disabled.

If you created a scheduled report to diagnose a particular problem, you can disable the report to prevent
it from executing after obtaining the information you need. Disabling a scheduled report conserves server
resources, but lets you retain the report settings for future use. You can disable a report temporarily, or
remove it from the server altogether.
1. From the Domino Administrator, click the Messaging - Mail tab.
2. Expand the Reports for Servername view and open the Scheduled Reports folder.
3. Select the report view containing the scheduled report to disable; for example, Daily or Weekly.
4. Select the scheduled report and do one of the following:
v Click Enable Report - Activates a currently disabled report so that the server executes the report at
the next scheduled interval.
v Click Disable Report - Prevents a currently enabled report from running, so that the server cannot
execute it at the scheduled intervals. The report remains in the Reports database and can be
activated at a later time.
v Press the DELETE key - Permanently removes the report from the Reports database.

Viewing mail usage reports

When Domino saves a report, it stores the report data in the Reports database. Reports that are mailed,
but not saved, are not added to the Reports database.

You can use the Reports database to analyze server mail usage. Views in the database display previously
saved reports according to date, schedule, report type, and user. An additional view displays all
scheduled reports by interval.

900 Lotus Domino Administrator 7 Help

You can open the Reports database (REPORTS.NSF) using either of two methods:

To open the Reports database directly

1. From a Notes client, Domino Administrator client, or Domino Designer client, choose File - Database -
Open (CTRL + O).
2. In the Server field, specify the name of the server where the database resides.
3. Choose Reports for Servername from the list of available databases, and then click Open.

To open the Reports database in the Domino Administrator

1. From the Domino Administrator client click, the Mail tab.
2. Select the Reports for Servername view.

Viewing report results

1. Expand the Report Results or Scheduled Reports folders.
2. From either folder, expand the category for the report you want to view.
For example, from the Report Results folder, click the By Schedule view, and then in the Results
panel, expand the category Once to see the results of all saved reports that were run one time only,
rather than on a repeating schedule.
3. To open a report, double-click it in the Results panel.

Note: For scheduled reports, the user is the server running the report; for reports that an administrator
runs manually, the user is the administrator.

Chapter 35. Monitoring Mail 901

902 Lotus Domino Administrator 7 Help
Chapter 36. Setting Up the Domino Web Server
This chapter describes how to set up a Domino server as a Web server.

The Domino Web server

Lotus Domino provides an integrated Web application server that can host Web sites that both Internet
and intranet clients can access, and can serve pages that are stored in the file system or in a Domino
database. When a Web browser requests a page in a Domino database, Domino translates the document
into HTML. When a Web browser requests a page in an HTML file, Domino reads the file directly from
the file system. Then the Web server uses the HTTP protocol to transfer the information to the Web
browser.

Using Domino to store Web pages as documents in a database has a major advantage over storing static
HTML pages: using Domino, any change that you make to a database is automatically reflected on the
Web server.

The following diagram shows how the Web server displays a Notes document as an HTML page to a
browser client.

Any Domino application can be a Web application. Before you create a Web application, become familiar
with the Domino features that can be translated into HTML and determine whether Web browser users,
Notes clients, or both will access the application. You can use the Notes formula language to detect which
type of user is accessing the application and then, based on the user type, change the display of
information in the application.

A Domino Web site can consist of a single database or several databases that are connected by links. In
addition to hosting Web sites, the Web server can run other server tasks, such as mail or directory
services. Be sure to enforce security on databases if you do not want users outside your organization to
access the databases on the server.

903
For information on designing Web applications, see Application Development with Domino Designer.

Web server features

Domino includes these Web server features:
v Translation of Notes features into HTML code. For example, in HTML code, hot spot links are
translated into anchor (<A>) tags.
v Passthru HTML. This is HTML code that you include in a form, document, or About and Using
documents that Domino does not interpret during the page translation. Passthru HTML lets you use
Web-only text formatting, links, images, commands, and programs. Using passthru HTML, you can
combine Domino features with HTML code.
v Security for applications using standard Domino security, such as the database ACL and Internet
security features, such as Secure Sockets Layer (SSL) and name-and-password authentication.
v Support for Java applets that are referenced using passthru HTML or embedded in a document.
v Support for JavaScript that is included as passthru HTML or embedded directly in a document.
v Support for CGI programs that are referenced using passthru HTML in a document. CGI supports EXE,
CMD, and BAT files and scripts written in Perl, Python, and PHP.
v Support for static HTML pages that are referenced in a directory on the server’s hard drive. Static
HTML pages can be referenced by passthru HTML included in a document or can be requested
directly using a URL.
v Support for a last-modified header in Domino URLs, which allows many Web browsers or proxy
servers to cache Domino pages.
v Support for URL extensions that expose Domino functionality to the Web client -- for example, opening
a database or view.
v Redirecting and remapping URLs and directories to another location.
v Support for multiple Web sites with separate DNS names to exist on a single server machine.
v Support for server clusters, which allow a server to fail over to an answering server if the first server is
unavailable and provides load balancing to maximize response time for users.
v Domino Web Server Application Interface (DSAPI) supports all phases of request handling, including
mapping and transforming incoming URLs, authenticating and authorizing users, processing requests,
and logging.

For information on customizing the authentication of Web application users, see the DSAPI
documentation in the Lotus C API Toolkit for Domino and Notes.

Making Web site content changes

You might find it convenient to set up one Web server as a production server and another Web server as
a ″staging″ server. Web content managers can make changes on the staging server without exposing the
changes to users. After all changes to the Web site are complete, the Web content manager replicates the
Web site from the staging server to the production server. In addition, using a staging server allows Web
content managers to view changes through a browser before replicating.

If you use a staging server, give access only to Web content managers. Also be sure to give the Web
content managers replication access on both the staging server and the production server.

In this example, Web content managers make changes on Webstage-E and replicate these changes to
Web-E, which is available to users outside the firewall.

904 Lotus Domino Administrator 7 Help

Setting up a Domino server as a Web server
You can specify that you want to run the HTTP task on a Domino server. The Domino server then acts as
a Web server so that browser clients can access databases on the server.
1. Set up the Domino server.
v Make sure you understand TCP/IP concepts, including DNS host names and IP addressing.
v Set up a Domino server.
v Set up security for the server.
For more information, see the chapters ″Configuring Additional Domino Servers″ and ″Planning
Security.″
2. Decide on an Internet connection strategy.
v To allow users to connect to the server over the Internet, connect the server to an Internet Server
Provider (ISP) and register the server’s domain name and IP address on the ISP’s DNS server. For
more information, contact the ISP.
v To allow users to connect to the server internally, without connecting to the Internet, register the
server’s domain name and IP address on the DNS server at your organization.
3. Start the Domino server.
4. From the Domino Administrator, click Files, open the Server document and enable ″Loads
configuration information from the Internet Sites view.″
5. Create at least one Web site.
6. Decide on an HTTP port strategy. You can enable ports for TCP/IP, SSL, or for both. In the Server
document, click Ports - Internet Ports - Web, and enable one or both: ″TCP/IP port status″ and ″SSL
port status.″
For information on setting up SSL, see the chapter ″Setting Up SSL on a Domino Server.″
7. (Optional) Enable the Domino Web server log.
8. Start the HTTP task.

To check the server setup, start your browser and enter the DNS name or IP address for the server.

Starting and stopping the Domino Web server

To do this Perform this task
Start the Web server manually Enter load http at the console.

Chapter 36. Setting Up the Domino Web Server 905

To do this
Start the Web server automatically when
you start Domino
Stop the Web server
Use new server configuration settings by
restarting the HTTP server task.
Use new server configuration settings
without restarting the HTTP server task.
Perform this task
Edit the ServerTasks setting in the NOTES.INI file to include the
command http. Domino adds the HTTP task by default to the
NOTES.INI file if you choose to install a Web server during
installation.
Enter tell http quit at the console.
Enter tell http restart at the console.
Enter tell http refresh at the server console.
Note: This command only works with settings specified in the Internet
Sites view.

Note: When the HTTP task starts up, a server console message indicates the Domino Directory view the
task is using for Web configuration information (Servers\Internet Sites or Servers\Web Configurations).

For more information on server commands and NOTES.INI settings, see the appendices ″Server
Commands″ and ″NOTES.INI File.″

Modifying Web server Internet port and protocol settings

In certain cases, you may need to change some default Internet port and protocol settings. Check
carefully before changing the defaults.

To modify Web server Internet port and protocol settings:

1. Open the Server document that you want to edit.
2. (Optional) Click Ports - Internet Ports - Web. Under Web (HTTP/HTTPS), complete these fields:

Field Action
TCP/IP port number Enter a port number. Default is 80.
TCP/IP port status Choose one:
v Enabled -- To configure the server to listen for HTTP requests on the specified
TCP/IP port.
v Disabled -- To prevent the server from listening for HTTP requests on the specified
TCP/IP port.
v Redirect to SSL -- To redirect any HTTP requests that come into the TCP/IP port to
the SSL port.
Enforce server access Choose one:
settings v Yes -- To enforce server access settings for this protocol on the server. Server access
settings are found on the Security tab of the Server document, and specify the names
of authenticated users who have been granted access to this server, and those who
have not.
v No -- To not enforce server access settings for this protocol.
SSL port number Enter a port number. Default is 443.
SSL port status Choose one:
v Enabled -- To configure the server to listen for HTTPS requests on the specified SSL
port.
v Disabled -- If you do not want to use SSL for this server.

906 Lotus Domino Administrator 7 Help

3. (Optional) Click Internet Protocols - HTTP, and complete these fields:

Field Action
Bind to host name Choose one:
v Enabled -- To enter up to 32 IP addresses and/or DNS names in the Host name(s)
field to which the Domino server will bind. This allows users to access a Web server
using a name other than the Domino server name.
v Disabled (default) -- To bind to all IP addresses on the server.
DNS lookup Choose one:
v Enabled -- To have Domino look up the DNS name of the requesting client. The
Domino log files and database contain host names corresponding to the machine used
by the Web client.
v Disabled (default) -- To not look up the DNS name of the requesting client. The
Domino log files and database contain IP addresses.
v Choosing Disabled improves the performance of the Domino server because the
server does not use resources to perform the DNS name lookup.
Note: The majority of browser users connect to the Internet through Internet server
providers (ISPs), so the host names returned by DNS lookup are those of the ISP’s
proxy servers, not the individual user machines.
DNS lookup cache Choose one:
v Enabled -- To have Domino cache the results of a DNS lookup for faster retrieval.
v Disabled -- To not have Domino cache DNS lookup results.
DNS lookup cache size Specify the maximum size of the DNS lookup cache. Default value is 256.
DNS lookup cache found Specify the length of time, in seconds, that IP addresses remain in the cache. Default
timeout value is 120 seconds.

4. Save and close the document.

5. Enter this command at the console so that the changes take effect:
tell http restart

Setting up protocol security for the Web server

If you set up protocol security, you can filter out requests that may be potential attacks, such as probing
for buffer overflows or request parsing errors.

If you host third-party applications, set the limits to the most stringent values that still allow the
applications to work normally. If the request exceeds the limit, the Web server discards the request and
returns an error to the browser.

To set up protocol security for the Web server:

1. Open the Server document you want to edit and click Edit Server.
2. Click the Internet Protocols - HTTP.
3. Under HTTP Protocol Limits, complete these fields:

Field Action
Maximum URL length Enter the maximum size, in KB, allowed for URLs received from HTTP clients. The
length includes the query string. The default is 4KB.

Increase the default only if you host an application that requires an extremely long URL.
Maximum number of Enter the number of segments allowed. The default is 64, which is usually more than
URL path segments enough. A segment is delimited by slashes; for example, the URL
″/products.nsf/widgets″ contains two segments.

Chapter 36. Setting Up the Domino Web Server 907

Field Action
Maximum number of Enter the total number of HTTP request headers allowed. The default is 48. Normally,
request headers there is no need to increase the setting; typical requests sent from browsers usually
include less than a dozen headers.
Maximum size of request Enter the total length, in KB, of all the headers in the request. The default is 16KB.
headers
Maximum size of request Enter the total amount of data, in MB, that can be contained in a request. The default is
content 10MB. The two most common ways for users to send data to the server is by submitting
forms or by uploading files. If none of the applications on the server allow users to
upload large files, you can probably set this to a much lower value.

Restricting access by IP address on the Web server

You can determine the client machines that are allowed to access the HTTP and HTTPS ports of the Web
server by specifying a list of IP addresses that have access, and a list of addresses that are denied access.
You can also specify which list takes priority if an address matches both lists.

Addresses can include wildcard characters, so that all addresses within a certain class of address will be
restricted. For example, denying access to address 123.45.6.* denies access to all addresses for that subnet.
Similarly, denying access to address 123.45.* denies access to all subnets for that address.

IP address filtering is useful for managing incoming requests to your Web server -- for example, your
server is behind a firewall and should only be accepting requests from the firewall and from the Domino
Administrator client. It also helps in minimizing excessive requests, such as those generated by machines
infected by a Web worm.

CAUTION:
IP address restriction should not be used as the only means of protecting your site, or as a substitute
for user authentication. Client IP addresses are specified in the network packets sent by the client, and
this information is easily spoofed. Additionally, hackers routinely use attack techniques that hide their
true IP addresses. IP address restriction cannot protect the server against such attacks.

To restrict access by IP address on the Web server:

1. Open the Server document you want to edit and click Edit Server.
2. Click the Internet Protocols - HTTP. In the Network Settings section, complete these fields:

Field Action
IP address allow/deny priority Specify which IP address list -- Allow or Deny -- takes priority if an incoming IP
address is listed in both the allow list and the deny list (this can happen when both
lists contain wildcards).

The default is that the Allow list takes priority.

IP address allow list List the IP addresses that are allowed to access the ports.
IP address deny list List the IP addresses that are denied access to the ports.

Note: If a client IP address does not match either list, then the connection is allowed.

Examples of typical IP address restriction settings:

Example configuration Settings Comment

Allow access to all addresses (leave IP address allow/deny priority: Allow IP
default settings) address allow list: <blank> IP address
deny list: <blank>

908 Lotus Domino Administrator 7 Help

Example configuration
Deny access to everyone
Deny access to a particular Web
crawler
Deny access from subnets that are
infected with a Web worm
Allow access only from two trusted
proxy servers
Settings
IP address allow/deny priority: Deny IP
address allow list: * IP address deny list: *
IP address allow/deny priority: Deny IP
address allow list: * IP address deny list:
123.45.6.78
IP address allow/deny priority: Deny IP
address deny list: 123.45.*; 95.123.4.* IP
address allow list: *
IP address allow/deny priority: Allow IP
address allow list: 123.45.6.78; 123.45.6.79
IP address deny list: *
Comment
All addresses are allowed, but
crawler is denied because it
matches the deny list, which
takes priority over the allow list.
In this case, you must use a
wildcard in the deny list so that
all other addresses will explicitly
match that list.

Hosting Java applets

Using the Java Notes classes, application developers can create applets that perform Domino tasks, such
as opening a session and retrieving information from a database access control list. The Domino server
can host the applet and when a client requests it, download the applet to the browser.

To run Java applets created with Java Notes classes on a Domino Web server, you must enable the
Domino IIOP (DIIOP) task on the server. This task allows Domino and the browser client to use the
Domino Object Request Broker (ORB) server program. The Domino ORB processes the applet requests
and transmits the information to the browser client to communicate. You must enable both the Domino
IIOP task and the Internet Inter-ORB protocol (IIOP) on the server before users can access the Domino
ORB to run the Java applets.

Application designers must create applets with the Java Notes classes and, in addition, they must specify
that the applets can use the Domino ORB to communicate with browser clients. Application designers
specify this setting when they add the applets to a document or form.

For information on designing Web applications, see Application Development with Domino Designer. For
more information on Java Notes classes, see Domino Designer Programming Guide, Volume 3: Java/Corba
Classes.

To set up the Domino ORB:

1. Open the Server document you want to edit.
2. Choose Ports - Internet Ports - DIIOP and complete these fields:

Field Enter
TCP/IP port number The name of the port the Domino IIOP task listens on. Do not change this port
unless you have assigned port number 63148 (the default) to another task.
Note: The default on Linux servers is 60148 because of an operating system
restriction.
TCP/IP port status Choose one:
v Enabled (default) -- To allow communication over this port.
v Disabled -- To prevent communication over this port.

3. Choose Internet Protocols - DIIOP and complete this field:

Field Enter
Number of threads The number of threads you want to allow the DIIOP server task to process at
the same time. The default is 10.

Chapter 36. Setting Up the Domino Web Server 909

4. Click Security and complete these fields in the Programmability Restrictions section:

Field
Run restricted Java/Javascript/COM
Run unrestricted Java/Javascript/COM
Enter
The name that the applet or application uses to access the
server. Applet or application names entered in this field
are allowed to run programs created using a restricted set
of Java and JavaScript features. If the applet or application
logs on anonymously, enter the word ″Anonymous″ in
this field.
The name that the applet or application uses to access the
server. Applet or application names entered in this field
are allowed to run programs created using all Java and
JavaScript features. If the applet or application logs on
anonymously, enter the word ″Anonymous″ in this field.

For information on this setting, see the topic Customizing Web server setup.
5. To restrict the level of authentication, choose a setting in the Internet server authentication field on the
Security tab and save the document.
6. If necessary, edit the ServerTasks setting in the NOTES.INI file to include the DIIOP task.
7. Set up SSL server authentication, name and password authentication, or anonymous access to the
IIOP port for the application or applet.
8. Define server access by browser clients that use Java and JavaScript. If the applet or application uses
name-and-password authentication, enter the name for the applet or application. Otherwise, use the
name ″Anonymous″ when setting up server access.
9. Restart the server.

Generating references to the Web server

You can specify how other servers generate URL references to this Web server. This feature works only
for servers that are in the same Domino domain (share the same Domino Directory).

A typical example of how this feature is used is that of a user performing a domain search from a
browser. The user sends the search request to Server A, but some of the search hits are actually located in
a database on Server B. When Server A generates the HTML for the search results page, it needs to create
URL links to Server B for those hits. To create those links, Server A will look up the Server record for
Server B in the Domino Directory, and use the fields in the table below to generate the correct syntax for
the URLs.

To generate references to the Web server:

1. Open the Server document you want to edit and click Edit Server.
2. Choose Internet Protocols - Domino Web Engine. Under ″Generating References to this Server,″
complete these fields:

Field Action
Does this server use IIS? (Domino 5.0x servers only) Specify whether this server uses the Microsoft IIS stack
instead of the native Domino HTTP stack.
Note: This setting is used only if the server is Domino 5.0x or earlier; Domino 6
and later servers always generate IIS-compatible links.
Protocol Indicate the protocol to be used in URL links to this server. Choices are HTTP and
HTTPS (for SSL).
Host name Indicate the fully-qualified host name to be used in URL links to this server; for
example, www.acme.com.

910 Lotus Domino Administrator 7 Help

Field Action
Port number Indicate the port number to be used in URL links to this server. The default is 80,
the standard HTTP port.

If Server A in the example above needs to generate a link to a database on Server B, and Server B’s
Server record has the fields set to these values:

Protocol: HTTP

Host name: www.acme.com

Port number: 8081

then Server A will create the URL like this:

http://www.acme.com:8081/<database replica-id>/....

Managing Java servlets on a Web server

A servlet is a Java program that runs on a Web server in response to a browser request. Servlets for
Domino must conform to the Java Servlet API Specification, an open standard published by Sun
Microsystems, Inc.

For information on creating Java servlets, see Application Development with Domino Designer.

To manage Java servlets on a Web server:

1. Open the Server document you want to edit.
2. Click the Internet Protocols - Domino Web Engine tab. Under ″Java Servlets″ complete these fields:

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

The default is domino\servlet.

Chapter 36. Setting Up the Domino Web Server 911

Field
Servlet file extensions
Session state tracking
Action
Enter a list of URL file extensions that signal Domino that a URL refers to a
servlet. You must map each extension to a single servlet by a directive in the
servlets.properties file. The default is no extensions.
Choose one:
v Enabled (default) -- To have the Domino servlet manager check periodically
the user activity of all HttpSession instances. Sessions that are idle for the
period of time specified in the Idle session timeout field are automatically
terminated. The servlet manager calls the method HttpSession.invalidate() to
inform the servlet that the session will be terminated.
v Disabled -- Does not check for user activity.

Idle session time-out
Maximum active sessions
Session persistence
Domino uses this setting and the settings below only if the servlet uses the Java
Servlet API HttpSession interface. The HttpSession interface support is
completely separate from the Domino HTTP session authentication feature.
Enter the amount of time in minutes the user is allowed to remain idle before
the session is terminated. The default is 30 minutes.
Enter the number of simultaneous active sessions allowed. The default is 1000.
After this limit is reached, the sessions that have been idle the longest are
terminated.
Choose one:
v Enabled -- To save session data to a disk file called sessdata.ser in the
Domino data directory when the HTTP task exits. Domino saves the data in
the Domino data directory in a file named sessdata.ser. Domino reloads the
session data when the HTTP task restarts. Domino also saves objects that the
servlet has bound to sessions if the objects implement the java.io.Serializable
interface.
v Disabled (default) -- Discards all session data when the HTTP task exits.

3. If appropriate for your servlet engine, control access to the servlet by specifying who has access to the
servlet files.
For more information, see the chapter ″Controlling Access to Domino Servers.″
Special properties for individual servlets can be specified in a text file called servlets.properties, which
is located in the Domino data directory. For more information about the servlets.properties file, see
the book Application Development with Domino Designer.

Setting up WebDAV
WebDAV (Web-based Distributed Authoring and Versioning) is a set of extensions to the HTTP/1.1
protocol which allow users to collaboratively edit and manage files on remote Web servers.

WebDAV support in the Domino Web Server enables accessing file resource type design elements in a
Domino database. This allows application designers to work with design elements such as HTML files,
images and other file based resources using web based authoring and development tools.

The WebDAV implementation in the Domino Web Server supports, and has been tested with, the
following clients; Macromedia Dreamweaver 4.01, Microsoft Office 2000, Microsoft Internet Explorer 5.0x
and 6.0, Windows Explorer on NT4, Windows 98, Windows XP, and Windows 2000.

You must be using Web Site documents to configure and manage the Web sites on your server in order to
use WebDAV.

Be aware that enabling WebDAV also enables the following HTTP methods for the web site: PUT,
DELETE, GET, HEAD, OPTIONS.

912 Lotus Domino Administrator 7 Help

There are some restrictions when using a WebDAV-enabled server. For the Web Site document for which
you have WebDAV enabled, do not do the following:
v Configure URL redirection.
v Enable the ″Redirect to SSL″ option.
v Enable session authentication on the Web Site for which you have WebDAV enabled.
v Create a File Protection document for the Web site that restricts access to the HTML root directory. If a
File Protection document is preventing access to the HTML directory (\domino\data\domino\html),
then some WebDAV clients will not be able to connect to or access the WebDAV database when
accessing this Web Site. The server console displays one of these error messages:
You are not authorized to perform this operation [_vti_inf.html]
You are not authorized to perform this operation [_vti_bin/shtml.exe/_vti_rpc]

To allow access to a database using WebDAV, do the following:

v Provide the user with either Designer or Manager access in the database ACL (Access Control List).
Also, the user must have both ″Create documents″ and ″Delete documents″ privileges enabled in the
database ACL.
v Set the ″Maximum Internet name & password″ field to either Designer or Manager access. This option
is located on the Advanced tab on the database ACL dialog box.
v Some WebDAV clients (such as DreamWeaver 4.01 and Microsoft Office 2000) attempt to lock WebDAV
items. In order for these clients to work correctly with Domino’s WebDAV implementation, you must
enable ″Design Locking″ for databases that will be used with WebDAV. You do this on the Design tab
of the Database Properties dialog box.
v In order to use Internet Explorer as a WebDAV client, the WebDAV database needs to reside in the
Domino data directory. Internet Explorer cannot access databases if they reside in a subdirectory within
the data directory.

Enabling WebDAV: Before you can use WebDAV (Web-based Distributed Authoring and Versioning), it
must be enabled.
1. From the Domino Administrator, choose Configuration - Web - Internet Sites.
2. Open the Web Site document on which you want to enable WebDAV.
3. Click the Configuration tab.
4. Under ″Allowed Methods,″ select ″Enable WebDAV.″

Note: If you enable WebDAV, the following HTTP methods are also enabled: GET, HEAD, OPTIONS,
PUT, and DELETE.
5. Enter this command at the console so that the settings take effect:
tell http refresh

For detailed information about using WebDAV, see the book Application Development with Domino Designer.

The browser.cnf file

The browser.cnf file is installed automatically in the server data directory when you install Domino. It
contains configuration settings for browsers used to render Domino Web applications. Specifically, this
file is used by @BrowserInfo to determine browser properties.

There are two types of directives in this file: Property and Rule. The property directive defines a browser
property that can be accessed by @BrowserInfo. The Rule directive specifies a regular expression pattern
which is used to match the browser User-Agent header.

Typically, Web application developers will make use of this file to ensure that their applications work
properly on the Domino Web server. However, because of the file’s location in the server data directory, it
is likely that you, as the Domino administrator, will need to make any necessary modifications.

Chapter 36. Setting Up the Domino Web Server 913

For more information on @BrowserInfo, see Application Development with Lotus Domino Designer 7.

Hosting Web sites

You can use Web Site documents to host Web sites on Domino. The Web Site document is one type of
Internet Site.

Web Site documents contain Web site configuration information and are managed through the
Servers\Internet Sites view along with other types of Internet site documents. However, for backward
compatibility the Domino 7 HTTP task still supports the R5 Servers\Web Configurations view. If you are
migrating your site from Domino 5 to a later release you do not need to immediately convert from the
old view to the new view. However, you will need to convert to the Internet Sites view to take advantage
of many of the Web Site features.

Many of the HTTP task Server record settings used in Domino 5 are now available in the Web Site
document. If you enable the new Internet Sites view, the HTTP task uses the Web Site settings instead of
those in the Server record.

To enable the Internet Sites view, in the Basics section of the Server document, click ″Loads Internet
configurations from Server\Internet Sites documents.″

For more information, see the topic ″Converting from Web Server Configuration to Internet Sites view″
later in this chapter.

Hosting Web sites with Web Site documents

Web sites are not explicitly associated with physical servers. A single Domino domain can support many
Web sites. Each Web site can be associated with any number of host names or addresses. All servers in
the same Domino domain can use the same Web Site documents in the Internet Sites view. You can
specify which Domino servers support a Web site. Each Web site has its own security, file-protection, and
URL rules, and you can modify them as needed.

By default, Web Site documents are not associated with specific Domino servers. All servers that share
the same Domino Directory -- that is, reside in the same Domino domain -- automatically use the same
Web Site documents in the Internet Sites view. This means that you do not have to re-create the same
Web configuration each time you add a new server to the domain. When you add or modify a Web Site
document, the changes are picked up automatically by all servers in the domain.

An optional field in the Web Site document allows you to specify the Domino servers that will host a
site. Servers that are not listed in this field will not load the site configuration.

To set up a Web Site

To set up a Web site on a Domino server, you must complete these procedures.
1. Enable the Internet Sites view.
2. Create a Web Site document.
a. Configure default mapping rules.
b. Configure DSAPI Filters and Allowed Methods.
c. Configure Domino Web Engine settings for the Web site.
3. (Optional) Create rules (directory, substitution, redirection) for the Web site.
4. (Optional) Create file protection.
5. (Optional) Create an authentication realm document.

914 Lotus Domino Administrator 7 Help

Hosting Web sites using Web Server Configurations
Lotus Domino 5 uses the model of multiple virtual servers that are associated with a single Domino Web
server. Each site is configured with its own IP address; default home page; customized Web server
message; and HTML, CGI, and icons directories. All of the virtual servers share a single Domino data
directory.

You set up each virtual server with a network connection with its own separate, permanent numeric IP
address or map multiple host names to the same IP address. The number of virtual servers is dependent
only on your operating system and the system hardware. See your operating system documentation and
hardware documentation for more information.

Converting from Web Server Configurations to Internet Sites view

You can convert Web sites that you created in Domino 5 to Lotus Domino 7. Documents in the Web
Configurations view correspond to documents in the Internet Sites view:

Release 5 Lotus Domino 6 and later

Server document Web Site document
Note: The Server document is still used for
some low-level HTTP task configuration
settings
Virtual server Web Site document
Web SSO Configuration document Web SSO Configuration Document
URL Mapping/Redirection document Rule
File Protection document File Protection
Realm Authentication Realm

If you are using virtual servers or hosts, create one Web Site document for each virtual site. If you
provided a default site in the Release 5 server record, you must either make one of the Web Site
documents the default site, or create a document for the default site.

To convert from the Web Server Configurations view to the Internet Sites view: If you do not have
virtual servers or hosts, follow these steps to convert to the new view:
1. Create a Web Site document.
2. Select the Web Site document and choose Edit Document.
3. Click Web Site and create the corresponding documents in Lotus Domino 7: Web SSO Configuration,
Rule (URL Mapping/Redirection), File Protection (File Protection), or Authentication Realm (Realm).
4. Open the Server document.
5. Click Basics and check Enabled for ″Loads Internet configurations from Server\Internet Sites
documents.″
6. Save the document, and restart the HTTP server task to use the new view.

Note: If you have created Web SSO Configuration documents in the Web Server Configurations view,
these need to be disabled before you can enable the Internet Sites view. Otherwise, this generates an error
message. You have the option of disabling them yourself, on the Internet Protocols - Domino Web Engine
tab of the Server document, or allowing Domino to do it for you. You will be prompted about this if you
try to enable Internet Sites when you have existing Web SSO configuration documents.

Hosting multiple Web sites on a partitioned server

You can set up multiple Web sites for each server’s HTTP process on a partitioned server.

To set up multiple Web sites on a partitioned server (for Web Site documents or for Virtual Servers):
1. Set up the partitioned server with separate TCP/IP addresses.

Chapter 36. Setting Up the Domino Web Server 915

2. Assign IP addresses or hosts to each specific HTTP process. In each Server document, click Internet
Protocols - HTTP. In the host name field, under ″Basics,″ include the host name or DNS name for each
Web server, separated by semicolons. (If you separate them with commas, it will be saved with
semicolons.)
3. Set up the Web sites, using either Web Site documents or virtual server documents, to further define
the HTTP configuration.
4. Restart HTTP. You should now be able to send HTTP requests to the partitioned servers and all of the
Web sites or virtual servers for each partition.

Configuring HTML, CGI, icon, and Java files for Web Site documents
Domino looks for individual HTML, CGI, and icon files in specific directories on the server’s hard drive.
You can change the URL path for icons and CGI program files. The URL path is where Domino looks for
icons or CGI programs when it encounters a reference in the HTML code to one of these.

Specifying icon and CGI URL paths is useful if you change the directory location of icons or CGI
programs and you do not want to modify HTML code that references the previous location of these files.

You need to add an extension to the file name for any files stored in the server CGI directory in order to
be able to execute them. For example, .exe must be added to the file names for executable files, .pl must
be added to the file names for Perl programs, and so on.
1. From the Domino Administrator, choose Configuration - Web - Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.
3. Click Configuration. Under ″Default Mapping Rules,″ complete these fields:

Field Action
Home URL Enter the URL command to perform when users access the Web site without specifying a
resource -- for example, the user just requests ″http://www.acme.com.″ Usually the home
URL points to the Web site’s home page -- for example, ″/welcome.nsf/hello?OpenPage.″
HTML directory Specify the directory that will be used to find HTML files if a URL does not specify a path
-- for example, http://www.acme.com/welcome.html. Default is domino\html. The path
can be relative to the Domino data directory, such as domino\myhtml, or it can be fully
qualified, such as c:\websites\html.

Service providers: This directory is relative to the main Domino data directory, not to the
hosted organization’s data directory.
Icon directory Enter the directory where icon files are located. You can specify the path for the icon
directory using either the fully qualified path or a relative path. Default is domino\icons.

Service providers: This directory is relative to the main Domino data directory, not to the
hosted organization’s data directory.
Icon URL path Enter the URL path that is used to map to the icon directory. The default is /icons.

For example, the URL http://servername/icons/abook.gif returns the file

c:\lotus\domino\data\domino\icons\abook.gif.
CGI directory Enter the default directory where CGI programs are located. The default is
domino\cgi-bin.

Service providers: This directory is relative to the main Domino data directory, not to the
hosted organization’s data directory.
CGI URL path Enter the URL path that is used to map to the default CGI directory. The default is cgi-bin.

For example, the URL http://servername/cgi-bin/test.pl runs the CGI program

c:\lotus\domino\data\domino\cgi-bin\test.pl.
Java applet directory Enter the directory where the Domino Java applets are located. The default is
domino\java.

916 Lotus Domino Administrator 7 Help

Field Action
Java URL path Enter the URL path that is used to access files in the default Java directory. The default is
/domjava.

Note: If you are using the Web Server Configuration view, open the Server document, choose Internet
Protocols - HTTP, and complete the fields in the ″Mapping″ section.

Configuring DSAPI, HTTP methods, and WebDAV in Web Site documents

You can set up a Web Site document to support the Domino Web Server Application Programming
Interface (DSAPI), various HTTP methods, and Web-based Distributed Authoring and Versioning
(WebDAV).

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
authentication for Web users. For more information about DSAPI and filters, see the C API User’s Guide
and the C API Reference Guide.

WebDAV is a set of extensions to the HTTP 1.1 protocol which allows users to collaboratively edit and
manage files on remote Web servers. WebDAV clients can only access design elements in the design
collection of a database. Users must have Notes manager or designer level access rights to the database.
Application developers are the typical uses of WebDAV.

For more information, see the topic ″Setting up WebDAV″ later in this chapter.

For more information about WebDAV, see the book Application Development with Domino Designer.

Note: If you are using the Web Server Configurations view, the DSAPI fields appear in the Server
document on the Internet Protocols - HTTP tab.
1. From the Domino Administrator, click the Configuration tab, expand the Web section and click
Internet Sites.
2. Choose the Web Site you want to edit, and click Edit Document.
3. Click the Configuration tab and complete these fields:

Field Action
DSAPI filter file names Enter the name of one or more DSAPI filter files.

Service providers: Each DSAPI filter applies to the entire server; therefore,
if the services must be different for individual hosted organizations, the
DSAPI filter itself must be coded to handle those differences for each
individual hosted organization.
Methods Choose one or more:
v GET (default)
v HEAD (default)
v POST (default)
v OPTIONS (default)
v TRACE (default)
v PUT
v DELETE
WebDAV Choose this option to enable Web-based Distributed Authoring and
Versioning.
Note: If you enable WebDAV, the following HTTP methods are also
enabled: GET, HEAD, OPTIONS, PUT, and DELETE.

Chapter 36. Setting Up the Domino Web Server 917

Domino Web Engine settings for Web Site documents
Use the Domino Web Engine tab to do the following:
v Set up session authentication.
v Specify GIF or JPEG conversion.
v Specify the number of lines to display in a view.
v Limit the number of documents displayed when searching.
v Find links with the Redirect URL command.
v Restrict the amount of data that users can send to a Domino database.
v Store Web user preferences in cookies.
v Set up language preferences.
v Specify an international character set when retrieving pages.

Note: If you are using the Web Server Configurations view, use the Server document.

Setting up session authentication for Web Site documents

You can enable session-based name-and-password authentication for a Web site document. Web clients
must use a browser that supports cookies. You can customize an HTML login form for users to enter
their credentials, address multiple login prompts, allow logout using the ?logout URL or formula, and log
user sessions.
1. From the Domino Administrator, click the Configuration tab, expand the Web section, and click
Internet Sites.
2. Choose the Web Site document you want to edit, and click Edit Document.
3. Click the Domino Web Engine tab. Under HTTP Sessions, in the Session authentication field, do one
of the following:
v Choose Multiple Servers (SSO) to allow a Web user to log on once to a Domino server, then access
any other Domino server in the same domain without logging on again. Under Web SSO
configuration, enter the name of the Web SSO configuration document.
v Choose Single Server to use cookies for a single server only. This option applies only when users
access this Web site. Under Idle session timeout, enter the time (in minutes) when the cookie will
expire and the session will be deactivated. Default is 30 minutes.
v Choose Disabled (default) to prevent cookies from being used by the Domino server for
authentication.
4. In the Maximum active sessions field, enter the maximum number of active, concurrent user sessions
on the server. Default is 1000.
5. Save the document.
For more information about session authentication and single sign-on, see the chapter ″Setting Up
Name-and-Password and Anonymous Access to Domino Servers.″

Specifying GIF or JPEG conversion in Web Site documents

You can control the format and method Domino uses to display images that appear in documents. The
Domino Web server supports both GIF and JPEG image formats. This setting has no effect on images
referenced using passthru HTML.

When you enable progressive or interlaced rendering, the image appears to download quickly and you
can typically identify the image before it is completely downloaded.

To specify GIF or JPEG conversion in a Web Site document:

1. From the Domino Administrator, click the Configuration tab, expand the Web section, and click
Internet Sites.
2. Choose the Web Site document you want to edit, and click Edit Document.
3. Click the Domino Web Engine tab. Under Conversion/Display, complete these fields:

918 Lotus Domino Administrator 7 Help

To specify GIF conversion:

Field
Image conversion format
Interlaced rendering
Enter
GIF (default) -- To convert images in documents to GIF format.
Choose one:
v Enabled (default) -- To display each line of the image individually.
v Disabled -- To wait for the entire image to download before displaying the
image.

To specify JPEG conversion:

Field
Image conversion format
Progressive rendering
JPEG image quality
Enter
JPEG -- To convert images in documents to JPEG format.
Choose one:
v Enabled (default) -- To display the image incrementally in several passes.
v Disabled -- To wait for the entire image to download before displaying the image.
A percentage between 5 and 100 to indicate the level of image quality. The larger the
value, the larger the file, the longer the files take to transmit, and the better the image
quality.

The default is 75.

Note: If you are using the Web Server Configuration view, open the Server document and click the
Internet Protocols - Domino Web Engine tab.

Specifying the number of lines to display in a view

You can specify the default number of lines to display in a view when users do not specify a line count
in a URL. The number of lines to display depends on your preference. Displaying many lines per view
makes it easy to find an item in a large view. Displaying fewer lines per view make it easy to read the
items in the view.

You can also specify the maximum number of lines to display in a view when the user specifies a line
count in a URL.

Entering a maximum number of lines prevents users from overloading server resources by requesting a
large number of lines to display.

To specify the number of lines to display in a view:

1. From the Domino Administrator, click the Configuration tab, expand the Web section and click
Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.
3. Click the Domino Web Engine tab. Under ″Conversion/Display″ complete these fields:

Field Enter
Default lines per view page A number from 1 to the number specified in the ″Maximum lines per view
page″ field. Default is 30.
Maximum lines per view page A number that is limited only by the browser software. Default is 1000.

Enter 0 if you do not want to limit the number of lines in a view.

Chapter 36. Setting Up the Domino Web Server 919

Note: If you are using the Web Server Configuration view, open the Server document and click the
Internet Protocols - Domino Web Engine tab.

Limiting the number of documents displayed during a Web Site search

You can specify a default and maximum number of documents to display as a result of performing a
search on a database. Users can specify the number of documents for a search query to return using the
SearchMax parameter with the SearchSite and SearchView commands.

Note: If you are using the Web Server Configuration view, open the Server document and click the
Internet Protocols - Domino Web Engine tab.

Change these options to prevent users from overloading server resources with search results.

To limit the number of documents displayed during a Web Site search:

1. From the Domino Administrator, click the Configuration tab, expand the Web section, and click
Internet Sites.
2. Choose a Web Site document you want to edit, and click Edit Document.
3. Click the Domino Web Engine tab. Under Conversion/Display, complete these fields:

Field Action
Default search result limit Enter the maximum number of documents to display when users do not specify the
SearchMax parameter in the URL.

If you set the value to 0, the number of documents displayed is the same value as
that specified in ″Maximum search result limit.″

The default is 250.

Maximum search result limit Enter the maximum number of documents that a user can specify for the
SearchMax parameter in a URL.

Enter 0 if you do not want to limit the number of documents displayed. The
default is 1000.

Finding links with the Redirect URL command

You use the Redirect URL command to create anchor, document, view, and database links on a Web page.
These links and the links for domain search results can direct users to a database on the same server or
another server. Enable this option on any server that runs the domain search and on servers for which
you want to resolve links to other servers.

To find links with the Redirect URL command:

1. From the Domino Administrator, click the Configuration tab, expand the Web section, and click
Internet Sites.
2. Choose the Web Site document you want to edit, and click Edit Document.
3. Click Domino Web Engine. Under Conversion/Display, complete this field:

920 Lotus Domino Administrator 7 Help

 For information on the Redirect URL command, see Application Development with Domino Designer.

Field Enter
Redirect to resolve external Choose one:
links v Disabled (default) -- To prevent the server from accepting Redirect URL
commands and to prevent the server from generating Redirect URL commands as
a result of a domain search.
v By Server -- To look up the server name specified in the URL in the Domino
Directory on the Web server. The Web server searches for the server name in both
the Host names field on the Internet Protocols - HTTP tab or in the Fully qualified
Internet host name field on the Basics tab.
v By Database -- To find the database in the Domino Directory on any available
server. Domino locates the database in the domain catalog, if available, or in the
server’s local catalog. Make sure the domain catalog contains up-to-date
information on the location of databases. By choosing this option, resolving links
take more time than the By Server option since the Web server searches for the
database on an available server, instead of just the server presented in the URL.
The By Database option however, may resolve more links since the Web server
tries to resolve the link using a replica of the database on servers in addition to
the server presented in the URL. Use this option on the server that runs the
domain search so more links are resolved for the user.

Since By Server and By Database both rely on the information in the Domino
Directory, make sure the server information in the Domino Directory is complete and
correct.

Note: If you are using the Web Server Configuration view, open the Server document and click the
Internet Protocols - Domino Web Engine tab.

Restricting the amount of data users can send to a Domino database

The HTTP POST and PUT methods allow users to send data to the Domino server. The Server record
field ″Maximum size of request content″ sets a limit on the amount of data that can be sent using either
POST or PUT. This limit is enforced for all POST and PUT methods, whether the target is a database, CGI
program, or Java servlet, and applies to all Web sites.

The Web Site document contains two additional settings that control POST and PUT methods that target
a database (for example, filling in a form or uploading a file attachment). These settings reside in the Web
Site document so that you can specify different values for each Web site.

To restrict the amount of data that can be sent to a Domino database:

1. From the Domino Administrator, click the Configuration tab, expand the Web section and click
Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.
3. Click the Domino Web Engine tab. Under ″POST Data″ complete these fields:

Field Action
Maximum POST data Enter the amount of data in KB that a user is allowed to
send to the Web site in a POST request that targets a
database. The default is 0, which does not restrict the
amount of data that users can send (however, the
amount is still limited by the Server record setting
″Maximum request content″). This limit applies to both
the PUT and the POST HTTP methods.

If users try to send more than the maximum allowed

data, Domino returns an error message to the browser.

Chapter 36. Setting Up the Domino Web Server 921

Field Action
File compression on upload Choose one:
v Enabled -- To compress files before adding them to a
database. Compressing files saves disk space on the
server.
v Disabled (default) -- If clients use a browser that
supports byte-range serving. You cannot download
compressed files using Domino byte-range serving.

For more information on byte-range serving, see the topic ″Improving file-download performance for
Web clients″ earlier in this chapter.

Note: If you are using the Web Server Configuration view, open the Server document and choose the
Internet Protocols - Domino Web Engine tab.

Specifying the character set to use when retrieving Web pages

Domino uses the default character set and character set mapping selection to generate HTML text for the
browser. If you have international users who need to see text in nonwestern languages, you’ll need to
make changes to the settings. The character set setting affects all databases on the server.

To specify an international character set:

1. From the Domino Administrator, click the Configuration tab, expand the Web section and click
Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.
3. Click the Domino Web Engine tab. Under ″Character Set Mapping″ complete these fields:

Field
Default character set group
Convert resource strings to
Use UTF-8 for output
Use auto-detection if database has
no language information
Enter
A character set group to allow users to choose their preferred character set
when they create or edit documents. The default is Western.
A language to use for messages, HTML for default search pages, and static
strings in pages. You can choose a language other than English only for
international versions of the Domino server that have translated text. The
default is English.
Choose one:
v Yes -- To generate pages using UTF-8.
v No (default) -- To generate pages using the character set mapping you
select.
Choose one:
v Yes -- To detect automatically the language to use for the database if no
default language is selected on the Design tab of the Database Properties
box.
v No (default) -- Tto use the language specified by the Use UTF-8 for output
field.

Character set in header
If the language is specified for a database on the Design tab of the Database
Properties box, Domino uses that language for text in the database.
Choose one:
v Yes (default) -- To add the character set to the ″Content-Type″ HTTP header
of an HTML page. If you select Yes, then the browser finds the character
set before rendering the page.
v No -- To exclude the characters from the HTTP header of an HTML page.
Use this option if you use early versions of browsers that do not
understand the character set tag in the HTTP header.

922 Lotus Domino Administrator 7 Help

Field Enter
Meta character set Choose one:
v Yes -- To add the character set to the <META> tag of an HTML page. This
option lets you save the character set information when you save an HTML
file on a server or on your hard disk.
v No (default) -- To exclude the character set from the <META> tag of an
HTML page.

4. In the fields that display the character set group names, select one of the available choices for
character set mapping.
5. Save the document.

Storing Web user preferences in cookies

Web users can configure their own time zone and regional preferences. Customized preferences are stored
in cookies that reside in Web client browsers. Thus, your preferences can’t be used if you access the
server from a browser other than the one for which you set up cookies.
1. From the Domino Administrator, choose Configuration - Web - Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.
3. Click Domino Web Engine. Under ″Web User Preferences,″ complete these fields:

Field
Store user preferences in cookies
Default regional locale
Action
Choose one:
v Disabled -- Users cannot customize their regional preferences
v Single Server -- Cookies for customized preferences are generated for
current Web site/server only
v Multi-server -- Cookies for customized preferences are generated for the
DNS domain to which the current Web site/server belongs
Use this field for those cases in which a user does not have any custom
regional settings enabled for their browser, and the format option for
regional setting fields is set to ″user’s setting.″ This information is needed
for formatting date, time, number, and currency fields.
v Server locale -- Use server’s operating system settings.
v Browser’s accept-language (default) -- Use browser’s accept-language.
By default, both Internet Explorer and Netscape send HTTP requests
with the accept-language header in the user’s preferred language(s).

Note: If you are using Server document settings and the Web Server Configurations view, you can enable
these settings in the Server document in Internet Protocols - Domino Web Engine, under ″Web user
preferences.″

Setting up language preferences

The Web server uses language string resource modules to render Web pages in different languages. The
Domino 7 Web server can support multiple languages and be configured to handle them on the fly. The
language in which a Web server generates a Web page is based on the ″Accept-Language″ setting in the
headers of client HTTP requests. For example, a Web server with English and French resource modules
will generate a Web page in French if a Web client sends an HTTP request with ″Accept-Langage:fr
(French)″ in its headers.
1. From the Domino Administrator, choose Configuration - Web - Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.

Chapter 36. Setting Up the Domino Web Server 923

3. Click Domino Web Engine. Under ″Web User Preferences,″ complete these fields:

Field
Default string resource language
Additional string resource languages
Action
Use this setting to select the default language string resource module
for Web clients who do not send ″accept-language″ information with
HTTP requests, or for cases in which the languages specified in the
″accept-language″ header are not in the languages available on the
server.
Use this setting to select the additional string resource languages that
are installed on the server.

Note: If you are using Server document settings and the Web Server Configurations view, you can enable
these settings in the Server document in Internet Protocols - Domino Web Engine, under ″Language.″

Table of character sets for Web server pages

The default character set governs the available choices for character set mapping. If a character set group
has mapping choices, you must also select which character set to use.

Character set group Mapping choices

Western US-ASCII

This set includes Windows and ANSI ISO-8859-1 (default)

characters.
ISO-8859-15

Windows-1252
Central European ISO-8859-2

Windows 1250 (default)

Japanese SJIS (default)

JIS(ISO-2022-JP)

EUC-JP
Traditional Chinese Big5 (default)

EUC-TW
Simplified Chinese GB
Korean KSC5601(EUC)
Cyrillic ISO-8859-5

Windows-1251

KOI8-R (default)
Greek ISO-8859-7

Windows-1253 (default)
Turkish ISO-8859-9

Windows-1254 (default)
Thai Windows-874
Baltic Windows-1257
Arabic Windows-1256 (default)

ISO-8859-6

924 Lotus Domino Administrator 7 Help

Character set group Mapping choices
Hebrew ISO-8859-8 (default)

Windows-1255
Vietnamese Windows-1258

Web Site rules and global Web settings

Web Site rules are documents that help you maintain the organization of a Web site. They have two main
uses:
v Enable the administrator to create a consistent and user-friendly navigation scheme for a Web site,
which is independent of the site’s actual physical organization.
v Allow parts of the site to be relocated or reorganized without breaking existing links or browser
bookmarks.

Web Site rules are created as response documents to Web Site documents, and apply only to that
particular Web Site document. If you want to apply a rule to more than one Web Site document, copy
and paste the rule document from one Web Site document to the other.

Before Web Site rules can be applied to an incoming URL, the URL is normalized according to a
predefined set of filtering and validation rules and procedures. These procedures reduce the URL to a
safe form before it is passed to an application for processing. Once the URL is normalized, the HTTP task
uses the rules defined for the Web Site to determine if the URL is to be modified in any way.

Note: Only the URL path is used for pattern matching. The query string is saved for use by the
application. Any patterns you specify for a rule’s Incoming URL pattern field should not include a host
name or query string.

There are four types of Web Site rules. If more than one type of Web Site rule has been created for a Web
Site document, the rules documents are evaluated in this order:
v Substitution
v Redirection
v Directory
v HTTP response header

Substitution rules: A substitution rule replaces one or more parts of the incoming URL with new
strings. Substitution rules should be used when you want to reorganize your Web site, and you don’t
want to have to rewrite all the links in the site, or when you want to provide user-friendly aliases for
complex URLs.

For example, a substitution rule would be useful if you moved a number of files on your Web site from
one directory to another. Instead of fixing all the links that refer to the old directory, your substitution
rule would map the old directory to the new directory.

The incoming and replacement patterns in substitution rules must each specify at least one wildcard. If
you do not explicitly include a wildcard somewhere in a pattern, the HTTP task automatically appends
″/*″ to the pattern when it stores the rule in its internal table.

Redirection rules: Redirection rules redirect incoming URLs to other URLs. There are two types of
redirection rules: external redirection and internal redirection. An external redirection rule causes the
server to inform the browser that a file or other resource requested by the browser is located at another
URL. If the incoming URL path matches an external redirection rule, the HTTP task generates a new URL

Chapter 36. Setting Up the Domino Web Server 925

based on the redirection pattern and immediately returns that URL to the browser. Using external
redirection rules allows existing links and bookmarks to keep working, but insures that new bookmarks
point to the new location.

An internal redirection rule acts like a substitution rule, as the HTTP task generates a new URL and then
re-normalizes it. There are two differences, however. First, the redirection table is searched recursively, so
you can create and nest multiple redirection rules. Second, an internal redirection rule does not require
the use of a wildcard character. Thus, you can choose to use an internal redirection rule instead of a
substitution rule if you want to force an exact match on the URL path.

If the incoming URL path matches an internal redirection rule, the HTTP task generates a new path,
normalizes the path, and searches the redirection rule table again. Because the HTTP task does a
recursive search through the redirection rule table, you can write broad redirection rules that capture
URLs no matter what substitution or redirection has been applied.

Note: Having a recursive search means that there is the potential for getting into an infinite loop if you
write redirection rules that match each other. To eliminate this possibility, the HTTP task has a built-in
recursion limit of ten.

Wildcards are allowed in redirection rules, but are not required.

Directory rules: A directory rule maps a file-system directory to a URL pattern. When the Web server
receives a URL that matches the pattern, the server assumes that the URL is requesting a resource from
that directory.

When you install a Domino 7 Web server, several file-resource directories are created automatically. These
default directories are mapped by directory rules that are defined on the Configuration tab of the Web
Site document. When the Web server starts up, it automatically creates internal rules to map these
directories to URL patterns. The three default directories are:
v HTML directory for non-graphic files
v Icon directory for graphic images such as .GIFs
v CGI directory for CGI programs

Directory rules can only be used to map the location of files that are to be read directly (such as HTML
files and graphic files) and executable programs to be loaded and run by the operating system (such as
CGI programs). Directory rules cannot be used to map the location of other types of resources, such as
Domino databases or Java servlets.

When you create a Directory Web Site rule, you specify read or execute access to a file-system directory. It
is critically important to choose the right access. Only directories that contain CGI programs should be
enabled for Execute access. All other directories should have Read access. If you specify the wrong access
level, unexpected results will occur. For example, if you mark a CGI directory for Read access, when a
browser user sends a URL for a CGI program, the server will return the source code of the program
instead of executing it, which could be a serious security breach.

Directory rules cannot override file-access permissions enforced by the operating system.

Note: Access level is inherited by all subdirectories under the specified directory.

HTTP response header rules: Every HTTP browser request and server response begins with a set of
headers that describe the data that is being transmitted. An HTTP response header rule allows an
application designer to customize the headers that Domino sends -- such as an Expires header or custom
headers to HTTP responses -- with responses to requests that match the specified URL pattern.

926 Lotus Domino Administrator 7 Help

The most important use of response rules is to improve the performance of browser caching. An
application designer can add headers that provide the browser with important information about the
volatility of the material being cached.

The caching headers include the Last-Modified header, Expires header, and Cache-Control header. The
Last-Modified header indicates when the resource or resources used to generate a response were last
changed. The Expires header tells the browser when resources are expected to change. A designer can
define a rule to add Expires headers to responses based on when the designer expects resources to
change. The Cache-Control header provides explicit instructions to browser and proxy server caches, such
as ″no-cache″ for responses that should not be cached, or ″private″ for responses that are cacheable but
are specific to a particular browser configuration.

You can also use response rules to customize headers. For example, you can create response rules for
custom headers that display specific error messages -- for example, when a user is not authorized to
access an application.

Unlike other Web site rules, response rules are applied to the outgoing response, just before the HTTP
task transmits the response to the browser. For response header rules, the pattern is matched against the
final form of a URL, after substitution and redirection rules have been applied to it. For example, if you
have a substitution rule that transforms /help/* to /support.nsf/helpview/* and you want to create a
response rule to match the response, the pattern for the response rule should be
/support.nsf/helpview/*.

The pattern can include one or more asterisks as wildcard characters. For example, the pattern
/*/catalog/*.htm will match the URLs /petstore/catalog/food.htm, /clothing/catalog/thumbnails.htm,
and so on. A wildcard is not required in a response rule. This allows you to create a rule that matches a
specific resource, for example, /cgi-bin/account.pl. Also, as with all rules, the incoming pattern cannot
contain a query string.

Response header rules are different from other rules in that not only do they have to match a URL
pattern, they also have to match the HTTP response status code. You need to specify one or more status
codes in the HTTP response codes field.

Global Web Settings: Global Web Settings enable you to apply Web rules to multiple Web sites. You
define a name for the Global Web settings document, and specify the servers to which the Global Web
settings apply. You then create Web Rules documents for a Global Web Settings document. The Web rules
then apply to all Web sites hosted by the servers specified in the Global Web settings document.

Global Web Settings document and associated Web Site rule documents are not automatically created. If
you want to use the Global Web Settings document and Web Site rules in your Web environment, you
need to manually create them.

Creating a Web Site Rule document: You can keep database files, HTML files, CGI scripts, and other
related Web files in multiple locations or move them to new locations without breaking URL links or
changing documents. Domino displays the Rules document as a response to the Web Site document on
the Configuration tab in the Web - Internet Sites view.

Redirecting a URL displays the page in the new location and displays the URL in the location box for the
user. Mapping a URL or directory displays the page in the new location and hides that new location from
the user.

To create a Web Site Rule document:

1. From the Domino Administrator, click the Configuration tab, expand the Web section and click
Internet Sites.
2. Choose the Web Site document you want to edit and click Edit Document.

Chapter 36. Setting Up the Domino Web Server 927

3. Click the Web Site button and choose Create Rule.
4. Click the Basics tab and complete the following fields:

Field Action
Description Enter a name that differentiates this rule from others you create.
Type of Rule Choose one:
v Directory -- To allow a server file-system directory to be accessed by a URL
path.
v Redirection -- Resource identified by the URL has been moved to a different
location or Web site.
v Substitution -- To replace a string in the URL with another string.
v HTTP response header -- To add an Expire header or custom headers to
HTTP responses that match specified URL patterns and response codes.
Incoming URL pattern Pattern that describes the URLs affected by this rule.

Redirect to this URL
If you are defining many rules, specify the longest unique pattern for each
rule. Do not include http or the host name in the pattern.
(Redirection only) Enter the new URL location. If the URL pattern in this field
starts with a slash, the rule is treated as internal redirection. Otherwise, the
rule is assumed to be external redirection.

Replacement pattern
Target server directory
The pattern for an external redirection needs to start with an Internet protocol
string that the browser understands, such as http: or ftp.
(Substitution only) Enter the string that replaces the matching part of the
incoming URL.
(Directory only) Enter the file-system directory path being mapped. This can
be specified as a fully-qualified path or a path relative to the data directory. If
you want to map a directory that isn’t under the Domino data directory,
specify the fully qualified path.

Service providers: Use the organization’s data directory.

Access level (Directory only) Choose one:
v Read access -- To allow browser users to read files from the directory are
displayed in the browser or downloaded. When a user requests a file from
the directory, the server sends the contents of the file back to the browser.
v Execute access -- To allow browser users to load and run CGI programs in
the directory. The server relays the output from the program to the browser.
HTTP response codes (HTTP Response Header only) Enter the HTTP response codes to which you
want your response headers applied.
Expires header (HTTP Response Header only) Choose one:
v Don’t add header -- Files in the directory are displayed in the browser or
downloaded.
v Add header only if application did not -- Files in the directory are CGI files
to be executed on the server.
v Always add header (override application’s header)
Note: If you choose to add a header, you must specify an expiration period --
either by specifying the number of days for which you want to enable this
header, or a date after which you want to disable this header.

928 Lotus Domino Administrator 7 Help

Field Action
Custom header (HTTP Response Header only) For each custom header you want to use,
specify:
v Name -- The name of the response header.
v Value -- The value of the response header.
v Override -- Override application’s header.

5. Save the document.

Note: If you are using Server document settings and the Web Server Configurations view, you can enable
these settings in the Server document. Open the Server document and click Create Web (R5) and select
″URL Mapping/Redirection.″

Configuring a Web Site rule to run PHP: PHP (from ″Personal Home Page Tools″) is a script language
and interpreter. The PHP script is embedded within a Web page along with its HTML. To enable a Web
Site document to use PHP, you need to create a directory rule for that site document to point to the PHP
executable files.

Note: The default directory for PHP scripts is defined by the DOCUMENT_ROOT CGI variable, and is
the /<notes root directory>/data/domino/html. PHP looks for scripts relative to this directory.

To configure a Web Site rule for PHP:

1. Install PHP on the Web server. Make sure that the PHP.EXE file can find the PHP.INI file. Be sure that
all paths are set up correctly for PHP. See the PHP installation documentation for more information.
2. Create a directory rule to run PHP scripts. Use the following settings:

Field Action
Description Enter a name that differentiates this rule from others you create.
Type of Rule Select Directory
Incoming URL pattern Enter :/php-bin

An example of an incoming URL would be: http://<server>/php-

bin/PHP.EXE/<php-scripts>
Target server directory Enter the location of the PHP binary file (for example, c:\PHP)
Access level Click Execute.

Creating a Global Web Settings document: The settings you enable in the Global Web Settings
document apply to all Web Site documents that you have set up on this server. After you have created
the Global Web Settings document, you can create rules for this document. These rules will apply to all of
the servers that are specified in the Global Web Settings document.

To create a Global Web Settings document:

1. From the Domino Administrator, click the Configuration tab, expand the Web section and click
Internet Sites.
2. Click Create Global Web Settings.
3. Click the Basics tab and complete the following fields:

Field Action
Descriptive name for this site Enter a name for this Web site.
Domino servers that host this site List all the servers in the domain that will host this Web
site

Chapter 36. Setting Up the Domino Web Server 929

Protecting files on a server from Web client access
File protection documents control access to non-database files that users can access via Web browsers.
Like database file (.NSF) access control lists (ACLs), which specify the names of the users who can access
them and the level of access they have, you can enforce file protection for files that browser users can
access -- for example, HTML, JPEG, and GIF -- also by specifying the level of access for these types of
files and the names of the users who can access them.

While you can also apply file protection to CGI scripts, file protection does not extend to other files
accessed by those scripts. For example, you can apply file protection to a CGI script that restricts access
to a group named ″Web Admins.″ However, if the CGI script runs and opens other files, or triggers other
scripts to run, the File Protection document cannot control whether ″Web Admins″ has access to these
additional files.

Do not create file protection documents that restrict access to the following directories, which contain
default image files and Java applets that are used by the Domino Web server and other applications, such
as mail databases:
v Domino\data\domino\java, accessed via Web browser using the path http://server/domjava
v Domino\data\domino\icons, accessed via Web browser using the path http://server/icons

File protection does apply, however, to files that access other files -- for example, HTML files that open
image files. If a user has access to the HTML file but does not have access to the JPEG file that the HTML
file uses, Domino does not display the JPEG file when the user opens the HTML file.

You can create a File Protection document for a directory or for an individual file. Protection defined for
a directory is inherited by all of its subdirectories. You must set up File Protection documents for all
directories accessible to Web users. Files and file directories that do not have File Protection documents
can be accessed by anyone using a Web browser.

Note: You do not need to use a file protection document to protect a database (.NSF) file; instead, you
use a database ACL.

Examples of controlling Web browser access to server files: Specifying these settings in fields in the
File Protection document allows all users in the Web User Group to open files and start programs in the
c:\notes\data\domino\html directory.

Path: c:\notes\data\domino\html

Access: Web User Group (GET)

Access: - Default - (No Access)

The file ″secret.htm″ resides in the notes\data\domino\html subdirectory. You can deny access to this file
to members of the Web User Group and allow access only to user Joe Smith. To do this, create an
additional File Protection document with the following settings:

Path: c:\notes\data\domino\html\secret.html

Access: - Default - (No Access)

Access: Joe Smith (GET)

Creating file protection for Web Site documents: In Domino 7, you create a file protection document
for a specific Web Site. This file protection documents then only applies to that specific Web Site.

930 Lotus Domino Administrator 7 Help

File protection documents provide limited security. Use Domino security features, such as database ACLs,
to protect sensitive information.

To create file protection for a Web Site document:

1. From the Domino Administrator, choose Configuration - Web - Internet Sites.
2. Open the Web Site document for which you want to create file protection.
3. Click Web Site and choose ″Create File Protection.″
4. Click Basics and complete these fields:

Field
Description
Directory or file path
Current Access Control List
Set/Modify Access Control List
Action
(Optional) Enter a name that differentiates this document from others you
create.
Specify the directory or file path that you want to which you want to restrict
access. It should be either in the fully-qualified path format, which includes
the drive letter -- for example, ″c:\lotus\domino\data\domino\cgi-bin,″ or
enter the path relative to the server’s data directory -- for
example,″domino\cgi-bin.″
Displays the users and groups who can access the file or directory you
specified, and the type of access they are allowed. Similar to a database ACL,
the access control list is always created with a -Default- entry, set to No Access,
which you can modify. As with a database ACL, those not listed in the Access
List receive the default access level.
To add users to the Access Control List, click Set/Modify Access Control List.
Select a user name or group from the Domino Directory or type a name in the
Name field. Select ″Read/Execute access (GET method),″ or
″Write/Read/Execute access (POST and GET methods,″ or ″No Access.″ Click
Add to add the entry to the Access Control List.

GET lets the user open files and start programs in the directory. POST is
typically used to send data to a CGI program; therefore, give POST access only
to directories that contain CGI programs. No Access denies access to the
specified user or group.

To remove an entry from the list, select it and click Clear.

If users connect to the server using Anonymous access, enter Anonymous in

the Name field and assign the appropriate access.
Note: If you wish to enter a user name that resides in an LDAP Directory, you
must replace the comma delimiters with slashes. Do not enter the name with
commas as delimiters.

For example, an LDAP user with the following name format:

cn=Anthony Jones,l=westford,o=airius.com

should be entered into the access list of a File Protection document like this:

cn=Anthony Jones/l=westford/o=airius.com

5. Click Administration and complete the Owners and Administrators fields. By default, the
administrator name you logged in with is the name that is assigned to both fields.
6. Save the document.
7. Enter this command to refresh the settings:
tell http refresh

Creating file protection for virtual servers (Domino 5.0x):

1. Do one of the following:

Chapter 36. Setting Up the Domino Web Server 931

 v From the Domino Administrator, choose Configuration - Servers, and open the Server document for
the server to which the file protection will apply.
v If you are creating a File Protection document for a virtual server, chose Web - Web Server
Configurations, and open the Virtual Server document.
2. Click Create Web (R5) and choose File Protection.
3. Click the Basics tab, and complete these fields:

Field Action
Applies to (Read-only) This setting applies to the base server, and all virtual servers or virtual
hosts that do not have file protection settings. If a virtual server or virtual host has any
file protection settings, then this setting does not apply.
Path Specify the drive, directory, or file to which you want to restrict access. You can use
fully-qualified path or the relative path.

4. Click Access Control, complete this field, and then save the document:

Field Enter
Current access control list The users and groups who can access the files or directories you specified and the type
of access they are allowed. By default, the access control list contains a -Default- entry,
set to No Access. Users who are not listed in this field receive the -Default- access level.

To add users to this list:

1. Click Set/Modify Access Control List.
2. Select a user name or group from the Domino Directory or enter a name in the
Name field.
3. Select ″Read/Execute access (GET method),″ or ″Write/Read/Execute access (POST
and GET methods),″ ″No Access.″
4. Click Next to add this entry to the access list.
Note: GET lets the user open files and start programs in the directory. POST is typically
used to send data to a CGI program; therefore, give POST access only to directories that
contain CGI programs. No Access denies access to the specified user or group.

To remove an entry from the list, select the entry and click Clear.

If users connect to the server using Anonymous access, enter Anonymous in the Name
field and assign the appropriate access.

5. Enter this command at the console to refresh the server settings:

tell http refresh

Domino displays the File Protection document as a response to the Server document.

Creating a Web Site authentication realm document

Using a Domino Web Site authentication realm, you can specify the text string that appears when a user
tries to access a certain directory, or file on a Domino Web server. When the browser prompts the user for
a name and password, the browser’s authentication dialog displays the text string. The browser uses the
realm to determine which credentials -- that is, user name and password -- to send with the URL for
subsequent requests. The Domino Web server caches the user’s credentials to use for different realms, in
order to avoid prompting the user repeatedly for the same credentials.

The realm string also applies to requests mapped to paths that have the specified path as their root,
provided that the child paths of the root do not already have a specified realm. For example, the realm
string specified for D:\NOTES\DATA also applies to a request mapped to D:\NOTES\DATA\FINANCE,
if the latter does not have a realm specification.

932 Lotus Domino Administrator 7 Help

If there is no realm specification for a given path, Domino uses the path from the request as a realm
string.

If you are using Web Site documents, you can create a Web Site Authentication Realm document for a
specific Web Site document. The Authentication Realm document appears as a response document to the
Web Site document in the Internet Sites view.

If you are using the Web Server Configurations view, or a virtual server (Domino 5), you create a Web
realm. The Web Realm document appears as a response to the Server document which can be seen in the
Web Server Configurations view.

To create a Web Site authentication realm document:

1. From the Domino Administrator, choose Configuration - Web - Internet Sites.
2. Choose the Web Site document for which you want to create an authentication realm, and click Edit
Document.
3. Click ″Web Site″ and choose ″Create Authentication Realm.″
4. Click the Basics tab and complete the following fields:

Field Action
Description (Optional) Enter a name that differentiates this document from others you
create.
Directory or file path Enter the name of the path that you want to protect. It should be in either
the fully-qualified path format, which includes the drive letter; for example,
use ″c:\lotus\domino\data\domino\cgi-bin,″ or the relative path to the
server’s data directory for example, ″domino\cgi-bin.″
Realm label returned to browser Enter a text string that describes the location on the server or any other
descriptive string, which will be used as the realm that is displayed to the
user and stored by the browser. This string should not contain any accented
or international characters, because they will not be displayed correctly by
the browser.

The browser displays the text string whenever there is an authentication or

authorization failure at the location. The text appears in the browser’s
authentication dialog.

5. Save and close the document.

6. Enter this command at the console so that the settings take effect:
tell http refresh

To create a Web Realm (pre-Domino 6.0):

1. Do one of the following:
v From the Domino Administrator, click Configuration and click Servers.
v If you are creating a Web Realm document for a virtual server, click Web - Web Server
Configurations.
2. Do one of the following:
v Open the Server document for the server to which the Web realm will apply.
v If you are creating a Web Realm document for a virtual server, open the Virtual Server document.
3. Click ″Create Web (R5)″ and choose Realm.
4. Complete these fields and then save the document:

Field Enter
IP Address (Optional) The IP address of the virtual server. Complete this field only if you are
creating a Web realm for a virtual server.

Chapter 36. Setting Up the Domino Web Server 933

Field Enter
Path Enter the name of the path that you want to protect. It should be in either the
fully-qualified path format, which includes the drive letter; for example, use
″c:\lotus\domino\data\domino\cgi-bin,″ or the relative path to the server’s data
directory for example, ″domino\cgi-bin.″
Realm returned to Enter a text string that describes the location on the server or any other descriptive
browser when access is string, which will be used as the realm that is displayed to the user and stored by the
denied browser. This string should not contain any accented or international characters, because
they will not be displayed correctly by the browser.

The browser displays the text string whenever there is an authentication or

authorization failure at the location. The text appears in the browser’s authentication
dialog.

5. Enter this command at the console so that the settings take effect:
tell http restart

Custom Web server messages

You can customize some of the error messages or responses that are generated by the Web server. If an
″Error & Response″ form-mapping document exists in DOMCFG.NSF, custom errors, not generic errors,
are used.

To create a message page, create a form for each type of message and then create a mapping document in
the Domino Configuration database (DOMCFG.NSF) to specify which form to display. While you can
store message pages in any database, the one most commonly used is DOMCFG.NSF.

You can customize the messages that a user receives when:

v The user fails to authenticate with the server.
v The user is not authorized to access one of the databases that is part of the Web site on the server.
v The user issues a command to delete a document from a database, and the server successfully
completes the deletion.
v The user’s Internet password has expired.
v The user attempts to change their Internet password and that is not allowed.
v The user changes their Internet password and the change is submitted and accepted.

In addition, you can specify a general message that appears for all other types of errors or responses that
occur on the Web server.

Note: The general error message will not be generated for errors that occur when accessing non-database
files. This type of custom error message only works when errors are encountered while accessing .NSF
files.

If you enabled session-based name and password authentication, Domino displays an HTML page you
specify to request name and password information from the user. Domino does not use customized error
pages to display errors when authenticating with the server or accessing a database if session-based name
and password authentication is enabled.

Database designers also have the ability to create custom error messages for individual databases that
reside on Domino servers. These types of custom error messages are stored within the database and will
only be generated when errors occur while accessing that specific database.

For information on customizing messages that a user receives for a specific database on a server, see
Application Development with Domino Designer. For information on session-based name and password

934 Lotus Domino Administrator 7 Help

authentication, see the chapter ″Setting up Name-and-Password and Anonymous Access to Domino
Servers.″ For information on changing Internet passwords, see the chapter ″Protecting and Managing
Notes IDs.″

In this example, the form for the message exists in the database ANYDB.NSF and is returned to the user
when the user encounters an error.

Users must have Reader access to the Domino Configuration (DOMCFG.NSF) database and Any database
(ANYDB.NSF).

You can create custom error pages that apply to the entire server, a specific Web site, or specific
databases. If you have a custom error page configured for a specific database, it overrides the server-wide
Web site specific custom error pages. If you have a Web site specific custom error page configured, it
overrides the server-wide custom error message.

Creating custom Web server messages

Complete these procedures:
1. Create the Domino Configuration database.
2. Customize the Web server messages.

Creating the Domino Configuration database

You use the Domino Configuration database to map custom messages that you create. These messages
can be those that browser users receive when they access a Web application, or they can be custom
HTML pages that you use to authenticate Web users with a name and password.

For information on customizing HTML pages for name-and-password authentication, see the chapter
″Setting Up Name-and-Password and Anonymous Access to Domino Servers.″
1. Make sure the Web server exists.
2. From the Domino Administrator, choose File - Database - New.
3. Under Server, enter the name of the Domino server on which you want to create this database.
4. Select the Domino Web Server Configuration template (DOMCFG5.NTF) from the Advanced
Templates list.
5. Under Title, enter a name for the database.
6. Under File name, enter DOMCFG.NSF.

Note: The database must have this file name.

Chapter 36. Setting Up the Domino Web Server 935

7. Click OK.
8. Add an entry named Anonymous to the database ACL and give the entry Reader access.
9. Map custom Web server messages.

Mapping custom Web server messages

You can change the message users receive when they encounter an error or delete a document while
working with a site on the Web server.
1. Make sure the Domino Configuration database exists.
2. Open the database that will store the customized messages.
You can store custom messages in DOMCFG.NSF or in any database on the server.
3. Using Domino Designer, create a form that contains the message you want to display, and save the
form.
4. Repeat Steps 2 and 3 for each custom message. The forms can exist in the same database or in
separate databases.
5. Select the Error & Response Mappings view and then click Add Mapping.
6. Do one of the following:
v Choose ″All Web Sites/Entire Server″ to customize a message for all Web sites on the server.
v Choose ″Specific Web Site/Virtual Server″ and enter the host name or IP address for the Web site.
The custom messages will then only apply to the specified Web Site or virtual server.
7. (Optional) Enter a comment about the error message or response.
8. For each type of error or response, under ″Target Database,″ enter the name of the database that
contains the form you want to display.
9. For each type of error or response, under ″Target Form,″ enter the name of the form you want to
display.
10. Save the Error Message Response Mapping document.
11. In the ACL for the database that contains the forms, assign Author access to the server that stores the
database.

See "Example of custom Web server messages.""

For information on creating forms and customizing Web server messages for a specific database on a
server, see Application Development with Domino Designer.

Example of custom Web server messages

This Error Message & Response Mapping document uses forms stored in the database named
MESSAGES.NSF on the current server. These forms contain custom messages for authentication and
authorization failures and for responses to document deletions. For all other general error messages,
Domino displays the default message text stored in the Domino Configuration database.

936 Lotus Domino Administrator 7 Help

Improving Web server performance
After you set up the Domino Web server and make sure that it runs properly, check the server’s
performance and response time. To improve server performance and response time, you can do any of
the following:
v Manage the memory cache on the Web server.
v Specify network timeouts on the Web server.
v Specify the number of threads used by the Web server.
v Improve file-download performance for Web clients.
v Specify whether more than one Web application agent can run at one time, as well as the timeout
period for all Web application agents.
v Restrict the amount of data that users can send to the server using the HTTP POST command.
v Set up the Domino Web server in a cluster.
For more information on improving clustered Web server performance, see Administering Domino
Clusters.

Managing the memory cache on the Web server

Mapping information about databases and authenticating users can take time. To optimize response time,
Domino uses a memory cache (command cache) to store this information. The memory cache stores the
information for quick access.

For more information, see the chapter ″Monitoring the Domino System.″ For more information on tuning
the performance of an application, see Application Development with Domino Designer.

To manage memory cache on a Web server:

Chapter 36. Setting Up the Domino Web Server 937

1. Open the Server document you want to edit and click Edit Server.
2. Choose Internet Protocols - Domino Web Engine. Under Memory Caches, complete these fields:

Field Action
Maximum cached designs Enter the number of database design elements to cache for users. The default is 128.

Maximum cached users
When a user opens a database, Domino maps each design element name to an
identification number. This mapping procedure takes time. Use this field to specify
how many elements you want to store in memory so the next time a user accesses
that element, it is immediately available.
Enter the number of users to cache. The default is 64.

After a user successfully authenticates with a server, Domino stores in memory the
user’s name, password, and the list of groups to which the user belongs. Use this
field to increase the number of users for whom Domino stores this information.
Cached user expiration Enter the time interval in seconds during which Domino regularly removes user
interval names, passwords, and group memberships from the cache. The default is 120.

Remove user names, passwords, and group memberships from the cache
periodically to force Domino to look up credentials in the directory the next time
those users access the server.

Specifying network time-outs on the Web server

Open, inactive sessions can prevent users from accessing the server. Specify time limits for activities
between the Domino Web server and clients or CGI programs so connections do not remain open if there
is no network activity between them.

To specify network time-outs on the Web server:

1. Open the Server document you want to edit and click Edit Server.
2. Click Internet Protocols - HTTP. In the Timeouts section, complete these fields:

Field Action
HTTP persistent connection Specify whether you want to enable persistent HTTP connections on the Web server.
These connections remain active under the following conditions:
v HTTP protocol is 1.1.
v The server application returns an HTTP response code less than 400. (If the server
application returns an HTTP response code greater than or equal to 400, the
connection will be closed by the server.)
v The HTTP request did come through a proxy server.
v The client did not send a connection close header.
v The number of connections that the server can support is running low, or the
number of connections queued for the thread processing the request is too large.

If the connection is kept open, then the following settings apply:

v The connection will be closed if the maximum number of requests per connection
is exceeded.
v The connection will be closed if the persistent time-out is exceeded.
v The connection will be closed if no data is received by the server within the
specified input timeout.
v The connection will be closed if a complete request is not received within the
specified request timeout.
Note: Persistent connections require more server overhead than connections that are
limited by network activity.

938 Lotus Domino Administrator 7 Help

Field Action
Maximum requests per Specify the maximum number of HTTP requests that can be handled on one
persistent connection persistent connection. The default is 5.
Persistent connection timeout Specify the length of time for which you want persistent connections to remain
active. The default is 180 seconds.
Request timeout Specify the amount of time for the server to wait to receive an entire request. The
default is 60 seconds. If the server doesn’t receive the entire request in the specified
time interval, the server terminates the connection.
Input timeout Enter the time, in seconds, that a client has to send a request after connecting to the
server. The default is 15 seconds. If no request is sent in the specified time interval,
then the server terminates the connection. If only a partial request is sent, the input
timer is reset to the specified time limit in anticipation of the rest of the data
arriving.
Output timeout Enter the maximum time, in seconds, that the server has to send output to a client.
The default is 180 seconds.
CGI timeout The maximum time, in seconds, that a CGI program started by the server has to
finish. The default is 180 seconds.

Running Web agents

You can specify whether Web application agents -- that is, agents triggered by browser clients -- can run
at the same time. These include application agents invoked by the WebQueryOpen and WebQuerySave
form events, and for agents invoked by the URL command ″OpenAgent.″ If you choose to enable this
option, the agents run asynchronously. Otherwise, the server runs one agent at a time.

You should set an execution time limit for Web application agents. The purpose of the time limit is to
prevent Web agents from running indefinitely and using server resources. However, do not rely on this
mechanism for the routine shutdown of agents. When the server shuts down an offending agent,
resources that the agent was using (such as disk files) may be left open.

To run Web application agents:

1. Open the Server document you want to edit.
2. Choose Internet Protocols - Domino Web Engine. Under Web Agents, complete these fields:

Field Enter
Run Web agents concurrently? Choose one:
v Enabled -- To allow more than one agent to run on the Web server at the
same time (asynchronously)
v Disabled (default) -- To run only one agent at a time (serially)
Web agent timeout The maximum number of seconds (elapsed clock time) for which a Web
application agent is allowed to run. If you enter 0 for the value (default value),
Web application agents can run indefinitely.
Note: This setting has no effect on scheduled agents or other types of server or
workstation agents.

Specifying the number of threads used by the Web server

An HTTP request is processed by a thread. A thread, in turn, can handle a number of network
connections. You can specify the number of threads the Web server can process. In general, the number of
threads specified is an indication of the number of users who can access the server simultaneously.

Chapter 36. Setting Up the Domino Web Server 939

If the number of active threads is reached, the Domino server queues new requests until another request
finishes and threads become available. The more power your machine has, the higher the number of
threads you should specify. If your machine spends too much time on overhead tasks, such as swapping
memory, specify a lower number of threads.

To specify the number of threads used by the Web server:

1. Open the Server document you want to edit, and click Edit Server.
2. Click the Internet Protocols - HTTP tab.
3. Under Basics, enter a number for ″Number active threads.″ The default is 40.

Improving file-download performance for Web clients

Web clients can download a file that is attached to a page or that is in a server directory that is mapped
by a URL. If a client is using a product that supports byte-range serving (available in HTTP 1.1 and
higher) the client downloads the file in sections -- ranges of bytes -- and tracks the progress of each file
download. If an interruption occurs, the client can resume the download from the point where it was
interrupted. Without byte-range serving, users must repeat interrupted downloads from the beginning.

Domino is compatible with clients that support the HTTP 1.1 specification. The clients may be
implemented in a variety of ways -- for example, as browser plug-ins, applets, or stand-alone programs.

Attached files must be decompressed so that clients that support byte-range serving can access them.
When you attach a file, you must deselect the Compress option. To verify that an existing attachment is
decompressed, from a Notes client choose File - Document Properties, select the $FILE item, and verify
that the Compression Type property is NONE.

Example of downloading a file from the server’s file system: The file INSTALL.EXE is located in a
directory that is enabled for downloading using a URL-mapping. A GetRight 3.1 client can use the
following URL to download the file:

http://hostname/install.exe

where hostname is the name of the site.

If the download is interrupted, the client can restart the download from the point where it was
interrupted.

Example of downloading a file attachment: A user can download a PDF file one page at a time if the
PDF file is attached to a document and the user has set the configuration option in Adobe Acrobat to
download a page at a time. Downloading one page at a time can greatly improve performance if the user
is interested in only a portion of a large file. For example, a user accesses the PROJECT.PDF file using the
following URL:

http:// hostname/dbname/viewUNID/docUNID/$FILE/project.pdf

where hostname is the name of the site, dbname is the name of the database that stores the attachment,
viewUNID is the Universal ID of the view for the attachment, and docUNID is the Universal ID of the
document to which the file is attached.

940 Lotus Domino Administrator 7 Help

Chapter 37. Setting Up Domino to Work with Other Web
Servers
This chapter describes how to set up Domino to process requests from other types of Web servers.

Setting up Domino to work with other Web servers

Back-end Domino 7 servers can receive, and respond to, requests from front-end IBM HTTP Servers (IHS)
or from Microsoft Internet Information Servers (IIS). For this communication to occur, the appropriate
WebSphere Application Server (WAS) 4.0.3 or later plug-in must be installed on the front-end server.
These plug-ins recognize HTTP requests for Domino applications and pass them along to the Domino
server. Other HTTP requests will be handled by the front-end server itself.

A typical scenario is for the front-end server to be outside a firewall. The front-end server receives
requests from Web users, the plug-in relays the requests over HTTP, through the firewall, to the HTTP
task on the back-end Domino 7 server. The Domino 7 server then processes the request and sends the
reply back to the plug-in, which relays it to the user.

A plug-in can be configured to support any number of back-end servers. Since Domino uses the same
plugins as WebSphere, you can also combine Domino and WebSphere servers. For example, a Domino
server hosting a mail application and a WebSphere server hosting a J2EE application could both be
placed behind the same IIS front-end server.

The back-end Domino server can be on any supported operating system platform. The following
front-end servers are supported:
v IBM HTTP Server on AIX, Windows 2000/2003, and Windows 2000 Server.
v Microsoft IIS on Windows 2000/2003 4.0 and Windows 2000 Server.

The plug-in files are packaged with the Domino 7 server and their use is covered by your Domino
license. You do not need to install any other WebSphere components to use the Microsoft IIS plug-in.
However, to use the IHS plug-in you must install the IHS components of WebSphere on the front-end
server.

The following features are supported for the Domino back-end servers: core Domino database
functionality, Domino Web Access, and Lotus Domino Off-Line Services (DOLS). Additional Domino
products may also be supported; refer to the product documentation for details.

Setting up Domino to work with IBM HTTP Servers

The IBM HTTP Server (IHS) is packaged as part of the WebSphere server. For information on installing
IHS and the WebSphere Application Server (WAS), see the WebSphere installation documentation.
Installing the plug-in is an option during WebSphere and IHS installation. For information on installing
the plug-in during WebSphere setup, see the WebSphere installation documentation.

The plug-in files are also packaged with the Domino server. If the plug-in was not installed during
WebSphere or IHS installation, the administrator can copy the plug-in files from the appropriate
directory:
v Domino\data\domino\plugins\was4
v Domino\data\domino\plugins\was5
v Domino\data\domino\plugins\was6

941
Since several of the required directory structures and files are created during the WebSphere and IHS
installs, they can also be created or copied from an existing installation.

To install the WebSphere plug-in from Domino

1. Install a Domino 7 server. The plug-in files are packaged with the server in the
\Domino\data\domino\plugins/<WAS version> directory
2. On the IHS server, create the appropriate directory structure.

For AIX, Solaris, and Linux: For Win32 (you can use any drive):
/usr/WebSphere/Plugins/bin c:\WebSphere\Plugins\bin
/usr/WebSphere/Plugins/config c:\WebSphere\Plugins\config
/usr/WebSphere/Plugins/logs c:\WebSphere\Plugins\logs

3. Copy the following files from the Domino server to the IHS server:

Copy this file from the Domino server to this location on the IHS server
For AIX, Solaris, and Linux:
<Domino data /usr/WebSphere/Plugins/bin
directory>/domino/plugins/<WASversion>/<platform>/mod_was_ap20_http.so
<Domino data directory>/domino/plugins/ plugin-cfg.xml /usr/WebSphere/Plugins/config
For Win32:
<Domino data directory>/domino/plugins/<WAS c:\WebSphere\Plugins\bin
version>/<platform>/ mod_was_ap20_http.dll
<Domino data directory>/domino/plugins/ plugin-cfg.xml c:\WebSphere\Plugins\config

4. On the IHS server, edit the IHS configuration file httpd.conf (on a default installation this file is
located at <IHS install directory>/conf/httpd.conf). Add the following lines to the bottom of the file:

For AIX, Solaris, and Linux: For Win32 :

LoadModule was_ap20_module LoadModule was_ap20_module
/usr/WebSphere/Plugins/bin/mod_was_ap20_http.so ″c:\WebSphere\Plugins\bin\mod_was _ap20_http.dll″
WebSpherePluginConfig ″c:\WebSphere\Plugins\config″
WebSpherePluginConfig/usr/WebSphere/Plugins/config/plugin-cfg.xml

5. Modify the plugin-cfg.xml file according to the instructions for configuring the WebSphere plug-in.
6. Set up the Domino server according to the instructions for IHS.
7. Restart the IHS server and test your installation.

Setting up Domino to work with Microsoft IIS servers

To use a Microsoft IIS server as a front-end machine, you must install the WebSphere Application Server
plug-in for IIS on the IIS server. The plug-in files are packaged with the Domino 7 server and must be
copied from the Domino server to the IIS server. After you copy the plug-in files, you must configure the
plug-in, then configure the Domino server to work with the plug-in IIS. You do not need to install any
other WebSphere components to use the Microsoft IIS plug-in.

See the following topics:

v To install the WebSphere plug-in on an IIS server
v To configure the WebSphere plugin
v To configure the Domino server to work with Microsoft IIS
v Setting up security for Microsoft IIS
v Details of Microsoft IIS security options

942 Lotus Domino Administrator 7 Help

To install the WebSphere plug-in on an IIS server
Do the following to install the WebSphere plug-in on the IIS server and enable it for a Web site. Before
beginning this procedure, you should be familiar with the Internet Information Services (IIS) Manager
configuration tool. On Windows 2000/2003, this tool is accessed through the Microsoft Management
Console.
1. Create the following directory structure on the IIS machine (you may use any drive);
C:\WebSphere\AppServer\bin
C:\WebSphere\AppServer\config
C:\WebSphere\AppServer\etc
C:\WebSphere\AppServer\logs
2. Copy the following files from the Domino server to the IIS server:
a. Copy data/domino/plugins/plugin-cfg.xml to c:\WebSphere\AppServer\config.
b. Copy data/domino/plugins/<WAS version>/w32/iisWASPlugin_http.dll to
c:\WebSphere\AppServer\bin.
3. Start the Internet Information Services Manager application.
4. Create a new Virtual Directory for the Web site instance you want to work with WebSphere. To do
this with a default installation, expand the tree on the left until you see ″Default Web Site.″ Right
click on ″Default Web Site″ and select New - Virtual Directory. This opens the wizard for adding a
Virtual Directory.
5. In the Alias field, enter ″sePlugins.″
6. In the Directory field, browse to the WebSphere bin directory (C:\WebSphere\AppServer\bin).
7. For access permissions, check and uncheck all other permissions.
8. Click Finish. A virtual directory titled ″sePlugins″ is added to your default Web site.
9. In this step, follow the appropriate procedure for your version of Windows.
On Windows 2000:
a. Right click the machine name in the tree on the left and select Properties.
b. On the ″Internet Information Services″ tab, select ″WWW Service″ in the ″Master Properties″ drop
down box and click Edit.
c. In the ″WWW Service Master Properties″ window, click the ″ISAPI Filters″ tab.
On Windows 2003:
a. Right-click the individual web site to enable for the plugin.
b. Click ″ISAPI Filters.″
10. Click Add. This opens the ″Filter Properties″ dialog.
11. In the ″Filter Name:″ field, type ″iisWASPlugin.″
12. In the ″Executable:″ field, click Browse. Open the WebSphere bin directory and select
″iisWASPlugin_http.dll.″
13. Close all open windows by clicking OK.
14. Open the Windows registry file and create the following key path: HKEY_LOCAL_MACHINE -
SOFTWARE - IBM - WebSphere Application Server - <WAS version>. Select this last key and create a
new string value ″Plugin Config″. Set the value for this variable to the location of the plugin-cfg.xml
file (C:\WebSphere\AppServer\config\plugin-cfg.xml)
15. To enable the plug-in for additional Web sites, repeat Steps 4 through 8.

To configure the WebSphere plug-in

The WebSphere configuration file WebSphere\AppServer\config\plugin-cfg.xml controls the operation of
the plug-in. In order for the plug-in to relay requests to the target Domino server, you must add
directives to plugin-cfg.xml to define a transport route to the server, and pattern rules for the URL
namespaces that identify requests which are to be relayed to Domino. The plug-in will only relay
requests that match a namespace rule. All other requests will be handled by the front-end Web server.

Chapter 37. Setting Up Domino to Work with Other Web Servers 943
To configure plugin-cfg.xml:
1. Open plugin-cfg.xml in Notepad.
2. Modify the <Transport> element to target the appropriate Domino server. To do this, change the
Hostname and Port parameters to the proper values required for the plug-in to reach your back-end
server’s HTTP task. For example:
<!-- Server groups provide a mechanism of grouping servers together. -->
<ServerGroup Name="default_group">
<Server Name="default_server">
<!-- The transport defines the hostname and port value that the web server
plug-in will use to communicate with the application server. -->
<Transport Hostname="mydomino.server.com" Port="81" Protocol="http"/>
</Server>
</ServerGroup>
3. Add these directives to the top of the <UriGroup> section. These directives specify common URL
patterns needed for accessing Domino Web applications.
<UriGroup Name="default_host_URIs">

<Uri Name=″/*.nsf″/>

<Uri Name=″/icons/*″/>

<Uri Name=″/domjava/*″/>

<Uri Name=″/execcgi/*″/>

<Uri Name=″/cgi-bin/*″/>

<Uri Name=″/servlet/*″/>

<Uri Name=″/download/*″/>

<Uri Name=″/mail/*″ />

If your Domino application requires additional namespaces, you can create <Uri> directives for those
patterns also.

Note: All the WAS plug-ins automatically reread the configuration file once a minute to pick up changes.
If you don’t want to wait that long, you must stop and restart the front-end Web server. In the case of the
IIS plug-in, you must stop the World Wide Web Publishing Service from the Windows services control
panel, then restart the Web site from the Internet Services Manager. Just stopping and restarting the Web
site by itself won’t work because the plug-in DLL won’t be reloaded.

To configure the Domino server to work with Microsoft IIS

On the back-end Domino server, add the following line to NOTES.INI:

HTTPEnableConnectorHeaders=1

This setting enables the Domino HTTP task to process the special headers added by the plug-in to
requests. These headers include information about the front-end server’s configuration and user
authentication status. As a security measure, the HTTP task ignores these headers if the setting is not
enabled. This prevents an attacker from mimicking a plug-in.

944 Lotus Domino Administrator 7 Help

Setting up security for Microsoft IIS
When you have set up an IIS plug-in and a Domino back-end server, Web applications are subject to both
IIS security and Domino security. After IIS authenticates a user based on the Windows account registry,
those credentials, if any, are passed to Domino for user authorization.

Microsoft IIS supports four methods of user authentication. The Domino plug-in configuration supports
all except Digest authentication.
v Anonymous access (the user does not enter a name or password)
v Basic Authentication (the user enters a name and password)
v Digest authentication (an enhanced version of Basic authentication available only on Windows 2000).
The Domino plug-in configuration does not support this authentication method.
v Integrated Windows authentication (a special protocol supported by Microsoft Internet Explorer).
v SSL

IIS requires user authentication in order to control access to resources owned by IIS such as the file
system and Active Server Pages. If a user requests access to a Domino resource, the IIS plug-in passes the
authentication information to Domino. The information passed depends on the combination of
authentication methods enabled on IIS. After the information is passed, Domino authenticates the user
according to the procedures discussed in the topic ″Details of Microsoft IIS security.″ All of the Domino
directory options are available, such as using multiple Domino Directories and LDAP directories.

For information on setting up security options on the Domino server, see the chapter ″Planning Security.″

To set up security on the IIS server:

1. Start the Internet Services Manager
2. Right-click the IIS Web site and select Properties.
3. Click the Directory Security tab.
4. Click Edit in the Anonymous Access and Authentication Control section.
5. Choose one or more of the authentication options and click OK.

Details of Microsoft IIS security options

Anonymous Access: Anonymous Access lets Web users access a Web site without a user name or
password. IIS always maps anonymous Web users to a specific anonymous user account, which you can
configure. If Anonymous Access is the only IIS authentication method enabled, IIS does not use any user
credentials -- that is, a user name and password -- sent by the browser for authentication, but the IIS
plug-in passes the credentials to Domino, and Domino will authenticate the user according to the normal
procedure for Web users. If an anonymous user attempts to access a Domino resource that requires
authentication, Domino will respond appropriately according to the security options you have set for the
Domino Web site (a Basic name-and-password challenge, or a session authentication login page).
Therefore, if you want Domino to completely handle user authentication, you should enable Anonymous
Access as the only security option for the IIS Web site.

For information, see the chapter "Setting Up Name-and-Password and Anonymous Access to Domino
Servers.″

Anonymous Access uses the following guidelines:

v The Web user does not need to be a registered 2000/2003 user.
v If you want a user to access secure resources, the Web user must be a registered Domino user and the
user must have an Internet password.

Basic Authentication: When using Basic Authentication, IIS verifies the user credentials that the browser
sends as a valid user account. If Basic Authentication is the only IIS authentication method enabled, IIS

Chapter 37. Setting Up Domino to Work with Other Web Servers 945
requires all browser requests to have credentials -- anonymous access is not allowed. Whenever a user
sends a Domino request, the IIS plug-in passes the user name to Domino and informs Domino that the
user has been authenticated by IIS. Such a user is called a ″pre-authenticated″ user. The plug-in passes
the pre-authenticated name exactly as the user entered it in the browser. Domino then attempts to look
up that name in its directories. Since IIS has already verified the user’s password, Domino does not use
the Internet password stored in the user’s Person document or LDAP entry.

If Domino finds the name in a Domino Directory, then Domino uses the primary name in the Person
record for authorization (ACL checking). If Domino does not find the name, then Domino uses the
pre-authenticated name as-is for authorization.

In both cases, Domino builds the user’s group list from the set of groups in the Domino Directory which
include the user as a member, and Domino also adds the special group ″-WebPreAuthenticated-″ to the
group list. You may use -WebPreAuthenticated- as a group entry in database ACLs and other access lists.

Note: If you want to list IIS users by name in database ACLs, you must be careful to use the correct form
of the name. Use the primary name if the user is listed in the Domino Directory, or the IIS
pre-authenticated name if the user is not in the directory. Remember that if a user is listed by name in an
ACL and is also a member of a group in the ACL (including ″-WebPreAuthenticated-″ or any other
group), the name entry takes precedence over the group entry.

In summary, Basic Authentication uses the following guidelines:

v Anonymous access is not allowed.
v The Web user must be a registered Windows 2000/2003 user.
v The Web user does not have to be a registered Domino user.
v Domino does not use the user’s Internet password.
v The Web user is automatically assigned to the -WebPreAuthenticated- group.

Integrated Windows Authentication: Integrated Windows authentication is a Microsoft-specific protocol

supported by Internet Explorer (IE). When a Web user makes a request to the site, IE automatically sends
to IIS the user’s current Windows logon account name. IIS verifies the name against the Windows registry
on the IIS server. When a user makes a Domino request, the IIS plug-in passes to Domino the user’s
Windows name and Domino processes the pre-authenticated name as described above for Basic
authentication.

Windows account names use the form domain\username or machinename\username -- for example,
SALES\JSmith. If Domino is using Person documents in the Domino Directory to authenticate the
Windows users, the documents must contain the exact Windows account names as aliases. For example, if
Joe Smith has a Notes ID in the ″CorpSales″ domain and a Windows user account in the ″SALES″
Windows domain, the User name field in Joe Smith’s Person document needs to contain:

Joe Smith/CorpSales

SALES\JSmith

This allows Domino to authenticate the Windows user SALES\JSmith as the Domino user Joe
Smith/CorpSales.

In summary, integrated Windows authentication uses the following guidelines:

v If this is the only authentication method enabled, only IE users can access the Web site.
v Anonymous access is not possible since IE automatically sends the user’s Windows account name on
every request.
v The Web user must be a registered Windows 2000/2003 user.

946 Lotus Domino Administrator 7 Help

v If you want to match the Windows user to a Domino Person document, You need to add the user’s
Windows account name as an alias to the Person documents.
v Domino does not use the Internet password.
v The user is automatically assigned to the -WebPreAuthenticated- group.

SSL: If you enable SSL on a Web server, IIS handles the actual SSL connection. However, if a Web user
provides a client certificate, the IIS plug-in passes the certificate to Domino and Domino uses the
certificate to authenticate the user. If Domino cannot find a certificate for the user, then Domino will
downgrade the user to Anonymous access.

Chapter 37. Setting Up Domino to Work with Other Web Servers 947
948 Lotus Domino Administrator 7 Help
Chapter 38. Setting Up the Web Navigator
This chapter describes how to set up the server that runs the Web Navigator and how to manage the
information retrieved from the Internet.

The Web Navigator

The Web Navigator lets Notes workstations access the Web, without having a direct connection to the
Internet. The Web Navigator server, which has a direct connection to the Internet, retrieves pages for
users. The Web Navigator retrieves pages on Internet servers -- for example, servers that use Internet
services such as HTTP, FTP, or Gopher.

When someone requests a new page, the Web Navigator server connects to the Internet server, retrieves
the requested page, and copies the page as a document into the Web Navigator database (WEB.NSF). If
the requested page already exists in the database, Domino immediately opens the document without
requesting it again from the Internet server.

Using the Web Navigator provides many benefits, including:

v Reduced Internet connection costs. Storing all the retrieved Web pages in a centralized database allows
users to access the page on the database instead of connecting to the Internet.
v Monitoring capabilities. You can monitor Web-based activity, if needed.
v Simplified troubleshooting for Internet connections. You troubleshoot only one connection instead of
troubleshooting one connection for each workstation.
v Familiar Notes interface. The retrieved Web pages are stored as documents in a database where people
can request, view, and manage them using the Notes interface.

The following diagram shows the process the Web Navigator uses to retrieve a page that a Notes client
requests from a Web site.

Setting up a Web Navigator server

The first time you start the Web task, Domino creates the Web Navigator database (WEB.NSF) and enters
default settings for the Web Navigator database.
1. Set up a Domino server.

949
 For more information, see the chapter ″Installing and Setting Up Domino Servers.″
2. Start the Web task on the server.
3. Set up the connection between the server and the Internet.
For information on setting up the Internet connection, contact your Internet Service Provider.
4. If necessary, use a proxy to connect the Web Navigator server to the Internet.
5. Edit the Server document for the users’ home/mail server.
6. Set up users to use the Web Navigator.

Starting and stopping the Web Navigator program

To do this Perform this task
Start the Web Navigator manually Enter load web at the console.
Start the Web Navigator automatically when you start Edit the ServerTasks setting in the NOTES.INI file to
Domino include the command web.
Stop the Web Navigator Enter tell web quit at the console.

For more information on server commands and NOTES.INI settings, see the appendices ″Server
Commands″ and ″NOTES.INI File.″

Using a proxy server to connect the Web Navigator to the Internet

You can set up the Web Navigator to connect to the Internet through a proxy server instead of using an
Internet Service Provider (ISP) to connect directly to the Internet. If you don’t specify a proxy, you must
use a direct Internet connection to access the Internet.
1. Make sure that:
v The proxy is set up to connect to the Internet.
v The Web task is running on the server.
2. From the Domino Administrator, click the Configuration tab.
3. Expand the Server section and click All Server Documents.
4. Open the Server document for the Web Navigator server.
5. Click the Ports - Proxies tab, complete these fields, and then save the document:

Field Enter
HTTP proxy The name or IP address of the proxy and the port to access HTTP pages.
FTP proxy The name or IP address of the proxy and the port to access FTP pages.
Gopher proxy The name or IP address of the proxy and the port to access Gopher pages.
SSL Security proxy The name or IP address of the proxy and the port you want to go through for pages on
Internet servers that use SSL.
HTTP Tunnel proxy Do not enter a value.

This field is used to send Notes remote procedure calls (NRPC). NRPC is the
architectural layer of Notes and Domino that control services such as replication and
mail. The Web Navigator does not use NRPC for communication.
SOCKs proxy The name or IP address of the proxy and the port.

If you enter a name or IP address in both the SSL Security proxy and SOCKs proxy
fields, Domino uses the SSL Security proxy.

If you enter a name or IP address in both the HTTP proxy and SOCKs proxy fields,
Domino uses the SOCKs proxy.

950 Lotus Domino Administrator 7 Help

Field Enter
No proxy for these hosts The names of the hosts and domains you want to access without going through the
and domains proxy. You can bypass the proxy to access certain domains on the Internet or to access
your internal intranet domain.

Do not enter the IP address in this field; you must use the name. Separate multiple
entries with commas or returns. You can use wildcard (*) characters, for example,
*lotus.com or www.*.com.

6. Complete the procedure ″Editing the Server document for the Web Navigator.″

Editing the Server document for the Web Navigator:

1. Make sure that you already set up the connection between the server and the Internet. If necessary,
use a proxy to connect the server to the Internet.
2. From the Domino Administrator, click the Configuration tab.
3. Expand the Server section and then click All Server Documents.
4. Open the Server document for the Web Navigator server.
5. Click the Basics tab. Open the Server Location Information section and go to the Servers section.
Complete the InterNotes server field, and save the document.

Field Enter
InterNotes server The hierarchical name of the server running the Web task. This is the default server to
use if the InterNotes server field in the user’s Location document is blank.

6. Complete the procedure ″Setting up users to use the Web Navigator.″

7. Restart the Web task on the server.

Setting up users to use the Web Navigator

You must specify the Web Navigator as the Internet browser for each user. You can specify the browser in
a policy, or you can set it individually for each user.

Setting up users using a policy: If you are using policies, you can specify the browser setting as the
default for all users or groups. The option is located on the Basics tab of the Setup Policy document,
under ″Setup Policy Options for Browsers.″ Complete each field using the information described in the
procedure ″Setting up users individually.″

Setting up users individually:

1. Edit the Server document for the Web Navigator server.
2. On each user’s machine, choose File - Mobile - Edit Current Location.
3. Click the Internet Browser tab and complete these fields:

Field Enter
Internet browser Notes
Retrieve/open pages ″From InterNotes server″ to use the Web Navigator server specified in the InterNotes
server field on the Servers tab.

4. Click the Servers tab and complete this field:

Field Enter
InterNotes server The hierarchical name of the server running the Web task. The server you specify in this
field takes precedence over the server specified in the InterNotes server field on the
Server document.

Chapter 38. Setting Up the Web Navigator 951

To allow users to access private Web pages: When users fill out forms on the Web or pages from
Internet servers to which users authenticate, the Web Navigator encrypts those pages with the user’s
public key and stores the pages in private folders in the Web Navigator database.

To ensure that the Web Navigator can encrypt these private pages, be sure that users’ public keys exist in
the Person documents in the Domino Directory on the server. Domino automatically adds the user’s
public key to the Person document when you register the user.

Customizing the Web Navigator

After you set up the Web Navigator on a server, you can customize it as follows:
v Allow multiple users to retrieve pages
v Control access to Web sites
v Control access to Internet services
v Set up the Web Navigator to retrieve pages from sites that are secured by SSL
v Send mail from Web pages to the Internet
For information, see the topics that follow.

Allowing multiple users to retrieve pages concurrently

You can specify the number of users who can use the Web Navigator to retrieve pages concurrently. If
users start more concurrent Web retrievals than allowed, Domino queues them and starts them as soon as
it can. Increasing the number of users who can retrieve pages improves response time, but increases the
server load.
1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
2. Click the Server Tasks - Web Retriever tab, complete this field, and then save the document:

Field Enter
Concurrent retrievers The number you enter depends on the system configuration for your server. If user
access is slow because the number of users specified in this field is less than the number
of users attempting to retrieve pages from the Internet, increase the number.

Default is 50.

Controlling access to Web sites

You can control the Web sites that users access. For example, you might want to prevent users from
browsing sites that are not work-related.

When you specify access settings, keep these tips in mind:

v Use a DNS name rather than an IP address. Entering an IP address forces the Web Navigator to take
extra steps to perform a Domain Name System (DNS) lookup. If the DNS cannot resolve an IP address,
access to that site is denied.
v A more specific reference overrides a less specific reference. For example, if you enter www.*.com in
the ″Deny access″ field and enter www.ibm.com in the ″Allow access″ field, users can access
www.ibm.com but cannot access sites with names such as www.lotus.com.
v If you enter an identical reference in both the ″Allow access″ and ″Deny access″ fields, the ″Allow
access″ entry overrides the ″Deny access″ entry.
v There is an implied [*] in the ″Allow access″ field at all times. This [*] allows access to all sites by
default, unless you enter settings in the ″Deny access″ field to override this default.

To control access to Web sites:

1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.

952 Lotus Domino Administrator 7 Help

2. Click the Server Tasks - Web Retriever tab, complete these fields, and then save the document:

Field Enter
Allow access to these One or more of the following, separated by commas or spaces:
Internet sites v A DNS name -- for example, www.lotus.com
v An IP address -- for example, 205.159.212.10
v A DNS name or IP address with a wildcard (*) --for example, www.*.com. You can
use only one wildcard per entry -- for example you cannot enter w*.*.com.
Deny access to these Same as above.
Internet sites

Controlling access to Internet services

You can control which Internet services users can access. The Web Navigator supports HTTP, FTP,
HTTPS, Gopher, and Finger.
1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
2. Click the Server Tasks - Web Retriever tab, complete this field, and then save the document:

Field Enter
Services One or more of the Internet services provided. The default is HTTP, FTP, and GOPHER.

Setting up the Web Navigator to retrieve pages on sites secured by SSL

If users are accessing Web sites that are secured by SSL, you must set up the Web Navigator to retrieve
pages on these sites. The Web Navigator server does not need to use SSL in order to retrieve pages from
a Web site that uses SSL.

To set up the Web Navigator server for SSL, do the following:

v Store the Web site’s SSL certificate in the Domino Directory on the Web Navigator server.
v Enable the HTTPS protocol on the Web Navigator server as an Internet service.
For more information on SSL, see the chapter ″Setting Up SSL on a Domino Server.″

The Web Navigator supports sites that have SSL certificates issued by the RSA Certificate Authority (CA),
so you do not need to obtain the Web site’s SSL certificate if it was issued by the RSA CA. If the Web site
does not have a certificate issued by the RSA CA, you must obtain the Web site’s certificate and add it to
the Domino Directory on the Web Navigator server. Obtaining the certificate from a secure location
ensures that the certificate you receive is valid and creates an optimally secure environment by allowing
access only to servers with which you share a valid certificate.

Although not recommended, you can set up Web Navigator to add the Web site’s SSL certificate
automatically to the Domino Directory. Set up this way, the Web Navigator allows users to access pages
on any Web site that uses SSL, even if the Domino Directory does not already contain the certificate. This
approach allows easy access for users, but compromises the security of the data sent by users, since the
server does not verify the identity of the remote server before allowing the user to access it.

To add specific certificates:

1. Identify the certificate required by the secured Web site by browsing to the site and obtaining the
certificate name.
2. Use a Notes workstation to merge the certificate for the CA into the Domino Directory.
For information, see the chapter ″Setting Up Clients for S/MIME and SSL.″
3. On the Server Tasks - Web Retriever tab of the Server document, select HTTPS in the Services field.

Chapter 38. Setting Up the Web Navigator 953

To add certificates automatically:
1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
2. Click the Ports - Internet Ports tab and complete this field:

Field Enter
Accept SSL site certificates Choose Yes.

3. Click the Server Tasks - Web Retriever tab, complete this field, and then save the document:

Field Enter
Services Choose HTTPS.

To view certificates:
1. From the Domino Administrator, click the Configuration tab, and choose Miscellaneous - Certificates.
2. Look at the Internet Cross Certificates category.

Sending mail from a Web page to the Internet

When users click a mailto URL on a Web page, Domino opens a new mail message and enters the
Internet address (user@company.com) in the To: field.

Note: If you use the Lotus SMTP MTA (Domino 4.6 and earlier) as the gateway for Internet mail, users
must append the foreign domain of the SMTP Gateway for each Internet address -- for example,
user@company.com@foreigndomain. So that users don’t need to specify the foreign domain each time,
you can specify the foreign domain of the gateway.
1. Make sure that users’ Notes workstations are already set up to use Notes mail.
For information, see the chapter ″Setting Up and Managing Notes Users.″
2. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
3. Click the Server Tasks - Web Retriever tab, complete this field, and then save the document:

Field Enter
SMTP Domain The name of the foreign domain of the SMTP mail gateway.

The Web Navigator database

The Web Navigator database (WEB.NSF) resides on the Web Navigator server and stores all pages that
users retrieve from Web sites. Storing Web pages in a central database reduces connection costs, since
after one user retrieves a page, the page is available in the database for others to browse. The Web
Navigator database contains features for Notes users and administrators.

Database access
The default user access for the Web Navigator database is Editor, which allows users to create HTML
forms, Recommendation documents, and Web tours. Domino adds the administrator names listed in the
Administrators field in the Server document for the Web Navigator server to the ACL for the Web
Navigator database and gives them Manager access with the WebMaster role.

Administration document
The Administration document is stored in the Web Navigator database and controls default settings for
the database. You must have the WebMaster role to access the document. Open WEB.NSF and access the
document from the Actions menu.

954 Lotus Domino Administrator 7 Help

Agents
The Web Navigator database contains three agents that administrators can use to manage documents in
the database. The Purge agent removes documents that meet the criteria you specify. Regularly purging
documents keeps the size of the Web Navigator database manageable.

The Refresh agent updates the contents of pages stored in the Web Navigator database with the Web site
content from which they were originally retrieved. Pages in the database are not automatically updated
after they are retrieved; therefore, the page content may quickly become outdated unless you use this
agent.

The Averaging agent creates an average rating of user-recommended pages. The top ten pages appear in
the Recommended by Top Ratings view.

Web tours and Recommendation documents

Web tours and Recommendation documents allow users to collaborate with others who use the Web
Navigator database.

Using a Web tour document, users can group a set of Web pages for others to view sequentially -- for
example, to create training materials or to collect a set of pages that you previously viewed on the Web.

Using a recommendation document, users can add useful Web sites to the Web Navigator database.

Customizing the Web Navigator database

You can customize the Web Navigator database as follows:
v Display the names of users who retrieve pages
v Customize the default appearance of elements on retrieved Web pages
v Save and view HTML sources
v Rename and move the database

Chapter 38. Setting Up the Web Navigator 955

v Set preferences for the Purge, Refresh, and Averaging agents
v Use the Purge agent to manage the size of the database
v Use the Refresh agent to update pages in the database
v Use the Averaging agent to calculate page ratings in the database
For information, see the topics that follow.

Displaying who retrieved a page in the Web Navigator database

By default, the Web Navigator database uses a view named ($All) to display information about each page
that users retrieve. However, this view does not display the name of the user who retrieved a particular
page.

To display the name of the user who retrieved a page, the Web Navigator template provides a view titled
($All with Authors). The name displays next to the title of the Web page. To use this as the default view,
rename it to ($All) so that the references to ($All) in the navigators work.
1. Make sure you have Designer access in the ACL of the Web Navigator template (PUBWEB50.NTF)
on the server.
2. Start the Domino Designer, open the Web Navigator template, and select the ($All) view.
3. Choose Edit - Copy and then choose Edit - Paste to paste the ″Copy of ($All)″ view into the
template.
4. Delete the ($All) view.
5. Open the ($All with Authors) view.
6. Choose Design - View Properties and rename the view to ($All).
7. On the Options tab, select ″Default when database is first opened″ to make this view the default.
8. Close and save your changes.
9. Replace the design of the Web Navigator database.
10. Make sure you have the WebMaster role in the ACL of the Web Navigator database.
11. Select the Web Navigator database using a network connection to the server.
12. Choose View - Go to and select All Documents.
13. Choose Actions - Administration, and select Save author information.

Customizing the default appearance of pages in the Web Navigator database

Web page authors use HTML tags to specify elements of a Web page. The Web Navigator interprets these
tags to determine how to display these elements. You can customize the default appearance of many
elements on retrieved Web pages.

The Web Navigator supports Courier, Helvetica, and Times fonts.

1. Make sure you have the WebMaster role in the ACL of the Web Navigator database.
2. Using the Notes client, open the Web Navigator database using a network connection to the server.
3. Choose View - Go to and select All Documents.
4. Choose Actions - Administration, and then in the HTML Preferences section, customize any of these
settings:

Field Enter
URL links Anchors Underline/Blue
Font and size of elements not defined in other Body Text Times 11-point
fields in the HTML Preferences section
Font for text in the <PLAINTEXT>, <PRE>, and Plain Courier
<EXAMPLE> tags
The font size is defined by the Body Text
field.

956 Lotus Domino Administrator 7 Help

Field Enter
Font for text in the <CODE>, <SAMPLE>, <KBD>m Fixed Courier
and <TT> tags
The font size is defined by the Body Text
field.
Font for text in the <LISTING> tag Listing Courier

The font size is defined by the Body Text

field.
Font for text in the <LISTING> tag Listing Courier

The font size is defined by the Body Text

field.
Font for text in the <ADDRESS> tag Address Times

The font size is defined by the Body Text

field.

Saving and viewing HTML sources in the Web Navigator database

You can save and view the HTML source for a Web page. Domino saves the source in the Body field in
the Web Navigator database.

This setting affects all pages retrieved by the Web Navigator server.

To save HTML sources:

1. Make sure you have the WebMaster role in the ACL of the Web Navigator database.
2. Using the Notes client, select the Web Navigator database using a network connection to the server.
3. Choose View - Go to, and then select All Documents.
4. Choose Actions - Administration.
5. In the HTML Save Options field, choose one of the following:
v Save as Rich Text only -- To store the rich text in the document in a Body field
v Save as Rich Text and HTML -- To create separate Body fields for the rich text and HTML tags
v Save as MIME only -- To store the document using MIME type format in a Body field

To view HTML sources:

1. Open the document in the Web Navigator database.
2. Choose View - Show - HTML Source.

Renaming and moving the Web Navigator database

To rename the Web Navigator database: By default, Domino names the Web Navigator database
WEB.NSF. You can use another name if necessary.
1. Exit Domino and use the operating system to rename the database file name.
2. Start Domino.
3. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
4. Click the Server Tasks - Web Retriever tab, complete this field, and then save the document:

Field Enter
Web Navigator database The new file name of the Web Navigator database

Chapter 38. Setting Up the Web Navigator 957

To move the Web Navigator database: By default, Domino looks for the Web Navigator database in the
data directory on the Web Navigator server. You can move the Web Navigator database to somewhere
other than the data directory, for example, to consolidate databases in a subdirectory.
1. Copy the Web Navigator database to a new subdirectory.
2. Delete the original Web Navigator database in the data directory.
3. Create a database link to the new database. You must create a database link using the file name
specified in the Web Navigator database field in the Server document for the Web Navigator server.
4. Restart the server.

Setting agent preferences for the Web Navigator

The Web Navigator database includes three agents -- Purge, Refresh, and Averaging -- that help you
manage the database. Before you use the agents, set up the preferences for them in the Server document
for the server on which the Web Navigator runs. You can specify agent security, execution time, and
schedule.

CAUTION:
The options you set in the Server document affect all agents that run on the server.

To specify agent security:

1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
2. Click the Security tab, complete these fields, and then save the document:

Field Enter
Run restricted Your user name so that you can run agents that use a subset of the LotusScript features
LotusScript/Java agents and run agents created with Java
Run unrestricted Your user name so that you can run agents with the full set of LotusScript features and
LotusScript/Java agents run agents created with Java

To specify agent execution options:

1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
2. Click the Server Tasks - Agent Manager tab, complete these fields in the Daytime Parameters and
Nighttime Parameters sections, and then save the document:

Field Enter
Max LotusScript/Java Maximum is 360. The default is 10 (Daytime Parameters) and 15 (Nighttime
execution time Parameters.)

This field controls the time, in minutes, that the LotusScript agent has to run. Also
controls execution time of agents created with Java.
Max % busy before delay Maximum is 90. The default is 50 (Daytime Parameters) and 70 (Nighttime Parameters.)

This field controls the percentage of time the agent manager can spend running agents.
The time is a percentage of the Start and End times.

To specify the agent schedule: The Web Navigator agents run at default times, but you can reschedule
them. By default, the Purge agent runs at 1 AM; the Refresh agent runs at 3 AM; and the Averaging agent
runs at 12 AM.
1. Start the Domino Designer and select the Web Navigator database (WEB.NSF).
2. Open the agent that you want to reschedule.
3. Select a value in the ″When should this agent run″ field.

958 Lotus Domino Administrator 7 Help

4. Click Schedule and then specify the starting time for the agent.
5. Save the document.

Using the Purge agent to manage the size of the Web Navigator database
As users open Web pages, the Web Navigator database gets larger. To manage the database, use the
Purge agent.

The Purge agent uses settings in the Web Navigator Administration document, which is in the Web
Navigator database (WEB.NSF), to determine what and how much to purge. Each night at 1 AM, the
Purge agent goes through the database three times, each time purging documents according to the criteria
you specify. As soon as the database size you specify is obtained, the Purge agent stops and queues to
run the following night.

The Purge agent purges the database in three passes:

v First pass -- Checks the Expired header on each Web page. If the Web page has expired, deletes that
page.
v Second pass -- Checks the document creation date on each Web page and deletes pages older than the
date you specify.
v Third pass -- Checks for pages that are larger than the size you specify, and then deletes them.

To specify purge criteria:

1. Make sure that you have already set up security for Web Navigator agents and that you have the
WebMaster role in the ACL of the Web Navigator database.
2. Using the Notes client, select the Web Navigator database (WEB.NSF) using a network connection to
the server.
3. Choose View - Go to, and then select All Documents.
4. Choose Actions - Administration, edit any of the following fields, and then save the document:

Field Enter
Maximum database size The maximum size of the Web Navigator database

The default is 500MB

Purge agent action One of these methods to use when purging documents:
v Delete page to delete pages permanently from the database.
v Reduce page to delete the contents of the page, but saves the URL so you still see the
page in the database views.

Delete page is the default.

Purge to what % of A percentage of the maximum database size setting that the Purge agent should reach
maximum size before stopping.

The default is 60%.

Purge documents older When to delete documents based on the number of days they have been in the
than database.

The default is 30 days.

Purge documents larger When to delete documents based on their size.
than
The default is 512KB.
Purge Private documents One of these that determines if the Purge agent deletes documents stored in users’
private folders:
v Unselected (default) -- To not purge documents stored in private folders
v Selected -- To purge documents stored in private folders

Chapter 38. Setting Up the Web Navigator 959

To enable the Purge agent: The Purge agent is set up to run at 1 AM, but it does not start this schedule
until you enable the agent.
1. Make sure you have already set up security for Web Navigator agents and that you have the
WebMaster role in the ACL of the Web Navigator database.
2. Using a Notes client, select the Web Navigator database (WEB.NSF) using a network connection to the
server.
3. Choose View - Go to, and then select All Documents.
4. Choose Actions - Administration.
5. Click the Enable Purge agent button.
6. Select the name of the server on which the Web Navigator runs in the Choose Server To Run On
dialog box, and then save the document.

Using the Refresh agent to update pages in the Web Navigator database
Regularly refreshing pages keeps the page content up to date. You can refresh pages using the Refresh
agent or set an interval for the update cache.

To use the Refresh agent to update pages: To keep the most up-to-date pages in the Web Navigator
database, use the Refresh agent, which compares the date of each Web page inside the database with the
date of the Web page on the server. If the Web page on the server is newer, the Refresh agent replaces the
Web page in the Web Navigator database. By refreshing out-of-date pages, the Refresh agent ensures that
users can quickly access the latest version of a page.

The Refresh agent refreshes only HTTP pages. It does not refresh FTP pages, Gopher pages, or private
pages stored in a user’s private folder in the database.

By default, the Refresh agent is scheduled to run at 3 AM, but it does not start this schedule until you
enable the agent.
1. Make sure you have already set up security for Web Navigator agents and that you have the
WebMaster role in the ACL of the Web Navigator database.
2. Using a Notes client, select the Web Navigator database (WEB.NSF) using a network connection to the
server.
3. Choose View - Go to, and then select All Documents.
4. Choose Actions - Administration.
5. Click the Enable Refresh agent button.
6. Select the name of the server on which the Web Navigator runs in the ″Choose Server To Run On″
dialog box, and then save the document.

To update pages when users retrieve pages: Domino stores each retrieved Web page in the Web
Navigator database. You can specify how often you want Domino to check the Web page on the server to
determine if the page has changed.
1. From the Domino Administrator, click the Configuration tab, and then open the Server document for
the Web Navigator server.
2. Click the Server Tasks - Web Retriever tab, complete this field, and then save the document:

Field Enter
Update cache Choose one:
v Never (default) -- To perform no verifications
v Once per session -- To check only the first time the user accesses the page during a
session
v Every time -- To check each time the user opens a page that is already in the database

960 Lotus Domino Administrator 7 Help

Using the Averaging agent to calculate page ratings in the Web Navigator
database
The Averaging agent collects ratings that users assign to Web pages and calculates the rating of pages in
the Web Navigator database (WEB.NSF). The pages appear in the Recommended by Top Ratings view in
the database. The Averaging agent also calculates the average rating for pages that have multiple ratings
from different users.

By default, the Averaging agent is scheduled to run at 12 AM, but it does not start this schedule until you
enable the agent.
1. Start the Domino Designer and open the Web Navigator database (WEB.NSF).
2. Select the Averaging agent , and then choose Actions - Enable.
3. Choose the Web Navigator server to run the agent.

Chapter 38. Setting Up the Web Navigator 961

962 Lotus Domino Administrator 7 Help
Chapter 39. 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:
v Know the business.
v Identify assets and threats (risk analysis).
v Develop strategies to protect your computing environment.
v Develop incident-handling procedures.
v Plan and deliver employee training.
v 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.

Once you have an understanding of the business requirements, you can then begin to plan the specifics
of your Domino infrastructure, including:
v Will more than one Domino domain be needed, or will the new domain need to interact with existing
domains?
v What is the best method to expose Domino data to the Internet?
v What service levels are needed to support the business?
v 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:

v Environmental destruction
v Automated attacks or hackers on the Internet

963
v Automated attacks from compromised systems in your intranet
v Interfaces with less secure systems
v Mistakes made by untrained or poorly trained users and administrators
v Data interception or alteration for criminal profit
v 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.

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:
v Limits on physical access to your servers
v Network access and protection
v Messaging infrastructure, through the use of execution control lists and anti-virus products
v Application security, through encryption and ACL management
v Encryption key management, including ID recovery
v Change control, through the use of the Domino Change Manager (or you can build your own)
v User training for organizational security rules and technology
v Security incident reporting

For more information on change control, see the chapter ″Using Activity Trends.″

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:

v Incident reporting plans and methods
v Response procedures for each incident type
v Incident response tests

Once you have your incident-handling plans in place, you will be better able to determine your
requirements for:
v Domino logging
v Domino HTTP logging
v Domino backup and restoring
v 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.″

964 Lotus Domino Administrator 7 Help

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:
v Domino security basics
v Notes IDs and how to them
v Notes Execution Control Lists and Execution Security Alerts
v Use of encryption and how to encrypt a mail message
v 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.

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.

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

Chapter 39. Planning Security 965

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:

v Breaking through into the network and accessing the server via the operating system and its native
services (such as file sharing).
v Impersonating an authorized Notes user
v 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.

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.
966 Lotus Domino Administrator 7 Help
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.

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:
v 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.
v Guidelines provide overall guidance on how to support and maintain security in the enterprise.
v 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.
v 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.

Most companies will have a matrix of responsibility similar to the one below:

Role Responsibility
CEO The CEO needs to be a virtual member of the team. Security
must flow from the both the top-down and the bottom-up.
CIO / CTO 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.
Security officer This person will be the driver of security in the organization.
Representatives from each functional department These representatives specify business needs and requirements.
They must have decision-making authority.

Chapter 39. Planning Security 967

Role Responsibility
Accounting They will provide the information for risk analysis.
IT Department These team members can translate business needs and
requirements into technology.
HR / Training HR needs to assist with user training. HR is also involved with
background checks, privacy of personal information, and
termination policies and procedures.
Legal These team members provide information on the legal
implications of anything to do with employees, risk
management, or publication of information.
Documentation experts/ technical writers This group creates and edits the documents.
Incident Response Team This team will handle incidents that are not covered by
implemented security practices.
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.

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.

968 Lotus Domino Administrator 7 Help

For more information on setting up administrator access to a Domino server, see the chapter ″Controlling
Access to Domino Servers.″

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.
v Server security
v Application security
v Application design element security
v Notes and Domino ID security
v Workstation security

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
Cross-certify Notes user IDs and Domino server and
certifier IDs
Allow or deny access to a server
Allow anonymous server access
Use
Set up a certifier that will be used to issue Internet
certificates in your organization.
Allow Notes users and Domino servers in different
hierarchically certified organizations to ascertain the identity
of users and servers in other Notes organizations.
Specify which Notes users, Internet clients, and Domino
servers are authorized to access the server.
Give server access to Notes users and Domino servers
outside of the organization without issuing a
cross-certificate.

Chapter 39. Planning Security 969

Task
Allow anonymous Internet/Intranet client access
Secure the server with name-and-password
authentication
Enable session-based authentication
Controlling the level of authentication for Web clients Specify the level of refinement that the server should use
Limit access to create new databases, replicas, or
templates
Control access to a server’s network port
Encrypt server’s network port
Password protect the server console
Restrict administrator access
Restrict server agents
Restrict passthru access
Restrict server access by browser users running Java
or JavaScript programs
Secure the server with SSL
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
970 Lotus Domino Administrator 7 Help
Use
Determine whether Internet/intranet users are allowed to
access the server anonymously.
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.
when searching for names and authenticating Web users.
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.
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.
Specify which Notes users and Domino servers can access
the server as a passthru server and specify the destinations
they may access.
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.
Task
Authenticate Web clients for a specific realm
Locate the server in a secure area
Secure the server console with a Smartcard
Use a firewall to protect access to a server
Restrict access to a server’s data directory
Use
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.
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.
Control unauthorized access to a private network from the
public Internet.
Use ACL files to protect server directories by specifying the
names of users authorized to access those directories.

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
Use the ACL to restrict application access Control Notes and Internet/intranet user and Domino server
access to an application.
Enforce a consistent ACL Protects databases and templates on the server by forcing all
changes to the ACL at a single location.
Encrypt applications Prevent unauthorized users from accessing an application
locally on a server or workstation.
Sign an application or template 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

Encrypt incoming and outgoing Notes mail
Electronically sign mail messages
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.
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.″

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 Use
Create Read access lists for views Specify which Notes and Internet/intranet users can see a
view

Chapter 39. Planning Security 971

Task
Create Read and Edit access lists for folders
Create Read and Edit access lists for forms
Create Readers and Authors fields
Create signed fields
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.
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
Compare a password with the password stored in
the Domino Directory and require users to change
their passwords periodically
Compare a Domino public key with the public key
stored in the Domino Directory
Recover lost or damaged IDs
Set up a security settings policy document
Lock the user ID after x minutes of inactivity
Use F5 to log off
Save user IDs on a disk instead of on the
workstation and keep disks in a safe place
Locate workstations in a secure area -- for example,
a locked room
Install Smartcard readers on user workstations and
have users log in to Notes with Smartcards
972 Lotus Domino Administrator 7 Help
Use
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
Specify which Notes and Internet/intranet users can create,
modify, or read specified documents
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
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
Prevent an unauthorized user from using an illicitly obtained
ID to authenticate with a server
Prevent an unauthorized user from using an illicitly obtained
ID to authenticate with a server
Regain access to a user ID file instead of issuing a new ID
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
Physically protect user IDs
Prevent unauthorized access to the ID files
Physically protect user IDs and private Internet keys
For more information on Smartcards, see the chapter ″Protecting and Managing Notes IDs.″For more
information on Smartcards, 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
Configure the Administration ECL and deploy to
client workstations.
Set up a security settings policy document
Encourage users to use operating system and screen
saver passwords
Encourage users to shut off workstations before
leaving
Use
Prevent unauthorized users from gaining access to data and
applications on client workstations, by defining authorized
users and authorized actions
Use security settings policy documents to:
v Set up and configure one or more administration ECLs
v Specify how and when you want workstation ECLs to be
refreshed or replaced
Discourage unauthorized workstation access
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.″

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

Chapter 39. Planning Security 973

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.

Internet certifiers: Domino vs. third-party

Internet certifier type Benefits
Domino certifier v Avoid the expenses that a third-party certifier charges to issue
and renew client and server certificates.
v Many administrators are already familiar with Domino, they will
not require additional training that would be needed to use a
third-party certifier.
v Easier and quicker to set up and deploy new certificates as
needed.
Third-party certifier (VeriSign, RSA, etc.) v Can simplify client configuration. If you get certificates from a
certifier that is pre-configured as trusted by the browsers you
use, it saves a step in client configuration.
v 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.

Domino Internet certifier type Benefits

Server-based certification authority
Domino 5 certificate authority
v Administrators can manage both Notes and Internet certifiers through
the CA process.
v Issues Internet certificates that are compliant with security industry
standards (such as X.509v3 and PKIX).
v 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.
v Supports the PKIX registration authority (RA) role, which allows
administrators to delegate the certificate approval/denial process.
v Issues certificate revocation lists (CRLs), which contain information
about revoked or expired Internet certificates.
v Required if you plan to use the Web Administrator client to register
Notes users.
v Can be set up to work with an IBM Workplace Collaboration Services
server to issue S/MIME signing certificates to Workplace users.
v Provides a simple means by which to set up an Internet certifier for
testing or demonstration purposes.

974 Lotus Domino Administrator 7 Help

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.

Chapter 39. Planning Security 975

976 Lotus Domino Administrator 7 Help
Chapter 40. Controlling Access to Domino Servers
This chapter includes information on setting up a Domino server to allow users and other servers to
access it.

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.

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

For more information, see the topic ″Denying Notes users access to all servers in a domain″ later in this
chapter.

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

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.

978 Lotus Domino Administrator 7 Help

3. In the Server Access section, complete one or more of these fields, and then save the document:

Field Enter
Access server 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:
v Names of users, servers, and groups.
v 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.
v An asterisk, followed by a certificate name -- for example, */Sales/East/Acme -- to allow
all users certified by a particular certifier to have access.
v 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.

Not access server Any of these:
v Names of users, servers, and groups.
v An asterisk, followed by a certificate name -- for example, */Sales/East/Acme -- to deny
access to all users certified by a particular certifier.
v 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.

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:
v Deny Notes users access to all servers in a domain.
v Restrict administrator access.

Chapter 40. Controlling Access to Domino Servers 979

v Compare public key values
v Set up anonymous server access.
v Control access to a specific server port.
v Control creation of databases, replicas, and templates.
v Control use of headline monitors.
v Control access to a passthru server or passthru destination.
v Control agents that run on a server.
v Control access by browser clients that use Java and Javascript
v Controlling Web browser access to files
v Controlling the level of authentication for Internet clients
v 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.ibm.com/developerworks/lotus/downloads/.

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.
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:
v Full access administrator -- gets all rights and privileges of all administration access levels listed.
v Administrator -- gets all rights and privileges of database administrator and full-console administrator
(but not system administrator).
v Full console administrator -- gets rights and privileges of view-only console administrator (but not
system administrator)
v System administrator -- gets rights and privileges of restricted system administrator

980 Lotus Domino Administrator 7 Help

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.
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
Full access administrators
Administrators
Database administrators
Full remote console administrators
Action
Enter the names of administrators who have full access to administer the
server. This is the highest level of administrative privilege. For more
information, see below.
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:
v Manager access to the Web Administrator database (WEBADMIN.NSF).
v Create, update, and delete folder and database links
v Create, update, and delete directory link ACLs
v Compact and delete databases
v Create, update, and delete full text indexes
v Create databases, replicas, and Master Templates
v Get and set certain database options (for example, in/out of service,
database quotas, and so on)
v Use message tracking and track subjects
v Use the console to remotely administer UNIX servers
v Issue any remote console command
Note: If you are using the (Java) Server Controller and you enter a group
name in this field, the group must have a group type of ″Multi-purpose″ to
allow the administrator names to appear in the Administrators field.
Note: For Domino 6.0 and subsequent releases, if the Notes.ini variable
Server_Restricted is used to restrict server access, administrators can still
open databases on the server.
Enter the names of administrators who will be responsible 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:
v Create, update, and delete Folder and Database links
v Create, update, and delete directory link ACLs
v Compact and delete databases
v Create, update, and delete full text indexes
v Create databases, replicas, and Master Templates
v Get and set certain database options (e.g., in/out of service, database
quotas, etc.)
Enter the names of administrators who can use the remote console to issue
commands to this server.

Chapter 40. Controlling Access to Domino Servers 981

Field Action
View-only administrators Enter the names of administrators who can use the remote 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.
System administrator Enter the names of administrators who are allowed to issue a full range of
operating system commands to the server.

Restricted system administrator
Restricted system commands
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 issue only the
operating system commands that are listed 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.″
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.

Administer the server from a browser
(Obsolete as of Domino 6)
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.
This setting applies only to pre-Domino 6 servers for the purposes of
backwards compatibility. The Domino Web Administrator client will only
work with Domino 6 and later servers. In the case where an existing
domain’s Domino Directory is upgraded from Domino 5 to a later release,
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:

v All the rights as listed for all administrator access levels (see above).

982 Lotus Domino Administrator 7 Help

v Manager access, with all access privileges enabled, to all databases on the server, regardless of the
database ACL settings.

Note: ACL roles must still be enabled manually for full access administrators.
v Manager access, with all roles and access privileges enabled, to the Web Administrator database
(WEBADMIN.NSF).
v Access to all documents in all databases, regardless of Reader names fields.
v The ability to create agents that run in unrestricted mode with full administration rights.
v 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.

Enabling full access administrator mode: In order to work in full access administrator mode, an
administrator must:
v Be using the Administrator Client.
v 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.
v 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.

Options for managing the full access administrator feature: There are several ways to grant full access
administrator
v 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.
v Create an OU-level certifier for granting full administrator access, and issue additional IDs to trusted
administrators -- for example, Jane Admin/Full Admin/Acme.
v 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.

Chapter 40. Controlling Access to Domino Servers 983

v Populate the Full Access Administrator field with a limited set of trusted administrators.

You can also track how this feature is used:

v Configure the Event Handler to send notification through EVENTS4.NSF when full access
administration privileges are invoked.
v Any database activity done using full access administrator access is recorded in the database activity
log, under Database Properties.
v Use of the feature is logged by the server.

Comparing public key values

The signatures on user and server certificates exchanged during authentication are always checked. You
can enable an additional level of verification for public keys, by having the value of the key passed in the
certificates checked against the value of the key listed in the Domino Directory. It is possible for users to
authenticate with a server, but have a mismatch between the value of the public keys in their certificates
and what is listed for them in the Domino Directory.

This extra level of key verification protects against misuse of a lost or compromised ID file. Typically, if
an ID file is lost, its owner needs to be registered to create a new ID file and directory entry; and if the
ID file has been compromised then the owner’s public and private keys need to be rolled-over and that
new set of keys need to be certified (thus updating the directory entry). By enabling directory-level key
checking, an attacker in possession of the old ID file will not be able to use it to access the server, even
though that old ID file may contain a valid certificate.

You can also choose to control whether a log message is generated if authentication succeeds but a
mismatch is detected. This allows admistrators to detect when the ID file contents have gotten out of
sync with directory entries, but to do so without preventing those users from authenticating because of
public key mismatches.

For more information on public key security, see the chapter ″Protecting and Managing Notes IDs.″
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, click the drop-down list next to ″Compare public keys″ and choose
one of the following options:
v Enforce key checking for all Notes users and Domino servers --to compare the key value in the
certificates passed during authentication against the key value stored in in the Domino Directory.
Any user or server not listed in a trusted directory will be treated as if it failed this verification
check and will not be allowed to access this server.
v Enforce key checking for Notes users and Domino servers listed in trusted directories only -- to
compare the key value in the certificates passed during authentication against the key value stored
in in the directory only when the user or server is listed in a trusted directory. Any user or server
not listed in a trusted directory will be treated as if it passed this verification check.

Note: This option allows administrators to give users not listed in the directory access to databases
and applications on the server. For example, a database may have its Access Control List configured
to give editor access enabled for users listed in the Domino Directory, and reader access for
everyone else. So if this key checking option is enabled, users not listed in the directory can still
access the server to use the database, for which they will have reader access only.
v Do not enforce key checking -- if you want only the certificate signatures checked during
authentication, but not verify the keys against the directory contents.
4. Click the drop-down list next to ″Log public key mismatches″ and choose one of the following
options:

984 Lotus Domino Administrator 7 Help

 v Log key mismatches for all Notes users and Domino servers -- to log events that occur when the
key value in the certficates passed during authentication does not match the key value stored in the
Domino Directory.
v Log key mismatches for Notes users and Domino servers listed in trusted directories only -- to log
events that occur when the key value in the certficate passed during authentication does not match
the key value stored in the directory only when the user or server is listed in a trusted directory.
v Do not log key mismatches -- to log only authentication failures.
5. Stop and restart the server so that the changes take effect. The server polls every hour to see if these
settings have changed, so if the server is not restarted it may be as long as an hour before the new
settings take effect.

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.″
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 -Default- access.
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:

v Allow_Access_portname = names
v 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.

Chapter 40. Controlling Access to Domino Servers 985

2. Click the Security tab.
3. In the Server Access section, complete one or more of these fields, and then save the document:
Field
Create databases and templates
Create new replicas
Create master templates
For information on creating groups, see the chapter ″Setting Up and Managing Groups.″
986 Lotus Domino Administrator 7 Help
Action
Enter any of these:
v Names of specific servers, users, and groups.
v An asterisk (*) followed by a certificate name -- for example,
*/Sales/East/Acme -- to allow all users certified by a particular certifier to
create databases.
v 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
databases on the server.
Separate multiple names with commas or semicolons.
Enter any of these:
v Names of specific servers, users, and groups.
v An asterisk (*) followed by a certificate name -- for example,
*/Sales/East/Acme -- to allow all users certified by a particular certifier to
create replicas.
v 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 databases on the server (see
above) cannot create new 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.
Enter any of these:
v Names of specific servers, users, and groups.
v An asterisk (*) followed by a certificate name -- for example,
*/Sales/East/Acme -- to allow all users certified by a particular certifier to
create templates.
v 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 only administrators can create
master database templates on the server.
Separate multiple names with commas or semicolons.
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 7 Help.

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 both of these fields, and then save the document:

Field Action
Allowed to use monitors Enter any of these:
v Names of specific users and groups.
v 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.
v 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 Enter any of these:
monitors v Names of specific users and groups.
v An asterisk (*) followed by a certificate name -- for example, */Sales/East/Acme -- to
prevent users certified by a particular certifier from using monitors.
v 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.″

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.
Chapter 40. Controlling Access to Domino Servers 987
2. Click the Security tab.
3. In the Passthru Use section, complete one or more of these fields, and then save the document:

Field Action
Access this server Enter any of these:
v Names of specific servers, users, and groups.
v 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.
v 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.

Route through Enter any of these:
v Names of specific servers, users, and groups.
v 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.
v 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.

988 Lotus Domino Administrator 7 Help

Field Action
Cause calling Enter any of these:
v Names of specific servers, users, and groups.
v An asterisk (*) followed by a certificate name -- for example, */Sales/East/Acme -- to
allow all users certified by a particular certifier to initiate calling.
v 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.
Destinations allowed 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.
3. In the Programmability Restrictions section, complete one or more of these fields, and then save the
document:

Chapter 40. Controlling Access to Domino Servers 989

Field Action
Run unrestricted methods Enter the names of users and groups who are allowed to select, on a per agent basis,
and operations 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 7 to build an
agent:
v restricted mode
v unrestricted mode
v 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).
Note: 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 on Enter the names of users and groups who are allowed to sign agents that will be
behalf of someone else executed on anyone else’s behalf. The default is blank, which means that no one can
sign agents in this manner.
Note: 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 Enter the names of users and groups who are allowed to sign agents that will be
behalf of the invoker of executed on behalf of the invoker, when the invoker is different from the agent signer.
the agent 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).
Run restricted Enter the names of users and groups allowed to run agents created LotusScript and Java
LotusScript/Java agents features, but 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 Enter the names of users and groups allowed to run to run simple and formula agents,
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.
Sign script libraries to run Enter the names of users and groups who are allowed to sign script libraries in agents
on behalf of someone else executed by someone else. For the purposes of backwards compatibility, the default
value is to leave the field empty, to allow all.

Controlling server access by browser clients that use Java and JavaScript
Note: These settings are for use only with pre-Domino 6.0 servers. They should not be used with
6.0

a Domino 6 or later 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 7 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:

990 Lotus Domino Administrator 7 Help

Field Action
Run restricted Enter the names of authenticated browser users and/or groups allowed to run server
Java/JavaScript/COM 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 and/or groups allowed to run server
Java/JavaScript/COM programs created with all Java and JavaScript features.

Leave the field blank (default) to deny access to all users and groups.

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:
v File protection documents
v Web realms

Restricting access to a server’s data directory

By default, any Notes user who can access a server can access the server’s entire 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, or ACL file, for it. ACL files are an option for protecting server directories, and contain the
names of users authorized to access those directories.

In order to use ACL files, you need to set the Notes.Ini variable Enable_ACL_Files=1. For more
information, see the chapter ″Appendix C: Notes.INI File.″

Note: ACL files are different than the access control list (ACLs) used to manage Notes databases,
although both serve the same function of restricting access to the directory or database, respectively, they
protect.

Creating a data directory access list:

1. Make sure you have at least database administrators access to the server.
2. In the Domino Administrator, click the Files tab.
3. In the left pane, select the directory to which you are restricting access.

Note: The access restrictions apply to any subdirectories of the directory as well.
4. In the Tools pane on the right, select Folder - Manage ACL. The Manage Directory ACL dialog box
appears.
5. Below ″Who should be able to access this directory?″ click the person icon. Do the following for each
name that you want to allow to access the directory:
v 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.
v Click Add.
6. When you are finished defining the access list, click OK.
7. Click OK again. In the left pane, the directory icon now appears with a padlock.

Changing or deleting a data directory access list:

1. Make sure you have at least database administrators access to the server.
2. In the Domino Administrator, click the Files tab.
3. In the left pane, select the directory with the ACL that you want to change. The directory icon has a
padlock.

Chapter 40. Controlling Access to Domino Servers 991

4. In the Tools pane on the right, select Folder - Manage ACL. The Manage Directory ACL dialog box
appears.
5. Do one of the following:
v To remove a name from the access list, below ″Who should be able to access this directory?″ select
the name and then click the red X. To delete the access list entirely, remove each name from the list.
v 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.
6. Click OK to save your changes.

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:
v Use the server without a mouse, and keep the keyboard locked.
v 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.
v 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.″
v 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.
v Use operating system features to secure data files and lock keyboard access. For more information, see
your operating system documentation.

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.

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:

v Have the Domino server workstation on, but do not launch the Domino server software.
v 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.

992 Lotus Domino Administrator 7 Help

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

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

Chapter 40. Controlling Access to Domino Servers 993

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.

994 Lotus Domino Administrator 7 Help

Chapter 41. 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:
v The owner’s name. A user ID file may also contain one alternate name. A certifier ID may contain
multiple alternate names.
v 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.
v 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.
v 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.
v (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.
v (Optional) One or more secret encryption keys, created and distributed by users to allow other users to
encrypt and decrypt fields in a document.

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:
v The name of the certifier that issued the certificate.
v The name of the user or server to whom the certificate was issued.
v 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.
v A digital signature.
v 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

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

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 Issued to
/Sales/East/Acme (International) Alan Jones/Sales/East/Acme
/Sales/East/Acme (North American) Alan Jones/Sales/East/Acme
/East/Acme /Sales/East/Acme
/Acme /East/Acme
/Acme /Acme
CN=AcmeCA/OU=East/O=Acme/L= EMAIL=alan_jones@acme.com/
Cambridge/ST=Massachusetts/C=US CN=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.
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.

996 Lotus Domino Administrator 7 Help

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

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

Chapter 41. Protecting and Managing Notes IDs 997

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.

128-bit ID file encryption

Notes keys are stored encrypted in the Notes ID file, and are encrypted with a key derived from the ID
file password. Prior to Domino 7, this key was 64-bits wide. In Domino 7, users have the option of using
a 128-bit key for ID file encryption. As the ID file can now store larger document encryption keys, the
encryption used to store them will be as least as strong as the stored keys.

For more information on 128-bit ID file encryption, see the topic ″Using 128-bit ID file encryption″ later in
this chapter.

For more information on larger document encryption keys, see the chapter ″Encryption and Electronic
Signatures.″

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.

998 Lotus Domino Administrator 7 Help

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

For information on how to secure the Domino server console with a Smartcard, see the chapter ″Planning
Security.″

Custom password policies

Many current information protection and data privacy laws include specific requirements for the selection
of secure passwords for identity verification. In order to help users comply with these laws, the ability to
implement password restrictions on a policy basis has been added to Lotus Domino 7. The new feature
enables users to meet the essence of these laws - that passwords must not be trivial or predictable.

You create and apply custom password policies through a security policy settings document.

For more information, see the topic ″Custom password policies″ later in this chapter.

Single password log-on to Notes client for IBM Workplace

Users of IBM Workplace Managed Client 2.6 or later may have the option of using the Notes plug-in,
through which they can access Notes databases and applications. In order to avoid having to be
repeatedly prompted for their Notes passwords, Domino administrators can enable the ability for
Workplace users to specify that the Workplace client ’remember’ the Notes password when accessing
Notes applications, through a security settings policy document . Then, the first time Workplace users
attempt to access Notes, they can enable this feature in the Notes User Security dialog box.

For more information on configuring the security settings document, see the chapter ″Using Policies.″

For more information on how to set up the Notes plug-in in IBM Workplace Collaborative Services, see
the IBM Workplace Information Center.

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.

Chapter 41. Protecting and Managing Notes IDs 999

Password quality scale Description Example
0 Password is optional. None.
1 Allow any password. ″b″, ″3″
2-6 Allow a weak password, even though ″password″, ″doughnut″ (password quality
you might be able to guess it by trial scale 3)
and error.
″lightferret″, ″b 4D″ (password quality scale
6)
7-12 Require a password that is difficult to ″pqlrtmxr″, ″wefourkings″ (password quality
guess, but might be vulnerable to an scale 8)
automated attack.
13-16 Require a strong password, even ″4891spyONu″ (password quality scale 13)
though the user may have difficulty
remembering it. ″lakestreampondriverocean″, ″stRem2pO()″
(password quality scale 15)

″stream8pond1river7lake2ocean″ (password
quality scale 16)

Tips for assigning passwords and scale

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

1000 Lotus Domino Administrator 7 Help

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). If Notes
and Internet passwords are synchronized, then any changes to Notes password settings may affect
Internet passwords.

For more information on Notes and Internet password synchronization, see the chapter ″Using Policies.″

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.

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 hash of an RSA public key, which is derived from the hash
of the Notes password and some other secret information stored in the ID file, 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:

Chapter 41. Protecting and Managing Notes IDs 1001

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.

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:
v The Administration Process is set up on the server
v You have at least Editor access and the UserModifier role in the Domino Directory.
v 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.

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.

1002 Lotus Domino Administrator 7 Help

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

Using 128-bit ID file encryption

Users can opt to change their ID file encryption strength when they change their passwords. However,
changing the ID file encryption strength requires that the password be changed, as well, as the key is
derived from the password.

To configure 128-bit file encryption

1. In the Notes client, click File - Security - User Security. The User Security panel appears.
2. Type your password.
3. The current ID file encryption strength appears in the section ″Who You Are.″ To change this value,
click Change Password. The Change Your Password dialog box appears.
4. Type and re-type your new password.
5. In the Encryption Strength drop-down box, select the encryption strength you want to enable.
6. Click OK. This changes the password and sets the ID file encryption strength to the chosen value.

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.

Chapter 41. Protecting and Managing Notes IDs 1003

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

Note: You can only use the ID recovery process to recover user ID files. You cannot recover certifier 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.

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:
v At registration, administrators create the ID file with a certifier ID that contains recovery information.

1004 Lotus Domino Administrator 7 Help

v Administrators export recovery information from the certifier ID file and have the user accept it.
v (Only for Domino 6 servers and higher) Administrators change recovery information using a Domino 7
Administrator client. Subsequently, recovery information is added automatically to users’ Notes IDs
when users authenticate to their home server.

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.

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.

In Domino 7, you can select the number of characters, or password length, for recovery passwords, which
helps determine password strength, or likelihood to be compromised. A password length that is less than
16 is calculated using both alphanumeric characters and hexadecimals. Sixteen-character length
passwords are generated using hexadecimals only. While password strength is important, as a strong
password is less likely to be compromised, so is usability. A long and complex password can be difficult
to use, so administrators also have the ability to choose a shorter password length.

In addition, administrators can now configure a custom message to help walk users through ID recovery.

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.

Chapter 41. Protecting and Managing Notes IDs 1005

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. In the
case of a server-based certificate authority , the recovery database will be updated once the user has
connected to the server. Recertifying a user does not generate an encrypted copy of the ID file to be sent
to the recovery database, as a user’s Person Document already contains the updated public key.

If a user has been renamed by or moved to a different certifier that contains recovery information that is
older than that of the user’s previous certifier, the new certifier’s recovery information will not be
accepted into the user’s ID file. Before using the new certifier, its recovery information must be updated
so that it is more recent than the previous certifier’s recovery information. To do this, the administrator
should modify the new certifier’s recovery information in some way and save it. This updates the
recovery information for that certifer with a new timestamp, and ensures that users who are subsequently
renamed with or moved to the updated certifier will have the correct recovery information propogated to
their user IDs. The administrator can then undo the change, if desired.

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. As of Domino 6, re-accepting recovery information happens automatically
when the user accesses a database on the home server. Changing the public key changes the public and
private keys stored in the ID file.

ID recovery logging
As of Domino 7, important information about client ID recovery activities are automatically logged to the
local log.nsf file so that this information is available to administrators for troubleshooting purposes.

The following ID recovery information will be logged locally.

v Date and time when recovery information is accepted into the ID file.
v Instances when recovery information is rejected or fails to be accepted in the ID file.
v Events that require a new backup to be mailed to the ID recovery database.
v Emailing the recovery ID to the recovery database (successes and failures)

Setting up ID recovery
Before users can recover their ID files, you must set up ID recovery. 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.
v 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.

1006 Lotus Domino Administrator 7 Help

 v 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. Select the length of the recovery password from the drop-down list. The default is 16 characters.
8. Click Add and select the names of the administrators who are the designated recovery authorities.
9. Choose whether you want to use an existing mailbox for recovery information or create a new one.
v 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.
v 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.
10. In the Custom Recovery Message field, type a customized message for the ″Enter passwords″ dialog
box that appears during the ID recovery process. For example, you may want to specify help desk
contact information. Message length is limited to 512 characters.

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.
11. Click OK.
12. 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.
13. 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:
v (Only for Domino 6 servers and later) 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.
v 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.

In Domino 7, users can determine whether recovery information is present in their user ID by seeing
whether the ″Mail Recovery ID″ button on the User Security dialog box is active. They can then click the
button to send an encrypted backup of the user ID to the centralized mail or mail-in database.

Chapter 41. Protecting and Managing Notes IDs 1007

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.
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.
v If you are using a server-based certification authority, click ″Use the CA process″ and select a
certifier from the drop-down list.
v 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 Enter
To Names of users and groups whose ID files you want to back up.
CC Names of users and groups to whom you want to send a copy of the message.
Subject 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.
Memo 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.

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.
3. Complete these fields, and then click Send.

Field Enter
To 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.
CC Names of users and groups to whom you want to send a copy of the message.
Subject 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:
v Backup of newly changed recovery information for user name
v Backup of recent changes to ID file for user name
Memo 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.

1008 Lotus Domino Administrator 7 Help

Use the Notes.ini variable ID_Recovery_Suppress_Recovery_ Msg to suppress the creation of the recovery
memo, if you want to suppress the standard message that appears on the recovery email and replace it
with a custom message.

For more information, see the chapter ″Appendix C: Notes.INI File.″

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.

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.
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, it is recommended that administrators
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. Note the recovery password. Give the user the recovery password that is displayed.

Note: The Extract Recovery and Recover ID File dialog boxes now display timestamp information for the
recovery information contained in the copy of the ID file being recovered. Each time recovery information
is generated or regenerated for an ID file, the recovery passwords all change. Occasionally, the recovery
cookie acquired by an administrator can’t unlock a user’s ID file; the recovery information had been
regenerated at some point, and administrator is using a copy of the ID file that has a different set of
recovery information. In situations like this, administrators can check the timestamp information
displayed in these dialog boxes to see if they are trying to recover an ID file with outdated recovery
information.

Chapter 41. Protecting and Managing Notes IDs 1009

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. For Notes/Domino 6.0 or later users, the updated
recovery information is authomatically accepted into the ID file the next time the users authenticate with
their home servers by accessing a database on the server.

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.
v If you are using a server-based CA, click ″Use the CA process″ and select a certifier from the
drop-down list.
v 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:
v To delete an administrator, highlight the administrator’s name, and then click Remove.
v 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.″

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, so that users can still use their old keys to decrypt encrypted email.

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.

1010 Lotus Domino Administrator 7 Help

Note: This is done in addition to the key verification done by validating the certificate presented by the
user during authentication.

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:
v 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.″
v 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.

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

In Domino 7, administrators can use the key rollover process for creating new public keys through a
security settings policy document. Users can also trigger key rollover through the User Security dialog
box.

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 Create New Public Keys dialog box, users can choose the new key strength and the method for
requesting the certificate.
5. If the user chooses ″Authentication Protocol,″ then the next time the user authenticates with their
home server, the keys are created and the certificate request is automatically entered into the server’s
Administration Requests database.
At this point, the administrator needs to complete the certification process as described in the topic
″User and server key rollover″ in this chapter.
6. If the user chooses ″Mail Protocol,″ then the keys are created immediately, and the New Public Keys
Confirmation dialog box appears.
7. In the New Public Keys Confirmation dialog box, click Continue to use Notes mail to send your
request for adopting new public keys.

Chapter 41. Protecting and Managing Notes IDs 1011

 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.
8. In the Mail New Public Key Request dialog box, address the request to one of the following:
v The certification administrator for the certifier.
v 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.
9. 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.
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 one of the following in the ″Compare public keys″ field:
v Enforce key checking for all users -- check all users’ public keys
v Enforce key checking for users in trusted directories only - only check public keys for users listed in
the Domino Directory.
v Do not enforce key checking - select only if you do not want to verify users public keys
4. Select one of the following in the ″Log public key mismatches″ field:
v Log key mismatches for all users -- to log any public key mismatch to the
v Log key mismatches for users in trusted directories only -- only log mismatches for users listed in
the Domino Directory
v Do not log key mismatches
5. Save the document.
6. Restart the server so that the changes take effect.

1012 Lotus Domino Administrator 7 Help

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).″
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.
4. Copy the public key from the clipboard, and paste it into one of the following fields:
v Certified public key field (hierarchical Domino certificates)
v (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.

Chapter 41. Protecting and Managing Notes IDs 1013

User and server key rollover
Key rollover is the process used to update the set of Notes public and private keys that is stored in user
and server ID files. Periodically, this set of keys may need to be replaced - as a precaution against
undetected compromise of the private key; as a remedy to recover from a known compromise of the
private key; or to increase security by updating to a larger key.

You configure triggers to initiate user key rollover through a security settings policy document, and for
the server key rollover, in the Server document. Triggers include:
v Existing key size
v Issue date of existing key
v Age of existing key

Prior to Domino 7, new keys could only be requested by individual users via email or by authenticating
with the server. In Domino 7, key rollover gives administrators the ability to deploy replacement keys to
groups of users through a security settings policy document

For more information on configuring triggers for user key rollover through a security settings policy
document, see the chapter ″Using Policies.″

Notes 7 users can also trigger key rollover through the ″Create New Public Keys″ button on the User
Security dialog box. If they choose ’Authentication protocol’ to as the certificate request method, the
current keys are rolled over just as if it were triggered by a policy setting. If they choose ″Mail Protocol,″
the R6 and earlier mail method is used.

For more information on how users can trigger key rollover, see Creating a new Notes public key and
adding it to the Domino Directory.

For more information on how users can trigger key rollover, see ″Creating a new Notes public key and
adding it to the Domino Directory″ in this chapter.

When a policy has been established, or if the user has triggered key rollover through the User Security
dialog box, the next time the user authenticates with the home server, key rollover information is written
to the ID file. When a trigger condition occurs, key rollover is initiated and new keys are created in the
user ID file and marked pending. When the user authenticates with the home server after the
new/pending keys are generated, a Certify New Key Request is created in the Administration Requests
database.

To complete the key rollover process:

1. In the Domino Administrator, open the Administration Requests database.
2. In the Certify New Key Requests view, select the request for the user, and then click Certify Selected
Entries.
3. In the Choose a Certifier dialog box, do one of the following:
v If you are using a server-based certification authority, choose one from the drop-down list.
v If you use the certifier ID, provide the certifier ID location and password.
When the request is completed and the new keys are certified, the Person document is updated with
new key and certificate information.
4. In the Certificate Expiration Date dialog box, verify that the date is correct and click OK.
5. In the Processing Statistics dialog box, verify that there are no failures and click OK.

When the user next authenticates with the home server, a dialog box appears, asking the new user if they
want to accept the new public keys. The user must click OK to accept the new certificates. The
new/pending keys in the user’s ID file are activated and the old keys are archived.

1014 Lotus Domino Administrator 7 Help

Note: The archived keys remain in the ID file so they are available to decrypt documents that were
encrypted with that key.

To configure server key rollover

1. In the Server document, click Administration.
2. Under Public Key Requirements, complete the following fields:

Field
Minimum Allowable Key
Strength
Maximum Allowable Key
Strength
Preferred Key Strength
Maximum Allowable Age for
Key (in days)
Earliest Allowable Key Creation Any key created prior to this date will be rolled over.
Date
Don’t automatically generate a
new key before
Maximum number of days the
old key should remain valid
after the new key has been
created
Action
Specify the weakest key size allowed. Keys weaker than this will be rolled over.
v No minimum (default).
v Maximum compatible with all releases (630 bits).
v Compatible with Release 6 and later (1024 bits).
Specify the strongest key size allowed. Keys stronger than this will be rolled over.:
v Minimum (512 bits)
v Maximum compatible with all releases (630 bits).
v Compatible with Release 6 and later (1024 bits) (default).
Specify the key strength to be used when a key is rolled over:
v Minimum (512 bits).
v Maximum compatible with all releases (630 bits).
v Compatible with Release 6 and later (1024 bits) (default).
Specify the maximum age a key can reach before needing to be rolled over.
Specify the earliest date on which keys not meeting key width requirements can
be rolled over
Specify the length of time that the old key can be used during network
authentication. During Notes key verification, all of the certificates, old and new,
and all of the rollover keys are organized into a tree. That tree is traversed looking
for a set of certificates that can be chained together to verify the key. If a certificate
has expired, it cannot be used in that chain. When rolling over a key because you
fear that it has been compromised, it is a good idea to set a short value for the
length of time the old certificates issued to that key can be used. Valid values for
this setting are 1 to 36500 days, and the default is 365.

3. Close and save the document.. Key rollover information is written to the server ID file. When a
trigger condition occurs, key rollover is initiated and new keys are created in the server ID file and
marked pending.
4. Restart the server.
5. In the Domino Administrator, open the Administration Requests database.
6. In the Certify New Key Requests view, select the request for the server, and then click Certify
Selected Entries.
7. In the Choose a Certifier dialog box, do one of the following:
v If you are using a server-based certification authority, choose one from the drop-down list.
v If you use the certifier ID, provide the certifier ID location and password.
8. In the Certificate Expiration Date dialog box, verify that the date is correct and click OK.
9. In the Processing Statistics dialog box, verify that there are no failures and click Ok.
10. At the server console, type ″tell adminp process all″ to complete the key certification processing.
11. Type ″restart server.″ Restarting the server causes the server to read its configuration and accept the
new certified keys.

Chapter 41. Protecting and Managing Notes IDs 1015

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

1016 Lotus Domino Administrator 7 Help

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 different organization, and the user does not already have a
cross-certificate issued to that server or one of its ancestors, 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 different organization and the recipient does not
already have a cross-certificate issued to that server or one of its ancestors, 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.

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

Chapter 41. Protecting and Managing Notes IDs 1017

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

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.

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:

1018 Lotus Domino Administrator 7 Help

 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 Enter
Certifier 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.
Server 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.
Subject name 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.
Subject alternate name list 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.
Expiration date Date when the cross-certificate will expire.

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

Chapter 41. Protecting and Managing Notes IDs 1019

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

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.

1020 Lotus Domino Administrator 7 Help

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 Enter
Certifier Name of your organization’s certifier ID
Server Location of the Domino Directory where you want to copy the cross-certificate
Subject name Organization or organizational unit certifier to be cross-certified -- for example,
/Acme
Subject alternate name list An alternate name that identifies the certifier ID. Alternate 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

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 Enter
Subject name Organization or organizational unit certifier to be cross-certified -- for example,
/Acme
Subject alternate name list 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.
Expiration date Date when the cross-certificate will expire
Certifier File name of your organization’s certifier ID
Server Location of the Domino Directory where you want to copy the cross-certificate

Chapter 41. Protecting and Managing Notes IDs 1021

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:
v From the Domino Administrator, click People & Groups, and open the Person document for the
user you are cross-certifying.
v In the Personal Address Book, open the Contact document for the user you are cross-certifying.
2. Choose Actions - Create Cross Certificate.
3. In the Create Cross Certificate dialog box, choose the certificate to cross-certify.
4. In the Issue Cross Certificate dialog box, complete these fields and then click Cross Certify:

Field Enter
Certifier 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.
Server 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.
Subject name 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.
Subject alternate names 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.
Expiration date Date when the cross-certificate will expire.

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

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. In the Choose a Certifier dialog
box, select the certifier with which you want to create a cross certificate.
2. Select the user ID to be cross-certified.
3. In the Issue Cross Certificate dialog box, complete these fields and then click Cross Certify:

Field Enter
Certifier 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.
Server 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.
Subject name 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.
Subject alternate name list 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.
Expiration date Date when the cross-certificate will expire.

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

1022 Lotus Domino Administrator 7 Help

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:
v Internet certifiers
v Notes certifiers
v Notes cross-certificates
v Internet cross-certificates

Certificates whose type cannot be determined are listed as Unknown.

Chapter 41. Protecting and Managing Notes IDs 1023

1024 Lotus Domino Administrator 7 Help
Chapter 42. 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:
v An access level
v Access level privileges
v A user type
v 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.″

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:
v -Default-
v Database creator user name
v LocalDomainServers
v OtherDomainServers

Of the default ACL entries, the database creator’s user name is the only entry that is automatically
defined as a Person in the ACL.

1025
The -Default- entry is the only entry that is 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. -Default- is created as an ACL entry only when the
database is created.

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

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.

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.

Acceptable entries in the ACL

Acceptable entries in the ACL include:
v Wildcard entries
v User, server, and group names (including user and group names of Internet clients)
v Alternate names
v LDAP users
v Anonymous, used for anonymous Internet user access and anonymous Notes user access
v 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.″

1026 Lotus Domino Administrator 7 Help

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

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

Chapter 42. Controlling User Access to Domino Databases 1027

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 LDAP Directory that has been configured for group authorization in the Directory Assistance
database.

Note: Be sure that any group names you use in an ACL comply with the specified guidelines for creating
them. The use of erroneous names may cause access problems.

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:
v 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.
v If you need to change the access level for several users or servers, you can do so once for the entire
group.
v 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 your 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.″For
more information on the Deny Access list, see the chapter ″Controlling Access to Domino Servers.″

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.

1028 Lotus Domino Administrator 7 Help

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

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

Chapter 42. Controlling User Access to Domino Databases 1029

Acceptable ACL entries for LDAP users
LDAP DN
cn=Scott Davidson+ id=1234,
ou=Sales,o=Acme
cn=Scott Davidson,o=Acme\, Inc
uid=smd12345,dc=Acme,dc=Com
uid=Sandra Smith,o=Acme,c=US
ACL entry
cn=Scott Davidson+id=1234/ou=Sales/o=Acme
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=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.

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.

The table below describes the different conditions for access that an anonymous user would have to a
database:

Anonymous access enabled for Anonymous access not enabled for

Anonymous access enabled in
database ACL
Anonymous given ″no access″ in
database ACL
Internet protocol Internet protocol
Users access the database with the Users are prompted to authenticate
Anonymous entry’s access level. For when they attempt to access any
example, if Anonymous access is set resource on the server. If the user is
to Reader, anonymous users who not listed in the database (through a
access the database will be granted group entry, a wildcard entry, or if the
Reader access. user name is explicitly listed), then
the user accesses the database with
the -Default- entry’s access level.
If Anonymous has been granted ″No
Access″ (and the Read & Write
public documents privileges are not
enabled) Anonymous users are not
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.

1030 Lotus Domino Administrator 7 Help

 Anonymous access enabled for Anonymous access not enabled for
Internet protocol Internet protocol
Anonymous not listed in database Anonymous users access the
ACL database with the -Default- entry’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.

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.″
v 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, if the user is Sandra E Smith, whose hierarchical name is Sandra E Smith/West/Acme, and

Chapter 42. Controlling User Access to Domino Databases 1031

 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.
v 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.
v 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.
v If a group entry and a wildcard entry both apply to a user attempting to access the database, then the
user has the access assigned to the group entry. For example, if the group Sales has Reader access and
the wildcard entry */West/Acme has Manager access, and both entries apply to a user, then the user
has Reader access to the database.
v 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 7 Help.

Configuring a database ACL

1. Make sure that you have:
v Manager access in the database ACL.
v 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.

1032 Lotus Domino Administrator 7 Help

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.

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.
v Administrators who are designated as full access administrators in the Server document have manager
access to all databases, with all privileges enabled, on the server, regardless of whether they are listed
in the database ACLs. However, roles must still be enabled manually for full access administrators.

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

Chapter 42. Controlling User Access to Domino Databases 1033

This table shows the user access levels, listed from highest to lowest.

Access level Allows users to Assign to

Manager Modify the database ACL. Two people who are responsible for the
database. Then if one person is absent, the
Encrypt the database. other can manage the database.
Modify replication settings.

Delete the database.

Perform all tasks allowed by lower access levels.

Designer Modify all database design elements. A database designer and/or the person
responsible for future design updates.
Create a full-text search index.

Perform all tasks allowed by lower access levels.

Editor Create documents. Any user allowed to create and edit
documents in a database.
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.
Author Create documents if the user or server also has Users who need to contribute documents to
the Create documents access level privilege. a database.
When you assign Author 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.
Reader Read documents where there is a Readers field
in the form and the user name is specified in the a database but not create or edit documents.
field.
Depositor 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.
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.
Users who only need to read documents in
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.

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.

1034 Lotus Domino Administrator 7 Help

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.

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 Optional privileges

Manager Create documents Delete documents

Create private agents Replicate or copy documents

Create personal folders/views

Create shared folders/views

Create LotusScript/Java agents

Read public documents

Write public documents

Designer Create documents Delete documents

Create private agents Create LotusScript/Java agents

Create personal folders/views Replicate or copy documents

Create shared folders/views

Read public documents

Write public documents

Editor Create documents Delete documents

Read public documents Create private agents

Write public documents Create personal folders/views

Create shared folders/views

Create LotusScript/Java agents

Replicate or copy documents

Chapter 42. Controlling User Access to Domino Databases 1035

Access level Default privileges Optional privileges
Author Read public documents Create documents

Delete documents

Create private agents

Create personal folders/views

Create LotusScript/Java agents

Write public documents

Replicate or copy documents

Reader Read public documents Create private agents

Create personal folders/views

Create LotusScript/Java agents

Write public documents

Replicate or copy documents

Depositor Create documents Read public documents

Write public documents

Replicate or copy documents (only if

″Read public documents″ has been
granted)
No Access None Read public documents

Write public documents

Replicate or copy documents (only if

″Read public documents″ has been
granted)

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.

1036 Lotus Domino Administrator 7 Help

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.

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.

Note: Users who have this privilege can modify or delete any shared folder, view, or navigator in the
database, regardless of whether they created it. Use caution when granting this privilege.

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.

Note: If the privilege ″Read Public Document″ is granted to users have No Access or Depositor access,
you can also enable the privilege ″Replicate or copy document.″

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 documents

Select this privilege to allow users to:
v create a new local replica or local copy of a database;
v copy, print, or forward documents from the database, or parts of these documents; and
v select all text in a document opened in read mode.

Note: Deselecting this option is not a true security measure because users can still print using Ctrl+Print
Screen or they can open a document and copy data to the clipboard.

You can select this privilege for all access levels; for users with access levels of Depositor and No Access,
you can only enable this if ″Read public document″ has also been granted.

Chapter 42. Controlling User Access to Domino Databases 1037

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

1038 Lotus Domino Administrator 7 Help

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 The designer uses

Edit specific documents An Authors field
Edit specific portions of a document Sections
Read specific documents A Readers field or a read access list on the Security tab of
the Document Properties dialog box
View and read documents in a specific view View properties
View and read documents in a specific folder Folder properties
Read documents created with a specific form Form properties
Create documents with a specific form 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:
v To create a role, click Add, and type a name for the role.
v To rename a role, click Rename. In the Rename Role box, type a new name for the role.
v To delete a role, click Remove, and type the name of the role that you want to delete.

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.

Chapter 42. Controlling User Access to Domino Databases 1039

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
v Use the Administration Process
v Use the Web Administrator
v Edit entries in multiple ACLs
v View the list of all database ACLs on a server.

To monitor changes to ACLs

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

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.
1040 Lotus Domino Administrator 7 Help
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:
v 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.
v Have Manager access in the database ACLs of all the databases you want to modify.
v 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:
v Add an ACL entry
v Remove an ACL entry
v Rename an ACL entry
v Add, remove, or rename a database role
v View the ACL change history
v Create a new database on the server based on templates
v Create a new copy of the database
v Delete a database
v Compact a database
v Create or update a full-text index of a database
v 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.

Chapter 42. Controlling User Access to Domino Databases 1041

You can also use the Web Administrator to manage database ACLs. For more information, the topic see
″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.
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:
v To change the user type assigned to an entry, select the user type from the drop-down list.
v To change the access level assigned to an entry, select the access level from the drop-down list.
v 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.

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.
v The By Name list shows the ACL list by ACL entry name, then access level, and then database title.
v The By Level list shows the ACL list by access level, then ACL entry name, and then database title.
v The By Database list shows the ACL list by database name, then server, then access level, and then
ACL entry name.

1042 Lotus Domino Administrator 7 Help

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.

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.

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.

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.

Chapter 42. Controlling User Access to Domino Databases 1043

4. Click Tools - Database - Manage ACL.
5. Click Advanced.
6. Select the option ″Modify Consistent ACL setting.″
v To enforce a consistent ACL, select ″Enforce a consistent Access Control List across all replicas of
this database.″
v 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.
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:
v Specify maximum Internet name-and-password access.
v Require an SSL connection to a database
v Default entries in the ACL.

Preventing users from accessing forms and views in a Web

application
If you design a database application that users will access with a browser, you may want to restrict
browser users from using URL commands that would open forms and views in your application. For
example, you can design your application so that a servlet that uses forms or views will only use the
forms and views using URL commands. With the ″Don’t allow URL open″ property set, it will be
impossible for browser users to manipulate these application components using Domino URL commands.

To restrict users from opening parts of an application using URL commands

1. Select a database and choose Design - Design properties.
2. In the Web Access section of the Database properties box, select ″Don’t allow URL open.″

1044 Lotus Domino Administrator 7 Help

The set of URLs that gets restricted is http://Host/Database.nsf/*Command. This set of URLs includes
any command that will open a database such as http://Host/Database.nsf and all URL commands that
are prefixed with a ?, such as http://host/database.nsf?OpenDatabase. When this property is set, the
error displayed is:
Error 500
HTTP Web Server Lotus Notes Exception - You are not authorized to access that database.

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.

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

Chapter 42. Controlling User Access to Domino Databases 1045

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.

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.

1046 Lotus Domino Administrator 7 Help

Chapter 43. 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 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.
1. Choose File - Security - User Security. Macintosh OS X users: Notes - Security - User Security.
2. Click What Others Do, and select either Using Workstation, Using Applets, or Using JavaScript.

Note: You need to be in the appropriate ECL pane to see the effective access for that ECL. For
example, to see who has access in the JavaScript ECL, you would need to select the JavaScript ECL.
3. Click the ″Effective Session ECL″ button.
v The listbox on the left shows the users and groups who have access to this ECL for the duration of
this session.
v Select a name to see the user or group access rights. The check boxes on the right side of the dialog
box indicate the access rights for the selected name.

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:

1047
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:
v Do not execute the action -- to deny the signer access to perform the specified action.
v 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.
v Trust the signer to execute this action for this Notes session -- to allow the signer access to perform
the action for the duration of the user’s Notes session, until the user logs out or Notes or switches
to another Notes ID. This option does not modify the ECL.
v 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.
v 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.

Determining effective access

Users can also determine the ″effective access″ that a person or a group has to the workstation ECL by
clicking the ’Effective Access’ button on an ECL. Effective access is not always apparent, especially if
users enable ECL access for a Notes session. For example, a user may grant temporary access to a group
that designed a database application in which the user is working. This access is valid for the duration of
a session, but a session might last all day.

Note: If you restrict users’ abilities to change their ECL, the ″Effective Session ECL″ button will be
greyed out.

ECL security access options

There are three categories of access options for ECLs.
v Workstation security
v Java applet
v 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 If enabled, allows formulas and code to

Access to file system Attach, detach, read to, and write from workstation files
Access to current database Read and modify the current database

1048 Lotus Domino Administrator 7 Help

Access option
Access to environment variables
Access to network
Access to non-Notes databases
Access to external code
Access to external programs
Ability to send mail
Ability to read other databases
Ability to modify other databases
Ability to export data
Access to Workstation Security ECL
If enabled, allows formulas and code to
Use the @SetEnvironment and @GetEnvironment variables and
LotusScript methods to access the NOTES.INI file
Bind to and accept connections on a privileged port (a port outside the
range 0 to 1024), and establish connections with other servers
Use @DBLookup, @DBColumn, and @DBCommand to access databases
when the first parameter for these @ functions is a database driver of
another application
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
Read information in databases other than the current database
Modify information in databases other than the current database
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 If enabled, allows the applet to

Access to file system
Access to Notes Java classes
Access to network addresses
Printing
Access to system properties
Dialog and clipboard access
Process-level access
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.

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

Chapter 43. Protecting User Workstations with Execution Control Lists 1049
Window object classes are described in the following table:

Window object class Description Default

Source window
Other window from same host
Other window from different host
Controls JavaScript access to the Window Allow read and write access
object on the same page as the JavaScript
code. Selecting this option does not
prevent a 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 and write access
object on a different page from the
JavaScript code, but from a page using the
same host. 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 read and write access
object on a different page within a
frameset 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.
Note: 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.

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 Description Default

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

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

1050 Lotus Domino Administrator 7 Help

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.

Use these guidelines to create secure ECLs:

v 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.
v 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.
v 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.
v 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 Applies to Default access options

-Default- Formulas and code that contain a signature, and None
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.
-No Signature- Formulas and code that contain an invalid or None
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-.

Chapter 43. Protecting User Workstations with Execution Control Lists 1051
Signature Applies to Default access options
BT Mail and Calendar Every template related to Binary Tree Mail and Access to file system, Access to
Migration Tools/Lotus Calendar Migration Tools. current database, Access to
Notes Companion environment variables, Access to
Products If your organization isn’t using this tool, you can external code, Ability to read other
remove this entry from the ECL. databases, Ability to modify other
databases
Domino Unified Every template related to Domino Unified Access to current database, Access
Communications Communications Services. If your organization isn’t to environment variables, Access to
Services/Lotus Notes using this tool, you can remove this entry from the external code, Access to external
Companion Products ECL. programs, Ability to send mail,
Ability to read other databases,
Ability to modify other databases
Lotus Fax Every template related to Lotus Fax for Domino. Access to current database, Access
Development/Lotus to environment variables, Ability to
Notes Companion If your organization isn’t using this tool, you can read other databases, Ability to
Products remove this entry from the ECL. modify other databases
Lotus Notes Template Every template shipped with Domino and Notes. All
Development / Lotus
Notes For example, the signer matches this type only if it
has the Lotus Notes Template Development/Lotus
Notes signature.
Sametime Every template related to Sametime. All except Access to workstation
Development/Lotus security ECL
Note Companion If your organization isn’t using this tool, you can
Products 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 Applies to
*/Trusted Signers/Acme 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.
Phyllis Formulas and code that have Phyllis Spera/Sales/East/Acme as the signature.
Spera/Sales/East/Acme
For example, the signer matches this type only if the ECL contains the Phyllis
Spera/Sales/East/Acme signature.

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.

1052 Lotus Domino Administrator 7 Help

 For more information, see the topic ″Collecting information for a new administration ECL″ in this
chapter.
2. Edit the Administration ECL.
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.
10. To let users modify their workstation ECLs or enable Java applets from trusted senders, select
″Allow users to modify.″
11. Click OK.

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:
v All entries in the form */org, where org is a local domain/organization
v -Default-
v -No signature-
v Lotus Notes Template Development/Lotus Notes
Chapter 43. Protecting User Workstations with Execution Control Lists 1053
 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″ For ″Allowed″

*/org, where org is a local domain/organization Deselect all selected items.
-Default- Deselect all selected items. ″Default″ should have no permissions.
-No signature- Deselect all selected items.
Lotus Notes Template Development/Lotus Notes 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:
v Do not trust any actions with ″-No Signature-″.
v 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.

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

Administration ECL 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>

1054 Lotus Domino Administrator 7 Help

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.

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.

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 deploy 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.
v Use the @Refresh ECL function, through a memo or common database event
v 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.
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.

Chapter 43. Protecting User Workstations with Execution Control Lists 1055
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:
v Do not trust any actions with ″-No Signature-″
v 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.

1056 Lotus Domino Administrator 7 Help

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

Note: For users with records located in an external LDAP directory, password verification takes place
through an LDAP bind operation that can only succeed if the user has provided the correct password.

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

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

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:
v 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.
v Create a Person document for each user in the Domino Directory on the Domino server and assign an
Internet password to each user. It should be noted that users can be located instead in an external
LDAP directory that is accessible to Domino through Directory Assistance.
v Edit server database ACLs to give users access.

To enable basic name-and-password authentication for Internet Site documents

Note: Be sure the option for the use of Internet Sites is enabled in the Server document.
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.
3. In the Internet Site document, click Security.
v 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.

1058 Lotus Domino Administrator 7 Help

 v 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

Note: Be sure the option for the use of Internet Sites is not enabled 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:
v 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.
v 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.)

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 initial, Last name Enter the user’s first name, middle initial, and last name. The user’s
last name is required.

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1059
Field Action
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. As Domino uses the first name
in this field to validate a user in database ACLs, design access lists,
groups, and File Protection documents, the first name in this field
should be the user’s Domino distinguished name (DN). The second
name should be the common name (CN) portion of the DN.

For example, this field can contain these names:

v Alan Jones/Sales/Acme
v Alan Jones
v Al Jones
v 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.″

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 defined as
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 user’s name and password
information is sent over the network only the first time the user logs in to a server, not each time a
request is posted. After login, the user’s name and logon information is stored in a cookie in the user’s

1060 Lotus Domino Administrator 7 Help

browswer, and the browser sends the cookie to the server with each request. Before honoring a request,
the server verifies the information in the cookie and uses the cookie contents to identify the logged-in
user. The session is only valid within the browser in which the login was performed. If the user shuts
down the browser in which the session login took place, the user’s session will be ended and the cookie
will be destroyed.

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.

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.

Idle session timeout

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 7 provides features for managing Internet passwords for session-based authentication through
policy documents and custom password policies.

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

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1061
restarted or crashes, session information is lost, and then users must re-enter their names and passwords.
In the multi-server session setting, the session cookie might still be valid when a server is restarted (if the
cookie has not yet expired); however, the user must continue to access the server from the same browser
window in which the user’s logon was performed.

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:
v 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.
v Create a Person document for each user in the Domino Directory on the Domino server and assign an
Internet password to each user. It should be noted that users can be located instead in an external
LDAP directory that is accessible to Domino through Directory Assistance.
v 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
Session authentication
Idle session timeout
Maximum active sessions
Action
Select single server. This is disabled by default.
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.

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.
3. Complete these fields:

Field
Session authentication
Idle session timeout
Maximum active sessions
Action
Select single server. This is disabled by default.
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.

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:

1062 Lotus Domino Administrator 7 Help

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 initial, Last name Enter the user’s first name, middle initial, and last 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. As Domino uses the first name
in this field to validate a user in database ACLs, design access lists,
groups, and File Protection documents, the first name in this field
should be the user’s Domino distinguished name (DN). The second
name should be the common name (CN) portion of the DN.

For example, this field can contain these names:

v Alan Jones/Sales/Acme
v Alan Jones
v Al Jones
v 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.″

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 US-ASCII
ISO-8859-1
HTTP session authentication Any printable characters in Unicode Any printable characters in US-ASCII

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1063
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:
v Create the Domino Web Server Configuration database. If you do not create the database, Domino uses
a generic log-in form.
v Create a custom form.
v 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.

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 7 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:
v 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.)
v 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:
v 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.
v 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
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.

1064 Lotus Domino Administrator 7 Help

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 five cases that cause the Login form to appear are encoded in the field ″reasontype″ and include:
v Prompt for the user to log in, at which no error message will display.
v ″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.
v ″You provided an Invalid username or password. Please sign in again.″ The user has given an incorrect
name or password.
v ″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.
v ″User Name, your login has been invalidated due to a timing issue with the login server. (The servers
may need to have their clocks synchronized to resolve this.) Please sign in again.″ This occurs when
multi-server session authentication is configured and an idle session timeout is enabled. This message
indicates that the SSO servers do not agree on the current time, which may invalidate the user’s SSO
session.

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, and the user has supplied a user name and password. 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 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 LDAP Directory authentication

Full hierarchical name DN
Common name or Common name with CN= prefix CN or CN with CN=prefix
Not applicable UID or UID with UID= prefix
Alias name (a name listed in the User name field of the Person Not applicable
document, excluding the first name listed in the field)
Internet address (user’s e-mail address as listed in the Internet address Mail
field in the user’s Person document)

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1065
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 LDAP Directory authentication

Last name Surname
First name Givenname
Common name or Common name with cn=prefix Common name (CN) or CN with
CN=prefix
Full hierarchical name (canonical) DN
Full hierarchical name (abbreviated) DN
Short name UID or UID with UID=prefix
Alias name (a name listed in the User name field of the Person Not applicable
document, excluding the first name listed in the field)
Soundex number Not applicable
Internet address (user’s e-mail address as listed in the Internet address Mail
field in the user’s Person document)

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:
v Fewer name variations with higher security (default).
v 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 Description
Alan Jones Common name
Alan First name
Jones Last name
Ajones Short name
Alan Jones/Sales/East/Acme/US Full hierarchical name (abbreviated)
cn=Alan Jones/ou=East/ou=Sales/o=Acme/c=us Full hierarchical name (canonical)
cn=Alan Jones Common name with CN=prefix

1066 Lotus Domino Administrator 7 Help

Example Description
alan_jones@acme.com Internet (e-mail) address

If you want to authenticate Alan in an LDAP Directory, he can use a browser to enter the following
names:

Example Description
Alan Jones Common name
Alan Givenname
Jones Surname
Ajones UID
cn=Alan Jones, cn=recipients, ou=Sales, ou=East, Full hierarchical name (canonical)
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, c=us (valid Full hierarchical name (canonical)
for a Netscape Directory Server)
uid=ajones (valid for Netscape Directory Server) UID with UID=prefix
Alan Jones/Sales/East/Acme/US Full hierarchical name (abbreviated)
alan_jones@acme.com 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 Description
Alan Jones/Sales/East/Acme Full hierarchical name (abbreviated)
CN=Alan Jones Common name with CN= prefix
Alan Jones Common name
cn=Alan Jones/ou=East/ou=Sales/o=Acme/c=us Full hierarchical name (canonical)
alan_jones@acme.com Internet (e-mail) address

If you want to authenticate Alan in an LDAP Directory, he can use a browser to enter the following
names:

Example Description
AJones UID
Alan Jones 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) CN with CN=prefix
uid=ajones, ou=Sales, ou=East, o=Acme, c=us (valid for a DN
Netscape Directory Server)
uid=Ajones (valid for a Netscape Directory Server) UID with UID= prefix
alan_jones@acme.com LDAP mail attribute

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1067
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.

For clients in secondary LDAP directories, it is also possible to map the name in an LDAP directory to a
Domino name, using the field ″Attribute to be used as Notes distinguished name.″ In this case, the user
may login by specifying a valid LDAP name and password, and as a result of successful authentication is
known within Domino as the corresponding Notes distinguished name.

For more information, see the chapter ″Setting Up Directory Assistance.″

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.

Internet password synchronization with Notes passwords

You can synchronize the 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 enable Notes-Internet password synchronization for individual or 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.

If custom password policies have been established for Notes users in a security settings policy document,
and the security policy setting also specifies ″Update Internet password when Notes passwords change,’

1068 Lotus Domino Administrator 7 Help

then the custom password policy will also be applied to user Internet passwords. This is the only time
that custom password policies are applied to Internet passwords.

Custom password policies are not applied to Internet passwords if users change them through a browser.

Note: The more secure password format is required if you choose to synchronize a user’s Internet
password with their Notes password.

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

For more information on custom password policies, see the chapter ″Using Policies.″

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.

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.

Note: The more secure password format is required if you choose to synchronize a user’s Internet
password with their Notes password.

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.

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 the following:

v 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.) If you are using Internet sites, you can create SSO configuration documents for each Internet
Sites(however, not all protocols honor Internet Site configurations).

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1069
v Enabling the ″Multi-servers (SSO)″ option for session-based authentication in a Web Site document 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
v It is important that all servers participating in an SSO group must use the same mechanism for
configuring Internet access. They must either all use Internet Site documents, or they must all have
Internet access configured in the Server document.
v The DNS domain that applies to the participating SSO servers is specified in the SSO configuration
document. 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 is included in the cookie (as specified by the configuration), and the DNS domain in the
cookie must match the server URL. This is why cookies cannot be used across TCP/IP domains.
v 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.
v If you enable Internet Sites in the Server document, any existing SSO configuration is automatically
disabled.

WebSphere issues
v WebSphere and Domino do not need to be configured for the same LDAP directory; however, if
WebSphere and Domino will not share the same directory, you likely will have a multi-identity
problem to plan for and address.
See the multi-identity section (probably this would be the topic on configuring LTPA user names, as
well as the topic that covers the DA feature ″Attribute to be used as Notes distinguished name″ ).
v Websphere configurations support two different formats of SSO LTPA cookies. One cookie has a name
″LtpaToken″, and the other cookie format is named ″LtpaToken2″. Domino SSO supports the
″LtpaToken″ cookie only, therefore WebSphere must be configured to issue the correct format cookie in
order for SSO to work between WebSphere and Domino.
v Websphere cannot use Domino LTPA tokens. To include Domino and WebSphere in the same LTPA
group, you must export the LTPA token from WebSphere and import it into Domino.
v If you have imported WebSphere keys into your Domino SSO configuration for interoperability with
WebSphere, then you cannot specify an SSO idle timeout. WebSphere servers do not honor an idle
timeout.
v 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 Domino 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 verifying 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.

1070 Lotus Domino Administrator 7 Help

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:
v Choose Domino only (no WebSphere servers participating in single sign-on), and then select ″Create
Domino SSO Key.″
v 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 Name Enter the name of the SSO configuration.

Notes
v If you create multiple Web SSO Configuration documents, be sure to give each
document a unique name. Web SSO documents are located by name and if
multiple documents have the same name, the SSO configurations won’t work
well. However, creating multiple SSO documents can only work under limited
circumstances. Multiple SSO documents are not recognized by all protocols. In
particular, SSO involving the Notes client, any Java agents, and other components
using the local Java back-end classes will not function if a name other than the
default LtpaToken is used.
v If the single sign-on configuration is a mixed-release configuration that includes
Release 5.0x servers, the Configuration Name must be LtpaToken, as Release 5.0x
servers only work with this configuration name.
Organization 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.
DNS Domain (Required) Enter the DNS domain (for example -- .acme.com) for which the tokens
will be generated. The servers enabled for single sign-on must all belong to the DNS
domain you specify.

When you enter the DNS domain, be sure you type the initial period. For example,
do not enter ″acme.com″; instead you should enter ″.acme.com″.

If the SSO domain includes WebSphere servers, WebSphere treats the DNS domain
as case-sensitive, so ensure that the DNS domain value is specified with appropriate
case.

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1071
Field Action
Map names in LTPA token Enable this option to map the user name that appears in a Domino-created LTPA
token to the user’s name that is expected by WebSphere SSO servers. You should
enable this setting if you have a mixed Domino and Websphere environment, and if
it is the case that Domino and WebSphere do not share the same directory.

Do not enable this option if you want Domino-created LTPA tokens to continue to
contain the user’s Domino distinguished name.

Domino Server Names
For more information, see the topic ″Configuring user name mapping in the SSO
LTPA token″ later in this chapter.
Enter the names of the Domino 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.

Expiration (minutes)
Idle Session Timeout
Minimum Timeout (minutes)
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.
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. Default is 30 minutes.
Note: If an Idle Session Timeout is configured, the session may timeout (based on
inactivity) at a time earlier than that specified by the expiration.
(Domino-only SSO configuration) Enable this option to end a user’s SSO session if
there is no activity for a specified amount of time (see below).
Note: If you chose to import Websphere LTPA keys, this option will not appear on
the Web SSO Configuration document.
If you enabled Idle Session Timeout, this option appears. Specify the length of time,
in minutes, that a user’s session must show no activity before timing out.

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.

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 or higher 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:
v Choose Domino only (no WebSphere servers participating in single sign-on), and then select ″Create
Domino SSO Key.″
v 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.)

1072 Lotus Domino Administrator 7 Help

 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 Name Enter the name of the SSO configuration.

Notes:
v If you create multiple Web SSO Configuration documents, be sure to give each
document a unique name. Web SSO documents are located by name and if
multiple documents have the same name, the SSO configurations won’t work
well. However, creating multiple SSO documents can only work under limited
circumstances. Multiple SSO documents are not recognized by all protocols. In
particular, SSO involving the Notes client, any Java agents, and other
components using the local Java back-end classes will not function if a name
other than the default LtpaToken is used.
v If the single sign-on configuration is a mixed-release configuration that includes
Release 5.0x servers, the Configuration Name must be LtpaToken, as Release 5.0x
servers only work with this configuration name.
Organization Name Leave this field blank, and this document will appear in the Web Configurations
view.
DNS Domain (Required) Enter the DNS domain (for example, .acme.com) for which the tokens
will be generated. The servers enabled for single sign-on must all belong to the
same DNS domain.

When you enter the DNS domain, be sure you type the initial period. For example,
do not enter ″acme.com″; instead you should enter ″.acme.com″.

If the SSO domain includes WebSphere servers, WebSphere treats the DNS domain
as case-sensitive, so ensure that the DNS domain value is specified with
appropriate case.
Map names in LTPA token Enable this option to map the user name that appears in a Domino-created LTPA
token to the user’s name that is expected by WebSphere SSO servers. You should
enable this setting if you have a mixed Domino and Websphere environment, and if
it is the case that Domino and WebSphere do not share the same directory.

Do not enable this option if you want Domino-created LTPA tokens to continue to
contain the user’s Domino distinguished name.

For more information, see the topic ″Configuring user name mapping in the SSO
LTPA token″ later in this chapter.
Domino Server Names Enter the names of the Domino 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.
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. Default is 30 minutes.
Note: If an Idle Session Timeout is configured, the session may timeout (based on
inactivity) at a time earlier than that specified by the expiration.
Idle Session Timeout Enable this option to end a user’s SSO session if there is no activity for a specified
amount of time (see below).
Note: If you chose to import Websphere LTPA keys, this option will not appear on
the Web SSO Configuration document.

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1073
Field Action
Minimum Timeout (minutes) If you enabled Idle Session Timeout, this option appears. Specify the length of time,
in minutes, that a user’s session must show no activity before timing out.

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 Web
Server Configurations 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 ensures that a server can participate in single sign-on (SSO). An SSO-enabled server
creates single sign-on cookies for users, which allowing them to log in to the server and then be able to
access other participating servers without having to log in again.

Before you begin, make sure that the SSO keys have been created or imported from a WebSphere file.

To enable single sign-on and basic authentication for a Web Site: Use this procedure to enable single
sign-on for Domino servers (Domino 6 and higher) configured with Web Site documents.

Note: When you enable the use of Internet Sites on a Domino server, any existing SSO configurations are
automatically disabled. Make sure that you have enabled this option prior to configuring SSO.
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.
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 pre-Domino 6 servers, or for Domino 6 and higher servers not configured
6

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.

1074 Lotus Domino Administrator 7 Help

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.

Note: You can optionally enable the use of client certificates for SSL authentication for users on an
SSO-enabled server. If the user authenticates with a client certificate, the server still creates an SSO token
for the user in case it will be useful for accessing resources on participating SSO servers.

Setting up the Web SSO Configuration document for more than one Domino
domain
This procedure lets you enable servers in your current Domino domain for SSO with servers in another
Domino domain, by setting up both domains to use the same key information. Two conditions must exist
in order to do this:
v 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. It may be necessary to have
administrative IDs cross-certified for operating in the two domains.
v 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 are stored
in each registered person and server document.
v Participating SSO servers must still reside in the same DNS domain -- for example, acme.com.

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.

Configuring user name mapping in the SSO LTPA token

The LTPA token that is created to authenticate users for single sign-on includes the name of the user who
has been authenticated. When Domino creates an LTPA token, it places the Domino distinguished name
in the token by default. If a Websphere server obtains the token from a user trying to access the server,
the Websphere server must be able to recognize this name format. If it does not, the token is ignored,
single sign-on fails, and the user is prompted to log in again.

This situation typically occurs in end-user configurations in which there are multiple directories used by
various servers participating in SSO, and consequently a user may have multiple identities. For example,
a user may be known in a Websphere LDAP directory as ″uid=jdoe,cn=sales,dc=acme, dc=com,″ but in a
Domino directory the same user is ″John P Doe/Sales/Acme.″ If Websphere receives an LTPA token
containing a user name like ″John P Doe/Sales/Acme,″ it attempts to find this user in the Websphere
directory and when it can’t, rejects the token.

Domino administrators can now map the user name that appears in a Domino-created LTPA token to the
name expected by WebSphere, to ensure that the name is recognized in a mixed Domino and Websphere
environment where Domino and WebSphere do not share the same directory.

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1075
Note: In a mixed-release Domino environment, user name mapping in the LTPA token only works if the
token is generated by a Domino 7.0 server. If the user name value that is used in the LTPA token is also
added as a secondary value in the fullname field of the Person record in pre-Domino 7.0 servers (for the
purposes of aliasing, for example), users will also be able to access databases on Domino 6.02 and higher
servers, as well as Websphere servers.

How you specify the user name to be used in the LTPA token depends on the directory configuration
used in your single sign-on environment:
v If Notes user information is contained only in a Domino Directory, you specify the user name mapping
in the Person document.
v If Notes user information is contained in a corporate LDAP directory, you configure the user name
mapping in Directory Assistance.
v If the organization uses both Domino and LDAP directories, you configure both the Domino person
record and the Directory Assistance SSO information.

As LDAP directory fields and Domino directory fields generally do not have a one-to-one
correspondence, the use of Directory Assistance documents for name mapping allows allows LDAP
administrators to specify which LDAP field should be used as the equivalent of the LTPA User Name
field.

Note: Any name mapping configuration in Directory Assistance documents will be ignored if the
mapping feature is not enabled in the SSO configuration document.

To configure user name mapping in a Domino Directory environment: In this environment, there are
Domino SSO users who have Person records in the Domino directory.
1. Enable name mapping for the LTPA token. In the Web SSO Configuration document that defines your
SSO environment, select Enabled for the ″Map names in LTPA token″ option.
2. In the user Person document, click Administration. Under ″Client Information,″ enter the user name
DN that is expected by WebSphere in the ″LTPA user name″ field. Typically, this will be the user’s
LDAP distinguished name (DN). Be sure to separate the name components with slashes.
For example, if the LDAP DN is
uid=jdoe,cn=sales,dc=acme, dc=com
enter the value as follows:
uid=jdoe/cn=sales/dc=acme/dc=com

Although the name is entered into the LTPA user name field in Domino format, Domino transforms the
configured LTPA user name into the appropriate LDAP format expected by Websphere before placing it
into the Domino-created LTPA token.

Note: The value entered in this field must be unique- that is, it should not match more than one person
in the organization.

To configure user name mapping in a corporate LDAP directory environment (a mixed Domino and
LDAP directory environment): In this environment, some or all Domino users do not have Person
records in the Domino directory. Instead, these Domino users have records in an external LDAP directory
that is accessible to Domino through Directory Assistance.
1. Enable name mapping for the LTPA token. In the Web SSO Configuration document that defines your
SSO environment, select Enabled for the ″Map names in LTPA token″ option.
2. Open the Directory Assistance document for the LDAP Directory. In the SSO Configuration section,
enter an LDAP attribute that should be used as the name in an SSO token created for this user. This
attribute will be used in the LTPA token when the LTPA_UserNm field is requested. It is important to
ensure that the selected field contains the user name that WebSphere expects. Options for this field
include:

1076 Lotus Domino Administrator 7 Help

 v Any appropriate LDAP attribute, as long as it uniquely identifies the user.
v A value of $DN to use the LDAP distinguished name. This is the most commonplace configuration,
indicating that the user’s LDAP DN is the name expected by WebSphere, rather than a name in
some arbitrary LDAP field.
v Leaving it blank to default to the Domino distinguished name, if known. Otherwise, the default
will be the LDAP distinguished name.

If Directory Assistance is configured such that a search on a particular user finds a match in both the
Domino Directory and in an LDAP directory, Domino requires consistency between a Domino Person
record and an LDAP record. Domino takes extra steps to determine that there are matching values for the
Internet email address located in both directories. To accomplish this, DA searches for the user’s LDAP
″mail″ attribute. This value must match the information found in the Domino Person record field
″internetaddress.″

Attribute in LDAP Directory Attribute in Domino Directory

mail: Jbond@secret.spies.com internetaddress: Jbond@secret.spies.com

In order for SSO to succeed, you must ensure that the value of the Domino attribute ’Internet address’
matches the value of the LDAP attribute ’mail.’

Other considerations:
v To support aliasing, in the Person document, add the LDAP name to both the LTPA_UserNm field and
as a secondary value in the User Name (i.e. document property Fullname) field.

For more information on alias dereferencing, see the chapter ″Setting Up Directory Assistance.″
v Notes client integration with Sametime (and therefore SSO with Sametime) is not supported if the
Sametime server is configured to use Internet Sites, as the Notes client protocol (NRPC) for obtaining
an SSO token does not work with the use of Internet Sites.
v Name mapping in the LTPA token is not supported when user information is stored in condensed
directory catalogs.

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.

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1077
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 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.
v 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.
v 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.
3. Click the tab that lists the protocol for which you want to allow anonymous access. For each protocol,
do the following:
v 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.
v 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.″

1078 Lotus Domino Administrator 7 Help

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:
v They attempt to do something for which access is restricted.
v 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 (or in an LDAP directory - some users are authenticated against an LDAP directory rather than
a Person record) and if the database ACL gives access to that user. Anonymous users are not
authenticated.

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.
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 (DN), 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.

Chapter 44. Setting Up Name-and-Password and Anonymous Access to Domino Servers 1079
 For users who do not have Person records, and instead have their records in a secondary LDAP
directory, the user’s LDAP name might appear on the ACL. To allow access to the user, the ACL
should include the user’s LDAP name (unless the user’s name is being mapped to a corresponding
Domino name by Directory Assistance, in which case the Domino DN should appear on the ACL).
a. 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.
b. 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.
c. 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.

1080 Lotus Domino Administrator 7 Help

Chapter 45. 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:
v 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.
v 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.
v 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.
v 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, 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 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.

1081
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 support the use of 630- and 1024-bit keys for key
exchange, and use 64- and 128-bit keys for bulk data encryption.

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

1082 Lotus Domino Administrator 7 Help

 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.

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

Chapter 45. Encryption and Electronic Signatures 1083

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.

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.

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

1084 Lotus Domino Administrator 7 Help

v 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.
v 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.
v 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 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 7 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 incoming mail, see Lotus Notes 7 Help.

in

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.

Chapter 45. Encryption and Electronic Signatures 1085

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. 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:
v It is not possible to guess the original message from looking at the digest.
v 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.
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 comparison 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.

1086 Lotus Domino Administrator 7 Help

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

Chapter 45. Encryption and Electronic Signatures 1087

1088 Lotus Domino Administrator 7 Help
Chapter 46. 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 a 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 both Notes and Internet certifiers to use the CA process.

Consider using the CA process because it:

v Provides a unified mechanism for issuing Notes and Internet certificates.
v Supports the registration authority (RA) role, which you use to delegate the certificate approval/denial
process to lower-echelon administrators in the organization.
v 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 manage
certificate requests without having to provide the certifier ID and password.
v Simplifies the Internet certificate request process through a Web-based certificate request database.
v Issues certificate revocation lists, which contain information about revoked Internet certificates.
v Creates and maintains the Issued Certificate List (ICL), a database that contains information about all
certificates issued by the certifier, including the policy and a copy of the certifier ID file.
v 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 certificate that it has issued, certificate
revocation lists (for Internet certifiers), 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:

v Certificate profiles, which contain information about certificates that are issued by the certifier.
v CA configuration document, which contains information about the certifier itself.
v 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.
v 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.

1089
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 in the CA’s certifier document, where it is used to assert
certificate validity by entities that require certificate authentication. The CRL in the Domino Directory is
retrieved by users using LDAP through a specific server that is named as part of the CA configuration.
This information is stored in the CRL distribution point, an X.509 extension of the issued certificate.

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: scheduled and immediate. For scheduled 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 an
immediate 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 an immediate 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 scheduled 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 server-based Domino certification authority

To set up a server-based Domino certification authority, you must configure and enable your certifiers
(Notes and Internet) to use 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.

1090 Lotus Domino Administrator 7 Help

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.

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:
v Create and configure certifiers.
v Modify certifiers. For example, only a CA administrator can edit ID recovery information for a Notes
certifier.
v 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
approve or deny a certificate request.

Domino Registration Authority administrator tasks

A registration authority (RA) administrator approves or denies Notes or 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
and Certificate Profile documents, stored in the CA’s ICL database, describes what is acceptable. A
current valid copy of the document is also stored with the certifier document as an attachment.

Domino administrators who register Notes users should also be listed as RAs for the Notes certifier, to
minimize the steps that are needed to have a certificate issued by the 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 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:
v Approve or deny Internet certificate requests.
v 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.

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1091

Note: If you need RAs to be able to register users, they must have at least Author access to the master
Domino Directory for the domain, with both the privilege ″Create document″ and role ″User Creator″
enabled. This is the same access required by a Domino administrator to register Notes users.

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.
4. In the ″Chose ID/key ring file″ dialog box, select the cert.id of the certifier you want to migrate.
v Choose the certifier ID (CERT.ID) and click Select to migrate a Notes certifier.
v 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
Select the server where the certifier will run
Name of ICL database to be created
Action
Select the server on which the migrated certifier will be
linked to the CA process. The ICL database for this certifier
will also be created on this server. Make sure that the client
location document points to this server.
(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).
Note: 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 Password required Action required

Encrypt ID with Server ID
Require password to activate
Encrypt ID with Lock ID
None None
Enter a new password for this If you choose to encrypt the certifier ID with
certifier the server ID and password, you need to
activate the certifier. Use the tell command:
tell ca activate <password>
Registered user ID and If you choose to encrypt the certifier ID with
password a lock ID, the certifier is locked until you
unlock it. Use the tell command:
tell ca unlock <idfile><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.

1092 Lotus Domino Administrator 7 Help

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 Action
Certificate duration for EE Enter the default, minimum, and maximum duration, in months, for an
certificate end-entity (EE) certificate. An end-entity certificate is granted to servers or end
users.
Certificate duration for CA Enter the default, minimum, and maximum duration, in months, for an
certificate certificate authority (CA) certificate. A CA certificate is granted to certifiers.

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

To manage the CA process, you use Tell commands at the server console.

To add a certifier to the CA process

1. If the CA process is not already running, at the server console enter:
load ca
2. 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: You need to reload the CA process each time you restart a server. You can do this through the
server console command ″load ca,″ or you can have it happen automatically by adding the parameter ca
to the ServerTasks= line in the server’s NOTES.INI file.

For more information on using CA server commands, see the appendix ″Server Commands.″

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 02:38:12 pm 1. O=Acme
10/22/2001 02:38:12 pm Certifier type: Notes

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1093

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

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 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:
v Common name -- Enter the certifier name.
v Organizational unit (optional) -- Enter the name of the certifier’s organizational unit, if applicable.
v Organization (optional) -- Enter the name of the certifier’s organization.
v City or locality (optional) -- Enter the organization’s city or locality.
v State or province (optional) -- Enter the full name of the state or province in which the
organization resides.
v Country (optional) -- Enter the two-character abbreviation for the country in which the
organization resides.
6. Choose the server on which the CA process is running. This is the same server on which the ICL
database will be created.
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 Action required

Encrypt ID with Server ID
Require password to activate
Lowest None None
Medium Server ID password If you choose to use a password,
you need to activate the certifier.
Use the tell command:
tell ca activate <password>

1094 Lotus Domino Administrator 7 Help

Option Security level Password required Action required
Encrypt ID with Lock ID Highest Registered user ID and If you choose to encrypt the
password certifier ID with a lock ID, the
certifier is locked until you unlock
it. Use the tell command:
tell ca unlock <idfile><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.
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.
10. On the Certificates tab, complete these fields:

Field Action
Include CRL distribution point extension Enable an attribute that identifies the location of for the certifier
CRL. It is recommended that you use this option so that you
can revoke certificates after they are issued. This is enabled by
default.
Backdate certificate validity The certificate validity period is the time interval during which
the CA warrants that it will maintain information about the
status of the certificate. In the event that the date on which the
certificate becomes valid is different than the date on which it is
created, you can choose to backdate the certificate’s validity
period. This option is enabled by default. You cannot enter a
date.
Certificate duration Enter the default, minimum, and maximum certificate duration
in months.
Key usage Choose the key usage extensions for this certificate.

Note: The only certificate type you can create is an end -entity certificate, and the option is enabled by
default. 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)
Time between CRLs (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.

13. Complete these fields to specify ″Key and certifier certificate″ information for this certifier:

Field Action
Signing algorithm Select the algorithm used to encrypt the certificate’s signature.

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1095

Field Action
Key length 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.
Certificate will expire on (Optional) Change the default certificate expiration date.

14. Complete these fields to specify the Certifier PKIX Alternative Name(s) information for this certifier:
The Certifier PKIX Alternative name field is for the Issuer Alternate Name. The Domino server-based
CA does not support the use of Subject Alternate Names.

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 Action
Type Enter the type of alternative name you want to use.
Value Enter the alternative name you want to use.

Click Add to add the alternative name to the certifier’s certificate.

15. Click OK. A message appears saying that you have successfully set up a CA.
16. Complete these procedures:
v Add the new certifier to the CA process.
v Create the Certificate Requests application.
For more information on certifier administrators and registration authorities, see the topic
″Administering a Domino CA″ earlier in this chapter.

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 or verifying a signature, 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 certificates 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.
Non-repudiation 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).
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.

1096 Lotus Domino Administrator 7 Help

Key usage extension Description
Data encipherment Use when the public key is used for encrypting user data, other than cryptographic
keys.
Key agreement 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.
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.
Decipher only Use only when key agreement is also enabled. This enables the public key to be used
only for deciphering data while performing key agreement.

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 Enable for these key usage extensions

TLS Web server authentication Digital signature, key encipherment or key agreement
TLS Web client authentication Digital signature and/or key agreement
Sign (downloadable) executable code Digital signature
Email protection Digital signature, non-repudiation, and/or key encipherment or key
agreement
IPSEC End System (host or router) Digital signature and/or key encipherment or key agreement
IPSEC Tunnel Digital signature and/or key encipherment or key agreement
IPSEC User Digital signature and/or key encipherment or key agreement
Timestamping Digital signature, non-repudiation.

Examples of required key usage extensions

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

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1097

Application Required key usage extensions
Object Signing Digital signature

Creating the Certificate Requests database

Each Internet certifier you create requires a Certificate Requests database (CERTREQ.NSF) to manage the
server keyring file and allow users to request client certificates from the browser or through email. 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.
6. In the Database Administration section, complete these fields:

Field Action
Supported CA 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.
Supported certificate types Choose one:
v 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.
v Server certificates only -- Select this if the certifier will issue server Internet
certificates. If you select this option, you must customize server requests.
v 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.

7. (Optional) In the Client Request Customization section, complete these fields:

Field Action
Validity period 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.
Key usages 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.

1098 Lotus Domino Administrator 7 Help

Field Action
Extended key usages 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.

8. (Optional) In the Server Request Customization section, complete these fields:

Field Action
Validity period 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.
Key usages 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.
Extended key usages The default extended key usage that will be submitted in server certificate
requests generated from this database. Default is Server Authentication.

9. For ″Processing method,″ choose the method by which requests are submitted to the Administration
Process:
v Manual (default) -- Choose this if you want an administrator to review requests submitted to the
Certificate Requests to approve or deny each request individually before it is submitted to the
Administration Request database (admin4.nsf) for further processing.
v Automatic -- Choose this to have requests submitted to the Administration Request database
processed without administrator 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 administrator (signer of the agent) 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.
v 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.
v 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.

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.

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1099

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 Action
File name Enter a file name for the Key Ring file and keep the .kyr.
Password Enter a password for the key ring file.
Key size Choose a key size.
Common name Enter the fully qualified host name -- for example, server.company.com.
Organization name Enter the name of the certifier organization.
State or province Enter the full name of the state or province in which the organization is located.
Country 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 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.
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 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).″
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:

1100 Lotus Domino Administrator 7 Help

 v 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.
v 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.
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
administrators approve or deny 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:

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1101

 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.
b. Open the request and verify the information in it.
c. Click Edit Request, then Approve Request. Press F9 until the request changes 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:
v Select the certifier document from the Domino Directory.
v Select the certifier ICL database.

Note: If the certifier is protected with a lock ID, you must unlock it in order to modify it.
6. In the Certifier dialog box, modify the certifier as needed. You can change these features:
v Method for activating the certifier ID
v CAs and RAs, and roles of current entries
v CRL distribution point extension (Internet certifiers only)
v Enable or disable backdating of certificate
v Certificate duration
v Certificate key usage (Internet certifiers only)
v CRL publication and duration (Internet certifiers only)
7. Click OK.

1102 Lotus Domino Administrator 7 Help

8. 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 certifier has been modified:
tell ca stat
For detailed information on these options, see the topic ″Creating a certifier for a server-based CA″
earlier in this chapter.

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.
v On the Basics tab, you can modify certifier name and issuer.
v Click ″Modify CA configuration″ to change CAA and RA associations.
2. Click Save and Close.

Viewing certificate requests

Domino CAAss 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 Administration Requests database.
2. In the left-hand pane, choose Certification Authority Requests - Certificate Requests.
3. Look for the certification authority for which you want to see certificate requests.

Revoking a certificate
A CA administrator can easily revoke an Internet certificate -- for example, 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 an immediate 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. This
sends a revocation request to the Administration Requests database.
7. Once you have made sure that the certifier has processed the revocation request and revoked the
certificate, issue an immediate (non-regular) CRL.

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1103

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 immediate CRLs, see the appendix ″Server Commands.″

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.
3. Make copies of the following (if you use them) and keep in a safe place:
v the lock ID and its corresponding password;
v the activation password;
v the server ID file.

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:
v Select the certifier document from the Domino Directory.
v 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.

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.
4. On the CA Configuration tab, disable the CA process for the certifier.

1104 Lotus Domino Administrator 7 Help

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.

Processing client certificate requests from IBM Workplace users

Users of IBM Workplace Collaboration Services 2.6 and later can request client S/MIME signing
certificates from the Domino server-based CA. While the certificate request process is similar to the native
Domino process, there are some notable differences.

A Workplace user requests an S/MIME certificate by sending an email to the Certificate Request database
(certreq.nsf) of the CA from which the certificate is being requested. The email is signed by a Workplace
agent, which vouches for the identity of the requester.

Another database agent converts the email to a certificate request, which then undergoes the normal
certificate request process. When the certificate is approved, it is returned to the Certificate Request
database. Another agent then mails the certificate back to the original requester.

The approval process for WCS requests differs in that the Domino administrator must manually approve
or reject the email request in the Certificate Request database. The administrator does not have to be
listed as an RA for the certifier. If the request is approved, then the certificate is sent to the
Administration Request database for processing.

The Workplace server communicates with the Domino CA through a Workplace PKI adapter. The adapter
actually signs and sends the certificate requests to the Domino CA, and processes the issued certificates.

The first time a certificate request is sent to the Domino CA, the PKI adapter actually sends a certificate
request for itself to Domino. The certificate issued to the adapter as a result of this request is the
adapter’s signing certificate, which is used by the adapter to sign client certificate requests submitted to
the Domino CA. The Domino PKI adapter’s certificate request is itself unsigned, however, and is the only
unsigned certificate request submitted to the Domino CA.

Note: In order for the Certificate Request database to receive email requests, the administrator must
make it a mail-in database in the Domino Directory.

Chapter 46. Setting Up a Domino Server-Based Certification Authority 1105

1106 Lotus Domino Administrator 7 Help
Chapter 47. 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:

v Data is encrypted to and from clients, so privacy is ensured during transactions.
v An encoded message digest accompanies the data and detects any message tampering.
v The server certificate accompanies data to assure the client that the server identity is authentic.
v 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:
v Web server and Web Navigator (HTTP)
v Internet Inter-ORB Protocol (IIOP)
The Java applet that uses this protocol must be set up to use SSL.
v Internet Message Access Protocol (IMAP)
v Lightweight Directory Access Protocol (LDAP)
v Post Office Protocol 3 (POP3)
v Simple Authentication and Security Layer (SASL)
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.
v 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.

1107
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.
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:
v Request server certificates from either a Domino or third-party CA
v Add a CA certificate as a trusted root
v Manage server certificates in a key ring file
v 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:
v Add the names of server administrators who will need to obtain and manage server certificates.
Assign Manager access.
v 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.

1108 Lotus Domino Administrator 7 Help

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 Action
Key Ring File Name 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.
Key Ring Password Enter the password for the key ring.
Key Size Specify the key size Domino uses when creating the public and private key pairs. The
larger the size, the stronger the encryption.
Common name 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.
Organization Enter the name of the organization -- for example, a company name, such as Acme.
Organizational Unit (Optional) Enter the name of certifier division or department.
City or Locality (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.

Chapter 47. Setting Up SSL on a Domino Server 1109

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.

Torequesta 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 Action
File name Enter a file name for the Key Ring file and keep the .kyr.
Password Enter a password for the key ring file.
Key size Choose a key size.
Common name Enter the fully qualified host name -- for example, server.company.com.
Organization name Enter the name of the certifier organization.
State or province Enter the full name of the state or province in which the organization is located.
Country 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.
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.

1110 Lotus Domino Administrator 7 Help

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 Enter
Key Ring File Name The name of the server key ring file, including the path to the file
Log Certificate Request Choose one:
v Yes (default) to log information in the Server Certificate Admin application
v 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:
v 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 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.
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:
v Yes (default) to log information in the Server Certificate Admin application
v No to not log information

Chapter 47. Setting Up SSL on a Domino Server 1111

Field Enter
Method Choose one:
v Paste into form on CA’s site (recommended)
v 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.
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.

Note: If you use Microsoft Internet Explorer, use HTTP to connect to the application.
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.
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.

1112 Lotus Domino Administrator 7 Help

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:
v 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.
v 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.″

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

VeriSign International Server CA - Class 3 VeriSign, Inc. Class 3 Public Primary US
Certification Authority
VeriSign Class 3 Public Primary Certification VeriSign, Inc. Class 3 Public Primary US
Authority Certification Authority
VeriSign Class 2 Public Primary Certification VeriSign, Inc. Class 2 Public Primary US
Authority Certification Authority
VeriSign Class 1 Public Primary Certification VeriSign, Inc. Class 1 Public Primary US
Authority Certification Authority
VeriSign Test Certificate Authority VeriSign, Inc. Test CA US
RSA Secure Server Certificate Authority RSA Data Security, Inc. Secure Server Certification US
Authority
Netscape Test Certificate Authority Netscape Communications Test CA US
Corp.
RSA Low Assurance Certificate Authority RSA Data Security, Inc. Low Assurance US
Certification Authority

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.

Chapter 47. Setting Up SSL on a Domino Server 1113

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:
v 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
v 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.″
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.

1114 Lotus Domino Administrator 7 Help

6. Do one of the following:
v If you copied the certificate to the Clipboard, choose Clipboard in the Certificate Source field. Paste
the Clipboard contents into the next field.
v 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.

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:
v The server must have a certificate from a Domino or third-party CA.
v 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.
v 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.″

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:
v Complete the above requirements for server authentication.
v The clients must have certificates from a Domino or third-party CA.
v The server must have the client’s CA certificate marked as a trusted root.
v 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.″

Chapter 47. Setting Up SSL on a Domino Server 1115

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.
3. Complete these fields:

Field
SSL key file
SSL protocol version
Accept SSL site certificates
Accept expired SSL certificates
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.
Choose one:
v V2.0 only to allow only SSL 2.0 connections.
v 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.
v V3.0 only to allow only SSL 3.0 connections.
v 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.
v 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.
Choose one:
v 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.
v No to not allow this server to accept site certificates.
Choose one:
v Yes to allow clients to access the server, even if the client certificate is expired.
v No to not allow clients to access the server with expired client certificates.

4. Click the tab for the protocol that you want to configure, and then complete these fields:

Field Enter
SSL port number 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.

1116 Lotus Domino Administrator 7 Help

Field Enter
Client certificate Choose one:
v No to not use client authentication.
v Yes to use client authentication.
Note: SMTP and IIOP do not support client authentication.
Name & password Choose one:
v No to not use name-and-password authentication.
v Yes to use name-and-password authentication.
Anonymous Choose one:
v Yes to allow anonymous access. You must choose Yes if you want users to
connect using server authentication only.
v 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.

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:

v For Domino 6 and later servers, use a Web Site document for requiring SSL connections for HTTP
clients. For IMAP and LDAP, you do this in the Server document.
v For all protocols on pre-Domino 6 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.

Chapter 47. Setting Up SSL on a Domino Server 1117

4. On the Basics tab, click Web Access: Require SSL connection.

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

Managing server certificates and certificate requests

Do the following to manage your server certificates and certificate requests:
v View SSL server certificates
v Renew an expired certificate
v View requests for certificates
v Mark or unmark a CA’s certificate as a trusted root
v Change the password for the server key ring file
v Creating an Internet cross-certificate for server-to-server SSL

Viewing SSL server certificates

Each SSL server certificate contains this information:
v The expiration date. The default trusted roots that come with Domino do not have expiration dates.
v The distinguished name of the server that requested the certificate.
v The distinguished name of the CA that signed the certificate.
v 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:
v To view the server certificate, select a document in the Site Certificates category.
v To view a trusted root certificate, select a document in the Certification Authorities category.

1118 Lotus Domino Administrator 7 Help

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.

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.
7. In the Certification Authorities category, open the document that contains the certificate you want to
edit.
8. Click one:
v ″Trust This Certificate″ to mark a certificate as a trusted root.
v ″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.

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.

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.

Chapter 47. Setting Up SSL on a Domino Server 1119

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 Enter
Key ring file name A file name with the extension .KYR.
Key ring password At least 12 case-sensitive, alphanumeric characters.
Common name A descriptive name that identifies the server certificate -- such as, Acme SSLCA.
Organization The name of the organization -- for example, a company name, such as Acme.
Organizational Unit (Optional) Name of certifier division or department.
City or Locality (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.

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:

1120 Lotus Domino Administrator 7 Help

v In an Internet Site document. If you use Internet Site documents, you can specify a different set of SSL
cipher restrictions for each protocol.
v 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.
v 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.″

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.

Chapter 47. Setting Up SSL on a Domino Server 1121

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

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.

1122 Lotus Domino Administrator 7 Help

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

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

1123
Outlook Express. 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.″

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:

v Software, such as a Web browser or a Notes client, that supports SSL.
v A trusted root certificate from a Domino or third-party certifier.
v (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.

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

1124 Lotus Domino Administrator 7 Help

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

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

Chapter 48. Setting Up Clients for S/MIME and SSL 1125

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

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

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.

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.

1126 Lotus Domino Administrator 7 Help

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

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:

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

Chapter 48. Setting Up Clients for S/MIME and SSL 1127

 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.

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.
1128 Lotus Domino Administrator 7 Help
 Note: The client cannot use the certificate to authenticate against database ACLs until the
Administration Process completes the request.

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.

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.
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 File Containing the Internet Certificate 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.

Chapter 48. Setting Up Clients for S/MIME and SSL 1129

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.

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

1130 Lotus Domino Administrator 7 Help

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

Chapter 48. Setting Up Clients for S/MIME and SSL 1131

Field Enter
Certifier 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.
Server 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.
Subject name 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.
Subject alternate name list Alternate names attached to the ID, if any.
Expiration date The date that the cross-certificate expires.

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.

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

1132 Lotus Domino Administrator 7 Help

signatures to the Contact document. When you send an encrypted message, Notes extracts only the
Internet certificate for encryption from the Contact document.

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:
v An Internet certificate issued by a Domino or third-party certifier.
v A trusted root certificate for a Domino or third-party certifier.
v (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.
v Software, such as a Web browser or a Notes workstation, that supports the use of SSL.

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.

Chapter 48. Setting Up Clients for S/MIME and SSL 1133

 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.

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.

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.

1134 Lotus Domino Administrator 7 Help

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 certifier 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 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:

v Be configured for SSL, accepting both client certificates and anonymous access
v 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.″

Chapter 48. Setting Up Clients for S/MIME and SSL 1135

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

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

1136 Lotus Domino Administrator 7 Help

Chapter 49. 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 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:
v Work with the application developer or database designer to implement and coordinate design changes
v Consider server resources and the connections between servers when putting databases on servers
For more information on designing or redesigning databases, see Lotus Notes and Domino Release Notes
and the book Application Development with Domino Designer.

Creating a database
Use the Domino Administrator to create a database. You can use one of Domino’s templates to create a
database or you can choose Blank to use a ″blank″ template.

You must have Domino Designer installed to make design changes to the database you create.

Many of the templates that ship with Domino are master templates. Changes made to a master template
are passed on to any databases created from that template unless you specify otherwise. If you plan to
customize a database and want to prevent design changes, either deselect the ″Inherit future design
changes″ option after you select a template, or deselect ″Inherit design from master template″ on the
Design tab of the Database Properties box for the database.

To create a database
1. From the Domino Administrator, choose File - Database - New.
2. Complete these fields:

Field Action
Server Do one:
v Select Local to store the database locally on your hard
drive.
v Enter the name of a server on which you want to store
the database.
Title Enter a database title. You can use a maximum of 96
characters

1137
Field Action
File name Use the default file name or specify a unique file name
of fewer than 32 characters, followed by the extension
.NSF. If you are creating the database locally, specify a
drive and directory in which to store the new database.
For example, C:/Databases/mydbs.nsf. Otherwise, the
database is stored in the Data directory. If you are
creating the database on a server, specify the server and
directory in which to store the database.
Create full-text index for searching Choose this option to enable full text searching on your
database. Full-text searching increases the speed of a text
search.

3. (Optional) Click Encryption if you want to encrypt the database and require an appropriate user ID in
order to open the database.
4. (Optiona) Click Advanced to set advanced database properties for the database you are creating.
5. Complete these fields:

Field Action
Server Specify the name of the server that contains the template
you are using to create the database.
Template Choose a template from the list or choose Blank if you
don’t want to use a template.
Show advanced templates Choose this option to select from all available Domino
templates.
Inherit future design changes Choose this option to update the database design when
the server task runs at night.

6. (Select ″Inherit future design changes″ if you want your database design to get updated when the
nightly server task runs.
7. (Recommended) Check ″Create full-text index for searching″ to speed searches on your new database.

Note: You can customize the ACL for a database that you create by updating the template’s ACL with an
entry that you specify. That is, you can specify an ACL entry such as [Alan Smythe/Sales/UK] and have
that value copied when you create the NSF database. For information, see the topics that reference
″CreateFromTemplate″ in the Domino Designer online help database.

For information about encrypting a database you are creating, see the topic ″To encrypt a database″ in the
Notes client online help.

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.

1138 Lotus Domino Administrator 7 Help

Mandatory tasks
Perform these tasks before copying a new database or database replica to a production server.

Task Considerations
Set up the database ACL for users and If you plan to make replicas of a database, make sure that the
servers that require access database ACL lists the name of each server containing a replica. If the
database uses roles, 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 Without proper access in a server ACL, users and servers won’t have
access to databases on the server.
Verify that the Domino Directory contains Create a Group document in the Domino Directory before adding a
the necessary Group documents 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.
Copy the new database to a server Consider server disk space, topology, and network protocols. Placing
a database on a cluster requires that you consider cluster resources.
Verify that the database appears in the Open While designing a database, the database designer often removes the
Database dialog box 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.
Decide which servers require replicas of the To make this decision, consider the purpose and size of the database,
database and then create the replicas the number and location of users who need access to the database,
and the existing replication schedules between servers.
Verify that Server documents in the Domino Server documents are, by default, enabled for replication, but to avoid
Directory are enabled for replication any problems, verify this.
Create or edit Connection documents If several servers have a replica of the database, make sure that any
necessary Connection documents are set up so that replication can
occur.
Set up a replication schedule Consider the location and time zones of users and the frequency of
database updates.

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
Create About This Database and Using This Provide the name, phone number, and e-mail address of database
Database documents managers in the About This Database document. Provide information
about the application in the Using This Database document.

For more information, see Application Development with Domino

Create an index for the database
Designer.
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.

Chapter 49. Rolling Out Databases 1139

Task Considerations
Distribute encryption keys If the database design includes encrypted fields, distribute encryption
keys to users.

For more information, see the book Application Development with

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

Copying a new database to a server

Plan the deployment of new databases before copying them to a server. Tasks to perform include:
v Setting up all appropriate Server documents in the Domino Directory, including a Mail-In Database
document if the database is designed to receive mail.
v 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.
v 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:
v ″Database design and documents″ to copy the database design and all documents
v ″Database design only″ if you do not want to copy any existing documents
8. Optional steps:
v Choose ″Access Control List″ to copy the ACL.

1140 Lotus Domino Administrator 7 Help

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

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

Creating a Mail-In Database document for a new database

The mail-in database is designed to allow mail to be received by a database that is set up to receive mail,
without the mail being added to a person’s mail file. The mail-in database can then be accessed by one
person, or by multiple people, who have access to read the database. For example, if you want multiple
users on a mailing list to read specific mail, that mail can be sent to a mail-in database instead of sending
it to numerous individual users. Those users can then open the database and review the mail that has
been sent to that 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 the Mail-In Databases Resources
view.
3. Click Add Mail-In database.
4. On the Basics tab, complete these fields and then save the document:

Field Description
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:
v No preference (default);
v Prefers MIME
v 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.
Encrypt Incoming Mail Yes or no according to your preference. Mail sent to the
mail-in database is encrypted with the Notes certified
public key entered in the next field.

Chapter 49. Rolling Out Databases 1141

Field Description
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:

Field Description
Owners Fully distinguished hierarchical name of users allowed to
modify this document.
Administrators Users or groups who can edit this document.
Allow foreign directory synchronization Choose one of these:
v 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.
v No -- Does not allow the entry to be exchanged with
foreign directories.
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.
Internet Certificate This field displays the Internet Certificate if one exists. If
there is no Internet Certificate for this mail-in database,
the field displays the message ″Not Available.″
Issuer name The field is populated only if the Internet Certificate field
displays an Internet Certificate.

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 Domino Designer 7 Help.

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.

1142 Lotus Domino Administrator 7 Help

3. Choose Tools - Database - Sign.
4. Choose one of the following:
v Active User’s ID to sign using your ID.
v 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:
v 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.
v All data documents to sign all active content (Hotspots) found in the data documents.
v All documents of type to sign a specific type of design element
v 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.

Chapter 49. Rolling Out Databases 1143

1144 Lotus Domino Administrator 7 Help
Chapter 50. 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.

Organizing databases on a server

When organizing databases on a server, you can:
v Store databases in the Domino data directory. This is the default.
v Create subdirectories of the Domino data directory to store groups of related databases.
v Create directory folders to store databases outside the Domino data directory and create links to the
databases from the Domino data directory.
v 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.

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.

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

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

1146 Lotus Domino Administrator 7 Help

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 user access to a server’s data directory or a subdirectory of the data directory by editing
the entries in the ACL.

For information about controlling access to the server’s data directory, see the chapter ″Controlling User
Access to Domino Databases.″

Chapter 50. Organizing Databases on a Server 1147

1148 Lotus Domino Administrator 7 Help
Chapter 51. 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.

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

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

1149
v 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.″

Restricted field names in full-text indexing

Some field names are not supported in full-text indexing. Do not use these field names when creating
forms in databases because these fields are not searched in full-text indexing:
v $Revisions
v RouteTimes
v $Hops
v UserCertificate
v Certificate

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. The full-text directory must reside in the
directory in which the corresponding database resides. The full-text directory must reside in the directory
in which the corresponding database resides.

For more information on directory and database links, see the chapter ″Organizing Databases on a
Server.″

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.

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.

1150 Lotus Domino Administrator 7 Help

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.

CAUTION:
Selecting this option can compromise system security.
Index sentence and Includes sentence and paragraph breaks in addition to word breaks to allow users to
paragraph breaks do proximity searches.
Enable case sensitive Allows searches by exact case match. This option increases the size of the index by
searches about 15%, as each word must be indexed twice -- for example, apple and Apple.

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 option Updates occur Select when

Daily (the default) Nightly when the Updall server The database is very large, because
program runs at 2 AM. updating a large index can take some time.
Note: To change the time that Updall
performs automatic daily index
updates, use the ServerTasksAthour
setting in the NOTES.INI file.
Hourly Every hour, as scheduled by the Frequent changes are made to the database
Chronos server task. contents. If subsequent monitoring of the
database and server reveals slow
performance of either, change to another
frequency setting.
Immediate As soon as possible after you close the Very frequent changes are made to the
database. database contents. If subsequent
monitoring of the database and server
reveals slow performance of either, change
to another frequency setting.
Scheduled As scheduled by a Program document None of the update frequency options
for the Updall server task in the described here meet your needs.
Domino Directory.
Note: 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.

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.

Chapter 51. Setting Up and Managing Full-text Indexes 1151

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.

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 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 Nightly when the Updall server program runs by default at 2 AM
Hourly Every hour, as scheduled by the Chronos server task
Immediate As soon as possible after you close the database
Scheduled As scheduled by a Program document for the Updall server task in the Domino
Directory
Note: 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.

1152 Lotus Domino Administrator 7 Help

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.

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

Chapter 51. Setting Up and Managing Full-text Indexes 1153

1154 Lotus Domino Administrator 7 Help
Chapter 52. 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 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 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.

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

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.

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.
6. Enter information in the following fields, and then close and save the database document:
v 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.
v 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.

1156 Lotus Domino Administrator 7 Help

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

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.

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:
v Creating your own categories to control the list of databases that appear in the Databases by Category
view of the catalog.
v Determining if there are any databases to exclude from the catalog’s default views (such as mail files).
v 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

Chapter 52. Setting Up Database Libraries and Catalogs 1157

Note: The Catalog task assigns Manager access in the ACL to administrators and to the server that stores
the catalog.

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

1158 Lotus Domino Administrator 7 Help

Chapter 53. 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:
v 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.
v 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.
v Server tasks -- Collect and record information about the Domino system. The Shutdown Monitor task
ensures that Domino terminates when requested to do so. The Process Monitor task applies only to
Domino on Microsoft Windows platforms, and monitors the processes that should be running in the
Domino server environment. 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 database (STATREP.NSF) or to another database
you can specify. The ISpy task executes TCP server and mail-routing event generators.
v 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.
v Domino server monitor -- Provides a visual representation of the status of the servers you are
monitoring.

Monitoring Configuration database

The Monitoring Configuration database includes a configuration user interface for use with Domino
Domain Monitoring (DDM). Use this new interface to set up DDM probes and a collection hierarchy of
servers that collect information from other servers. A collection server collects two classes of event
information, enhanced events and simple events. Enhanced events include events generated by the DDM
probes, events generated by instrumentation that is new in Domino 7.0, events generated by the Event
Generator, and any other event that is associated with a specific target. A simple event is any event that
is not associated with or that does not contain specific target information. For example, most of the
events that are reported to the event console are simple events.

1159
For more information about the new configuration user interface, DDM, and the collection hierarchy, see
the topic Domino domain monitoring.

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 Description
DDM Probe Defines the probe type, probe subtype, a general
description of the probe, configurable specifics on what
the probe monitors, how results are reported, and other
related information
DDM Filters Defines which event types, event classes and event
severities are reported to the DDM file.
Event Generator Defines the parameters of an event.
Event Handler Describes what action to take when an event occurs.
Event Notification Method Defines the notification method to use when the Event
Handler document prescribes notification.
Log Filter Specifies events that you do not want to log.
Server Console Configuration Sets the text, background, and color attributes for the
Domino server console.
Statistic Description Describes a statistic.
Server Statistic Collection Specifies one or more servers from which statistics are
collected and identifies the server that performs the
collecting.

Monitoring server shutdown

Domino’s Shutdown Monitor task ensures that Domino terminates when requested to do so, that is, the
server does not hang while attempting to shut down. When you request a server shutdown, the System
Monitor task monitors the shutdown activity. If no activity occurs for a specified amount of time, Domino
automatically acts as though the server has crashed and takes appropriate action including collecting data
about the state of the server and then terminating the server. An NSD log is generated before the server
terminates.

You specify the amount of time that Domino monitors the shutdown activity in the field, Server
Shutdown Timeout, in the Automatic Server Recovery section of the Server document. To disable this
feature, enter 0 (zero) in the Server Shutdown Timeout field.

Monitoring processes running in the Domino server environment

Domino’s ″Process Monitor″ task applies to Domino on Microsoft Windows platforms only. This task
monitors the processes that should be running as part of the Domino server environment. If one of these
processes is missing, or if one terminates unexpectedly without completing the usual Domino termination
routines, this task causes the server to Panic and indicates the process that has prematurely terminated.
The Process Monitor task works with nprocmon.exe, which monitors the nserver.exe process for abnormal
termination.

This functionality is implemented in Domino for Unix platforms without using a separate server task.

To disable the Process Monitor task, set the variable PROCESS_MONITOR_DISABLED=1 in the server’s
NOTES.INI file.

1160 Lotus Domino Administrator 7 Help

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.

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.

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.

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 Description

Database event generator
Domino server response event generator
v Monitors database activity and free space
v Monitors frequency and success of database replication
v Reports on ACL changes, including those made by
replication or an API program
v Checks connectivity and port status of designated
servers in a network

Chapter 53. Monitoring the Domino Server 1161

Event generator Description
Mail routing event generator v 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
Statistic event generator v Monitors a specific Domino or platform statistic
Task status event generator v Monitors the status of Domino server and add-in tasks
TCP server event generator v 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 Meaning

Fatal Imminent system crash
Failure Severe failure that does not cause a system crash
Warning (high) Loss of function requiring intervention
Warning (low) Performance degradation
Normal Status messages

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 Action
File name Enter the name of the database.
Servers Choose one:
v All in the domain
v Only the following. Then select one or more servers to monitor.

4. In the ″What to monitor″ section, choose one or more of the following:

v Monitor ACL Changes -- To monitor all ACL changes, including those made by replication.
v Monitor replication -- To monitor the frequency and success of database replication. Then complete
these fields on the Replication tab:

Field Action
Server(s) with which the database must replicate Choose one:
v All in the domain.
v Only the following. Then select one or more servers
from the list.
Replication timeout Enter a time-out value. The default is 24 hours.

v 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:

1162 Lotus Domino Administrator 7 Help

Field Action
Trigger the event when unused space exceeds Enter a percent. The default is 30%.
Automatically compact the database when the above (Optional) Select this option (the default) to compact the
condition is met database.

v 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 Action
Time periods to monitor Choose one:
v Daily
v Weekly
v Monthly
Minimum sessions Enter a minimum number of sessions that will trigger an
event. The defaults are:
v Daily -- 10 sessions
v Weekly -- 50 sessions
v Monthly -- 300 sessions

5. On the Other tab, complete these fields, and then save the document:

Field Action
Generate a database event of severity Select a severity level.
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 Action
Target server(s) Choose one or more servers to probe.
Probing server (source) 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.
5. Choose one of the following options:
v Check just the ability to access the destination server
v Check the ability to access the destination server and open this database, and then enter a file name

Chapter 53. Monitoring the Domino Server 1163

6. Click the Probe tab, and then complete these fields:

Field Action
Ports Do one:
v Enable the field to use any configured port to check access.
v 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
On time-out, generate a Server event of severity Select a severity level.
Create a new event handler for this event Click to launch the Event Notification 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.

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
All Domino servers in the domain
will probe themselves
Recipient
Probing servers (source)
Show intermediate hop times
Action
Do one:
v Check this option to have each server to probe only the local mail box.
v Uncheck this option to probe specified servers.
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.

1164 Lotus Domino Administrator 7 Help

5. Click the Probe tab, and complete these fields:

Field Action
Send interval Enter the number of minutes between probes. The default is 15.
Time-out threshold 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 a Mail event Select the severity level.
of severity
Create a new event handler for this Click this button to launch the Event Notification Wizard and create an event
event handler.

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:
v All in the domain
v 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:
v 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.
v Monitor as a number (bytes). Then click the Threshold tab, and enter a threshold value in bytes.
5. For the ″Generate the event when″ field, choose one:
v The statistic is less than the threshold value
v The statistic is greater than the threshold value

Chapter 53. Monitoring the Domino Server 1165

 v The statistic is a multiple of the threshold value
6. Click the Other tab, complete these fields, and then click Save & Close.

Field Action
Generate a statistic event of severity Select a severity level.
Create a new event handler for this event Click this button to launch the Event Notification 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 Action
Task name Select the name of the task.
Servers Choose one:
v All in the domain
v Only the following. Then select the name of one or
more servers
What to monitor v Monitor task down
v Monitor task up
v Monitor task not responding
v Monitor task resumed responding

4. Click the Other tab, complete these fields, and then save and close.

Field Action
Generate a monitor event of severity Select a severity level.
Create a new event handler for this event Click this button to launch the Event Notification Wizard
and create an event handler.

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:

1166 Lotus Domino Administrator 7 Help

 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:
v Check the option to have each server probe all services on its own configured ports. Then
continue with Step 6.
v Uncheck the option to specify the server ports and services to probe.
5. Under Target Servers, choose one:
v All in the domain (default) -- To probe the ports of all servers in the domain.
v 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.
7. Click the Probe tab, and complete these fields:

Field Action
Probe interval Enter the number of minutes between probes. Default is
15.
Service time-out threshold 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.
v Probe all configured TCP services
v 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
v Probe just the port -- To probe the availability of the HTTP service on the port.
v 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:
v Probe just the port -- To probe the availability of the NNTP service on the port.
v 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 an event Select the severity level.
severity
Create a new notification profile for Click this button to launch the Event Notification Wizard and create an event
this event handler.

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.

Chapter 53. Monitoring the Domino Server 1167

To do this Perform this task
Start the ISpy task automatically when the server Edit the ServerTasks setting in the NOTES.INI file to include
starts runjava ISpy.
Start the ISpy task manually Enter the command load runjava ISpy at the console.
Stop the ISpy task Enter either the command tell runjava ISpy unload or tell
runjava quit at the console.

For more information about NOTES.INI settings and server commands, see the appendices.

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.

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.

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:
v Event handler wizard -- Creates an event handler.
v Database and statistic wizard -- Creates database and statistic event generators.
v 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.

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.

1168 Lotus Domino Administrator 7 Help

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:
v Log the event to a configured destination
v Notify you that the event occurred and specify the method of notification
v Forward the event to another program for additional processing
v Prevent the event from being logged to the server console or to a specified destination
v Run an agent
v Send console commands and scripts

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

Notification method Result

Broadcast Reports the event to all users logged onto the server or to a specified group of
users according to the option that you select.
Log to a database Logs the event to a database, typically STATREP.NSF, on the server on which
the event occurred, or on a server that you specify. Select this method only if
the specified server is reporting events to its own collection database.
Mail 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.
Log to NT Event Viewer Reports the event to the Windows NT Event Viewer.
Pager Uses the mail address of an alphanumeric pager to report a modified version of
an event to a pager.
Relay to other server 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.

Chapter 53. Monitoring the Domino Server 1169

Notification method Result
Run an agent Runs a specified agent based on the configured Event Handler. Use this method
to resolve an issue without user intervention. You specify the agent name, the
server and database containing the agent, and any parameter to pass to the
agent.
Note: You must have the appropriate database access to run an agent from a
database.
Run Program Runs an add-in program or specified command to correct problems
automatically. The Run Program notification method also provides the option to
pass event parameters. You can specify which parameters to pass when the
program runs. Optionally, you can specify switches for the parameters. You
must have full remote console access in the Server document to issue LOAD
commands.

For more information on passing event parameters, see the topic Passing event
parameters using the Run Program notification method.
Send a console command to the Sends a console command, or commands, to the server according to the Event
server Handler that was configured. You can specify the server console commands to
be run. Any console command can be used with an event handler. The console
command must be delineated by quotes when you enter it. For example

’SHOW SERVER, SHOW TASK’

You can also use this option to run a console script.

Send Java Controller command
For a local event handler configured for the Domino Administrator, you specify
the server on which to run the command or script. For event handlers that
exectute on a server, the command is sent to the server that is executing the
event handler.
Sends Java server controller commands based on an event. The commands that
can be sent to the controller are restart Domino, start Domino, and shutdown
Domino. You specify the server and the Java controller command. Your
username (short name) and Internet password are used by the event task to
access the Java controller. For more information, see the topic Setting, modifying
or deleting the server controller user’s ID properties.

You also need to create a Connection document to the server that is running the
server controller. For more information, see the topic Creating a Connection
document for use with a Java controller command.
Sound Sounds an alarm on the designated server when the event occurs. You specify
the sound file.
SNMP Trap 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.
Log to UNIX System Log Reports the event to the UNIX system log.

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.

1170 Lotus Domino Administrator 7 Help

Passing event parameters using the Run Program notification method: You can pass event parameters
to a program that you want to run. The run program event handler passes information to the program as
parameter. The following event parameters can be passed to a program in the order in which they are
listed. All parameters are passed as text except for the error code, which is passed as a number.
v Event Type
v Event Severity
v Error Code
v Originating Server
v Event Time
v Event Text
v Target Server
v Target Database
v Target User
v Target Extra Data

You also have the option of entering switches for the event parameters.

Note: If you have created Event Handler documents that use the Run Program notification option, using
a Domino release issued prior to Domino 7, you need to re-edit and then save those Event Handler
documents to allow them to be compatible with Domino 7.

For information about how to create an event handler, see the topic Creating an event handler.

Setting, modifying or deleting the Java server controller user’s ID properties: Use this dialog box to
set, modify or delete the user ID and Internet password used to access the Java controller. The ID
properties for the server controller are stored in the server’s ID file.

The Java console command must be sent to a remote server and that server must be running within a
Java console. You need Administrator access to that server for authentication purposes. Set the
Administrator access in the Administrators field on the Security tab of the Server document.

When an event handler of notification type ″Send Java Controller command″ that you created or edited
runs, the event task uses your short name and Internet password to access the Java controller. When that
access is established, the event task sends the Java controller command.
1. From the Domino Administrator, click Configuration - Monitoring Configuration.
2. Click Tools - Set Server Controller’s ID.

Field Action
Server Controller username Enter the user’s short name for accessing the server controller.
Server Controller password Enter the user’s Internet password for accessing the server
controller.

3. Do one of these:
v To set or modify the user name or password for the server controller user, click Set and then
proceed to step 5.
v To delete the user name and password for the server controller user, click Clear and then proceed
to step 5.

Chapter 53. Monitoring the Domino Server 1171

Field Action
Password verify Do one:
v If you are modifying the user’s server controller password (Internet
password), re-enter the new password to verify the password you
entered in the Server Controller password field.
v If you are deleting a user account name (user’s short name), re-enter
the existing Server Controller user’s Internet password to allow the
delete to take effect.

Creating a Connection document for use with a Java controller command: To use the event handler of
notification type ″Send Java Controller command,″ you must create a Connection document between the
server running the Java controller and the server sending the Java controller command.

The server that is running the Java controller must have entries in these fields in order for the ″Send Java
Controller command″ notification to work correctly:
v Optional network address
v Use the port(s)

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 Generates

Add-in Messages related to the Add-in task.
Adminp Messages related to the Adminp task.
Agent Messages related to agents.
Client Messages related to the client.
Comm/Net Messages related X.PC.
Compiler Messages related to compute and compile functions.
Database Messages related to databases.
Directory (LDAP) Messages related to directory services.
Mail Messages related to mail routing.
Misc Miscellaneous messages not in another event category.
Monitor Messages related to events generated on the Domino Administrator by Server Monitoring.
Network Messages related to the LAN.
Replica Messages related to replication, including event handler notifications generated by a
database event generator.
Resource Messages related to system resources.
Router Messages related to mail events.
Security Messages related to ID files and server and database access, including event handler
notifications generated by a database event generators.
Server Messages related to conditions on a particular server or server connectivity. These messages
can include event handler notifications generated by Domino server event generators.
Statistic Messages related to statistic alarms.
Unknown Messages that have an unknown prefix and are not listed in another event category.
Update Messages related to indexing.
Web (HTTP/HTTPS) Messages related to the HTTP task.

1172 Lotus Domino Administrator 7 Help

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:
v Notify of the event on any server in the domain
v Notify of the event only on the following servers. Then select the server from a list.
4. Under Notification trigger, If you choose ″Any event that matches a criteria,″ complete these fields on
the Event tab:

Field Action
Event type Choose one:
v Events can be any type
v Events must be this type. Then select the type from the list.
Event severity Choose one:
v Events can be any severity
v Events must be one of these severities. Then select a severity level from the list.
Message text Choose one:
v Events can have any message
v Events must have this text in the event message. Then type the message text.

If you choose ″A built-in or add-in task event,″ click the Events tab, and then click Select Event. Select
the event from the list, and choose one:
v Events can have any message
v Events must have this text in the event message. Then type the message text.
If you choose ″custom event generator,″ select it from the list or click New to create a new custom
event generator.
v (Optional) Click ″Details″ to view a custom Event Generator document.
5. Click the Action tab and choose the notification method.

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:
v Enable this notification -- To enable the notification during all hours.
v Disable this notification -- To disable the notification so that it does not run.
v 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.
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.

Chapter 53. Monitoring the Domino Server 1173

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.

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.

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:
v Log All Types -- Then specify a severity level.
v 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:
v Log All Types -- Then specify a severity level.
v 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.″

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:
v All
v By Action
v By Author
v By Severity

1174 Lotus Domino Administrator 7 Help

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

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:
v Event Messages -- To view all messages, sorted by type and then by severity level.
v 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 Default color

Console Background Black
Normal Events Light grey
Fatal Events Red

Chapter 53. Monitoring the Domino Server 1175

Console display Default color
Failure Events Magenta
Warning (High) Events Yellow
Warning (Low) Events White

6. (Optional) To reset the colors to the defaults, click Reset to Defaults.

7. Click Save & Close.

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:
v Check the field to use the defaults set in the Server Console Configuration document for the server.
This is the default.
v 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:
v To remove a stop trigger, select Live Console - Local - Remove Stop Trigger.
v To set a stop trigger, select the event for which to set a stop trigger. Then from the menu, select
Live Console - Set Watch.
5. Do one to restart the Domino Administrator server console:
v If you clicked Pause, click Resume.
v 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.

1176 Lotus Domino Administrator 7 Help

6. Do one to restart the Domino Administrator server console:
v If you clicked Pause, click Resume.
v 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:
v If you clicked Pause, click Resume.
v 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.

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.

Chapter 53. Monitoring the Domino Server 1177

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.

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

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.
4. Choose one of the following:
v All servers in this domain -- To collect statistics from all servers connected to the collector server.
v 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.
v 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 Action
Database to receive reports 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.

1178 Lotus Domino Administrator 7 Help

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

Server statistics and replication status

One of many types of server statistics are the replication statistics that indicate the status of replication
attempts that occur on the Domino server. To view the server statistics, including those pertaining to
replication, type this command at the server console:
Show stat

The server console displays a list of all server statistics that are collected on your server. The following
replication-related statistics may appear:

Statistic Description
NotesMergedBack The destination note sequence is actually higher than the source.
Domino will assume a replication merge happened here and
update the source as well
NotesReceived If the NSF Database is the source database
NotesReopened There is a possible replication conflict; Or Domino couldn’t find a
corresponding item for an incremental note, therefore domino can’t
perform an incremental update and will try again with a full note
open.
NotesSent If the NSF Database is the destination database

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.

By default, the Statistic Collector task continuously gathers these statistics:

v Logical disk -- Statistics for individual disks and total percent use of all disks
v Paging file -- Statistics that show use of paging files
v Memory -- Statistics showing memory allocation and use, including available memory
v Network -- Statistics for individual network adapters and cumulatively for all the network adapters on
the system
v 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.)
v System -- Statistics on the information captured -- for example, a summary of system CPU use and
queue length.

Chapter 53. Monitoring the Domino Server 1179

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 2000) or a system command, such as this UNIX command:
iostat /vmstat/ netstat

Platform statistics for Domino for Linux

Domino for Linux does not require iostat, vmstat, or netstat to collect statistics.

Note: If Logical Disk statistics do not appear, ensure that the sysstat package is installed on your server.

Platform statistics for Domino with AIX

To obtain platform statistics for Domino AIX, the perfstat package is required. Ensure that the perfstat
package is installed. By default, disk statistics are not automatically collected each time the server is
rebooted. To enable continuous collection of disk statistics, enable the system attribute, iostat..

To determine whether iostat is enabled to allow continuous collection of disk statistics, enter the
following command:
lsattr -E -l sys0 -a iostat

If a value of false is returned for the system attribute, iostat, continuous collection of disk statistics is
disabled.

To enable the continuous collection of disk statistics, enter the following command:
chdev -l sys0 -a iostat=true.

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:
v Logical disk
v Memory
v Network
v Paging file
v Process
v 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:

1180 Lotus Domino Administrator 7 Help

v 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.
v 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).
v 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 systems: If you use Perfmon on 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.

Network statistics: On Solaris, AIX, Linux, Linux on z/Series and OS/400®, Domino provides statistics
for a maximum of ten network adapters. On Windows 2000, 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, 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, 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.

Logical disk statistics: On 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).

System statistics: On Windows 2000 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, Linux, Linux
for zSeries, and AIX, the value of the combined CPU utilization statistic is defined as sum of the user and
privileged CPU utilization values.

Chapter 53. Monitoring the Domino Server 1181

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:
v Domino 6 -- To view platform statistics available for both Domino 5 and Domino 6 servers.
v 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_Statistics_Disabled=1

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:

v View statistic reports of the most commonly used statistics.
v View default statistic thresholds
v Define new statistics
v View a list and description of all statistics
v Export statistics to a spreadsheet
v Mail statistics to a mail-in database
v Create a statistic profile

Viewing statistics reports

Domino includes these default statistics reports:
v Calendaring and Scheduling
v Clusters
v Communications
v Mail and Database
v Network
v Platform
v System
v Web Server & Retriever

1182 Lotus Domino Administrator 7 Help

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.

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.

For more information about Activity Trends and resource balancing, see the topic Resource balancing in
Activity Trends.

For more information about Activity Trends and resource balancing, see the chapter ″Using Activity
Trends.″

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

Chapter 53. Monitoring the Domino Server 1183

3. On the Basics tab, complete these fields:

Field Action
Statistic name Enter the name of the new statistic.
Data type Choose one:
v Text
v Number
v Time
Statistic unit Enter one:
v The unit in which the statistic is measured -- for example, bytes or minutes
v The word ″none,″ if this is a text statistic
Statistic description Enter a description of the statistic

4. Click the Advanced tab, and do one of the following:

v If you selected Text or Time as the data type, go on to Step 5.
v 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:
v Has trended values -- If the statistic has both trended and last-occurrence values.
v Has prime/24-hour values -- If the statistic includes values for the prime shift and for a 24-hour
period.
v Is user selectable -- If the statistic will be used as a selection -- for example, in a dialog box.
v Used in resource balancing -- If the statistic will be used when balancing resources using Activity
Trends.
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 Action
Threshold operator Select the condition against which to evaluate the threshold:
v Less than
v Greater than
v Multiple of
v Percentage of
Threshold value Enter a number.
Event severity Select the severity that will cause an alarm.
Suggested response (Optional) Enter an explanation of a how to resolve the event that
caused the alarm.
Useful in setup 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.

1184 Lotus Domino Administrator 7 Help

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:
v All documents
v Selected documents
7. For ″Detail to incorporate,″ check ″Include view titles″ to include titles.

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 Action
To Enter the title of one or more mail-in databases for one or more servers.
Subject Do one:
v Enter a statistic category -- for example, disk or platform -- to get a subset of statistics.
v Enter the name of one statistic -- for example, Disk.C.Free.
v Use an asterisk to indicate a group of specific statistics. For example, enter Disk.C.* to report
all disk statistics for drive C.
v Leave the field blank to mail all server statistics.

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.

Chapter 53. Monitoring the Domino Server 1185

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:
v Create and edit statistic profiles
v Remove existing statistic profiles or combine them into a new one
v Gather historical statistics over a specified period of time
v View the details of each statistic
v View an isolated statistic
v Start and stop real-time charting dynamically
v 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.

To create a statistic profile:

1. From the Domino Administrator, click the Server - Performance tab.
2. Do one:
v If there are no statistics profiles displayed in the statistic profiles list, click Add.
v 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:
v Bundled statistics -- To create a group made up of predefined sets of statistics.
v Individual statistics -- To create a new group made up of selected individual statistics.
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

1186 Lotus Domino Administrator 7 Help

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:
v Click the Notes tab, and select a predefined color.
v 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.

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:
v Maximized -- To display only the statistic chart.
v Maximum Width -- To display the list of statistics and the statistic chart.
v Maximum Height -- To display the statistic chart and the server pane.
v 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
Get a numerical representation of a graphical
statistic
Get a textual representation of the statistic
chart
Chart an isolated statistic
Action
Click the Stop/Start button.
Click the statistic in the profile list. Then look at the bar area
between the profile list and the chart.
Double-click the chart to display a document that you can edit and
print.
Double-click a graph line.

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 Action
Dynamically remove a statistic from the chart displayed In the profile list, clear the check box next to the statistic.
Dynamically add a statistic Click Add, and then select a statistic.
Dynamically add a server Click the down arrow, and then select a server.
Dynamically remove a statistic Select a statistic in the profile list, and then click Remove.

Note: Save the profile to keep any changes.

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.

Chapter 53. Monitoring the Domino Server 1187

2. Select a statistic profile from the list, and do any of the following:

Task Action
Add a statistic 1. Click Add.
2. Select the Domain and server, and then select the statistic.
3. Click Add Statistic.
Add a server 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.
Delete (remove) a statistic from a profile Select the statistic, and click Remove.
Delete the entire profile 1. Select the name of the profile in the Statistics profile field.
2. Click Performance Monitor - Saved Statistics Profiles - Delete.

3. To save the profile, do one:

v Click Performance Monitor - Saved Statistics Profiles - Save -- To overwrite the original statistic
profile with the changes.
v Click Performance Monitor - Saved Statistics Profiles - Save As -- To save the modified statistic
profile under a new name, leaving the original statistic profile intact.

1188 Lotus Domino Administrator 7 Help

Chapter 54. 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:
v 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.
v 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.
v 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.

The Domino SNMP Agent’s main functions

The agent provides:
v Out-of-band server status through the MIB
v Control of a Domino server through SNMP
v Real-time alerts on server status
v Forwarding of Domino events as SNMP traps
v 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:
v Stop the Domino server
v Start the Domino server
v Reboot the operating system

1189
 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:
v The information is provided in real-time.
v The information is available out-of-band. Determining whether the server is up or down does not
require the Notes client or Domino server.
v The information is qualitatively better. Instead of two states, up or down, SNMP can determine seven
states or events as follows:

Specific trap Clearing trap

Message Status number number
Domino server is up: [server name] (This server has been Normal 11 12
started by a console command or using SNMP.)
Domino server is shut down: [server name] (This server Disabled 12 11
has been shut down by a console command or using
SNMP.)
Domino server pulse has failed: [server name] (This Warning 13 14
server is excessively busy or unresponsive to the SNMP
pulse.)
Domino server pulse is restored: [server name] (This Normal 14 13
server is no longer busy and now responding to the
SNMP pulse.)
System is rebooting (The Domino SNMP Agent is Informational 15 N/A
rebooting the entire system.)
Domino server is not responding: [server name] (This Critical 16 17
server may have crashed or hung.)
Domino server is now responding: [server name] (This Normal 17 16
server is now responding again.)

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.

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.

1190 Lotus Domino Administrator 7 Help

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

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

Chapter 54. Using the Domino SNMP agent 1191

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

Domino SNMP Agent architecture

Domino SNMP Agent services are provided by two types of programs:
v 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.
v 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:

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

1192 Lotus Domino Administrator 7 Help

For additional information, refer to your operating system’s or network management tool’s
documentation (such as NetView or OpenView).

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:

v 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.
v lnControl -- Values provided by LNSNMP including those monitoring and controlling the server.
v lnInterceptor -- An internal branch relating to the Event Interceptor add-in task.
v lnUnix -- An internal branch that supports for NetView for AIX.
v lnMPAInfo -- A branch with one value provided by LNSNMP that gives the version of the Domino
SNMP Agent.

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
System requirements for the Domino SNMP Agent are listed below.

Chapter 54. Using the Domino SNMP agent 1193

Microsoft Windows requirements
v Microsoft Windows native TCP/IP.
v Microsoft Windows SNMP Agent service.

IBM AIX requirements

v IBM AIX native TCP/IP.
v IBM AIX Master SNMP Agent (snmpd).

Linux requirements
v Linux native TCP/IP.
v 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. A
suitable version of the NET-SNMP 5.0.7 Master Agent is included with Domino for Linux.

Solaris requirements
v Solaris® native TCP/IP.
v 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. A
suitable version of the NET-SNMP 5.0.7 Master Agent is included with Domino for Solaris.

Note: Prior versions of Domino have included the PEER Networks Master SNMP Agent for Solaris.
You can continue using the PEER Networks Master SNMP Agent with this version of Domino, but it is
no longer distributed or supported.

z/OS requirements
v See the most recent Lotus Domino z/OS Installation Guide for current requirements.

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:
v Windows
v AIX
v Linux
v Solaris
v OS/390
2. Complete the configuration.

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

1194 Lotus Domino Administrator 7 Help

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 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:
v Windows: Windows System directory
v AIX, Linux or Solaris: /opt/lotus
v 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

Chapter 54. Using the Domino SNMP agent 1195

 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.

Configuring the Domino SNMP Agent for Microsoft 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
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

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.

1196 Lotus Domino Administrator 7 Help

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 or /etc/snmpdv3.conf, depending on whether your system uses the SNMPv1 or
SNMPv3 master agent:
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/ibm/lotus/notes/latest/ibmpow/lnsnmp.sh /etc/lnsnmp.rc
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. To use the NET-SNMP Master Agent provided, refer to Using NET-SNMP with
the Domino SNMP Agent. Otherwise, verify that your Master SNMP Agent supports the SMUX protocol,
per RFC 1227. Ensure that the Domino executable and the Domino data directories are in your search
path.

Tip: If you are using the NET-SNMP Master Agent provided, the trap destinations and community
names are configured in the /etc/net-snmpd.conf file. Otherwise, refer to the documentation for the
master agent technology you are using. 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, stop the LNSNMP process before beginning the upgrade process.

Note: The following commands should be executed as the root user.

1. Stop the LNSNMP process. Enter this command:
lnsnmp.sh stop

Chapter 54. Using the Domino SNMP agent 1197

2. Stop the Master SNMP Agent. If you’re using the NET-SNMP Master Agent provided, enter this
command:
/etc/net-snmpd.sh stop
If you’re not using the NET-SNMP Master Agent provided, refer to your Master SNMP Agent’s
documentation.
3. Configure the Master SNMP Agent to accept LNSNMP as an SMUX peer. If you are using the
NET-SNMP Master Agent provided, this has already been done. Otherwise, refer to your Master
SNMP Agent’s documentation. 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 NET-SNMP Master Agent provided, enter this
command:
/etc/net-snmpd.sh start
If you’re not using the NET-SNMP Master Agent provided, 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 if necessary:
ln -f -s /opt/ibm/lotus/notes/latest/linux/lnsnmp.sh /etc/init.d/lnsnmp
insserv /etc/init.d/lnsnmp

You have completed the Linux-specific portion of the Domino SNMP Agent configuration. 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, ensure that TCP/IP and SNMP are properly installed and
configured on the server. To use the NET-SNMP Master Agent provided, refer to Using NET-SNMP with
the Domino SNMP Agent. Otherwise, verify that your Master SNMP Agent supports the SMUX protocol,
per RFC 1227. Ensure that the Domino executable and the Domino data directories are in your search
path.

Tip: If you are using the NET-SNMP Master Agent provided, the trap destinations and community
names are configured in the /etc/net-snmpd.conf file. Otherwise, refer to the documentation for the
master agent technology you are using. Configure appropriate trap destinations and community names
for your remote management infrastructure.

Note: The Domino SNMP Agent is set up to run automatically. Once the Domino SNMP Agent is
configured, it is virtually always running, even when Domino is not. If you later upgrade Domino, stop
the LNSNMP process, before beginning the upgrade process.

Note: Execute the following commands 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 NET-SNMP Master Agent provided, enter this
command:
/etc/net-snmpd.sh stop

1198 Lotus Domino Administrator 7 Help

 If you are not using the NET-SNMP Master Agent provided, refer to your Master SNMP Agent’s
documentation.
3. Configure the Master SNMP Agent to accept LNSNMP as an SMUX peer. If you are using the
NET-SNMP Master Agent provided, this has already been done. Otherwise, refer to your Master
SNMP Agent’s documentation. 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 NET-SNMP Master Agent provided, enter this
command:
/etc/net-snmpd.sh start
If you are not using the NET-SNMP Master Agent provided, 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/ibm/lotus/notes/latest/sunspa/lnsnmp.sh /etc/init.d/lnsnmp
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

You have completed the Solaris-specific portion of the Domino SNMP Agent configuration. Follow the
instructions found in Completing the Configuration of the Domino SNMP Agent.

Configuring the Domino SNMP Agent for z/OS

Follow the steps below, once per LPAR, to configure the Domino SNMP Agent for z/OS.

Before using the Domino SNMP Agent, ensure that TCP/IP and SNMP are properly installed and
configured on the LPAR. Also, verify that the Domino executable and the Domino data directories are in
your search path. We only support community-based security (SNMPv1 / SNMPv2 formats).

If you do not have SNMP configured on your LPAR, see the following IBM documentation to configure
SNMP:
v z/OS Communications Server: IP Configuration Guide, SC31-8775
v z/OS Communications Server: IP Configuration Reference, SC31-8776

The SNMP agent and subagents record trace information via the z/OS UNIX System Services syslog
daemon using the daemon facility. If you are using SNMP, set up the syslog daemon. For detailed
information regarding syslogd and specifying the daemon facility in the /etc/syslog.conf configuration
file, see the z/OS Communications Server manuals listed above.

Note: There is also a Syslogd How To informational APAR, apar II12021.

To verify that SNMP is configured correctly, enter the following command from within Unix System
Services:
osnmp -h <host name> walk system

The output should resemble the following sample output:

1.3.6.1.2.1.1.1.0 = SNMPv3 agent version 1.0 with DPI version 2.0
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.2.3.13

Chapter 54. Using the Domino SNMP agent 1199

1.3.6.1.2.1.1.3.0 = 1192800
1.3.6.1.2.1.1.4.0 = <userid>
1.3.6.1.2.1.1.5.0 = <hostname>
1.3.6.1.2.1.1.6.0 = <location>
1.3.6.1.2.1.1.7.0 = 76
1.3.6.1.2.1.1.8.0 = 950000
1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.2.11.7.1
1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.2.11.7.2
1.3.6.1.2.1.1.9.1.3.1 = z/OS SNMP Agent
1.3.6.1.2.1.1.9.1.3.2 = z/OS TCP/IP SNMP Subagent
1.3.6.1.2.1.1.9.1.4.1 = 0
1.3.6.1.2.1.1.9.1.4.2 = 1800

If the output from the osnmp command does not resemble the sample output, SNMP is not correctly
configured. Verify that you have SNMP configured correctly by reviewing the z/OS Communications
Server manuals prior to continuing. You need to be aware of the following when setting up SNMP for
Domino:
1. If you include a SACONFIG statement in your TCP/IP profile, verify that the statement in your
profile is similar to the following example:
SACONFIG ENABLED COMMUNITY public AGENT 161 SETSENABLED
You can replace public with any password you prefer. If you choose to change the password, and you
use a password in /etc/pw.src, verify that you have also changed that password.
2. Verify that port 161 is reserved in your TCP/IP profile.
PORT
161 UDP OMVS ; SNMP Agent
3. Verify the procedure OSNMPD is configured correctly and that it starts after every IPL.

Note: Before setting up the OSNMPD procedure, review the ″ z/OS Communications Server: IP
Configuration Guide″ which contains important information about data set naming and search
sequences.
The following is an example of an OSNMPD EXEC card:
//OSNMPD EXEC PGM=EZASNMPD,REGION=4096K,TIME=NOLIMIT,
// PARM=(’POSIX(ON) ALL31(ON)’,
// ’ENVAR("RESOLVER_CONFIG=/etc/resolv.conf"’,
// ’"OSNMPD_DATA=/etc/osnmpd.data")’,
// ’/-d 0’)
4. Mibs.data, osnmpd.data, pw.src and snmptrap.dest are not required for running the Domino SNMP
agent. However, if you choose to use these members, they must be set up correctly. Verify that these
members in /etc have Read access for user, group and other.
(rwxr - - r -)
If mibs.data and osnmpd.data are not in /etc, or if they are from a previous level, you can obtain the
current level from TCPIP samples located in /usr/lpp/tcpip/samples.

Note: Ensure that osnmp.conf is not located in /etc, because it is reserved for user-based security.

Tip: Trap destinations are defined in the SNMPTRAP.DEST dataset. Configure appropriate trap
destinations and community names for your remote management infrastructure.
5. If you are using /etc/pw.src or /etc/snmpd.conf, verify that they have the correct hostname as well
as the IP address for the Domino server. Hostnames are case-sensitive. Enter the following command
from within Unix System Services to obtain the correct host name for your system.
hostname

1200 Lotus Domino Administrator 7 Help

 The pw.src should resemble the following sample:
HOSTNAME 9.1.2.3 255.255.255.255
public 9.1.0.0 255.255.0.0
test1 9.1.0.0 255.255.0.0
If you set SACONFIG in the TCP/IP profile to not use public, replace hostname with the password
used in the SACONFIG statement.
6. Verify that snmptrap.dest has the correct hostname. Hostnames are case-sensitive.
HOSTNAME UDP
For more Information about common set up problems, see information APAR II13477.

To start the Domino SNMP agent

1. As a uid 0 user, start the LNSNMP process by typing this command:
lnsnmp.sh start

Note: Automatic start of the Domino SNMP Agent is not supported on z/OS.
2. When lnsnmp is started, verify that SNMP is aware of the Domino MIB by entering the following
commands:
osnmp -h <host name> walk system
The output should include this line:
1.3.6.1.2.1.1.9.1.3.3 = Lotus Domino SNMP Agent
osnmp getnext 1.3.6.1.4.1.334.72
The following should be displayed:
1.3.6.1.4.1.334.72.2.1.0 = 2

The value returned should have an OID number that starts with 1.3.6.1.4.1.334.72. This confirms that the
SNMP Agent is receiving the request, forwarding it to lsnmp, and that lsnmp is returning a valid value.

If you do not see the appropriate responses shown above, or if the getnext response is for an OID outside
of the Lotus Domino MIB, additional debugging is required. Start an SNMP Agent trace at level 255.

To determine whether there are additional things to check for and to obtain information about setting up
an SNMP Agent trace, see informational APAR II13477.

To stop the LNSMP agent use

Enter this command:
lnsnmp.sh stop

Completing the configuration of the Domino SNMP Agent

After you have performed the platform-specific configuration steps, complete the configuration of the
Domino SNMP Agent by following these steps which apply to all platforms. 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:

Chapter 54. Using the Domino SNMP agent 1201

 load collect
4. Arrange for the add-in tasks to be restarted automatically the next time that Domino is restarted. Add
quryset and/or intrcpt and collect to the ServerTasks variable in Domino’s NOTES.INI file.

Configuring traps for Domino events

After the Domino SNMP Agent is configured, the 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. Create the 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.

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, see the topics Creating a statistic event generator and Creating an event handler.

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, 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, the Domino SNMP Agent cannot be used to remotely
restart a Domino server. 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 identified itself to the
Domino SNMP Agent. To prevent this situation, include information about the server in the lnsnmp.ini
file.

The Allow Server Start and Allow Server Stop configuration options are in the SNMP tab of the server
Configuration Settings document.

To initiate a server start or server stop, the remote management console must set the lnServerTblSetState
MIB object. In the case of a non-partitioned server, the lnNotesServerSetState MIB object can also be used.

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,
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 document
unless you want to enable the Domino SNMP Agent to reboot the system.

Note: Rebooting is not supported on the z/OS platform.

For a partitioned server, all running partitions must configured to allow a system reboot. If one running
partition is configured to not allow a system reboot, then the reboot is not performed.

The Allow System Reboot configuration option is on the SNMP tab of the server Configuration Settings
document.

To initiate a system reboot, the remote management console must set the lnRemoteReboot MIB object.

1202 Lotus Domino Administrator 7 Help

Manually starting and stopping the Domino SNMP Agent
After you configure the Domino SNMP Agent, when you restart the system the Domino SNMP Agent
automatically starts. If necessary, you can stop the agent and then manually restart it.

Microsoft 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

IBM 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/init.d/lnsnmp stop

To start the lnsnmp process, enter this command as root:

/etc/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

z/OS
To start the lnsnmp process, from an OpenEdition command line, enter this command as a uid=0 user:
lnsnmp.sh start

To stop the lnsnmp process, enter this command as a uid=0 user:

lnsnmp.sh stop

Using NET-SNMP with the Domino SNMP Agent

On the Linux and Solaris platforms, the Domino SNMP Agent uses the SMUX protocol, per RFC 1227, to
communicate with the system’s Master SNMP Agent. Some Linux distributions include a Master SNMP
Agent that supports the SMUX protocol; others do not. The Solaris Master SNMP Agent does not support
the SMUX protocol, making it necessary to substitute a Master SNMP Agent that does. On the Linux and
Solaris platforms, Domino includes a suitable NET-SNMP Master Agent, called NET-SNMPD, already
configured to support the SMUX protocol and the Domino SNMP Agent.

Follow the instructions below to use the NET-SNMPD provided with Domino.

Note: Before using NET-SNMPD, disable any existing Master SNMP Agent. For information on disabling
an existing Master SNMP Agent, see your Master SNMP Agent’s documentation.

Chapter 54. Using the Domino SNMP agent 1203

Installing NET-SNMPD on Linux
Log on as the root user and then install NET-SNMPD on Linux as follows:
1. Install the NET-SNMPD files. Enter this command, changing the Domino executable path if necessary:
cp /opt/ibm/lotus/notes/latest/linux/net-snmpd* /etc
2. Arrange for NET-SNMPD to be restarted after a reboot. Enter these commands:
ln -f -s /etc/net-snmpd.sh /etc/init.d/net-snmpd
insserv /etc/init.d/net-snmpd

You have completed the installation of NET-SNMPD on Linux. Configure and start NET-SNMPD as
explained below.

Installing NET-SNMPD on Solaris

Log on as the root user and then Install NET-SNMPD on Solaris as follows:
1. Install the NET-SNMPD files. Enter this command, changing the Domino executable path if necessary:
cp /opt/ibm/lotus/notes/latest/sunspa/net-snmpd* /etc
2. Arrange for NET-SNMPD to be restarted after a reboot. Enter these commands:
ln -f -s /etc/net-snmpd.sh /etc/init.d/net-snmpd
ln -f -s /etc/init.d/net-snmpd /etc/rc2.d/S76net-snmpd
ln -f -s /etc/init.d/net-snmpd /etc/rc1.d/K76net-snmpd

You have completed the installation of NET-SNMPD on Solaris. Configure and start NET-SNMPD as
explained below.

Configuring NET-SNMPD
Update the /etc/net-snmpd.conf file with appropriate trap destinations and community names for your
remote management infrastructure. Trap destinations are set using the trapsink directive. Community
names are set using the rocommunity and rwcommunity directives.

Manually Starting and Stopping NET-SNMPD

To start NET-SNMPD, log on as the root user and enter this command:
/etc/net-snmpd.sh start

To stop NET-SNMPD, log on as the root user and enter this command:
/etc/net-snmpd.sh stop

How NET-SNMPD was Created

The NET-SNMP package, which is distributed by http://www.net-snmp.org, contains a variety of tools
for SNMP, however, Domino only includes the NET-SNMP Master Agent.

For Domino, the NET-SNMP 5.0.7 package was configured and built with the following options:
--enable-shared=no
--with-default-snmp-version=3
--with-logfile=/var/log/snmpd.log
--with-mib-modules=smux
--with-openssl=no
--with-persistent-directory=/var/net-snmp
--with-sys-contact=Unknown
--with-sys-location=Unknown

The resulting agent/snmpd was used as the NET-SNMPD for Domino.

1204 Lotus Domino Administrator 7 Help

Creating and Configuring your own NET-SNMP Master Agent
Because the UCD-SNMP and NET-SNMP packages, which are distributed by http://www.net-snmp.org,
contain many optional components, you may want to create and/or configure your own Master SNMP
Agent for use with Domino. To do so, invoke the source configure script with the following option, to
include SMUX support:
--with-mib-modules=smux

Add the following line to the snmpd.conf file:

smuxpeer 1.3.6.1.4.1.334.72 NotesPasswd

Note: If you use the NET-SNMPD provided with Domino, you do not need to create or configure your
own NET-SNMP Master Agent. Both have been done for you.

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

Note: The Domino MIB is actually used by the Domino 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.

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 7 server.
2. Choose Monitor - Customize Traps.
The Customize Trap Alarms dialog appears.
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

Chapter 54. Using the Domino SNMP agent 1205

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.

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 7 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
You receive a message for each trap added.
5. Restart NetView. Enter this command:

1206 Lotus Domino Administrator 7 Help

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

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:
v The platform-specific Master SNMP Agent
v The Domino SNMP Agent
v 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:
v 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.
v MIB variable to determine if the Domino SNMP Agent is working, for example,
iso.org.dod.internet.private.enterprises.lotus.notes.mpaInfo.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.
The message stops if you start the agent or tell the QuerySet Handler to quit running.
v MIB variable to determine if the QuerySet Handler is working, for example,
iso.org.dod.internet.private.enterprises.lotus.notes.lnInfo.lnQSBuildNumber (.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.

Chapter 54. Using the Domino SNMP agent 1207

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.

1208 Lotus Domino Administrator 7 Help

Chapter 55. Using Server Health Monitoring
This chapter describes Server Health Monitoring and explains how to use it. Server Health Monitoring
extends the usefulness of traditional performance troubleshooting by automatically calculating health
statistics, comparing those statistics to predefined thresholds, and reporting on overall server health.

Server Health Monitor

In Domino, performing traditional performance troubleshooting involves:
v Using event generators and notifications and Domino server monitoring to perform real-time
data-analysis
v 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
v 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.

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

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

Overall server health statistics

Statistic Rating Explanation
0 = Health.Overall.Value Never Seen The server has never been seen running
during the current server monitor session.
0 < Health.Overall.Value Healthy The server is performing within
acceptable levels of tolerance.
and

Health.Overall.Value <
Health.Overall.Threshold.Warning
Health.Overall.Threshold.Warning < = Warning One or more server components are
Health.Overall.Value approaching unacceptable levels of poor
performance.
and

Health.Overall.Value <
Health.Overall.Threshold.Critical
Health.Overall.Threshold.Critical <= Critical One or more server components are
Health.Overall.Value failing to perform acceptably.

and

Health.Overall.Value <= 97
98 = Health.Overall.Value Critical One or more server tasks issued a fatal
error message.
99 = Health.Overall.Value Critical One or more tasks are not responding.
100 = Health.Overall.Value Server Down The server is not responding.

Component health statistics

Overall health ratings are based, in part, on component health statistics values.

Statistic Rating Explanation

0 = Health.*.Value Never Seen The component is not being monitored.
0< Health.*.Value Healthy The component is performing within
acceptable levels of tolerance.
and

Health.*.Value < Health.*.Threshold.Warning

1210 Lotus Domino Administrator 7 Help

Statistic Rating Explanation
Health.*.Threshold.Warning <= Health.*.Value Warning The component is approaching
unacceptable levels of poor performance.
and

Health.*.Value< Health.*.Threshold.Critical
Health.*.Threshold.Critical <= Health.*.Value and Critical The component is failing to perform
acceptably.
Health.*.Value <= 97
98 = Health.*.Value Fatal The task associated with the component
issued a fatal error message.
99 = Health.*.Value Not Responding The task associated with the 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 Description
Never Seen The server has never been seen running during the current server monitor session.
Healthy The server is performing within acceptable tolerances.
Warning One or more server components are approaching unacceptable levels of poor
performance.
Critical The server is experiencing one or more of these critical problems:
v One or more server components are failing to perform acceptably
v One or more tasks on the server have issued a fatal error
v 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 Description
Healthy The server component appears to be running correctly.
Warning The server component is approaching unacceptable levels of poor performance.
Critical The server component is failing to perform acceptably.
Fatal The task related to this component has issued a fatal error.
Not Responding The task related to this component is not responding.

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.

Chapter 55. Using Server Health Monitoring 1211

 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:
v Enable platform statistics on the server. Platform statistics are enabled, by default, in Domino. 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.
v Make sure you have at least View-only Administrator rights for every server you want to monitor.
v 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:
v Specify which server components to monitor
v Enable statistic alarms
v Modify threshold values for server components
v Create health reports
v Excluding a server from monitoring by the Server Health Monitor
v Change the purge interval for historical health reports
v Improve the performance of the Server Health Monitor

1212 Lotus Domino Administrator 7 Help

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:
v Automatic -- to allow the Server Health Monitor to select the components to include in health
reports, based on which server tasks are running.
v 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.

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

Chapter 55. Using Server Health Monitoring 1213

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

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:

v 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.
v 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.
v Details Regarding Rating -- This information backs up the recommendations. Information can include
details about the server’s configuration or performance.
v Short Term Recommendations -- These are things you can do immediately to improve the server’s
performance.
v Long Term Recommendations -- These are suggestions for making lasting improvements that will
prevent a poor health rating in the future.

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.

1214 Lotus Domino Administrator 7 Help

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

To reduce the amount of statistic data:

v Increase the server polling interval in Administration Preferences.
v 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 Domnio server monitor, and then restart
it.
v 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:

v Use monitoring profiles to monitor server health
v View server health
v Define event generators and event handlers for health statistics (Jump to topics)
v Excluding a server from monitoring by the Server Health Monitor from being monitored or from
generating health reports
v Create statistics profiles and chart health statistics

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

Chapter 55. Using Server Health Monitoring 1215

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 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:
v Creating monitoring profiles in the Domino server monitor
v Modify a system profile
v 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.
3. In the Health column (Hea), the Server Health Monitor uses these icons to indicate the server’s overall
health:
v Green thermometer -- the server’s overall health rating is Healthy. All server components are within
the appropriate range.
v Yellow thermometer -- the server’s overall health rating is Warning. One or more server
components being monitored are approaching unacceptably poor levels of performance.
v 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.
1216 Lotus Domino Administrator 7 Help
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.
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:
v Create statistics profiles
v Modify statistic profiles
v Display statistic charts

For information on creating statistic profiles and charting statistics, see the chapter ″Monitoring the
Domino Server.″

Chapter 55. Using Server Health Monitoring 1217

1218 Lotus Domino Administrator 7 Help
Chapter 56. Monitoring Domino Domains
This chapter explains Domino domain monitoring (DDM), how to create and maintain probes, set up and
maintain a DDM server collection hierarchy, schedule probes, as well as how to use the Domino Domain
Monitor database (DDM.NSF) to resolve problems.

Domino Domain Monitoring (DDM)

v Domino Domain Monitoring
v Creating and configuring DDM probes
v Maintaining DDM Probes
v Server collection hierarchy
v Domino Domain Monitor database (DDM.NSF)
v Correlating Events
v Assigning events to an administrator in DDM
v DDM Filters

Domino domain monitoring

Note: If you already have a Domino Domain Monitor database (DDM.NSF) from a previous Domino 7
beta release, before you upgrade to Domino 7 (non-beta), delete the beta copy of DDM.NSF and allow the
current release of Domino 7 to create a new Domino Domain Monitor database on all of your servers.
You should also delete all Probe configuration documents before you upgrade from a beta release of
Domino 7.

Domino domain monitoring (DDM) provides one location in the Domino Administrator client that you
can use to view the overall status of multiple servers across one or more domains, and then use the
information provided by DDM to quickly resolve problems. DDM requires a Domino 7 server.

DDM does the following:

v Automates problem determination and determines probable cause in multiple feature areas.
v Provides an active monitoring capability utilizing more than 50 new probes with highly-configurable
schedules, content and targets.
v Provides a top-down, feature-oriented view of the domain status with the ability to selectively view
detailed information on that status.
v Provides visual indicators for displaying which problems are most critical, which are resolved, and
which are not.
v Provides default settings for probe configuration to make setup easy.
v Recognizes and reports critical server and client issues within minutes.
v Provides corrective actions and links to databases in order to resolve reported problems.

DDM uses configurable probes to gather information across multiple servers and then consolidates and
reports that information on specially-designated collection servers in the Domino Domain Monitor
database (DDM.NSF). A probe is a discrete check, or set of checks, configured to run against one or more
servers, databases, and services. The probe returns status and server health information to DDM.NSF.
Probes run according to a default schedule, a schedule that you specify, or on an as-needed basis as
determined by the probe and the events on the server.

1219
To gather and report information across multiple servers and domains, DDM uses a collection hierarchy
consisting of servers that collect information from other servers, and node servers from which the
information is collected. All event information is stored and consolidated in the Domino Domain Monitor
that you can view. You specify the collection hierarchy, that is, which servers are collection servers and
which are node servers. A collection hierarchy can be multi-tiered with collection servers collecting from
other collection servers, but that is not required for DDM to run. As with the DDM probes, the collection
hierarchy is easy to create and modify in a configuration user interface in the Monitoring Configuration
database (EVENTS4.NSF).

Enhanced events and simple events

A collection server collects two classes of event information, enhanced events and simple events. When
you open an event, the Event document contains a Class type field in the upper-right corner which
indicates whether the event is a simple event or an enhanced event. Enhanced events include events
generated by a DDM Probe configuration document, events generated by a Domino event generator, or
any other event with specific target information appearing in the DDM event report. Target information
includes servers, databases, agents, or a user-specified target. A simple event is any event that is not
associated with or that does not contain specific target information. For example, most of the events that
are reported to the Domino server console are simple events.

Note: If the Domino Directory design has not been upgraded to Domino 7, the servers that display when
creating or maintaining probes may include non-Domino 7 servers from the domain. Be certain to specify
Domino 7 servers when setting up or maintaining probes.

DDM probes
Domino has a default set of DDM Probe documents that are shipped with the product. These documents
contain the following information about the DDM probes:
v A general description of the probe, including its purpose and intended use.
v Probe type and probe subtype, for example, messaging is a probe type and one of its associated probe
subtypes is router process state. This combination of probe type and probe subtype creates a mail
router status probe.
v Configurable specifics on what the probe monitors and how it should report, for example, thresholds
for events it generates.
v Configurable probe targets, that is, which servers, database, etc., that the probe runs against.
v Where applicable, configurable scheduling information.

Probe configuration information is set and stored in individual Probe documents stored in the Monitoring
Configuration database (EVENTS4.NSF). You can create multiple probes for each feature area and
individually configure each probe to run selective checks against specific servers and/or databases at
specific times.

You can use the default Probe documents with their default settings to get you ″up and running″ with
DDM or you can configure probes to run in a manner that is specifically tailored to your organization by
creating new Probe documents in which you define and customize your own probes. To use the probes
that are defined with the default Probe documents, enable those probes in DDM.

For more information about enabling DDM probes, see the topic Enabling and disabling DDM probes.

The following probes are available in DDM:

v Application Code probes
v Database probes
v Directory probes
v Messaging probes
v Operating System probes

1220 Lotus Domino Administrator 7 Help

v Replication probes
v Security probes
v Server probes
v Web probes

Scheduling DDM probes

When deploying DDM probes in your domain, consider how replication affects probe scheduling. New or
rescheduled probes use the new schedule after the new or revised Probe document replicates across the
domain.

Example:
v A Web Best Practices probe is set to run weekly, every Tuesday at 3:45 A.M. The ″How should missed
probes be handled″ field is set to ″Run missed probe at startup″.
v You change the schedule or you reset the ″How should missed probes be handled″ value for the probe.
The change is made on one server, but the change has not yet replicated to all servers in the domain.
v You launch a server. The probe runs according to the original schedule because the updated schedule is
not recognized until the schedule change has replicated to all servers in the domain.

You can schedule probes to run daily, weekly, on a specific day during the month, or at almost any other
time. You also specify the repeat interval for the probe. You can schedule probes to run on individual
servers or on groups of servers.

Set up the probe schedule on the Schedule tab of the Probe document when creating or editing a probe.

If the DDM database (DDM.NSF) contains unusual Event documents, or documents that were generated
or updated at unexpected times, determine whether a schedule change was made to the Probe document
for the probe that generated the Event documents. A probe schedule change may have generated
unexpected Event documents.

Application Code probes

An application code probe monitors agent schedules and the resources that agents use. For example,
using an application code probe, you can identify agents that use excessive resources, that run longer
than they should, and that fall behind schedule. In addition, probes can suggest solutions to resolve
problems.

Application probes monitor server-based scheduled agents that the Agent Manager runs and server-based
Web agents that the Domino HTTP process runs. On a daily basis, each application probe identifies the
100 most problematic agents in each probe subtype.

The Application Code -- Long running agent probe, which identifies potential run-away agents, generates
a ranked list of agents that have run the longest. The list of 100 daily problems is restarted each day at
midnight for HTTP probes and at a cache refresh time for Agent Manager probes, as specified in the
Server document. The minimum configuration for scheduled agents run by the Agent Manager is five
minutes, which corresponds to the polling interval. The minimum configuration for We agents run by the
HTTP process is one minute, which corresponds to the polling interval. The polling interval is not
configurable. When the probe is enabled, all agents are monitored.

The Application Code -- Agents ranked by memory usage probe tracks memory use of LotusScript and
Java agents. The ranking for the same agent may differ when the agent runs in Agent Manager as
compared to when it runs in HTTP. If HTTP is configured to run concurrent agents, the memory is
shared by concurrently-executing agents. Therefore, the threshold for rankings depends, in part, on the
current server setting for the maximum number of HTTP active threads, whether the Web agents are
configured to be executed concurrently, and on the memory used by the agent. When the probe is
enabled, all agents are monitored.

Chapter 56. Monitoring Domino Domains 1221

Specify the maximum number of threads in the Number of Active Threads field on the Domino Server
document -- Internet Protocols -- HTTP tab. Specify the concurrent agents setting in the Run web agents
concurrently field on the Domino Server document -- Internet Protocols -- Domino Web Engine tab.

Note: HTTP probes (Web agent probes) are not available for AIX, Linux and Linux on zSeries.

Another type of probe does not require any configuration on your part, is always running, and identifies
several error conditions. This probe does not limit its error reporting to 100 errors. It monitors the
following conditions:
v Agent security errors
v Disabled agents for the design update task
v Agents that terminate abnormally when the maximum time to run is exceeded
v Full-text search operations performed on databases that are not full-text indexed

This table contains the names and descriptions of the Application Code probes that you can define. For
information about configuring the Application Code probes, see the topic Creating Application Code
probes.

Application code probe name Description

Application code -- Agents behind schedule
Application code -- Agents ranked by CPU usage
Application code -- Agents ranked by memory usage
Application code -- Long running agents
Identifies which agents have fallen behind schedule by
the greatest amount of time for the current day. The
minimum configuration for this probe is five minutes,
which corresponds with the polling interval. This probe
applies to agents run by the Agent Manager.
Generates a list of the 100 agents that use the greatest
amounts of CPU for the current day. This probe has a
relatively high overhead. When the probe is enabled, all
agents are monitored. This probe applies to agents run
by the Agent Manager and Web agents.
Tracks memory use of LotusScript and Java agents. This
probe applies to agents run by the Agent Manager and
Web agents.
Identifies potential run-away agents, generates a ranked
list of agents that have run the longest. This probe
applies to agents run by the Agent Manager and Web
agents. The minimum configuration for Web agents is
one minute; the minimum configuration for scheduled
agents run by the Agent Manager is five minutes.

Creating Application Code probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Application Code.

1222 Lotus Domino Administrator 7 Help

6. Complete these fields, and then click Save and Close.

Field Action
Probe Subtype Choose one:
v Agents behind schedule
v Agents ranked by CPU usage
v Agents ranked by memory usage
v Long running agents
Probe Description Type a short description of the probe.
Which servers should run this probe? Choose one:
v All servers in the domain -- The probe monitors all
servers in the domain.
v Special target servers -- Specify the type of servers that
will run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the probe will run.
Which process should be probed? Choose one:
v Agent Manager -- Monitors scheduled agents that the
Agent Manager runs.
v HTTP -- Monitors agents that are invoked from a Web
browser.
If Memory utilization is greater than Enable or disable event generators.

Select a value from the list ″If Memory utilization is

Ranking by CPU seconds used
If agent is running behind schedule by more than
If an agent has been running for more than
greater than″ to generate an event of the corresponding
severity when memory utilization falls within the stated
range. The values and corresponding events are shown
in the table following this procedure.
Enable or disable event generators. Enter the number of
seconds that a CPU can be used, prior to generating an
event of the corresponding severity. When the CPU
usage falls within the stated range, an event is generated.
Enable or disable event generators. Enter the number of
minutes defining how long an agent may run behind
schedule prior to generating an event of the
corresponding severity. When the agent runs behind
schedule for a period of time within the stated range, an
event is generated.
Enable or disable event generators.

Enter the number of minutes that an agent runs before it

generates an event of the corresponding severity.

Will report agents with peak memory between these two

Setting ″If memory utilization is greater than″ settings
Very high Between Very High and Out of memory
High Between High and Very High
Medium Between Medium and High
Low Between Low and Medium
All (any) Between 0 and Low

Chapter 56. Monitoring Domino Domains 1223

Database probes
A database probe opens one or more databases, performs database operations, and then closes the
database.

Before you configure a Database -- Compact probe or Database -- Design probe, make sure that you are
familiar with the Compact task and with updating database designs.

When configuring the Database -- Error Monitoring probe, use the Errors to ignore field to specify errors
that the probe should ignore. This probe provides visibility to unusual NSF and NIF errors on local
servers. When this probe is enabled, and an error is encountered, the error code is checked against an
″Errors to ignore″ list. If the error code is on the list, no further action is taken. If the error is not on the
list, a DDM event is generated. The event identifies the operation that failed, the issuing server, the
database name, and the specific error code. DDM automatically appends information that pertains to the
error code, such as the probable cause and corrective action, if any.

This table contains the names and descriptions of the Database probes that you can define. For
information about configuring the Database probes, see the topic Creating Database probes.

Database probe name Description

Database -- Compact Reports errors that occur when a database is compacted.
Database -- Design Reports errors that occur when the design of a database
is updated.
Database -- Error monitoring Monitors key APIs in NSF and NIF, which are used to
perform database operations and generates events for
errors that occur.
Database -- Scheduled Checks Reports if the named database cannot be opened. The
probe can also check for unused space in the database
and for database inactivity.

Creating Database probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Database.
6. Complete these fields on the Basics tab. The actual fields and tabs that are available to be completed
depends on the probe that you choose.

Field Action
Probe Subtype Choose one:
v Error Monitoring
v Scheduled Checks
Probe Description Enter a short description of the probe.
Which server(s) should run this probe? Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Database probe will run.

1224 Lotus Domino Administrator 7 Help

Field
Severity
Select one or more databases to probe
Monitor database for unused space
Monitor database for user inactivity
What periods do you want to monitor and what are the
minimum number of sessions that must be met before
generating an event?
Errors to ignore
7. If you are creating a Database -- Scheduled Checks probe, complete these fields on the Schedule tab.
(For all other probes, continue with Step 8.)
Field
How often should this probe run?
Defined schedule
Should this probe run twenty-four hours per day, seven
days per week?
On which days should this probe run?
On which day of the week should this probe run?
During which hours of the day should this probe run?
Action
Choose the severity level that generates an event.
Select the names of databases to probe.
Click the check box to designate that the probe should
monitor the specified database for unused space.
Click the check box to designate that the probe should
monitor user activity for the specified database.
Do both of these:
v Choose the time periods to monitor -- daily, weekly, or
monthly.
v For each time period that you chose, in the Minimum
Sessions field, enter the number of minimum sessions
after which an event will be generated.
This field lists the errors that are ignored and therefore
do not generate an event.
Choose one or both:
v Add Error Codes to the List -- Select error codes to
add, and then click OK.
v Remove Error Codes from List -- Select error codes to
remove, and then click OK.
Action
Choose one:
v Run multiple times per day -- The probe runs more
than once each day. Causes the ″Defined schedule″
field to display.
v Daily -- The probe runs once each day. Use the field
″On which days should this probe run″ to specify the
days on which the probe is run.
v Weekly -- The probe runs once each week. Use the
field ″On which day of the week should this probe
run?″ to specify the day on which the probe is run.
v Monthly -- The probe runs once each month. Use the
″On which day of the month should this probe run″
field to specify when the probe should run.
Specify the number of minutes that should pass between
each run of the probe.
Choose one:
v Yes -- The probe runs continuously.
v No -- The probe runs according to a schedule that you
define.
Choose the days on which the probe runs.
Choose the day on which the probe runs.
Specify the probe starting time in the From field, and the
probe ending time in the To field.
Chapter 56. Monitoring Domino Domains 1225
Field
On which day of the month should this probe run?
At what time should this probe run?
How should missed probes be handled?
Action
Enter the day of the month on which to run the probe.
For example, enter 15 to run the probe on the 15th day
of each month.
Choose the time to run the probe.
Choose one:
v Ignore missed probe -- The missed probe is not run or
rescheduled.
v Run missed probe at startup -- The next time that the
server starts, the missed probe runs.
v Run missed probe at next time range -- The missed
probe reschedules itself once. For example, if a probe
scheduled to run every Tuesday at 5:00 AM fails to
run, the probe reschedules itself to run on Wednesday
at 5:00 AM. After that, the probe returns to its regular
schedule.

8. Click Save and Close.

Directory Probes
A directory probe monitors whether LDAP is configured and running correctly on Domino servers and
reports on the use and overall health of the domain’s directories.

The Directory -- Directory Availability probe monitors the primary Domino Directory, remote primary
Domino Directory (configuration-only databases), local server-based condensed directory catalogs,
cascaded local directories, secondary Notes directories, and secondary LDAP directories.

The algorithm used in the Directory -- LDAP View Update Algorithm probe can be temporarily
overridden by the LDAPBatchAdds NOTES.INI setting.

This table contains the names and descriptions of the Directory probes that you can define. For
information about configuring the Directory probes, see the topic Creating Directory probes.

Directory Probe name Description

Directory -- Directory Availability
Directory -- Directory Catalog Aggregation Schedule
Directory -- Directory Catalog Creation
Directory -- Directory Indexer Process State
Directory -- LDAP Process State
Directory -- LDAP Search Response
Directory -- LDAP TCP Port Health
Directory -- LDAP View Update Algorithm
Monitors the availability of all directories being served
by the server and reports any errors. The probe also
reports on namesake update issues and local LDAP
server issues.
Based on the Directory Catalog task schedule, this probe
subtype monitors missed aggregations and aggregations
in progress longer than expected.
Monitors the Directory Catalog task process of creating
directory catalogs by aggregating source directories into
destination directory catalogs.
Monitors whether the Directory Indexer task is running.
Monitors whether the LDAP process is running.
Monitors the server’s average search response time for
LDAP searches.
Monitors whether LDAP is listening on its ports and
responding promptly.
Monitors the LDAP view-update algorithm that is being
used by the server.

1226 Lotus Domino Administrator 7 Help

Directory Probe name
Directory -- NAMELookup Search Response
Directory -- Secondary LDAP Search Response
Description
Monitors the average search response time of all
NAMELookups performed on the server.
Monitors the average search response time of searches of
secondary LDAP servers that are performed on the
server.

Creating Directory probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Directory.
6. Complete these fields, and then click Save and Close. The actual fields and tabs that are available to
be completed depends on the probe that you choose.

Field Action
Probe Subtype Choose one:
v Directory Availability
v Directory Catalog Aggregation Schedule
v Directory Catalog Creation
v Directory Indexer Process State
v LDAP Process State
v LDAP Search Response
v LDAP TCP Port Health
v LDAP View Update Algorithm
v NAMELookup Search Response
v Secondary LDAP Search Response
Probe Description Type a short description of the probe.
Severity Choose the severity that will generate an event.
Which server(s) should run this probe? Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Directory probe will run.
Which server(s) should be probed? Choose one:
v All servers in the domain -- Probes all servers in the
domain.
v Only the following servers: -- Probes the servers that
you specify.

Chapter 56. Monitoring Domino Domains 1227

7. Complete the following fields on the Specifics section of the Basics tab:

If you chose this probe subtype Enter this information

Directory Availability Enable or disable reporting on view-update issues and
local LDAP directory serving issues. The probe always
reports general directory availability issues.
Directory Catalog Aggregation Schedule Enable or disable generating events. If you enable the
setting, enter the number of minutes after which missed
aggregations are reported and enter the number of
minutes after which long-running aggregations are
reported.
Domino Directory Search Response Enable or disable generating an event when the Domino
Directory search response exceeds the specified number
of responses. For any settings that are enabled, enter the
number of responses after which an event is generated.
The severity of the event is shown in the column
″Generate an event of severity.″
LDAP Search Response Enable or disable generating events. For any settings that
are enabled, enter the average LDAP search response
maximum value in milliseconds. If the probe encounters
an average LDAP search response time that is greater
than the value that you enter, an event is generated. The
severity of the event is shown in the column ″Generate
an event of severity.″
LDAP TCP Port Health Choose the services to which the probe applies, and then
enter a time-out value. If the probe encounters a time-out
greater than the value that you enter, an event is
generated.
Secondary LDAP Search Response Enable or disable individual settings defining the
maximum allowable secondary LDAP average search
response time. If a secondary LDAP average search
response time exceeds the value that you enter, and the
setting is enabled, an event is generated. The severity of
the event is shown in the column ″Generate an event of
severity.″

8. Complete the following fields on the Schedule tab for Directory Availability, Directory Catalog
Aggregation Schedule, Directory Indexer Process State, LDAP Process State, and LDAP TCP Port
Health probe subtypes.

Field Action
How often should this probe run? Choose one:
v Run multiple times per day -- After you choose this
option, complete the ″Defined schedule″ field.
v Daily -- After you choose this option, complete the
″On which days should this probe run″ field.
v Weekly -- After you choose this option, complete the
″On which day of the week should this probe run″
field.
v Monthly -- After you choose this option, complete the
″On which day of the month should this probe run″
field.
Defined schedule Specify the number of minutes between each run of the
probe.

1228 Lotus Domino Administrator 7 Help

Field
Should this probe run twenty-four hours per day, seven
days per week?
On which days should this probe run?
On which day of the week should this probe run?
On which day of the month should this probe run?
During which hours of the day should this probe run?
At what time should this probe run?
How should missed probes be handled?
Messaging probes
The messaging probes collect data about messaging configuration, the messaging infrastructure, and
message routing.
This table contains the names and descriptions of the Messaging probes that you can define. For
information about configuring the Messaging probes, see the topic Creating Messaging probes.
Messaging probe name
Messaging -- SMTP TCP Port Health
Messaging -- Message retrieval TCP Port Health
Messaging -- Route Process State
Messaging -- SMTP Process State
Messaging -- Message retrieval process state
Messaging -- NRPC Routing Status
Messaging -- Transfer Queue Check
Messaging -- Mail Flow Statistic check
Action
Choose one:
v Yes -- The probe runs continuously.
v No --The probe runs according to a schedule that you
define. After you choose this option, complete the ″On
which days should this probe run″ field.
Choose the days on which to run the probe.
Choose the day on which to run the probe.
Enter the day of the month on which to run this probe.
For example, enter 15 to run the probe on the 15th day
of the month.
Specify the start time in the From field, and the end time
in the To field. The probe will run during those hours.
Choose the time at which you want the probe to run.
Choose one:
v Ignore missed probe -- The missed probe is not run or
rescheduled.
v Run missed probe at startup -- The next time that the
server starts, the missed probe runs.
v Run missed probe at next time range -- The missed
probe reschedules itself once. For example, if a probe
scheduled to run every Tuesday at 5:00 AM fails to
run, the probe reschedules itself to run on Wednesday
at 5:00 AM. After that, the probe returns to its regular
schedule.
Description
Verifies that SMTP services are successfully processing
protocol requests.
Verifies that the IMAP and POP3 services are
successfully processing protocol requests.
Monitors the status of the router.
Monitors the status of the SMTP process.
Verifies the health of the IMAP and POP3 tasks that are
configured to run on the specified servers.
Using NRPC, the probe sends a message to verify that
mail routing is working.
Monitors mail flow to individual destinations.
Monitors the amount of mail on a Domino server and
checks whether the number of mail messages in the
MAIL.BOX file exceeds the number of mail messages
that the router can process.
Chapter 56. Monitoring Domino Domains 1229
Messaging probe name Description
Messaging -- Mail Reflector Tests mail routing to Domino and non-Domino mail
systems.
Messaging -- Mail DSN Uses the Delivery Status Notification (DSN) method to
test the mail flow to an SMTP mail system. The
destination domain must support the .dsn extension.

Creating Messaging probes:

Note: When the Messaging -- Mail Flow Statistic Check probe is running, if the MAIL.BOX file contains
an excessive number of mail messages, the performance of the mail router is impacted. A ″slack
percentage″ is created. The slack percentage is the number of messages by which the router can fall
behind in processing before a fatal event is generated.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Messaging.
6. Complete these fields and then click Save and Close. The actual fields and tabs that are available to be
completed depends on the probe that you choose.

Field Action
Probe Subtype Choose one:
v SMTP TCP Port Health
v Message Retrieval TCP Port Health
v Router Process State
v SMTP Process State
v Message Retrieval Process State
v NRPC Routing Status
v Transfer Queue Check
v Mail Flow Statistic Check
v Mail Reflector
v Mail DSN
Probe Description Type a short description of the probe.
Severity Choose the severity level of the events that will be
generated by the probe.
Note: This field does not apply to the Mail Flow Statistic
Check probe subtype.
Which server(s) should run this probe? Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Messaging probe will run.
Database(s) to attempt to open? Specify the names of the databases that the probe tries to
open.

1230 Lotus Domino Administrator 7 Help

Field
Timeout for open attempt
7. Complete these fields on the Schedule tab:
Field
How often should this probe run?
Defined schedule
Should this probe run twenty-four hours per day, seven
days per week?
On which days should this probe run?
On which day of the week should this probe run?
On which day of the month should this probe run?
During which hours of the day should this probe run?
At what time should this probe run?
How should missed probes be handled?
Operating System probes
Use an operating system probe to monitor system resources, CPU usage, disk activity, physical memory
use, and network traffic.
Action
Enter the amount of time, in milliseconds, that the probe
has to open the selected databases. If the probe fails to
open the databases in this amount of time, an event is
generated.
Action
Choose one:
v Run multiple times per day -- The probe runs more
than once each day. Causes the ″Defined schedule″
field to display.
v Daily -- The probe runs once each day. Use the ″On
which days should this probe run″ field to specify the
days on which the probe is run.
v Weekly -- The probe runs once each week. Use the
″On which day of the week should this probe run?″
field to specify the day on which the probe is run.
v Monthly -- The probe runs once each month. Use the
″On which day of the month should this probe run″
field to specify when the probe should run.
Specify the number of minutes or seconds between each
run of the probe.
Choose one:
v Yes -- The probe runs continuously.
v No -- The probe runs according to a schedule that you
specify. Complete the ″On which days should this
probe run″ field.
Choose the days on which to run the probe.
Choose the day of the week on which to run the probe.
Enter the day of the month on which to run the probe.
For example, enter 15 to run the probe on the 15th day
of the month.
Specify the start time in the From field, and the end time
in the To field.
Choose the time that you want the probe to run.
Choose one:
v Ignore missed probe -- The missed probe is not run or
rescheduled.
v Run missed probe at startup -- The next time that the
server starts, the missed probe runs.
v Run missed probe at next time range -- The missed
probe reschedules itself once. For example, if a probe
scheduled to run every Tuesday at 5:00 AM fails to
run, the probe reschedules itself to run on Wednesday
at 5:00 AM. After that, the probe returns to its regular
schedule.
Chapter 56. Monitoring Domino Domains 1231
The Server document, Miscellaneous tab, contains a spindle count interface that is used with the DDM
OS Disk probes for Microsoft Windows servers only. Specifying spindle counts is important because the
disk statistics monitored by the OS Disk probe on Microsoft Windows is adjusted by Domino to account
for the disk spindle counts. Enter spindle count information after setting up the DDM OS probes.

This table contains the names and descriptions of the Operating System probes that you can define. For
information about configuring the Operating System probes, see the topic Creating Operating System
probes.

Operating System probe Description

Operating System -- CPU Monitors CPU usage.
Operating System -- Disk Monitors activity on all disks.
Operating System -- Memory Monitors the amount of physical memory being used.
Operating System -- Network Monitors the amount of network traffic on the server.

Creating Operating System probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Operating System.
6. Complete these fields, and then click Save and Close:

Field Action
Probe Subtype Choose one:
v CPU
v Disk
v Memory
v Network
Probe Description Type a short description of the probe.
Which server(s) should run this probe Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Operating System probe will run.
Which operating systems should be monitored? Choose one or more operating systems to be monitored by
the CPU probe subtype. For each operating system that
you choose, provide this information:
v The processor utilization percent information and the
severity level detail on the corresponding tab.
v For AIX and Solaris, also complete the processor queue
length fields.

Replication probes
The replication probe checks server replication. To configure the replication probe, specify the target
servers to be probed. Target servers are those servers that replicate with the probe server. For example, if

1232 Lotus Domino Administrator 7 Help

the probe runs on Server A (originating server), the target servers to monitor are those servers that
replicate with Server A. In this case, Server B, Server C, and Server D.

Use the Replication - Replication Check probe to filter out replication of databases that do not require
replication, and to closely monitor replication of those databases that require frequent replication. Critical
system databases, such as NAMES.NSF, EVENTS4.NSF, and ADMIN4.NSF which are used across servers
and that are required to be up-to-date, can be monitored more often than less-important databases. You
can also define a lower tolerance for conditions that create events on system-critical databases than you
would define for conditions that create events on non-critical databases.

Replication on selected servers and databases is monitored according to the schedule specified in the
Probe document.

When you run the Replication -- Errors probe, replication occurs as it typically would, but events are
reported to DDM. This probe may also report some conditions that are not errors, but that are not desired
behavior. For example, this probe may report Replication Note Errors when the replication is successful
but some notes are not replicated. If the destination database does not have the source database in its
ACL, and there have been changes to the source database, the notes in the source database which are
new or updated are not replicated to the destination server because of the ACL. The replication probe
will report this and include a document link to the notes that did not replicate. The Replication -- Errors
probe may also report replication conflicts in DDM and include a document link to the conflict
document. This is not a true error condition for replication but it may not be desired behavior; therefore,
it is reported.

The Replication -- Replication Check probe takes null replication into consideration. Null replication
occurs when a database is up-to-date and no replication is required, but the replication is attempted. Null
replication is not reported in the DDM database. Previously, Domino had similar functionality but it took
into account only those replications which resulted in the replication history being updated (only
successful replications and databases which were not up-to-date). In DDM, the replication check probe
takes into account a replication attempt where the files are up-to-date. Including up-to-date replications
removes many of the false reports indicating that replication on a database has not occurred.

Note: In hub-and-spoke topologies, replication is typically one-way only. Do not monitor replication in a
direction in which replication is disabled.

This table contains the names and descriptions of the Replication probes that you can define. For
information about configuring the Replication probes, see the topic Creating Replication probes.

Replication probe name Description

Replication -- Errors Monitors replication and reports replication errors to
DDM.
Replication -- Replication Check Monitors whether a specified database replicates within a
specified time interval.

Creating Replication probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view and then click New DDM Probe.
5. Choose Replication.
6. Complete these fields, and then click Save and Close. The actual fields and tabs that are available to
be completed depends on the probe that you choose.

Chapter 56. Monitoring Domino Domains 1233

Field
Probe Subtype
Probe Description
Which server(s) should run this probe?
Which server(s) should be probed?
Select one or more databases to probe
Select one or more databases not to probe
Severity
Generate an event if the included databases have not
replicated within the following interval
Check the following modes of replication
Attempt to diagnose problems
How often should this probe run?
Defined schedule
1234 Lotus Domino Administrator 7 Help
Action
Choose one:
v Errors
v Replication Check
Type a description of the probe.
Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Replication probe will run.
Note: You can specify a wild card but you cannot
specify a server group.
Choose one:
v All servers in the domain -- Probes all servers in the
domain.
v Only the following servers: -- Probes the servers that
you specify.
Note: You can specify a wild card but you cannot
specify a server group.
Specify the databases to probe. The default is * meaning
that all databases are probed.
Specify the databases which should not be probed.
Specify the severity level that the probe generates.
Specify a number, and then select Minutes, Hours, or
Days as the interval.
Choose one or both:
v Push -- Monitors the success of one-way replication
from one database to one or more specified databases.
v Pull -- Monitors the success of replication from one or
more databases to another database.
Select this check box to have Domino attempt to
diagnose problems that the probe reports.
Choose one:
v Run multiple times per day -- The probe runs more
than once each day. Causes the ″Defined schedule″
field to display.
v Daily -- The probe runs once each day. Use the ″On
which days should this probe run″ field to specify the
days on which the probe is run.
v Weekly -- The probe runs once each week. Use the
″On which day of the week should this probe run?″
field to specify the day on which the probe is run.
v Monthly -- The probe runs once each month. Use the
″On which day of the month should this probe run″
field to specify when the probe should run.
Specify the number of minutes between each run of the
probe.
Field
Should this probe run twenty-four hours per day, seven
days per week?
On which days should this probe run?
On which day of the week should this probe run?
On which day of the month should this probe run?
During which hours of the day should this probe run?
At what time should this probe run
How should missed probes be handled?
Action
Choose one:
v Yes -- Run the probe continuously.
v No -- Run the probe only on the days and times that
you specify. After you choose this option, complete the
″On which days should this probe run″ field.
Choose the days on which to run the probe.
Choose the day of the week on which to run this probe.
Enter the day of the month on which to run this probe.
For example, enter 15 to run the probe on the 15th day
of the month.
Specify the start time in the From field, and the end time
in the To field.
Choose the time to run the probe.
Choose one:
v Ignore missed probe -- The missed probe is not run or
rescheduled.
v Run missed probe at startup -- The next time that the
server starts, the missed probe runs.
v Run missed probe at next time range -- The missed
probe reschedules itself once. For example, if a probe
scheduled to run every Tuesday at 5:00 AM fails to
run, the probe reschedules itself to run on Wednesday
at 5:00 AM. After that, the probe returns to its regular
schedule.

Security probes
Create a security probe to assess the overall security of servers and databases in a domain. When a
security probe finds a problematic database or server configuration, it generates an event. Do not set the
severity levels for the Security -- Configuration probe; severity is assigned during runtime. The severity
level is calculated during runtime based on the number of potential problems found. Severity level is a
percentage-based score that is calculated for each Server document and Server Configuration document
that is probed. The percentage breakdown and matching severity level is as follows:

Percentage Severity level

0.00 Normal
< = 50% Warning (low)
> 50% Warning (high)

The Best Practices probe reports on the first 25 Person documents that do not comply with the probe
configuration settings. You can use the NOTES.INI setting
DDM_SECPROBE_PERSONDOC_LIMIT=<NumberOfPersonDocsReported> to report on a maximum of
250 Person documents, or you can set it to report on less than the default 25 Person documents. The
minimum setting is 0 (zero), in which case, no Person documents are reported but a summary report is
generated indicating the number of Person documents that do not comply with the probe specification.
The probe stops reporting at 25, or at a number of Person documents that you specify, but the probe
continues to review the remaining Person documents.

This table contains the names and descriptions of the Security probes that you can define. For
information about configuring the Security probes, see the topic Creating Security probes.

Chapter 56. Monitoring Domino Domains 1235

Security probe name Description
Security -- Best Practices Compares a set of baseline security configuration settings
to the same settings in a domain. This probe is a ″Best
Practices″ security audit of the domain.
Note: To create your own Best Practices probe, modify the
security configuration settings on the Specifics tab.
Security -- Configuration Compares settings in a specific Server document to
settings in a specified ″good″ Server document. Any
discrepancy generates an event.
Security -- Database ACL Monitors the access control privileges that groups and
individuals have in specified databases on the server
running the probe. You designate the acceptable access
levels on the Specifics tab.
Security -- Database Review Reviews the security properties for a specified database
and generates a report on the probe findings.
Security -- Review Generates a report on the security settings specified in the
Specifics tab of the Probe document. You have the option
of selecting the ″Directory Profile Note″ and the ″Security
settings in my configuration document″ options if you
want the settings in those documents reviewed by the
probe.

Creating Security probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database.
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Security.
6. Complete these fields, and then click Save and Close. The actual fields and tabs that are available to
be completed depends on the probe that you choose.

Field Action
Probe Subtype Choose one:
v Best Practices
v Configuration
v Database ACL
v Database Review
v Review
Probe Description Type a description of the new probe.

7. Complete these fields on the Target tab:

Field Action
Which server should run this probe? Specify the server that will run this probe.

1236 Lotus Domino Administrator 7 Help

Field
Which servers should run this probe?
Which servers should be probed?
Which servers’ security configuration should be probed?
Select one or more databases to probe
Which servers should not be probed?
8. Complete these fields on the Specifics tab:
Field
Which server should be used as the guideline server?
Which server settings should be compared to the
guideline server settings?.
Generate an event when any of the entries listed have
access greater than ″access level.″
Which server settings should be validated?
Review all ACL members whose privileges are equal to
or greater than
Review the following database properties
Review agents defined as
Action
Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Security probe will run.
Choose one:
v All servers in the domain -- Probes all servers in the
domain.
v Only the following servers: -- Probes the servers that
you specify.
Choose one:
v All servers in the domain -- The security probe runs
against the security configuration for all servers in the
domain.
v Only the following servers -- Security configurations
are probed for the servers you specify.
Specify the names of the databases to probe. The default
is NAMES.NSF.
Specify the names of servers that are not to be probed.
Action
Specify the name of the server to use as the ″good″
server against which other Server documents are
verified.
Choose the settings you want to compare to those in the
Server document for the server being probed. Check as
many settings as apply.
Complete this field for as many access levels as
necessary. Specify the people, groups, and servers that
apply to each specific access level.
Specify the individual server settings to validate against
a set of ″good″ settings.
Specify the ACL privilege level from which the probe
should begin checking ACL member privileges.
Beginning with the ACL privilege you select, all member
privileges at that level and above are reviewed by the
security probe.
Specify the database properties to be reviewed by the
security probe.
Specify one or both of these agents to be reviewed by the
security probe:
v Restricted
v Unrestricted
Chapter 56. Monitoring Domino Domains 1237
Field
Which server settings should be reported?
9. Complete these fields on the Schedule tab:
Field
How often should this probe run?
Defined schedule
Should this probe run twenty-four hours per day, seven
days per week?
On which days should this probe run?
On which day of the week should this probe run?
On which day of the month should this probe run?
During which hours of the day should this probe run?
At what time should this probe run
How should missed probes be handled?
1238 Lotus Domino Administrator 7 Help
Action
Specify the individual settings from the Server document
that are to be reported. Specify the ″Directory Profile
Note″ and the ″Security settings in my configuration
document″ options if you want the settings in those
documents reviewed by the probe.
Action
Choose one:
v Run multiple times per day -- The probe runs more
than once each day. Causes the ″Defined schedule″
field to display.
v Daily -- The probe runs once each day. Use the ″On
which days should this probe run″ field to specify the
days on which the probe is run.
v Weekly -- The probe runs once each week. Use the
″On which day of the week should this probe run?″
field to specify the day on which the probe is run.
v Monthly -- The probe runs once each month. Use the
″On which day of the month should this probe run″
field to specify when the probe should run.
Specify the number of minutes between each run of the
probe.
Choose one:
v Yes -- Run the probe continuously.
v No -- The probe runs on the days and at the times that
you specify. After you choose this option, complete the
″On which days should this probe run″ field.
Choose the days on which to run the probe.
Specify the day of the week on which to run this probe.
Enter the day of the month on which to run this probe.
For example, enter 15 to run the probe on the 15th day
of the month.
Specify the start time in the From field, and the end time
in the To field. The probe will run during those hours.
Specify the time that you want the probe to run.
Choose one:
v Ignore missed probe -- The missed probe is not run or
rescheduled.
v Run missed probe at startup -- The next time that the
server starts, the missed probe runs.
v Run missed probe at next time range -- The missed
probe reschedules itself once. For example, if a probe
scheduled to run every Tuesday at 5:00 AM fails to
run, the probe reschedules itself to run on Wednesday
at 5:00 AM. After that, the probe returns to its regular
schedule.
Server probes
There is one server probe subtype -- Administration. Use the Administration probe subtype to monitor
whether selected administration requests run and to report on any requests that fail. For each reported
administration request failure there is a corresponding error report in the Domino Domain Monitor
database (DDM.NSF).

After you select administration requests in the Probe document, run the administration request as you
would any administration request.

For more information about running administration requests, see the topic Forcing an administration
process request to run.

This table contains the names and descriptions of the Server probes that you can define. For information
about configuring the Server probes, see the topic Creating Server probes.

Server Probe name Description

Server -- Administration Reports any administration process requests that fail to
run when the request is scheduled to do so.

Creating Server probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database.
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Server.
6. Complete these fields, and then click Save and Close.

Field Action
Probe Subtype Choose Administration
Probe Description Type a description of the new probe.
Which servers should run this probe? Choose one:
v All servers in the domain -- Runs the probe on all
servers in the domain.
v Special target servers -- Specify the type of servers to
run the probe, such as POP3 servers or the
administration server for the Domino Directory.
v Only the following servers -- Specify the servers on
which the Server probe will run.

7. From the list provided, choose the administration requests that are to be reported in DDM when the
request fails to run on the servers you selected.

Web probes
There are two Web probes, the Web -- Configuration probe and the Web -- Best Practices probe. Both
probes provide results in the form of a Domino Event document in the DDM database. Use this
document to verify the accuracy of the Web server configuration and to compare other servers’
configurations against that of a known good server.

The Web -- Configuration probe provides feedback related to the Web settings associated with a Web
server or list of Web servers. This feedback is based on the most recent Web profile as specified in the
Probe document. The probe reviews Web server configuration values on specified servers against a set of
predefined values. If the values differ, the probe attempts to make a recommendation by suggesting

Chapter 56. Monitoring Domino Domains 1239

values to either correct the Web server configuration or to improve server performance or security. This
probe reviews field values in the Server document, the Internet Site document, and the Web Server
Configurations document, according to which documents exist.

The Web -- Best Practices probe monitors HTTP-specific fields in the domain that are compared to a
recommended value. The HTTP specific fields are in the Server document, the Internet Site document (if
one exists), and the Web Server Configuration document (if one exists). A detail document is generated
outlining the fields that do not match the recommended value, and providing information on how to
resolve any issues. For example, suggestions for improving a server’s configuration could include
corrections to server functionality, server performance, or server security. The Web probes help you
improve overall security and Web server performance.

The severity of an event generated by the Web probes is determined using a percentage formula; you
cannot determine the severity of a Web probe event. A Web probe severity score is calculated during
runtime based on the number of potential problems that are found. The Web probe severity percentage
score is calculated for each event that is logged to DDM. This table shows the detail.

Percentage Severity Level

0.00 Normal
< = 50% Warning (low)
> 50% Warning (high)

This table contains the names and descriptions of the Web probes that you can define. For information
about configuring the Web probes, see the topic Creating Web probes.

Web probe name Description

Web -- Best Practices Reviews Web server configuration values on specified
servers against a set of predefined values.
Web -- Configuration Performs a comparison of Web server configuration values
on specified servers against the same values for a known
good server or guideline server.

Creating Web probes:

1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Choose any DDM probe view, and then click New DDM Probe.
5. Choose Web.
6. Complete these fields, and then click Save and Close.

Field Action
Probe Subtype Choose one:
v Best Practices
v Configuration

Both probes provide results in the form of a Domino

Event document in the Domino Domain Monitor
database (DDM.NSF). Use this document to verify the
accuracy of the Web server configuration and to compare
other servers’ configurations against that of a known
good server.

1240 Lotus Domino Administrator 7 Help

Field
Probe Description
Which server should run this probe?
Which servers’ Web configuration should be probed?
Which sever should be used as the guideline server?
Specifics
How often should this probe run?
Defined schedule
Should this probe run twenty-four hours per day, seven
days per week?
On which days should this probe run?
On which day of the week should this probe run?
On which day of the month should this probe run?
During which hours of the day should this probe run?
At what time should this probe run?
Action
Type a short description of the probe. The description is
used to identify the probe.
Specify the server that will run this probe.
Choose one:
v All servers in the domain -- The probe reports results
for all servers in the domain.
v Only the following servers -- The probe reports results
for servers that you specify.
Specify the name of the server to use as the ″good″
server against which other configuration documents are
verified.
Choose one according to the probe subtype:
v Best Practices -- Choose the configuration settings that
the probe will verify or check.
v Configuration -- Choose the configuration settings that
the probe will verify or check. Specify one guideline
server per Probe document.
Choose one:
v Run multiple times per day -- The probe runs more
than once each day. Causes the ″Defined schedule″
field to display.
v Daily -- The probe runs once each day. Use the ″On
which days should this probe run″ field to specify the
days on which the probe is run.
v Weekly -- The probe runs once each week. Use the
″On which day of the week should this probe run?″
field to specify the day on which the probe is run.
v Monthly -- The probe runs once each month. Use the
″On which day of the month should this probe run″
field to specify when the probe should run.
Specify the number of minutes between each run of the
probe.
Choose one:
v Yes -- The probe runs continuously.
v No -- The probe runs according to the schedule that
you specify. After you choose this option, complete the
″On which days should this probe run?″ field.
Choose the days on which to run the probe.
Choose the day of the week on which to run the probe.
Enter the day of the month on which to run this probe.
For example, enter 15 to run the probe on the 15th day
of the month.
Specify a probe starting time in the From field, and the
probe ending time in the To field.
Choose the time that you want the probe to run.
Chapter 56. Monitoring Domino Domains 1241
Field Action
How should missed probes be handled? Choose one:
v Ignore missed probe -- The missed probe is not run or
rescheduled.
v Run missed probe at startup -- The next time that the
server starts, the missed probe runs.
v Run missed probe at next time range -- The missed
probe reschedules itself once. For example, if a probe
scheduled to run every Tuesday at 5:00 AM fails to
run, the probe reschedules itself to run on Wednesday
at 5:00 AM. After that, the probe returns to its regular
schedule.

Maintaining DDM Probes

Use the procedures in this section to view, modify, and delete Probe documents, and to enable and
disable probes.
v Enabling and disabling DDM probes
v Editing a DDM Probe document
v Deleting DDM Probe documents
v Reporting DDM operating system probe events to Tivoli Enterprise Console
v Viewing DDM Probe documents

Enabling and disabling DDM probes

You can enable or disable all probes, or only selected probes.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. (Optional) Sort the list of probes by choosing the view All Probes by Author or All Probes by Type.
5. Click the name of the probe that you want to enable or disable.
6. Do one of these:
v To enable or disable the selected probes, click Enable Probes or Disable Probes, and then click
Enable Selected Probes or Disable Selected Probes.
v To enable or disable all probes in the view, click Enable Probes or Disable Probes, and then click
Enable All Probes in View or Disable All Probes in View.

Note: To enable or disable a probe from the New Probe document, click Enable Probe or Disable Probe.

Editing a DDM Probe document

Use this procedure to edit existing DDM Probe documents. Changes made to Probe documents take effect
immediately.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Click the subtype of the probe.
5. Select the Probe document to edit, and then click Edit Document.
6. Edit the document, and then click Save and Close.

1242 Lotus Domino Administrator 7 Help

Deleting a DDM Probe document
When you no longer need a Probe document, delete the Probe document.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration.
4. Click the type of probe to delete.
5. Select the Probe document to delete, and then click Delete Document.
6. Click F9 to refresh the view, and then click Yes to delete the document.

Reporting DDM operating system probe events to Tivoli Enterprise Console

You can have the operating system probe events reported to the Tivoli Enterprise Console (TEC) in
addition to the DDM.NSF database. To do so, set the TEC information in the Domino Server
Configuration document and then install the operating system probe definitions on the TEC server.

Setting TEC information: In this procedure you enter the TEC server IP address and port number.
Obtain that information from the TEC server administrator.
1. From the Domino Administrator, click Configuration.
2. Choose Server - Configurations.
3. Select the Server Configuration document you are modifying and click Edit Configuration.
4. On the Basics tab - Tivoli Enterprise Console Settings section, click Enable logging to Tivoli Enterprise
Console.
5. Enter the IP Address of the TEC server.
6. Enter the port number to listen to. The default is 5529.
7. Click Save and Close.

Installing the DDM OS probe definitions on the TEC server: When you install Domino 7, five text
files with a .baroc file name extension are installed in the rmeval subdirectory of the Domino data
directory.

The .baroc files are:

v RMLogicalDisk.baroc
v RMMemory.baroc
v RMNetwork.baroc
v RMProcessor.baroc
v Tmw2k.baroc
1. Locate the text files that have the .baroc extension.
2. Copy the files and send them to the TEC administrator who will copy the files to the TEC server.
They can then be installed and loaded on that server.

For more information about installing and loading BAROC files, see the Tivoli Enterprise Console (TEC)
documentation.

Viewing DDM Probe documents

When you open the Monitoring Configuration database (EVENTS4.NSF) and click DDM Configuration,
you can view probes by type or by author by clicking the appropriate view.

DDM server collection hierarchy

DDM probes run on a server and report events to the Domino Domain Monitor database (DDM.NSF)
that is on that server. Rather than visit every Domino Domain Monitor database on every server to
review the probe results, create a DDM server collection hierarchy and have the data aggregated to a few
servers.

Chapter 56. Monitoring Domino Domains 1243

Use the DDM server collection hierarchy document to define how data is collected in a domain. You can
designate that one server collect all DDM event data or you can define a custom DDM server collection
hierarchy consisting of multiple collecting servers and, optionally, multiple server tiers.

You use the Monitoring Configuration database (EVENTS4.NSF) to create and manage the DDM server
collection hierarchy. The first time that you click the DDM server collection hierarchy view in the
Monitoring Configuration database, a message indicates that no server collection hierarchies exist. You
can create a server collection hierarchy, or you can exit the view. To create a DDM server collection
hierarchy, specify one or more collection servers. A collection server collects the probe results that are
generated when probes are run against monitored databases and servers. To use a DDM server collection
hierarchy, you must specify at least one collection server that collects from other servers.

There are many ways to design a DDM server collection hierarchy. For example, you can set it up to
represent an existing Domino server topology, for example, hub and spoke servers. Or, you can set it up
to ensure that the administrator receives only information that is pertinent to the servers he or she
maintains.

Data roll-up
Each Domino 7 server writes its probe results to a local replica of the DDM database. Each collection
server’s DDM database contains that server’s probe results, and the probe results from every server from
which it collects data.

The DDM collection hierarchy provides the DDM reporting rollup capability, allowing you to open DDM
on a collection server and see all events for that server and its subordinate servers. Without the DDM
collection hierarchy, you must open DDM.NSF on each server on which DDM is running to see events for
that server.

DDM data roll-up propagates the probe results up the DDM server collection hierarchy. Data roll-up is
accomplished using Domino’s selective replication to transport the data. The replication formulas are
created automatically when you define your DDM server collection hierarchy. Each selective replication
formula is specific to each server in the Domino Domain Monitor replica. When fully populated, the
selective replication formula references the collection server and all of its monitored servers. The selective
replication formula filters out all documents from servers that are not members of the collecting server’s
hierarchy.

The collected probe results in the DDM database are replicated when one of these occurs:
v A collection server is notified about the change in an event state -- When a collection server receives
notification that one of its monitored servers has an event state change, the collection server replicates
the monitored server’s DDM database. When a replication triggered by an event state change is
complete and the collection server is a monitored by another collection server, it notifies its collection
server of the state change. The state change is then replicated up the server collection hierarchy.
v The collection interval time has been exceeded -- The periodic collection interval is five minutes and is
not modifiable. Collection servers monitor replication for each server being monitored. Every five
minutes, each collection server uses Pull replication to obtain updates from the DDM database on each
of their monitored servers.

You must create a DDM server collection hierarchy to initiate data roll-up.

CAUTION:
Review which servers are included in the server collection hierarchy prior to retiring a server from the
domain. If you plan to retire a server, remove it from the hierarchy, and then retire the server. Failure
to remove the server causes problems with data roll-up after the server is retired.

1244 Lotus Domino Administrator 7 Help

Example of a DDM server collection hierarchy

In this example, three collection servers collect from six non-collection servers running DDM.
v Collection Server 2 (CS2) collects and reports information about itself and non-collection servers S1 and
S2.
v CS3 collects and reports information about itself and non-collection servers S4, S5 and S6.
v CS1 collects and reports information about every server shown, since it collects and reports information
from CS2 (and its servers S1 and S2), CS3 (and its servers S4, S5 and S6) and the non-collection server
S3.

The information reported exists in the DDM.NSF database on each server that is running DDM probes or
collecting DDM information or both, and that contains information about the server it is on and the
servers below it in the collection hierarchy. For example, DDM.NSF on CS2 would contain information
about itself and servers S1 and S2. To view just the information for CS2 and the servers from which it is
collecting, open DDM.NSF on the CS2 server. In this example, opening DDM.NSF on CS1 would reveal
DDM event information about this entire domain.

Managing the DDM server collection hierarchy

To manage a DDM server collection hierarchy, you use the Monitoring Configuration database,
EVENTS4.NSF. Perform the following tasks to manage a server collection hierarchy:
v Create a new server collection hierarchy
v Change the collecting server for the displayed server collection hierarchy
v Delete one or more server collection hierarchies
v Add subordinate servers to a server collection hierarchy
v Remove servers from a server collection hierarchy

Creating a DDM server collection hierarchy

Use this procedure to create a DDM server collection hierarchy.

If you choose to define your own server collection hierarchy, you can specify the subordinate servers
from which the collecting server collects DDM probe results.

For more information about adding subordinate servers to server collection hierarchy, see the topic
Adding subordinate servers to the DDM server collection hierarchy.

Chapter 56. Monitoring Domino Domains 1245

Note: If the Domino Directory design has not been upgraded to Domino 7, the servers that display when
creating or maintaining probes may include non-Domino 7 servers from the domain. Be certain to specify
Domino 7 servers when setting up or maintaining probes.
1. From the Domino Administrator, click Files.
2. Select and open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose Server Collection Hierarchy.
4. Click New Server Collection Hierarchy.
5. Complete these fields, and then click OK:

Field Action
How would you like to configure the server collection Choose one:
hierarchy? v One server will collect from all servers in the domain --
The server collection hierarchy will have only one
collection server that you specify.
v Define the hierarchy -- The server collection hierarchy
will consist of as many collection and monitoring servers
as you specify.
Choose the collecting server Choose a collecting server from the list.
Enter a short description to identify the hierarchy (i.e., Enter a description of the hierarchy. This description is
Mail Servers) used to identify the hierarchy you are creating.

Changing a DDM collection server

Use this procedure to select a new collection server for the specified hierarchy.

Note: If the Domino Directory template design is not Domino 7, a message appears stating that you are
not running the correct template design and the server list may include servers that do not support
DDM.
1. From the Domino Administrator, click Files.
2. Select and then open the Monitoring Configuration database.
3. Choose Server Collection Hierarchy.
4. Select the server collection hierarchy for which you want to choose a different collection server.
5. Click Change Collection Server.
6. Select a new collection server from the list. The server list only includes Domino 7 servers, because
Domino 7 supports DDM.
7. Choose File - Close to exit.

Deleting a DDM server collection hierarchy

Use this procedure to delete a server collection hierarchy from the Monitoring Configuration database
(EVENTS4.NSF).

Note: If you select a server collection hierarchy and that hierarchy is displayed, you cannot delete the
selected server collection hierarchy unless it is the only server collection hierarchy in the domain.
1. From the Domino Administrator, click Files.
2. Select and then open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose Server Collection Hierarchy.
4. Click Delete Server Collection Hierarchy, and then select one or more hierarchies to delete.
5. Click OK.

1246 Lotus Domino Administrator 7 Help

Adding subordinate servers to the DDM server collection hierarchy
Use this procedure to add one or more subordinate servers to a server collection hierarchy.
1. From the Domino Administrator, click Files.
2. Select and then open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose Server Collection Hierarchy. Verify that the selected hierarchy is the one with which you want
to work. If it is not the correct server collection hierarchy, choose another one.
4. Click the name of a collection server to which you want to add a subordinate server.
5. Choose one or more subordinate, and then click OK.

Removing servers from the DDM server collection hierarchy

When removing servers from a DDM collection hierarchy, the removal list is only populated with servers
that are directly subordinate to the selected server. The list of servers does not include servers that are
subordinate to the subordinate servers. The first step in deleting a server from the DDM collection
hierarchy is to select the parent (collection) server of the subordinate servers to be deleted from the
hierarchy. You can then remove one or more subordinate servers from that hierarchy. You need to be
aware of the following information pertaining to removing servers from a DDM server collection
hierarchy:
v If you remove a ″root″ collection server, all subordinate servers are also removed. A root collection
server collects from all other servers in the hierarchy. All servers in the server collection hierarchy are
subordinate to the root collection server.
v If you select a subordinate server that has no subordinate servers assigned to it, you can only remove
the selected subordinate server because there are no other servers to remove.
v If you select a subordinate server that has subordinate servers assigned to it, you have the option to
remove the subordinate server you selected and all servers subordinate to the selected server, or you
can specify which servers to remove that are subordinate to the selected server.

Use this procedure to remove one or more servers from a server collection hierarchy.
1. From the Domino Administrator, click Files.
2. Select and then open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose Server Collection Hierarchy. Verify that the selected hierarchy is the one with which you want
to work. If it is not the correct server collection hierarchy, choose another.
4. Click the name of the server that you want to remove from the server collection hierarchy. Depending
on the selected server’s place in the hierarchy, one or both of these options are available. Choose one:
v Remove subordinate servers from <Server Name.>
v Remove <Server Name> from the server collection hierarchy.
5. Click OK.

Domino Domain Monitor database (DDM.NSF)

The Domino Domain Monitor database contains event information that is reported by DDM probes as
well as event information reported by other checks that are built into Domino 7 for DDM. Those checks
include event generators; new checks that run as part of specific server tasks, such as the router or
replicator; and checks that generate events in previous Domino releases and that have now been modified
to report into DDM with additional information.

Use the Domino Domain Monitor database to view DDM events, review probable causes and possible
solutions for reported DDM events, assign DDM events to an administrator for resolution, and to open a
link to the appropriate database from which you can resolve a reported event. DDM contains two classes
of event information, enhanced events and simple events. Enhanced events include events generated by a
DDM Probe configuration document, events generated by a Domino event generator, or any other event
with specific target information appearing in the DDM event report. A target can be a server, a database,

Chapter 56. Monitoring Domino Domains 1247

an agent, or a user-specified target. A simple event is any event that is not associated with or that does
not contain specific target information. For example, most of the events that are reported to the Domino
server console are simple events.

From the Domino Domain Monitor database, you can select an event and view detailed information
about an event. Then you can use the Probable cause and possible solution tab to view information about
the cause of the event, and, in some cases, use a database link to access the appropriate database from
which you can resolve the event. Some DDM Event documents include a Details tab that displays
additional details about the event and a Correlation tab that contains links to other DDM Event
documents that may be related to the open DDM Event document.

The first time that a Domino 7 server starts, the Domino Domain Monitor database (DDM.NSF) is created
from the DDM.NTF template. This database contains DDM event information for the server on which it
resides. If the server is a collection server, the database also contains information from the servers from
which it collects data. Each time a problem is detected, a DDM event is generated -- based on the probe
type, probe subtype, and severity that you specify in the DDM Probe document when you create or
modify a probe.

For information about event generators, see the topic Event generators.

Viewing events in the Domino Domain Monitor database

Use the Domino Domain Monitor database to view events sorted by severity, type, server, date or
assignment. You can also view open events, recent events or all events simply by clicking a tab in these
views. Use the My Events view to view only those events that are assigned to you. When you open the
Domino Domain Monitor database, data is presented at a high level, but you can choose to view detailed
information about a particular event or set of events. You can also toggle between viewing unread events
or all events. If you notice that a particular event is generated frequently, you can view a detailed history
of that event to assist you in determining a cause and solution for the event.

Note: Recent events consist of all Open events and all Closed events that had a status of Open during
the previous 7 days.

Event messages often, include two statements -- a problem statement followed by a reason statement. For
example,:
Unable to replicate with server server name: Server not responding.

The problem statement is the first statement and the reason statement is the second statement. (In this
example, the two statements are separated by a colon, but messages comprised of one statement can also
have colons.) Each statement has its own type and severity. ″Unable to replicate with server server name″
has the message type and the severity of Replication/Failure, and ″Server not responding″ has the
message type and severity of Resource/Failure. Messages that are comprised of two statements generate
two events. There is no definitive way to determine whether a message is comprised of one statement or
of two, but when a message statement follows the pattern of problem statement followed by a reason
statement, two events are usually generated.

To view an event message that was generated by a pre-Domino 7 event generator, open the Monitoring
Configuration database (EVENTS4.NSF), and then open the view Advanced -- Message by Text to view
how that event message is categorized in DDM. The information on the Basics panel shows the name of
the new Event Type and the Old Event Type. In Domino 7 in DDM, there are 9 event types and in
pre-Domino 7, there are 22 event types. You use the information on the Basics panel to see how the old
event types are incorporated into the new event types. For example, this event message has Server as the
Event Type and Mail as the Old Event Type
Compacting <database name>

1248 Lotus Domino Administrator 7 Help

The first time that an event is logged to the Domino Domain Monitor database, one of these states is
automatically assigned to the event:
v Open -- The event has a non-normal severity and the administrator has not closed the event.
v Closed -- The event has a normal severity and an administrator has closed the event .If a Closed event
is later reported with non-normal severity, the event state changes to Open.
v Permanently Closed -- An administrator has marked the event Permanently Closed. These events never
reopen automatically, but an administrator can reopen them or designate them as Closed.

Every time that a probe runs, event documents are updated. If the severity of an event changes, the
event’s state automatically changes accordingly. The event state is determined by the event severity.
Events with a severity of normal are closed; events with a severity of non-normal are open. An event’s
state can automatically change many times between Open and Closed. Permanently Closed events are
never automatically opened or pended. When you assign an event state of Permanently Closed to an
event, that state is maintained as a fixed state unless you manually change the state back to Open or
Closed. Permanently Closed is a stable category for resolved problems, obsolete problems, or problems
that you simply want to ignore.

After you review or assign an event, you can manually assign it a state of Open, Closed, or Permanently
Closed.

Note: To change an event’s state, you must have a minimum of Author access with the role Change State
in the ACL for DDM.NSF. The Change State button does not display if you do not have the required
access.

The Document Change History section of the Event documents records details about assignment and
state changes so that you can determine what has changed, when the change occurred, and who initiated
the change.

Note: To assign or reassign an event to an administrator, you must have a minimum of Author access
with the role Assign Events in the ACL for DDM.NSF. If you lack the required access, the Assign Events
and Reassign Events buttons do not display.

You can look at the Event Change History section of the Event documents to see previous event change
activity.

Maintaining the Domino Domain Monitor database

Use the following topics to manage events in the Domino Domain Monitor database.
v Assigning events in the DDM database to an administrator
v Reassigning an event in the DDM database
v Changing an event state in DDM
v Viewing Correlated events in DDM
v Resolving an event in the DDM database

Specifying ACL settings and roles in the DDM database

Several of the actions that you can perform while maintain the Domino Domain Monitor database
(DDM.NSF) require that an administrator have a specific minimum level of access assigned in the ACL
for DDM.NSF. Additionally, some activities require that a specific minimum level of access and a specific
role be assigned.

Action Minimum access and required roles

Read Event documents Read access
Add comments to your own events Author access

Chapter 56. Monitoring Domino Domains 1249

Action
Add comments to another administrator’s events
Assign or reassign your own events
Assign or reassign events regardless of owner
Change state of your own events
Change state of event regardless of owner
Minimum access and required roles
Editor access
Author access and the [Assign Events] role
Editor access and the [Assign Events] role
Author access and the [Change State] role
Editor access and the [Change State] role

Assigning events in the DDM database to an administrator

In the DDM database, you can assign one or more selected events to an administrator that you choose.
Assigning events enables you to manage Event documents and to delegate issues to be addressed in your
domain.

When you finish assigning events to administrators, you can verify that you have assigned all events
correctly by opening the By Assignment view. You can also look at the entries in the Event Change
History section of an Event document to see assignment activity. Every Event document also displays the
event state and assignment at the top of the document.

Note: To assign an event to an administrator, or to reassign events that are owned by another
administrator, you must have a minimum of Editor access with the role Assign Events in the ACL for
DDM.NSF. To assign one of your own events to another administrator, you must have Author access with
the role Assign Events. The Assign Events button does not display if you do not have the required access.
Author access is required to add comments to your own events; Editor access is required to add
comments to another administrator’s events.

Assigning events from within a view:

1. From the Domino Administrator, click Files.
2. Open the Domino Domain Monitor database (DDM.NSF).
3. On the left panel, choose the view that you want to open.
4. Choose one of these for the field, Assign selected Event(s) to:
v Administrator -- To assign one or more events to another administrator, specify the name of the
administrator who will be responsible for resolving the event(s).
v Myself --To assign one or more events to yourself.
5. Enter comments as necessary. Comments are added to the Document Change History section of the
Event document.
6. Click OK.

Assigning events from an open Event document:

1. From the Domino Administrator, click Files.
2. Open the Domino Domain Monitor (DDM.NSF).
3. Choose the view that you want to open.
4. Open the Event document for the event you are working with.
5. Choose one of these for the field, Assign selected Event(s) to:
v Administrator -- To assign the event to another administrator, specify the name of the administrator
who will be responsible for resolving the event.
v Myself --To assign the event to yourself.
6. Enter comments as necessary. Comments are added to the Document Change History section of the
Event document.
7. Click OK.

1250 Lotus Domino Administrator 7 Help

Changing the state of an event in DDM
Use the Change State button to change the state of an event. The Change State button is available when
you open an event to view detail about the event. If you change the event state of an Event document
that is unassigned, the event is assigned to you. If you change the event state of an Event document that
is assigned to another administrator, the event owner is not changed.

You can look at the Event Change History section of the Event documents to see previous event state
change activity.

Note: To change an event state for one of your own events, you must have a minimum of Author access
with the role Change State in the ACL for DDM.NSF. To change the state of any event documents,
regardless of owner, you must have Editor access with the Change State role in the database ACL. Author
access is required to add comments to your own events; Editor access is required to add comments to
events owned by another administrator.
1. From the Domino Administrator, click the Files tab.
2. Open the Domino Domain Monitor database (DDM.NSF).
3. Select the event whose state you are changing. You can open the event but it is not necessary that you
do so.
4. Click Change State and then choose the new state. Enter comments as necessary. Comments are
added to the Document Change History section of the Event document.
5. Click OK.

Controlling the content and size of the DDM database

To prevent the DDM database from becoming too large and using an excessive amount of disk space, you
can filter by severity level the messages that are logged to the Domino Domain Monitor. You can also
designate whether both enhanced and simple events are filtered or whether only simple events are
filtered. When you apply a filter to a set of events, you control which events are collected and stored in
DDM and which are not. You can configure the individual probes to report events of a particular severity
instead of logging all events.

To adjust the individual probe configurations to limit which severity levels are reported in the DDM
database, open the Probe document for a particular probe and adjust the settings on the Specifics tab of
the Probe document.

Viewing correlated events in DDM

A problem can generate multiple events. For example, when a target server becomes unavailable, the
router, replicator, and other components may each generate errors. DDM correlates these events and
reports them as one error. In keeping with this example, multiple errors are reported as one error --
″Server not responding.″

Event documents in the DDM database are correlated, that is, grouped into similar categories whenever
possible. You can view correlated events by clicking the Correlated Events tab in the Probe document for
any event that is correlated. Those events that do not have related events are not correlated and the
Correlated Events tab does not display.

Events are correlated across servers by opening the DDM database on the collection servers, and then
correlating the events.

Reassigning an event in the DDM database to an administrator

The Domino Domain Monitor has a Reassign Event feature, accessible from within the Event document,
that you use to reassign an event that you have opened.

Note: You must have Author access with the role Assign Events in the ACL for DDM.NSF to assign your
own events to another administrator. You must have Editor access with the role Assign Events to reassign
any event documents, regardless of the event’s owner. The Reassign Events button does not display if

Chapter 56. Monitoring Domino Domains 1251

you do not have the required access. Author access is required to add comments to your own events;
Editor access is required to add comments to events owned by another administrator.
1. From the Domino Administrator, click Files.
2. Open the Domino Domain Monitor database (DDM.NSF).
3. Choose the view that you want to open.
4. Select the event you want to reassign and double-click to open the Event document.
5. Click Reassign Event.
6. Specify the name of the administrator to whom you are reassigning the event. Enter comments as
necessary. Comments are added to the Document Change History section of the Event document.
7. Click OK.
8. (Optional) When you finish reassigning events to administrators, open the By Assignment view to
verify that you assigned all events correctly,.

Resolving an event
When you open an Event document in the Domino Domain Monitor database, you can review the
Probable Cause and Possible Solution statements. In many cases, there is a Choose Solution button that
you can use to automatically implement a particular solution to resolve an event. When you click Choose
Solution, and there are multiple possible solutions that can be automated, a list of automated solutions
appears. This list may contain all possible solutions or it may contain a subset of possible solutions --
only those that can be automated. It is important to consider all possible solutions, whether automated or
not automated.

If only one automated solution is available, when you click Choose Solution, that solution is
implemented.
1. From the Domino Administrator, click Files.
2. Open the Domino Domain Monitor database (DDM.NSF).
3. Choose the view that you want to open.
4. Open the Event document for the event that you want to resolve.
5. Review the Probable Cause and Possible Solution statements, and then click Choose Solution.
6. Select the automated solution that you want to implement, and then click OK.
The automated solution is initiated. For example, if a database does not have a full-text index, a
full-text index may be created. Or, if a change needs to made to a Server document, that Server
document is opened and you can make the necessary change.

How resolved problems are handled: Probes decide when their DDM events should be cleared, and for
the most part clear them individually.

Use the Domino Domain Monitor to view, resolve and close current problems. You also have the option
of viewing recent events. Use the Recent Events tab to view detailed information including fields that
indicate the event’s worst status in the past 24 hours, week, and month. These views are updated daily as
needed.

Using IBM Lotus instant messaging in the Domino domain monitor

database
You can initiate an IBM Lotus instant messaging chat with another DDM administrator from the Domino
Domain Monitor (DDM) user interface. Locate the Show Administrators feature located on the left pane
of the DDM user interface. Use the Show Administrators feature to locate the name of the administrator
with whom you want to initiate a Sametime chat.

If the field IBM Lotus Sametime Server on the Location document - Server tab, contains a Sametime
server name, the option Show Admin List is visible in the DDM user interface. If the IBM Lotus
Sametime Server field is blank, the Show Administrators feature is not operational. The list of
1252 Lotus Domino Administrator 7 Help
administrator names that displays is derived from the fields ″Full Access Administrators″ and
″Administrators″ on the Security tab of the Server document.

Note: If the fields ″Full Access Administrators″ and ″Administrators″ on the Security tab of the Server
document are updated, the Sametime list in the DDM user interface is not automatically updated. To
refresh the list, restart the Event task on the Domino server.

To hide the list of administrator with whom you can initiate a chat, when the list is expanded, click Hide
Administrators.

The IBM Lotus instant messaging pane in DDM.NSF on a collecting server contains an option allowing
you to specify which server’s list of administrators you want to access. On all other servers, that is,
non-collecting servers, the IBM Lotus instant messaging pane displays the Administrator list for that
server only. The collecting server contains the rolled-up data from other servers in the domain.

Filtering events in DDM

Create and use DDM filters to control which events are collected and then stored in DDM. You specify
whether to apply a filter to both enhanced and simple events, or only to simple events. You can then
apply a filter to all servers or only to those servers that you specify; however, you can only apply one
filter to any one server. Use DDM filters to specify which event types, event classes, and severity levels
are to be included in the DDM database.

Note: If the Domino Directory design has not been upgraded to Domino 7, the servers that display when
creating or maintaining filters may include non-Domino 7 servers from the domain. Be careful to specify
Domino 7 (or more recent) servers when setting up or maintaining filters.

See these procedures for information on creating and managing DDM filters:
v Filtering DDM events
v Modifying a DDM filter
v Deleting a DDM filter

Filtering DDM events

DDM can produce a substantial amount of information for you. You can use DDM filtering to control
which events are reported to DDM.

Use this procedure to create a filter, assign the filter to one or more servers and to specify event types,
event classes, and severity levels to log. You can apply the filter both to enhanced and simple events, or
only to simple events. When assigning a filter to a specific server, you can specify one server or you can
use a wild card character to designate all servers in a particular organization. For example, enter */Sales
to assign a filter to all servers in the Sales organization. New DDM filters are applied to new events that
are generated after the Filter document is saved.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose DDM Configuration - DDM Filters.
4. Click New DDM Filter.

Chapter 56. Monitoring Domino Domains 1253

5. Complete these fields:

Field Action
Description Type a description of the filter you are creating. The
description that you specify displays as a means of
identifying this filter from other filters on the list of DDM
filters in the Monitoring Configuration database. You can
enter a maximum of 125 characters for the filter
description.
Event Filter Choose one:
v Apply filter to enhanced and simple events -- Applies
the DDM filter to both enhanced events and simple
events.
v Only apply filter to simple events -- Applies the DDM
filter to simple events only.
Event types and severities to log Choose one:
v Log All Event Types -- Reports all event types to DDM.
If you choose this option, then specify the severities to
report.
v Log Selected Event Types -- Specify the event types that
are to be reported to DDM as well as the corresponding
severities for each event type.
Servers on which the filter will be applied Choose one:
v All servers in the domain -- Applies the new DDM
filter to all servers in the domain.
v Special target servers -- Specify the types of servers to
which the filter will be applied, such as POP3 servers or
the administration server for the Domino Directory.
v Only the following servers -- Choose this option to
specify by name, the servers to which the new DDM
filter will apply.

6. Click Save and Close.

Modifying a DDM filter

Use this procedure to edit a DDM filter.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose Filters - DDM Filters.
4. Select the filter that you want to edit and then click Edit Document.
5. Make changes, and then click Save and Close.

Deleting a DDM filter

Use this procedure to delete a DDM filter.
1. From the Domino Administrator, click the Files tab.
2. Open the Monitoring Configuration database (EVENTS4.NSF).
3. Choose Filters - DDM Filters.
4. Select the filter that you want to delete, and then click Delete Document.
5. Press F9 to refresh, and then click Yes.

1254 Lotus Domino Administrator 7 Help

Chapter 57. 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:

v Schedule regular backups. Backups based on transaction logs are faster and easier than full database
backups that do not use transaction logging.
v 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.
v 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.
v 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.

1255
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:

v You enable transaction logging for the first time.
v You run the Compact task with an option -- for example, the option to reduce file size.
v You run the Fixup task on corrupted databases.
v You move a Domino database to a logged server.

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.

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.

1256 Lotus Domino Administrator 7 Help

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.

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.

v 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.
v 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.
v 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.
v 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).
v Choose the logging style that fits your needs. Logging styles include archived, circular, and linear.
v 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.

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.

Chapter 57. Transaction Logging and Recovery 1257

4. Click the Transactional Logging tab, complete these fields, and then save the document:

Field Action
Transactional Logging* Choose one:
v Enabled -- To start transaction logging
v Disabled (default) -- To not use transaction logging
Log path* 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.

Use all available space on log
device
Maximum log space
Note: If the device is used solely for storing the transaction log, set the ″Use all
available space on log device″ field to Yes.
For circular and linear logging only. Choose one:
v 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.
v No -- To use the default or specified value in the ″Maximum log space″ field.
For circular and linear logging only. The maximum size, in MB, for the transaction
log. Default is 192MB. Maximum is 4096MB (4GB).
Note: When Domino is configured to run with DB2, a minimum log file size of 192
MB is required.

Allocate a separate disk with at least 1024MB (1GB) of disk space for the
transaction log.

Automatic fixup of corrupt
databases
Runtime/Restart performance
Domino formats at least 3 and up to 64 log files, depending on the maximum log
space you allocate.
Choose one:
v 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.
v 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.
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:
v Creates a recovery checkpoint record in the transaction log that lists each open
database and the starting point transaction needed for recovery
v Forces database changes to be saved to disk if they have not been saved already

Choose one:
v Standard (default and recommended) -- To record checkpoints regularly.
v 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.
v Favor restart recovery time -- To record more checkpoints. This option improves
restart recovery time because fewer transactions are required for recovery.

1258 Lotus Domino Administrator 7 Help

Field Action
Logging style** Choose one:
v Circular (default) -- To re-use the log files and overwrite old transactions.
v 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.
v 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.

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 Issue
Transactional Logging 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.
Log path 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.
Use all available space on log If you change only this field, you do not need to restart the server. As Domino
device logs the transactions, the changes take effect.
Logging style If you change the logging style, you must perform a full backup of all databases
because Domino assigns new DBIIDs to all the databases.

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.

Chapter 57. Transaction Logging and Recovery 1259

To disable transaction logging for a specific database
Note: The Advanced Database Properties are available only to those administrators listed in the
Administrators field on the Security tab of the Server document.
1. Do one of the following to choose ″Disable transaction logging″:
v If you are creating a new database, use the Advanced Database Options dialog box.
v If you are working in an existing database, use the Advanced tab of the Database Properties box.
v 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.″

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

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:
v Databases in formats that are earlier than Domino 5
v Databases that are in Domino 5 format but have transaction logging disabled
v 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.

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.

1260 Lotus Domino Administrator 7 Help

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

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 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 2000/2003 systems do not require any system resource changes.

Enabling fault recovery

1. From the Domino Administrator, click the Configuration tab, and expand the Server section.
2. Open the Server document, click Edit Server, and click the Basics tab.
3. In the Fault Recovery section, check ″Automatically Restart Server After Fault/Crash Enabled.″
4. Save and close the document.

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 Server, and click the Basics tab.

Chapter 57. Transaction Logging and Recovery 1261

3. In the Fault Recovery section, complete these fields:

Field Action
Run This Script After Enter the entire script name, including any extensions.
Server Fault/Crash
Do not try to enable NSD from this field. You can enable NSD in the field ″Run NSD to
collect diagnostic information.″

Note: Directory separators (slashes) in the file name portion are converted for the
operating system, but slashes in optional arguments are not converted.
Run NSD To Collect Enable this field to activate NSD when there is a fault or crash.
Diagnostic Information
Cleanup Script/NSD Enter the number of seconds for the cleanup script to run. Default is 300 seconds (5
Maximum Execution minutes). Maximum is 1800 seconds.
Time
Maximum Fault Limits Enter the number of restarts allowed during a specified time limit -- for example, 3
crashes within 5 minutes. If the number of crashes exceeds the time limit, the server exits
without restarting.
Mail Fault Notification Enter a user or group name. When the server restarts, Domino checks if it is restarting
to after a crash and sends e-mail to the person or group.

Setting up a Fault Reports database

The Lotus Notes/Domino Fault Reports database stores data that is collected at the time of a server
crash. Data is collected from both the client and the server and can then be used to measure client
reliability and determine the areas where problems exist.

A Fault Reports database is created by default during first server setup in the domain. Optionally, you
can set up additional Fault Reports databases -- for example, you may want to separate the data from
client and server crashes. You would then specify different Fault Reports databases on various Server
Configuration and Desktop Setting documents. However, it is not necessary that you do so.

For information about the automatic collection of data, see the topic ″Collecting diagnostic information
after a server or client crash″ in this chapter.

For information about using the desktop policy settings document when setting up automatic data
collection, see the chapter ″Using Policies.″

When you create a new Fault Reports database, the administration process generates an administration
process request that automatically creates the mail-in database document for you.

Creating a Fault Reports database

The Lotus Notes/Domino Fault Reports database is created for your domain during first server setup.
You can, however, create additional fault report databases if needed.
1. From the Domino Administrator, click the Server tab
2. Click Analysis.
3. From the Tools pane, click Analyze - Open Fault Reports.
4. Enter the server name/domain name in the Server field.
5. Enter a unique file name with the file name extension of .NSF.

Note: The file name defaults to LNDFR.NSF. If you attempt to create another database with this
name, an error message is generated.
6. Enter the database title.

1262 Lotus Domino Administrator 7 Help

7. Click Create.

Collecting diagnostic information after a server or client crash

The automatic diagnostic collection tool collects diagnostic data after server and client crashes and sends
the collected data to a mail-in database when the server or client restarts. You can then use the collected
data to determine the cause of the crash. Data is stored in Fault Report documents. One mail-in database
in each domain. You can store all of the Fault Report documents from all client and server crashes in a
domain in one database, or you can create one database for server crashes and one database for client.
You specify the mail-in database when you set up this feature. The collected data from client crashes can
be sent to the customer’s local Automatic Data Collection database(s) enabling customers to quickly
identify duplicate problems encountered at their site, or the data can be sent to the same database as the
server data.

Fault Analyzer is a server add-in task that processes all new crashes as they are delivered to the
Automatic Data Collection mail-in database. For each new crash, the fault analyzer task searches the
database containing the Fault Report documents and determines whether the stack matches a crash that
has already been seen by a user or server at that customer site. The Automatic Data Collection database
lists all Fault Reports, as well as Response documents for any duplicate occurrences of the same crash
and indicates whether the duplicate occurrence is an exact match or a partial match of the original crash.
The duplicate occurrences response documents are the Exact Match Fault Report and the Partial Match
Fault Report documents. The Partial Match Fault Report document also includes a ″percentage match″
that indicates the percentage of the report that matches the original Fault Report for the crash.

Use the fields on the Diagnostics tab of the Server Configuration Settings document to specify whether
the Fault Analyzer task is enabled on a server. When fault analyzer is enabled, at server startup, Domino
reads the Server Configuration Settings documents and desktop policy documents in the local Domino
Directory. If any document has a Fault Reports database specified, Domino determines whether the
database resides on the local server and if so, Domino adds it to its list of databases to monitor. Every 10
seconds the process determines whether the data modified time of any of the its monitored databases has
changed and if so, fault analyzer scans for new unprocessed documents to try to match.

An occurrence count and unique ID count are updated in the parent Fault Report document for the crash.
The occurrence count is the total number of times a crash has occurred; the unique ID count is the
number of clients and servers on which that problem has been reported.

The Administrator section of the Fault Report document contains a Resolved field that you can use to
mark a crash as resolved for all versions of clients and servers reporting to the database, or resolved for
specific versions that you identify by release level, for example, Domino Notes 6.5.1 or by hot fix
numbers, for example, 652HF10.

When a fault is marked as resolved, all clients and servers that crashed with the same signature and that
are at a version level for a fault that is to be resolved are not be marked as a duplicate. Instead, the Fault
Report document is kept as a parent document. Resolved documents have a check mark displayed next
to them in the views.

For information on creating a new mail-in database, see the chapter ″Rolling Out Databases.″

The following files that were previously stored in the Domino data directory are now stored in the
diagnostics directory, IBM_TECHNICAL_SUPPORT, located beneath the Notes/Domino data directory:
v nsd output
v memcheck output
v core files
v memory dump files (created in the format memory_<platform>_<machine name>_<date>@<time>.dmp
instead of memory.dmp)

Chapter 57. Transaction Logging and Recovery 1263

v notes_child_pid

To prevent the diagnostic files from becoming quite large and using a significant amount of disk space,
you can specify the number of days that these files can be stored before they are deleted by the automatic
diagnostic collection tool.

When setting up automatic diagnostic collection for clients, you can designate whether this feature is
invisible to users or whether users should be prompted to designate whether they want to send a
diagnostic report to the mail-in database. If you designate that the user is not to be prompted, this feature
is transparent to the user. The process then runs in the background after the user restarts the client and
enters their password. If you designate that the user should be prompted to specify whether to report the
crash, the user can also designate whether to view the report before it is sent.

Writing status bar history to a log file

You can use the NOTES.INI setting LOGSTATUSBAR=1 to enable logging of status bar messages to the
local log file, LOG.NSF. To view the logged messages, open the file, LOG.NSF, and then click the
Miscellaneous Events view. Status bar messages are appended with ″Status Msg.″

To write the status bar messages to an external file, use the NOTES.INI setting Debug_Outfile=<path to
file> with the NOTES.INI setting LOGSTATUSBAR=1. For example,
LOGSTATUSBAR=1
Debug_Outfile=c:\temp\StatusBarLogging.txt

Use the information that is written to the log file to assist you when troubleshooting problems.

For more information about the NOTES.INI variables used to enable logging of status bar messages, see
the topic NOTES.INI Settings.

Setting up automatic diagnostic data collection on clients

Use the desktop policy settings document to set up automatic diagnostic data collection on clients. If you
have already created a desktop policy settings document, open that document and complete the fields on
the Diagnostics tab. If you have not already created a desktop policy settings document, complete the
entire procedure to create the document.

For information on creating a desktop policy settings document, see the chapter ″Using Policies.″

Setting up automatic diagnostic data collection on the server

Use the Server Configuration document to set up automatic diagnostic data collection on the server. You
can also enable or disable Fault Analyses from this same tab on the Server Configuration Settings
document.
1. From the Domino Administrator, click the Configuration tab.
2. Click Server - Configurations.
3. Select the Server Configuration document you want to edit and click Edit Configuration.
4. Click the Diagnostics tab and complete these fields.

Field
Mail-in Database for diagnostic reports
Maximum size of diagnostic message including
attachments (in MB)
Action
Click in this field, and then select the mail-in database to
which you want the diagnostic report for server crashes
mailed. Click OK.
Enter the maximum size of the entire message that
automatic diagnostic data collection will create, including
all attachments -- NSD, console output, user defined
files, and so forth.

1264 Lotus Domino Administrator 7 Help

Field
Maximum size of NSD output to attach (in MB)
Maximum amount of console output file to attach in
(KB)
Diagnostic file patterns
Remove diagnostic files after a specified number of days
Number of days to keep diagnostic files
Action
Enter the maximum size of the NSD log that can be
attached to the document created by automatic
diagnostic data collection. (Automatic diagnostic data
collection collects data and then creates documents in a
mail-in database.)
Use the default value of 10240, or enter another value
between 10mb and 1kb. 10240 is the upper limit. This
value represents the portion of the CONSOLE.LOG file
to be sent, beginning with the end of the file and moving
toward the beginning.
Enter a file name pattern that Domino will search for. If
the pattern is located and it is listed in the file,
DIAGINDEX.NBF, the file will be attached to the
message that is sent to the mail-in database.
DIAGINDEX.NBF contains all of the files associated with
the crashing instance of the client or server. For example,
the following is a file pattern: addin_log*.txt. These files
would be located based on that pattern:addin_log1.txt,
addin_log_2004_11_23@16_21_20.txt, etc...
Choose one of these:
v No -- (Default) Choose No to accept the default of
never automatically deleting the diagnostic files
created on the server.
v Yes -- Choose Yes to enter the number of days after
which the diagnostic files on the server are to be
deleted. Displays the field ″Number of days to keep
diagnostic files.″
Accept the default value of 365 days, or enter another
value representing the number of days after which the
diagnostic files are to be deleted from the server. (This
field displays only if you chose Yes for the ″Remove
diagnostic files after a specified number of days.″)

5. Save and close the document.

Enabling the Fault Analyzer task on the server

You can complete this task at the same time that you set up automatic diagnostic data collection. Use the
Server Configuration document to set up automatic diagnostic data collection on the server and to enable
or disable Fault Analyses
1. From the Domino Administrator, click the Configuration tab.
2. Click Server - Configurations.
3. Select the Server Configuration document you want to edit and click Edit Configuration.
4. Click the Diagnostics tab and then complete these fields.

Field Action
Run Fault Analyzer on Fault databases on this server Choose one:
v Yes -- Enables the Fault Analyzer task on this server.
v No -- Disables the Fault Analyzer task on this server.

Chapter 57. Transaction Logging and Recovery 1265

Field
Run Fault Analyzer on
Databases to run Fault Analyzer against?
Remove attachments for duplicate faults
Action
Choose one:
v All mail-in databases on this server -- Fault Analyzer
runs on all mail-in database on this server. Fault
Report documents may be posted to any mail-in
database on the server.
v Specific mail-in database -- Specify the mail-in
database on which you want Fault Analyzer to run.
Fault Reports documents will be posted to this
database.
Specify the databases against which you want Fault
Analyzer to run. The Fault Analyzer task searches these
database for Fault Report documents and determines
whether the stack matches a crash that has already been
seen by a user or server at that customer site.
If Fault Analyzer locates duplicate fault reports, the new
crash is reported as a response to the original crash and
attachments are either removed from the response
document to save space in the database, or they are
saved with the response document.

Choose one:
v Yes -- Aattachments are removed from the response
document to save space in the database
v No -- Attachments are saved with the response
document.

5. Click Save and Close.

Using the IBM_TECHNICAL_SUPPORT directory

The IBM_TECHNICAL_SUPPORT database contains data that has been collected using the Domino
Configuration Collector and the Automatic Diagnostic Data Collection tool, as well as system information
files and documents that have been exported from the Domino Directory and saved as .dxl documents
using the Save command entered at the Domino server console. System information files are
automatically generated each time Domino starts when Domino issues an NSD command. Domino
collects a variety of information about the system configuration, as opposed to the configuration collector
which collects information about the Domino server configuration. Information such as available memory,
available disk space, operating system version, and other related data is collected to determine what has
changed when the server begins to have problems. Files are saved using a standard file name convention
of
type_platform_systemname_date@time.log

For example, sysinfo_W32I_SystemA_06_11@17_25.log

Note: You can disable the NSD command by using the NOTES.INI setting
Disable_SaveNSDConfig=value.

Periodically review the size of the IBM_TECHNICAL_SUPPORT database to prevent it from using
excessive disk space. By default, Domino stores a maximum of ten of each file type. Use the NOTES.INI
setting MAX_CONFIG_FILES to change the number of files saved for each type of document .If you
reduce the number of files that can be stored, the appropriate number of each type of file is deleted. The
NOTES.INI setting is checked each time the server starts, or whenever there is a configuration change. To
modify only the number of NSD files saved in IBM_TECHNICAL_SUPPORT database, use the

1266 Lotus Domino Administrator 7 Help

NOTES.INI setting MAX_NSDINFO_FILES. If this setting exists in the NOTES.INI file, it will be used to
control the number of NSD files instead of using MAX_CONFIG_FILES.

To disable the automatic collection of data from the Domino server, use the NOTES.INI setting
DISABLE_SAVESERVERCONFIG.

To enable or disable only the collection of NSD information, use the NOTES.INI setting
DISABLE_SAVENSDCONFIG.

If the value DISABLE_SAVENSDCONFIG exists, it is honored; otherwise, the value

DISABLE_SAVESERVERCONFIG is honored.

This table shows when NSD is enabled and when the NOTES.INI settings are honored:

DISABLE_SAVESERVERCONFIG DISABLE_SAVENSDCONFIG NSD Auto Collect

Value = 0, or setting not present Value = 0 Enabled
Value = 0, or setting not present Value = 1 Disabled
Value = 0, or setting not present Setting not present Enabled
Value = 1 Value = 0 Enabled
Value = 1 Value = 1 Disabled
Value = 1 Setting not present Disabled

Chapter 57. Transaction Logging and Recovery 1267

1268 Lotus Domino Administrator 7 Help
Chapter 58. 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:
v Control the size of the log file
v Record additional information in the log file
v View the log file
v Search the log file

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.

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.

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 Setting, field, or command

Mail routing ″Logging level″ field on the Router/SMTP - Advanced - Controls tab of
the Configuration Settings document.
Modem I/O File - Preferences - User Preferences - Ports - COMx - Trace
Modem script I/0 File - Tools - Preferences - Notes Preferences - Ports - COMx - Trace -
Options
Traced network connections Set a com port option in the Port Setup dialog box.
Web Navigator The ″Retriever log level″ field on the Server Tasks - Web Retriever tab of
the Server document.
Web server Additional information regarding the Web server is logged in the
Domino Web server log (DOMLOG.NSF).

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

Views in the log file (LOG.NSF)

View Contains information about
Database - Sizes v Size and activity of all databases on the server
v Percentage of each database’s disk space that is in use
v Total disk space of each database
v Weekly usage of the database
v Populated by the nightly Statistics Log task
Database - Usage v Sessions (including K transferred)
v Documents read and written
v Replications
v Sorted by database
v Populated by the nightly Statistics Log task
Mail Routing Events v Mail routing details not available in the Miscellaneous Events view
Miscellaneous Events v Events that do not appear in other views
v Modem I/O messages
v Script I/O messages
v Server task messages
v Sorted by date
Object Store Usage v Object store file name
v Mail database file name
v Mail database title
v Number of documents referenced in the object store
v Total size of the documents in the object store
v Details on the shared mail object store usage on your server
Passthru Connections v Starting and Ending times, destination, and protocol for each passthru connection
Phone Calls - By Date v Information about calls made and received by a server, sorted by date or by user
Phone Calls - By User

1270 Lotus Domino Administrator 7 Help

View Contains information about
Replication Events v All replication sessions between servers, sorted by server
v Information includes the name of the initiating server, time and duration of
replication, port used, and the number of documents added, deleted, or modified
Sample Billing v 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
Usage by Date v Sessions this server had with users or other servers, sorted by date or by user
Usage by User v Information includes: sessions opened; session duration; databases opened;
database-access duration; number of transactions (workstation-to-server database
requests); and network usage (K transferred)
v 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
v Includes totals by date, by user/server, and for all usage
Search Results v Results of log analysis
v 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 or more recent 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:
v Status of the event, displayed as an icon
v Type of event
v Severity of the event
v Time the event occurred
v A description of the event

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.

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

Chapter 58. Using Log Files 1271

Search criteria Complete the following
Date Start and End Date -- Select the dates you want to search.

Start and End Time -- Select the times you want to search.

Select one:
v Use above time range in any time zone -- Use this setting when you do not need to
vary the search start and end parameters.
v 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 Click in the column to the left of a message to select the error message for which you
want to search.
Event Text Do any of the following to refine your text.
v Look for -- Choose one of these:

any of the words

all the words

exact phrase
v Enter -- Enter the words or phrases for which you want to search.
v Must Contain the Words -- Enter the words that the log search must contain to be
successful.
v Must Not Contain the Words -- Enter the words or phrases that would make a search
result invalid.
Queries 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.

1272 Lotus Domino Administrator 7 Help

Analyzing Domino log files using an older Domino 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.

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:
v Date and time the request was made
v User’s IP address (or the DNS address if DNS lookup is enabled in the Server document)
v User’s name (if the user supplied a name and password to access the server)
v Status code the server returns to the browser to indicate its success or failure in generating the request
v Length of the information, in bytes, sent from the server to the browser
v Type of data accessed by the user -- for example, text/html or image/gif
v HTTP request sent to the server from the browser
v Type of browser used to access the server
v Internal and Common Gateway Interface (CGI) program errors
v URL the user visited to gain access to a page on this site
v Server’s IP address or DNS name
v Amount of time, in milliseconds, to process the request
v Cookies sent from the browser
v 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.

Chapter 58. Using Log Files 1273

5. (Optional) Under ″Exclude From Logging,″ complete these fields to exclude certain types of
information from the log file:

Field Enter
URLs URL paths to exclude -- for example, *.gif or /anydir/*
Methods HTTP methods -- for example POST or DELETE
MIME types MIME types to exclude -- for example, image (for all images) or image/gif (for
.gif images)
User agents Strings that are part of user agent (browser) strings to exclude requests from a
particular user agent.
v To exclude Microsoft Internet Explorer, enter MSIE*
Return codes HTTP response status codes to exclude -- for example, 300 or 400
Hosts and domains 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.

Logging Domino Web server requests

You can log Domino Web server requests to a database or to text files.
v Text files -- Text files are smaller and can be used with third-party analysis tools.
v 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.

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:
v Extended Common
v 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.

1274 Lotus Domino Administrator 7 Help

When you log to a text file, the following information is recorded.

Text file Records

Access 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 v User agent if available, otherwise shows ″-″
Referer v URL the user visited to gain access to a page on this site

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.

Chapter 58. Using Log Files 1275

5. Under ″Log File Settings,″ complete these fields:

Field Enter
Access log format Choose one:
v Common -- To log information in three separate log files
v 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:
v LocalTime (default) -- To use the time zone currently set on the server
v GMT-- To use Greenwich Mean Time
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.
v 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
v 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.
v 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

Example: The access log file for May 2001 is access-log--052001.log.

v 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
Maximum size of access log
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.
The maximum size allowed for the access log file. If this 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 files The directory to store the log files; if this field is blank, 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.
Agent log 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.

1276 Lotus Domino Administrator 7 Help

Field Enter
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.
CGI error 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.

7. (Optional) Under ″Exclude From Logging,″ complete these fields to exclude certain types of
information from the log file:

Field Action
URLs Enter URL paths to exclude -- for example, *.gif or /anydir/*
Methods Enter HTTP methods -- for example, POST or DELETE
MIME types Enter MIME types to exclude -- for example, image (for all images) or image/gif
(for .gif images)
User agents Enter strings that are part of user agent (browser) strings to exclude requests from
a particular user agent.
v To exclude Microsoft Internet Explorer, enter MSIE*
Return codes Enter HTTP response status codes to exclude -- for example, 300 or 400
Hosts and domains 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.

Chapter 58. Using Log Files 1277

1278 Lotus Domino Administrator 7 Help
Chapter 59. Setting Up Activity Logging
This chapter describes how to set up and use the Lotus Domino 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.

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

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 When a Domino server runs scheduled agents, as well as the running time of the agents
HTTP Web server requests
IMAP Activity generated during an IMAP session
LDAP 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.
Mail 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.
Notes Database When Notes clients and Domino servers open, use, and close Notes databases and the
duration of use.
Notes Passthru When users or servers connect through a Domino passthru connection, as well as the activity
that is generated through that connection
Notes Session When Notes clients and Domino servers acting as clients start and end sessions with a
Domino server
POP3 Activity generated during a POP3 session
Replica Activity generated by replication with another server or with a client
SMTP Activity generated during an SMTP session

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

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.

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

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

1280 Lotus Domino Administrator 7 Help

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:
v 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.
v Checkpoint records, which log activity that occurs when an IMAP session has been open for a specified
length of time
v 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.

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
Add 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
Bind 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
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
Delete 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
Extended 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
Modify 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

Chapter 59. Setting Up Activity Logging 1281

Request type Information logged
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
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
Unbind Organization name, user name, server name, client IP address, the LDAP result code, and any
error messages returned to the client

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.
Delivery Mail is delivered from MAIL.BOX to a user.
Delivery failure The router could not deliver a message.
Transfer 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.
Transfer failure The router cannot transfer a message to another server. This is logged on the sending server.

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.

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:

1282 Lotus Domino Administrator 7 Help

v Open records, which log when a session begins
v Checkpoint records, which log activity that occurs when a session has been open for a specified length
of time
v Close records, which consolidate all session information into a single record when a session ends

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 v Opening a database or any action that opens a database, such as checking database properties
v Starting replication
v Having a remote server open another server’s MAIL.BOX
Checkpoint v Reading documents
v Editing documents
v Saving and updating documents
v Viewing or changing an ACL
v Rebuilding a database view
v Performing any other activity while a session is open
Close v Closing a database
v Ending replication
v Logging off, either manually or automatically
v Exiting Notes
v Having a remote server close MAIL.BOX

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:
v Open records, which log when a database opens
v Checkpoint records, which log activity that occurs when a database has been open for a specified
length of time
v Close records, which consolidate all log information for a database session into a single record when a
database closes
v CloseEnd records, which consolidate database information at the end of a Notes session (when the
client logs off of the server)
v 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 v Opening a database or any action that opens a database, such as checking database properties
v Starting replication, including opening a database to determine if replication is needed (even
if no replication is needed)*
v Having a remote server open another server’s MAIL.BOX

Chapter 59. Setting Up Activity Logging 1283

Type of record Type of activity
Checkpoint v Editing documents
v Saving and updating documents
v Viewing or changing an ACL
v Performing any other database activity while a database is open
Close v Closing a database
v Ending replication
v Logging off, either manually or automatically (one record for each open database)
v Exiting Notes (one record for each open database)
v Having a remote server close MAIL.BOX
CloseEnd v Closing a database at the end of a session
v Closing databases that the server opened for replication
v Logging off of Notes
v Exiting Notes
MailDeposit Depositing a mail message that does not contain an attachment into MAIL.BOX

* When Domino closes databases after determining that replication is not necessary, it generates a Close
record that contains 0 (zero) in the Duration field.

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:
v Open records, which log when a passthru connection begins
v Checkpoint records, which log activity that occurs when a passthru session has been open for a
specified length of time
v 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

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:
v Authorization records, which log when a user is authenticated and a session begins
v Checkpoint records, which log activity that occurs when a POP3 session has been open for a specified
length of time
v Close records, which consolidate POP3 information into a single record when a POP3 session ends

1284 Lotus Domino Administrator 7 Help

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:
v Open records, which log when an SMTP session begins
v Checkpoint records, which log activity that occurs when an SMTP session has been open for a specified
length of time
v Close records, which consolidate SMTP information into a single record when an SMTP session ends

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.

Server that generates

Activity Records generated records
1. User opens mail database Notes Session Open Sending server

Notes Database Open

2. User creates a mail message The following are possible: Sending server

Notes Session Checkpoint

Notes Database Checkpoint

3. User sends message to Mail Deposit plus the following: Sending server
MAIL.BOX
If the message contains an attachment:

Notes Database Open

Notes Database Close

If the message does not contain an attachment:

Notes Database MailDeposit

Chapter 59. Setting Up Activity Logging 1285

 Server that generates
Activity Records generated records
4. User saves message The following are possible: Sending server

Notes Session Checkpoint

Notes Database Checkpoint

5. The Router picks up the Mail Transfer Sending server
message from MAIL.BOX
6. The Router deposits the Mail Deposit plus the following: Receiving server
message in the destination
server’s MAIL.BOX If the message contains an attachment:

Notes Database Open

Notes Database Close

If the message does not contain an attachment:

Notes Database MailDeposit

7. The Router delivers the Mail Delivery Receiving server
message to the user’s mail
database
8. User opens mail database and Notes Database Open Receiving server
reads message

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

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:

1286 Lotus Domino Administrator 7 Help

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

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 Description
Agent For agent activity, shows the user, date, database, agent name, and run time
All Shows the activity type and timestamp of all activity logging records
HTTP For HTTP activity, shows the target server, user name, date, HTTP request, time of the request,
and the length of the content
IMAP For IMAP activity, shows the organization name, server name, user name, timestamp, bytes sent
and received, and the duration
LDAP Add 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
LDAP All For all LDAP activity, shows the organization name, type of activity, user name, and the
timestamp
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 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
LDAP ModifyDN 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)
Mail Processed 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
Notes Database 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
Notes Passthru 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

Chapter 59. Setting Up Activity Logging 1287

View Description
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
POP3 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
Replica For replication activity, shows the date, source server and database name, destination server and
path, and the number of bytes transferred
SMTP Session 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

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.

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:
v To log all the types of activity, skip this step. By default, all activity types are selected.
v 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.
v 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.
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:
v On your local computer, choose File - Database - Open.
v 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.

1288 Lotus Domino Administrator 7 Help

Chapter 60. 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 Frequency
Monitor replication, if a database replicates Daily
Check for and consolidate replication or save conflicts Daily, for large active databases; weekly for other
databases
Monitor database activity Weekly
Monitor database size 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 Frequency
Run the Updall task to update all views and full-text Daily. Occurs by default daily at 2 AM.
indexes
Run the Designer task to keep databases that inherit design Daily. Occurs by default daily at 1 AM.
from master templates 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.
Monitor the database cache Occasionally

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

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:
v View file information
v Manage databases -- for example, compact databases and manage ACLs
v Manage folders and links
v Display disk space information

To customize the Files tab, you can:

v Choose the types of files you see
v Choose the folder contents you see
v Customize the column display

1289
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:
v Databases only -- Displays databases but not templates
v Templates only -- Displays templates and databases that act as templates
v Mail Boxes only-- Displays only MAIL.BOX databases for administrators to quickly open when
monitoring mail
v All database types -- Displays all databases and templates
v All files -- Displays all types of files
v Database links only -- Displays only database links
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:
v Databases
v Templates -- Displays all templates except advanced templates
v Advanced templates -- Displays advanced templates
v Database links
v Mail boxes
v ID files
v Modem files
v Custom -- You can further customize the display by specifying one or more file extensions. Only
those files types display.

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:
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:
v Title
v File name
v Physical Path
v File Format
v Size
v Max Size

1290 Lotus Domino Administrator 7 Help

v Quota
v Warning
v Created
v Last Fixup
v Is Logged
v Template

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:
v To move the column one place to the right, click the up arrow below the box.
v 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 Description

Manage ACL Manages access control lists
Create Replica Creates replicas of databases using the Administration
Process server task
Compact Compacts databases
Full-text index Manages full-text indexes
Multi-Database Index Enables and disables multi-database indexing for
databases
Advanced Properties Set advanced database properties
Note: The Advanced Database Properties are available
only to those administrators listed in the Administrators
field on the Security tab of the Server document.
Quotas Set quotas to limit the size of databases
Move Moves databases using the Administration Process
server task
Sign Signs databases with signatures that can be used for
workstation data security
Replication Enables and disables replication of databases

Chapter 60. Maintaining Databases 1291

Database tool Description
Fixup Fixes corrupted databases
Cluster Manages databases in a cluster
Analyze Runs a database analysis
Find Note Finds a document based on Note ID or UNID and
displays its properties to aid in troubleshooting
Create Db Event Generator Monitors a database based on various criteria
Manage Views Frees space used by view indexes

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:
v New
v New Link
v Update Link
v 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.

Monitoring replication of a database

If there are replicas of a database, you can use any of these methods to monitor replication daily.

Method Description
Replication history Records each successful replication session for a database. Useful for
determining at a glance if a replication is occurring.
Replication Events view of the log file Shows details about replication events between servers. Useful for
(LOG.NSF) determining the cause of replication failure and for verifying that the
expected number of replication updates occurred.
Replication monitor 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.
Database Analysis tool 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.

In addition to ensuring that a database is replicating, you should routinely check for and consolidate
replication and save conflicts.

1292 Lotus Domino Administrator 7 Help

For more information on the Database Analysis tool, see the topic ″Database analysis,″ later in this
chapter.

The database replication history

In the Basics tab of the Database Properties box, there is a button ″replication history,″ which opens the
window of the same name. 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 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.″

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. Click Done when you finish reviewing the history.

Tip: To copy the entire replication history to the Clipboard, click Copy.

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.
v To clear one entry, select it, click Clear, then click Yes.
Chapter 60. Maintaining Databases 1293
 v To clear the entire replication history, click Clear All, then click Yes.
4. 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.

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:
v The document edited and saved the most times becomes the main document; other documents become
Replication or Save Conflict documents.
v 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
v 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.

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:
v 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.
v Specify a Form property for versioning so that edited documents automatically become new
documents.
v Lock documents in a database.
v Use LotusScript to write a custom conflict handler.

1294 Lotus Domino Administrator 7 Help

 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.

The last three are techniques that a system administrator or database manager can use:
v Assign users Author access or lower in the database ACL to prevent users from editing other users’
documents.
v Keep the number of replicas to a minimum.
v 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:
v Copy any information you want to save from the main document into the Replication or Save
Conflict document.
v 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.
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:
v Set database properties that improve performance.
v Create a replica of the database on another server, if possible, one within a server cluster.
v Move the database to a more powerful server.
v Move the database to a disk that is less heavily used, or if it’s a large database, to its own disk.
v 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.

Chapter 60. Maintaining Databases 1295

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
Shows total number of times user and Yes Yes
servers 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 Yes No
0)
Shows names of users and servers who read No Yes
and wrote documents, sorted by date*

* Includes activity for anonymous and authenticated Internet clients.

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:
v Select Notes Log - Database - Sizes
v 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.

1296 Lotus Domino Administrator 7 Help

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.

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.

Replicating unread marks

Unread marks can be replicated for selected databases, most notably mail databases, by using the
advanced database properties from the Domino Administrator or from the database properties box. When
you enable the replication of unread marks on mail databases, users can read their mail from a
workstation on ServerA, and after replication, can read their mail from a workstation on ServerB, with
unread mail clearly delineated from mail that has previously been read. When the replicate unread marks
feature is enabled for a database, the unread marks are replicated along with the database according to
your established replication schedule. This feature is intended primarily for mail databases.

Note: Replicating unread marks in high-activity user databases other than mail databases is not
recommended due to the performance impact.

Synchronizing unread marks before replicating

Before enabling replication of unread marks, ensure that the unread marks in the database and in all of
its replicas are synchronized. If you enable replication of unread marks and the unread marks are not
already synchronized between the database and all of its replicas, those unread marks will not be
synchronized unless you do so manually. Once unread marks are synchronized and the replicate unread
marks feature is enabled, the unread marks remain synchronized.

Use one of these methods to synchronize unread marks:

Chapter 60. Maintaining Databases 1297

v Select the messages whose status you are changing, and then use the Insert key to toggle between read
and unread for any selected messages.
v Select the messages whose status you are changing, and then click Edit - Unread Marks - Mark
Selected Read or Mark Selected Unread.

Enabling replication of unread marks

Note: The Advanced Database Properties are available only to those administrators listed in the
Administrators field on the Security tab of the Server document.
1. From the Domino Administrator, click the Files tab.
2. Select the database(s) for which you are enabling the replication of unread marks.
3. From the Tools pane, click Database - Advanced Properties.
4. Click Select and then click the check box to left of Replicate unread marks.
5. Do one of these:
v To enable replication of unread marks for the selected database(s) across all servers, click All
servers.
v To enable replication of unread marks for any cluster containing a replica of the database, click
Clustered server only.
6. Click OK.

Disabling replication of unread marks

1. From the Domino Administrator, click the Files tab.
2. Select the database(s) for which you are disabling the replication of unread marks.
3. From the Tools pane, click Database - Advanced Properties.
4. Click the ″Select″ check box to the left of Replicate unread marks and then click the Replicate unread
marks check box to remove the check mark from that check box.
5. Click OK.

Enabling or disabling replication for one database directly from the client
If you are enabling or disabling replication of unread marks for one database, you can do so directly
from the client. Open the database for which you are enabling or disabling replication of unread marks.
Choose Files - Database - Properties. Click the tab furthest to the right on the Properties dialog box.
Choose one of the ″Replicate Unread Marks″ settings to enable or disable replication of unread marks.

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:

v The Update task
v The Updall task
v Keyboard shortcuts
v 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.″

1298 Lotus Domino Administrator 7 Help

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. The indexer uses modest system resources by waiting five
seconds between each database update operation that is performs.

The Update task performs three different updating tasks:

v Updates views in the Domino Directory.
v Updates views in all other databases. When a request is made to update a view, the view is only
updated if there are at least 20 note changes since the last update and if the view has been accessed in
the last 7 days. The view update service increases the speed of the view access time when a view is
opened in the Notes client. If views are not updated often, the only effect on users or applications is a
slow view open time because views are automatically updated when opened.
v Updates full-text indexes. Full-text indexing provides the ability to search for notes that have been
recently added. If a note is added after the most recent full-text indexing, that note will not be found
by a full text search.

The Update task uses a separate thread for full-text indexing which makes view updates more timely
than in releases prior to Domino 7.

Update maintains two queues of work -- an immediate queue and a deferrred queue. Other server
components, such as the router and replicator, post requests to the updater when changes are made to
databases. Some requests are posted as deferred and some as immediate.

This table lists how full-text index updates are performed according the update frequency:

Update frequency Description

Daily Performed by the nightly Updall task. If this nightly task
is not run, the daily updating is not performed.
Scheduled Performed by a Program document which runs Updall.
You need to set the frequency to Scheduled and create the
proper Program document. You can also use this method
to update different databases at different times.
Hourly Triggered by the chronos task and performed by the
update task if the update task is running. If the update
task is not running, chronos performs the update. If the
chronos task is not running, the update is not performed.
Immediate Performed by the Update task. If Update is not running,
the update is not performed. All immediate requests are
processed as they are received.
Deferred Deferred requests are held for 15 minutes before they are
processed. Requests to update the same database that
occur in that time are ignored as duplicate requests.

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. Update deletes the view index or full-text index and rebuilds
it.

Chapter 60. Maintaining Databases 1299

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 so that any changes to
the directory are usable as soon as possible. The directory indexer runs against any local or remote
Domino Directory or Extended Directory Catalog that a server uses for directory services. The task of
updating the Domino Directory view indexes does not lock the views, and you should be able to create
new server sessions while this task is running.

To improve view-indexing performance, you can run multiple Update tasks if your server has adequate
CPU power.

Managing the update task and its use of system resources: The indexer is able to keep up with the
update rate in the server’s default configuration if the server has a low update rate, that is, if few
changes are made to databases on the server. If a server has a high update rate due to heavy application
database use, a large number of mail users, or a large volume of mail, the default resource usage
configuration can cause the updater queues to become large. To determine whether the updater queues
are large, examine the queue length statistics that are available in Lotus Domino 7. If you determine that
the update queues are too large, determine a methodology for performing updates on that server. Long
queues typically indicate that views and full-text indexes are not up-to-date.

Here are some sample scenarios and practices that you may want to use as well as the steps to
implement them.
v Scenario one -- The queues are usually short, unless a full-text index starts for a large update volume
database. When this occurs, the view updating requests wait for the full-text index. This causes the
queues to increase until the full-text indexing is complete. To use slightly more system resources to
keep the queues short, perform view updates and full-text index updates in separate threads. To do so,
enter this variable, UPDATE_FULLTEXT_THREAD=1, in your server’s NOTES.INI file.
v Scenario two -- The queues grow slowly over time and become too long because the Updater task is
not getting sufficient system resources to keep the queues short. To use additional resources to keep the
queues short, set a delay between each Update operation. To set the delay, enter these variables,
UPDATE_IDLE_TIME (and FTUPDATE_IDLE_TIME if two threads are used) in the server’s
NOTES.INI file. By default, the delay is 5 seconds. To allow the Update task to use additional system
resources, set the delay to less than 5 seconds. Finer precision may be required on a large server. In
that case, you can set the delay in milliseconds (Domino 7 only) by adding these variables,
UPDATE_IDLE_TIME_MS (and FTUPDATE_IDLE_TIME_MS if two threads are used), to the server’s
NOTES.INI file.
v Scenario -- Servers that have high update rates often require too many system resources to keep the
queues small. In this case, you can decide not to perform view updates at all, and just allow view
opens to perform the updates automatically. Disable the view updates by adding this variable,
UPDATE_DISABLE_VIEWS=1, to the server’s NOTES.INI file. Another option is to limit the number of
immediate updates for full-text databases. You change the update frequency for databases to hourly,
daily, or to a specific schedule. You can also delete extraneous full-text indexes.
To allow frequent full-text indexing on only a small number of databases, and to prevent other
databases from being full-text indexed, disable full -text indexing in the Updater and then add
Program documents to schedule Updall to run, for example, every half hour (30 minutes). To disable
full-text indexing in the Updater, enter this variable, UPDATE_DISABLE_FULLTEXT=1, in the server’s
NOTES.INI file.
You can prevent performing any updates at all, and just allow view opens to perform the view updates
automatically. To prevent updates, edit the NOTES.INI variable by remoinge the update string.
If a system has adequate system resources to perform updates, you can run multiple Update tasks. To
do so, edit the variable, ServerTasks, in the NOTES.INI file and add a second Update task.
You can adjust the controls that determine whether a modified view is actually updated or not. The
database and view must still be opened, but if these thresholds are not reached, the view is not
updated.

1300 Lotus Domino Administrator 7 Help

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.

Note: When views are being rebuilt - either through the Designer or Updall tasks - all new server
sessions that are attempted once the rebuild process has started are locked out. Therefore, it is
recommended that changes to master templates, as well as complete view rebuilds, be scheduled for late
at night, when users are far less likely to require access to the server.

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 Update Updall

When it runs Continually after server startup 2 AM and when you run it
Runs on all databases? No. Runs only on databases that have Yes
changed.
Refreshes views indexes? Yes Yes
Updates full-text indexes? Yes. Updates full-text indexes set for Yes. Updates all full-text indexes.
immediate and hourly updates.
Detects and attempts to Yes Yes
rebuild corrupted view
indexes?
Detects and attempts to Yes Yes
rebuild corrupted full-text
indexes?
Purges deletion stubs? No Yes
Discards unused view No Yes (after a view is unused for 45
indexes? days or according to a view discard
option specified by a designer)
Ignores ″Refresh index″ view Yes Yes
property?
Can customize with options? No Yes

Updall options
You can use any of these methods to run Updall on a server:
v Task - Start tool in the Domino Administrator -- Use this method if you don’t want to use
command-line options.
v 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.
v Program document that runs Updall -- Use this method to schedule Updall to run at particular times.

Chapter 60. Maintaining Databases 1301

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

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 tool Command-line option Description

v Index all databases
v Index only this database or
folder
Update this view only
databasepath ″Only this database″ updates only the specified database.
To update a database in the Domino data folder, enter the
For more information file name, for example, SALES.NSF. To update databases
on databasepath, see in a folder within the data folder, specify the database
the topic ″Using a path relative to the data folder, for example,
console command″ DOC\README.NSF.
later in this chapter.
″Index all databases″ (or no database path) updates all
databases on the server.
database -T viewtitle Updates a specific view in a database. Use, for example,
with -R to solve corruption problems.
Note: -T cannot be used with .IND (indirect) files.

Option in Task - Start tool Command-line option Description

Update: All built views -V Updates built views and does not update full-text indexes.
Update: Full text indexes -F Updates full-text indexes and does not update views.
Update: Full text indexes: Only -H Updates full-text indexes assigned ″Immediate″ as an
those with frequency set to: update frequency.
Immediate
Update: Full text indexes: Only -M Updates full-text indexes assigned ″Immediate″ or
those with frequency set to: ″Hourly″ as an update frequency.
Immediate or Hourly
Update: Full text indexes: Only -L Updates full-text indexes assigned ″Immediate,″ ″Hourly,″
those with frequency set to: or ″Daily″ as an update frequency.
Immediate or Hourly or Daily

1302 Lotus Domino Administrator 7 Help

Updall - Rebuild options:

Option in Task - Start tool Command-line option Description

Rebuild: Full-text indexes only
Rebuild: All used views
Rebuild: Full-text indexes and
additionally: All unused views
-X Rebuilds full-text indexes and does not rebuild views. Use
to rebuild full-text indexes that are corrupted.
-R 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.
database -C Rebuilds unused views and a full-text index in a database.
Requires you to specify a database.

Updall - Search Site options:

Option in Task - Start tool Command-line option Description

Update database -A Incrementally updates search-site database configurations
configurations: Incremental for search site databases.
Update database -B Does a full update of search-site database configurations
configurations: Full for search site databases.

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:
v To customize how Updall runs, click ″Select advanced options,″ click Start Task, specify options to
customize how Updall runs, then click OK.
v 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
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

Specific databases in the Domino Load updall SALES.NSF,DEV.NSF DATA\SALES.NSF
data folder
DATA\DEV.NSF

Chapter 60. Maintaining Databases 1303

To compact Example command Files compacted
All the databases in a folder relative Load updall SALES DATA\SALES\all databases
to the Domino data folder
A specific database in a folder Load updall SALES\USER1.NSF DATA\SALES\USER1.NSF
relative to the Domino data folder
All the files specified in an IND file Load updall WEEKLY.IND DATA\SALES.NSF
created in the Domino data folder
Note: If you are using the -T flag to where WEEKLY.IND contains: DATA\DEV.NSF
specify a view, Indirect files (.IND)
cannot be used. SALES.NSF DATA\SALES\USER1.NSF

DEV.NSF DATA\SALES\NEW\all databases

SALES\USER1.NSF

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 Enter
Program name Updall
Command line Command line options. Don’t specify ″load″ before the options.
Server to run on Server on which to run Updall
Comments Optional comments

For more information on the available command-line options, see the topic ″Updall options,″ earlier in
this chapter.
5. Complete these fields on the Schedule tab:

Field Enter
Enabled/disabled Enabled
Run at times Times to run Updall each day
Repeat interval of How soon to run Updall again after it completes
Days of week 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 Description When to use

F9 Updates the current view To display current information in the view

1304 Lotus Domino Administrator 7 Help

Shortcut Description When to use
SHIFT+ F9 Rebuilds the current view To fix problems with a view
CTRL+SHIFT+F9 Rebuilds all views in a database that To rebuild or update all views if you are unable to run
are not built; updates all other views the Updall task. You must wait until the process is
complete, so use Updall instead if possible.

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:
v Click Edit Configuration to edit an existing Configuration settings document
v Click Add Configuration to create a new Configuration settings document
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

Chapter 60. Maintaining Databases 1305

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

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.

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 run the Designer task against a specific database or folder.

1306 Lotus Domino Administrator 7 Help

Note: When views are being rebuilt - either through the Designer or Updall tasks - all new server
sessions that are attempted once the rebuild process has started are locked out. Therefore, it is
recommended that changes to master templates, as well as complete view rebuilds, be scheduled for late
at night, when users are far less likely to require access to the 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

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.
-f filename Synchronizes a specific database. For example, to synchronize the database
DATA\SALES.NSF, specify -f SALES.NSF.
-i name 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.

The following table shows an example of the -i command line option.

then load design -i SCHEDULE is the

If the file SCHEDULE contains this where same as this
SALES SALES is a directory and load design -d SALES

DEV DEV is a directory load design -d DEV

DEV\USER1.NSF load design -f DEV\USER1.NSF

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.

Chapter 60. Maintaining Databases 1307

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:
v Document NTdocument number in database database name is damaged
v Document document number in database database name has been deleted

The following messages indicate that Domino has rebuilt, is in the process of rebuilding, or was unable to
rebuild damaged views:
v Page format is incorrect
v Invalid CNO vector - position == 0
v 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.
v Run Fixup to fix corrupted views and documents.
v Run Updall to fix corrupted views and full-text indexes; if a corrupted view is the problem, try Updall
before trying Fixup.
v Run Compact with the -c option to fix corruption problems that Fixup doesn’t correct.
v Press SHIFT+F9 to rebuild one view; press CTRL+SHIFT+F9 to rebuild all views in a database.
v 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.

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

1308 Lotus Domino Administrator 7 Help

v 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.
v Run Fixup using a Program document -- Use this method to schedule Fixup to run at particular times.
v 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.
Fixup options
Fixup options in Fixup tool and
Task - Start tool
v Fixup all databases
v Fixup only this database or
folder
Report all processed databases to
log file
Scan only since last fixup
Scan all documents
Perform quick fixup
Exclude views (faster)
Don’t purge corrupted documents
Optimize user unread lists
Command-line equivalent Description
databasepath ″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).
-L Reports to the log file every database that Fixup
opens and checks for corruption. Without this
argument, Fixup logs only actual problems
encountered.
-I When you run Fixup on a specific database, Fixup
checks only documents modified since Fixup last
ran. Without this option, Fixup checks all
documents.
-F When you run Fixup on all databases, Fixup
checks all documents in the databases. Without
this option, Fixup checks only documents
modified since it last ran.
Note: To specify this option using the Fixup tool,
deselect ″Scan only since last fixup.″
-Q Checks documents more quickly but less
thoroughly. Without this option, Fixup checks
documents thoroughly.
-V Prevents Fixup from running on views. This
option reduces the time it takes Fixup to run. Use
if view corruption isn’t a problem.
-N Prevents Fixup from purging corrupted documents
so that the next time Fixup runs or the next time a
user opens the database, Fixup must check the
database again. Use this option to salvage data in
documents if the corruption is minor or if there
are no replicas of the database.
-U Reverts ID tables in a database to the previous
release format. Don’t select this option unless
Customer Support recommends doing so.
Chapter 60. Maintaining Databases 1309
Fixup options in Fixup tool and
Task - Start tool Command-line equivalent Description
Fixup transaction-logged databases -J Runs on databases that are enabled for transaction
logging. Without this option, Fixup generally
doesn’t run on logged databases.

If you are using a certified backup utility, it’s

important that you schedule a full backup of the
database as soon after Fixup finishes as possible.
Fixup open databases -O If you run Fixup on open databases, Fixup takes
the databases offline to perform the fixup.

This is the default if you run Fixup and specify a

Don’t fixup open databases
database name. Without this option, when you do
not specify database names, Fixup does not run on
open databases.
-Z Applies only to running Fixup on a single
database. When a database isn’t taken offline and
is in use, then Fixup is not run.

This is the default when Fixup is run on multiple

Verify only
Fixup subdirectories
Don’t fixup subdirectories
Update this view only
databases.
-C Verifies the integrity of the database and reports
errors. Does not modify the database (for example,
does not purge corrupted documents).
-Y Runs Fixup on databases in subfolders
(subdirectories).
-y Does not run Fixup on databases in subfolders
(subdirectories).
-T Updates a specific view in a database.
Note: You cannot use Indirect (.IND) files with the
database -T viewtitle -T flag to specify a view.

For information on transaction logging, see the chapter ″Transaction Logging and Recovery.″

Running the Fixup task:

Using the Task - Start tool: Use this method primarily to run Fixup on all unlogged databases on a server.
1. From the Domino Administrator, select the server on which to run Fixup.
2. Click the Server - Status tab.
3. In the task panel on the right, click Task - Start.
4. Select Fixup.
5. Do one of the following:
v To specify options to control how Fixup runs, Click ″Select advanced options,″ click Start Task,
select options to customize how Fixup runs, then click OK.
v To run Fixup without options, deselect ″Select advanced options″ and then click Start Task.
For information on the options available, see the topic ″Fixup options″ earlier in this chapter.

Using a console command:

1. From the Domino Administrator, select the server on which to run Fixup.
2. Click the Server - Status tab.
3. Click Console.

1310 Lotus Domino Administrator 7 Help

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 fixup databasepath options
where databasepath specifies the files on which to run Fixup and options are Fixup command-line
options.

The following table illustrates how you can use databasepath to specify databases, folders, and subfolders.

To fixup Example command Files on which Fixup runs

Specific databases in the Domino data Load fixup SALES.NSF,DEV.NSF DATA\SALES.NSF
folder
DATA\DEV.NSF
All the databases in a folder relative Load fixup SALES DATA\SALES\all databases
to the Domino data folder
A specific database in a folder relative Load fixup SALES\USER1.NSF DATA\SALES\USER1.NSF
to the Domino data folder
All the files specified in an .IND file Load fixup WEEKLY.IND DATA\SALES.NSF
created in the Domino data folder
Note: If you are using the -T flag to where WEEKLY.IND contains: DATA\DEV.NSF
specify a view, Indirect files (.IND)
cannot be used. SALES.NSF DATA\SALES\USER1.NSF

DEV.NSF DATA\SALES\NEW\all databases

SALES\USER1.NSF

SALES\NEW

Using a Program document: Use a Program document if you want to schedule Fixup to run at a regular
time.

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. Select Server - Programs and then click Add Program.
4. On the Basics tab, complete these fields:

Field Enter
Program name Fixup
Command line Command line options. Don’t specify ″load″ before the options.
Server to run on Server on which to run Fixup
Comments Optional comments

For more information on the available command-line options, see the topic ″Fixup options″ earlier in
this chapter.
5. On the Schedule tab, complete these fields:

Field Enter
Enabled/disabled Enabled
Run at times Times to run Fixup each day
Repeat interval of How soon to run Fixup again after it completes

Chapter 60. Maintaining Databases 1311

Field Enter
Days of week The days to run Fixup

6. Click Save and Close.

Using the Fixup tool: Use this method to run Fixup on one or a few databases.
1. From the Domino Administrator, select the server that stores the databases you want to run Fixup on.
If the Domino Administrator does not run on a server, you can select local to run Fixup on databases
stored on the client.
2. Click the Files tab.
3. Select the databases on which to run Fixup.
4. In the Tools panel at the right, select Database - Fixup.
5. (Optional) Select options to control how Fixup runs.
For information on the options available, see the topic ″Fixup options″ earlier in this chapter.
6. Click OK.

Moving databases
It may be necessary to move a database from one server to another -- for example, to distribute databases
evenly among servers. If there are replicas of the database, the server to which you move the database
should have the appropriate Connection documents to replicate the database to other servers that store
replicas. If you’re moving a database to a server in a cluster, replication between the server and other
servers in the cluster that have replicas of the database occurs without Connection documents.

Keep in mind that within a cluster, the Cluster Manager distributes workloads and provides failover to
database replicas if one cluster server becomes disabled. Before moving a database in a cluster, you
should analyze the cluster workload to be sure it will remain balanced after you move the database. Only
the person who administers the cluster should perform the move.

For more information on clusters, see the book Administering Domino Clusters.

You can use any of these methods to move a database:

v Use the Domino Administrator and the Administration Process to move the database.
v Manually move the database. Use this option when you do not have access to the Domino
Administrator and the Administration Process.

Moving databases using the Administration Process

This feature isn’t intended for moving mail files.

For information on moving mail files, see the chapter ″Setting Up and Managing Notes Users.″
1. Make sure the source and destination servers are running the Administration Process.
2. Make sure that you have Create Database access in the Server document of the destination server
and at least Manager with ″Delete documents″ access in the ACL of the databases on the source
server.
3. Make sure that the source server (or another server that replicates with the source server and has a
replica of the database) has Create Replica access in the ACL of the destination server.
4. Make sure the destination server has at least Reader access in the ACL of the replica on the source
server.
For information on specifying server access in an ACL, see the chapter ″Creating Replicas and
Scheduling Replication.″ For information on using a Server document to set ″Create replica
databases″ access, see the chapter ″Controlling Access to Domino Servers.″

1312 Lotus Domino Administrator 7 Help

 5. From the Domino Administrator, in the server pane on the left, select the server that stores the
databases you want to move. To expand the pane, click the Servers icon.
6. Click the Files tab.
7. In the files pane, select one or more databases to move.
8. In the Tools pane on the right, select Database - Move. Or drag the selected database(s) to the Move
tool.
9. (Optional) If the current domain includes a cluster, click ″Show only cluster members″ to display
only destination servers that are members of the cluster.
10. Select one or more destination servers. To select a server that doesn’t appear in the list, click Other,
specify the hierarchical server name, then click OK.
11. (Optional) Select a destination server, click ″File Names″ to choose a custom file path on the
destination server for any database you’re moving and then click OK. You can repeat this procedure
for each destination server. If you don’t choose this option, the database is stored on the destination
server in the same location as on the source server.
To move a database to a folder below the data folder, type the folder name, backslash, and then the
file name -- for example, JOBS\POSTINGS. If the specified folder does not exist, Domino creates it
for you.
12. Click OK. A dialog box shows the number of databases processed and indicates if any errors
occurred. See the status bar for more information.
13. If the source server is not a cluster server, you must approve the deletion of each original source
database after the Administration Process completes the ″Non Cluster Move Replica″ request, which
creates a replica at the new location. To do this:
a. Make sure you have Editor access to the Administration Requests database (ADMIN4.NSF).
b. Open the Administration Requests database.
c. Select the Pending Administrator Approval view.
d. Open the ″Approve Deletion of Moved Replica″ request for each source database that you
moved, click Edit Document, click Approve File Deletion, click Yes, and then click Save and
Close.
14. Notify users that you’ve moved the database.

Moving databases by dragging them to a destination server: Rather than choosing Database - Move,
you can drag databases to a destination server. When you use this method, you must store all databases
in one preexisting folder on the destination server. This method also uses the Administration Process to
automate moving the database. You can’t use this method to move a database to another Domino
domain.
1. From the Domino Administrator, click the Files tab.
2. In the files pane, select one or more databases to move.
3. Press Ctrl and drag the selected databases to a destination server in the server pane on the left.
4. In the dialog box that appears, select ″Move database,″ select a folder on the destination server in
which to store the database(s), then click OK.

Moving a database without using the Administration Process

Use this procedure to move a database to a server in another Domino domain or to move a database
when you don’t have access to the Domino Administrator. Do not use this procedure to move a mail file.

For information on moving mail files, see the chapter ″Setting Up and Managing Notes Users.″
1. Make sure that you have Create Replica access in the Server document of the destination server.
2. Make sure you have Manager with ″Delete documents″ access in the ACL of the original database.
3. Choose File - Replication - New Replica to create a replica of the database on the destination server.
4. Make a note of the file name and path of the original database. You’ll include this information when
you notify users of the move.

Chapter 60. Maintaining Databases 1313

5. Choose File - Database - Delete to delete the original database.
6. If the database receives mail, change the Mail-In Database document in the Domino Directory to
reflect the new location.
7. In the ACLs of any replicas of the database, remove the name of the server that you moved the
database from and add the name of the destination server.
8. Notify users that you have moved the database.

Converting non-mail databases

You can use the server’s mail convert utility to convert non-mail databases to another type of non-mail
database. Non-mail databases are all databases that do not have a $Inbox folder. Use the convert utility
with the -d switch to prevent the conversion process from creating new folders for each category in the
databases you are converting.

When the load convert task is used without a switch, folders are created for all categories within the
database. The load convert task looks for a $inbox, if there is no $Inbox, it processes the categories as
views.

Enter the load convert -d task from the Domino server command line as follows:
load convert -d databasename * newtemplatename
v Where databasename * is the name of the database you are converting (includes all documents in that
database).
v Where newtemplatename is the name of the template that creates the type of database to which you
are converting the non-mail database.

You can also convert an entire directory as shown in this example,

load convert -d doclibrary\ *.nsf newtemplatename
v Where doclibrary\ *.nsf represents the name of the directory being converted and all databases in that
directory.
v Where newtemplatename is the name of the template that creates the type of database to which you
are converting all databases in the named directory.

Deleting databases
To keep a server performing efficiently and to free disk space, delete databases that are no longer active.
To delete databases from a cluster server, you use the Cluster database tool in the Domino Administrator.
To delete databases on non-cluster servers, select the databases and delete them manually, or use the
Delete database tool in the Domino Administrator to have the Administration Process deletes replicas of
the database.

Within a cluster of servers, you create a number of replicas for each database to ensure user access to an
updated replica even if a particular cluster server becomes unavailable. You can mark a cluster replica for
deletion while users are working with the replica. Domino then prevents new users from accessing the
marked replica and deletes the database after all current users exit the database. Before deleting the
database, Domino replicates any changes to other replicas in the cluster.

For more information on clusters, see the book Administering Domino Clusters.

Deleting a replica in a cluster

1. Make sure you have Manager access in the database ACL.
2. From the Domino Administrator, select the server that stores the replicas you want to delete.
3. Click the Files tab.
4. Select the folder containing the replicas you want to delete.
5. In the files window, select the replicas you want to delete.

1314 Lotus Domino Administrator 7 Help

6. In the Tools pane on the right, select Database - Cluster. Or drag the selected replicas to the Cluster
tool.
7. Select ″Pending delete.″
8. Click OK to mark the database for deletion.

Deleting a non-cluster database and its replicas using the Administration Process
1. Make sure you have Manager access in the database ACL.
2. From the Domino Administrator, select the server that stores the database you want to delete.
3. Click the Files tab.
4. Select the database to delete.
5. Click Database - Delete
6. (Optional) Select ″Also delete replicas of this database on all other servers″ if you want the
Administration Process to delete other replicas.
7. Click OK.

Deleting a non-cluster database manually

1. Make sure that you have Manager access in the database ACL.
2. Notify users of the impending deletion and the reason for it.
3. If there are no replicas of the database, make an archive copy of it.
4. Record the file name and path of the original database. This allows you to replace the deleted
database with a new database that notifies users that the original database has been deleted.
5. Select the database icon.
6. Select File - Database - Delete.
7. (Optional) Select ″Delete all replicas of this database.″
8. Click Yes to confirm the deletion.
9. Delete any Mail-In Database documents associated with the deleted database.
10. Remove references to the database in database libraries and bookmarks.
11. Notify users that you have deleted the database.

Archiving an obsolete database

v If users occasionally need to access the database, keep the archive copy on a Domino server. If no
access or very little access is required, copy the database to a file server or optical disk.
v In the database ACL of the archive copy, assign Manager access to at least two users and assign Reader
access to all other users.
v Indicate in the database title and in the About This Database document that the database is an archive
copy.
v Notify users of the location of the archive copy.

Database analysis
You can perform a database analysis to collect information about one or more databases from a variety of
sources -- the replication history, the User Activity dialog box, and the log file (LOG.NSF) -- and view it
in a single ″results″ database. You can perform a database analysis only if you have access to the Domino
Administrator.

Use database analysis to collect the following information about a database:

v Replication history, as recorded in the Replication History dialog box
v User reads and writes, as recorded in the User Activity dialog box
v Document creations, edits, and deletions, as recorded in a database
v Design changes, as recorded in a database

Chapter 60. Maintaining Databases 1315

v Replication additions, updates, and deletions, as reported in the log file (LOG.NSF)
v Mail messages delivered by the mail Router

You can collect this information from multiple replicas of a database.

The results database

When you perform a database analysis, you create a database that holds the results, which are stored in
analysis documents. After you create a results database, each time you perform a database analysis, you
can choose to overwrite its contents or append new results to its contents. The results database is created
from the Database Analysis (DBA4.NTF) template.

Analysis documents
Each analysis document in the results database contains fields that describe a particular event.

Field Describes
Date Date of the event
Time Time of event
Source of Event Information The analyzed database or its replicas or the log file (LOG.NSF)
Source Database Name of a database containing documents that were read

For database replication events, name of database from which information

was pulled
Source Name of server that stores a database containing documents that were read
or written

For database replication events, name of server that stores the database from
which information was pulled
Destination Name of a database on which documents were updated

For database replication, name of the database to which information was

replicated
Destination machine Name of a server that stores a database that was updated

For database replication, name of a server that stores a database to which

information is replicated
Description Description of the event

Analysis documents describe these types of events:

Event Describes Required database analysis option

Activity Number of user or server reads and writes User reads
generated by the Statlog task
User writes
+Activity Number of user reads and writes as noted in the Log file activity
database and in the log file
User reads or User writes
Mail Router Number of documents delivered to the database User writes
Data Note Document creations, edits, and deletions Changes to documents
Design Note Changes to the database ACL and design Changes to design
Replicator Replication history Replication history
+Replicator Number of replication additions, updates, and Log file activity
deletions, as reported in the log file (LOG.NSF)

1316 Lotus Domino Administrator 7 Help

Running a database analysis
1. From the Domino Administrator, select the server that stores the databases you want to analyze.
2. Click the Files tab.
3. Select the folder containing the databases you want to analyze.
4. In the files window, select the databases you want to analyze.
5. In the Tools pane on the right, select Database - Analyze. Or drag the selected database(s) to the
Analyze tool.
6. In the ″Analyze last x days of activity″ field, enter a number that represents how many days’ worth
of information to report. You can specify up to 99; the higher the number, the longer it takes to
generate the results.
7. Select one or more of the remaining options from the following table.
8. Click Results, do one of the following, then click OK.
v Specify the server, title, and file name of the database where you want to store the results. It’s
recommended that you create the results database on a local client rather than on a server. If
multiple people generate results databases on a server, they should each specify a different file
name so the results don’t conflict.
v If the specified results database already exists, click ″Overwrite database″ to write over the
existing contents or click ″Append to this database″ to add the new results to existing ones.
9. Click OK to run the analysis.
10. To see the results, open the database and choose one of the available views.
11. Open Database Analysis Results documents in the selected view.

Database analysis options

Option Reports
Changes in: Data documents Details of document additions, edits, and deletions
Changes in: Design documents Changes to the database ACL and design
User activity: User reads Total times users opened documents in the database

Total times servers read documents

User activity: User writes Total times users and servers created, modified, or deleted
documents

Total number of mail messages delivered to the database

Replication: Find replicas on other servers
Replication: Replication history
In logfile: Miscellaneous Events view
In logfile: Database usage view
Data for other replicas
Successful replications of a database as reported in the
database replication history
Events relating to this database, as recorded in the
Miscellaneous Events view of the log file
Database activity, as recorded in the Usage - By User view of
log file

Chapter 60. Maintaining Databases 1317

1318 Lotus Domino Administrator 7 Help
Chapter 61. Maintaining Domino Servers
This chapter describes how to manage your existing Domino servers. It includes information on
recertifying a server, deleting a server name and decommissioning servers as well as other server-related
activities.

Changing the server administrator

If the name of the former administrator is explicitly listed in the access control list (ACL) for the Domino
Directory, delete the name of the former administrator from the ACL. Add the name of the new
administrator and assign the administrator Manager access.

For more information on modifying ACLs, see the chapter ″Controlling User Access to Domino
Databases.″

If the name of the former administrator is included in any groups, delete the former administrator’s name
from the Group document(s), if appropriate. Add the name of the new administrator.
1. From the Domino Administrator, select the Configuration tab.
2. Click Server, and then select one:
v Current Server Document -- to change the administrator name for the current server.
v All Server Documents -- and then select the server document you want to change.
3. Click ″Edit Server.″
4. Click the Administration tab.
5. In the Administrator field, type the administrator’s name or click the arrow and complete the
following fields as necessary in the Select Names dialog box:

Field Action
Choose address book Select the address book and choose a name from the list.
Click one of the following:
v Add -- to add the name to the Names list.
v Details -- to view address details from the Person
document
Find names starting with (Optional) Enter a user name, last name followed by first
name, to search for a name if you are unsure of the
spelling or the complete name.
Add name not in list Enter a user name and then click Add to add the name
to the Names list without selecting it from an address
book.
Names (Optional) Do one:
v Select a name and then click Remove to remove the
selected name from the Administrator field.
v Don’t select any names. Click Remove all to remove all
names from the Administrator field.
Select a name and click to copy a name from the open
address book to the local address book.

6. Click OK, and then click ″Save & Close″ in the Server document.
7. Use the Replicate server command at the console to force replication of the Domino Directory and
disseminate the change quickly.

1319
 For more information on the Replicate command, see the appendix ″Server Commands.″

Setting and managing passwords for the server console

Use server console passwords to protect against unauthorized use of the server console.

Setting a new server console password

1. Enter a new password in the ″Console password″ field.
2. Re-enter the same password in the ″Verify″ field.
3. Choose Set.
4. Click OK.

Changing an existing server console password

1. Click Change. The Change Console Password dialog box appears.
2. Enter the current password.
3. Enter the new password.
4. Re-enter the new password.
5. Click OK.
6. Exit out of the Secure Console dialog box by clicking Cancel.

Removing a server console password

1. Enter the current password
2. Click Clear.
3. Click OK.

Decommissioning a Domain Search server

If you want the server that creates full-text indexes of the Domino domain to resume duty as a regular
Domino server, remove it from the appropriate group in the Domino Directory, edit its Server document,
and then delete some files from its directory structure.

To decommission a Domain Search server

1. From the Domino Administrator, click the Files tab.
2. Open the Domino Directory (NAMES.NSF), and then click Groups.
3. Select LocalDomainCatalogServers and click ″Edit Group.″
4. On the Basics tab, in the Members field, remove the indexing server you want to decommission.
5. Click ″Save and Close.″
6. Expand the Servers section in the view pane, and then click Servers.
7. Select the server that you want to decommission, and click ″Edit Server.″
8. Click the Server Tasks - Domain Catalog tab.
9. In the Domain Catalog field, select Disabled and click OK.
Disabling the Domain Catalog automatically disables the Domain Indexer schedule on the next tab.
10. Click ″Save and Close.″
11. Delete the Domain Catalog (CATALOG.NSF) from the server.
12. Delete the FTDOMAIN.DI subdirectory from the server’s Domino data directory.

Note: Users’ Location documents can be automatically updated with the name of your new indexing
server if you include the new server in your desktop policy settings.

1320 Lotus Domino Administrator 7 Help

For more information on policy settings documents, see the chapter ″Using Policies.″

Decommissioning a server
You use the Decommission Server Analysis tool when you are consolidating existing servers and/or
permanently removing a server from service. Whether you are combining two servers into one server or
renaming a server, the result is the same -- the old server name is replaced with the new server name.
The analysis tool can help you avoid a loss of service for your Domino server and can be used to help
build a foundation for a decommission ″to do″ checklist. The role of the Server Analysis Tool is to
compare the responsibility of the source server to that of the target server and to report differences that
could cause a possible loss of service.

When you run the Decommission Server Analysis tool, you create a Results database containing detailed
information comparing the source server and the target server. The source server is the server being
removed from service, and the target server is the server taking the place of the source server. The source
and the target servers must be Domino servers that have hierarchical names and that are in the same
domain.

Inconsistencies between the source and target servers are marked in the Results database to alert you to
the administrative tasks you may need to do before you can decommission the server. Each comparison
that the Decommission Server Analysis tool makes is somewhat individual. Relationships between
analysis items are not determined by this tool; therefore, you need to review each report and make your
own comparisons before taking any action. Perform comparisons between only two servers at a time. You
do not need to resolve all differences before you decommission a server.

Before decommissioning a server

Before decommissioning a server, you may need to perform the following types of administrative
activities:
v Check each database for formulas that contain specific server name references.
v Update the documents in the Domino Directory, such as the Connection and Program documents, to
reflect the new server name.
v If the old server had cross-certificates, make sure the new server has the same cross-certificates.
v Notify other domains that access the server about the change.
v Inform users about the new location for databases, including their mail database, if necessary.
v Make sure the network protocols on the old and new servers match.
v Replicate all the databases from the old server to the new server.
v Update mail routing tables to ensure that mail gets delivered correctly.

To run an analysis report on Decommission Server

1. To use the Decommission Server Analysis Tool, you must have administrator access to both the source
and the target servers.
If you don’t have administrator rights, some portions of the report may not be completed properly.
2. From the Domino Administrator, click the Server - Analysis tab.
3. From the tools pane, select Analyze - Decommission Server.
4. Complete these fields:

Field Enter
Source server Name of the server being decommissioned
Target server Name of the server that will replace the server being decommissioned

Chapter 61. Maintaining Domino Servers 1321

Field
Results database
Append to this database
Overwrite this database
Enter
Name and/or location of the Results database if you are not using the default
file name DECOMSRV.NSF. Complete these fields:
v Server
v Title
v File Name
v Folder
(Default) Adds the new report to the end of the existing information in the
Results database without deleting any existing data
Adds the new Results database by overwriting the existing database

5. Click OK.
When the analysis is complete, the Results database opens to the Reports view. This can take up to
several minutes depending on network traffic and the number of databases on both the source and
target servers.

Note: You can create multiple reports in the same database or in different databases and then use these
reports to verify that differences between the two servers are remedied and cannot be seen by the system
when you run the Decommission Server Analysis tool. You can re-run the reports as many times as you
wish.

Viewing the report in the Results database

The Decommission Server Analysis tool generates a categorized list of items that were analyzed. Each
category represents a different aspect of a server’s configuration that needs attention. Within each
category, items are listed alphabetically. Each item lists any differences between the source and the target
server’s settings or values. In the Results database, you can view the categorized list of the items that
were analyzed.

1322 Lotus Domino Administrator 7 Help

Each item is represented by a document. A document’s status is indicated by an icon to the left of the
document as follows:

Icon Explanation
A difference was found when doing the comparisons and may require the
attention of an administrator.
An error was encountered when performing or trying to perform a
comparison.
No icon No attention is required because the fields being compared are either
equivalent or the source’s values are a complete subset of the target’s
values.

Click a document to open it and view the actual report that was generated. A sample report is shown
here:

Report Field Description

Report category The section or category that the document belongs to. These categories are:
Certificates, Cluster, Connections, Databases, Domains, Internet, Miscellaneous,
Network, Programs, Security, SMTP, and Router.
Report title The specific field or item that is being analyzed -- for example, Databases -- Mail
Users or Databases -- No Matching Replica.
Report date Date the report is generated.
Server to be decommissioned Name of the server being retired.
(source server)
Server to accept responsibility Name of the server that will assume the responsibilities of the server being
(target server) decommissioned.

Chapter 61. Maintaining Domino Servers 1323

Report Field Description
Errors Errors that occur during the analysis on this item or field. This field is blank if
there are no errors.
Report details Information that indicates the problem or inconsistency that exists between the
source and target servers.

Report comparisons
The following types of field comparisons are done between the two Server documents and the
Configuration documents:

Field Comparison Explanation

Boolean The content of the two fields being compared must be an exact match. In some
cases, if the field on the source server is not set, no comparison is done with the
value for the target server.
Numeric The two fields are compared and differences are reported.
Text list Two text lists are compared and a report is generated if the source is not a
complete subset of the target.
Name list Two names lists are compared by expanding both lists to single entries, removing
duplicates, and generating a report if the source is not a complete subset of the
target. When expanding names lists, all groups are expanded until only single
entries remain.
Special cases In some cases, a blank field has a special meaning. In these cases, the specific
interpretation of blank for each field is taken into consideration when
comparisons are performed.

Comparisons are made to the following documents:

Document comparison Explanation

Connection documents
A comparison is performed on any connection in which the server to be
decommissioned is listed as the source server in the Connection document. The
comparison ensures that all destination servers in those connections are also
included in the target server’s Connection documents. A report is generated if
the Tasks differ or if any corresponding connections do not exist.

All connections listing the server to be decommissioned as the Destination

server are reported.
Program documents All Program documents that list the source server as the server on which to run
the program are included in the report. No comparison between the source and
target Program documents is done because there is no way to ensure that the
executables exist or are the same on the source and target.
Domain documents All Foreign domain documents are checked to see if the Gateway server name
lists the source server. If one is found, a document is generated showing which
foreign domain documents list the source.
Cross-Certificates Any cross-certificate that lists the source server in the Issued By field is
reported.

These comparisons are made to databases:

Database comparison Explanation

Mail-in databases, Rooms, Resources, Each document that lists the source server as the Mail server is reported.
Certifiers, Person documents

1324 Lotus Domino Administrator 7 Help

Database comparison Explanation
Replicas Any database on the source server that does not have a matching replica on
the target server is reported.

A file name comparison for all databases that do not have replicas on the
target is done. Any database on the source that has a name conflict with a
different database with the same name on the target is listed.

These comparisons are made to networks:

Network comparison Explanation

Enabled ports A comparison is done for both port name and protocol. A report is
generated for any differences.
Notes named networks If the source and target servers do not share the same Notes named
networks, a report is generated.

Deleting a server name

Follow these steps to use the Administration Process to delete references to a server from the Domino
Directory and from database ACLs and Extended ACLs. The Administration Process automatically deletes
mail-in database documents and cross-certificate documents as necessary during the Delete Server
process.

For more information on the Administration Process, see the chapter ″Setting Up the Administration
Process.″
1. To delete a server name, you must have:
v At least Author with Delete documents role and the ServerModifier privilege, or Editor access to
the Domino Directory.
2. From the Domino Administrator, click the Configuration tab.
3. Click Server - All Server Documents.
4. Select the server name you are deleting and click Delete Server.
5. Do one of these:
v Click the check box ″Delete servers from Domino Directory immediately″ to immediately remove
the server name from the Domino Directory, and post Administration Requests to remove the
server name from ACLs, Names fields, and other locations.
v Leave the check box ″Delete servers from Domino Directory immediately″ not selected, to create
Administration Requests to remove the server name from the Domino Directory, ACLs, Names
fields, and all other locations.
6. Click OK.
For information on removing a server from service and replacing it with another server, see the topic
″Decommissioning a server″ in this chapter.

Finding a server name in the domain with the Domino Administrator or

the Web Administrator
You can search for a server name in the domain and then view a log that includes document links and
directory links to each occurrence of the server name.
1. From the Domino Administrator or the Web Administrator, click the Server - Analysis tab.
2. From the Tools pane, click Analyze - Find Server.
3. Do one of these:

Chapter 61. Maintaining Domino Servers 1325

 v From the Domino Administrator, select a server name from the list box, and click OK.
v From the Web Administrator, enter a server name and click Send.
4. One of these occurs:
v On the Domino Administrator, a message appears indicating that an administration request will be
initiated to search the enterprise for the server name. Click Yes.
v On the Web Administrator, the status line displays a message indicating that an administration
request has been generated to locate the server name. Click Done or enter another server name and
repeat the process.

To view the log of locations

1. To view the log of locations where the server name has been located, from the same view, click
Administration Requests(R6).
2. Click All Requests by Name.
3. Locate the server name you are looking for.
4. Expand the section and locate the Find Name in Domain request.
5. Open the request. View the documents that contain that server name in the ″Links to items found
within Domino Directory documents″ field. View the database ACLs that contain that server name in
the ″Links to item found in Database ACLs″ field.
6. Click Cancel to close the Response Log document.
For more information on using the Web Administrator, see the chapter ″Setting Up and Using Domino
Administration Tools.″

Recertifying a server ID
Follow this procedure to use the original certifier to recertify a server ID that has a certificate that is
about to expire.
1. To recertify a server ID, you must have:
v Author with Create documents access and the ServerModifier role, or Editor access to the Domino
Directory
v At least Author with Create documents access to the Certification Log
2. From the Domino Administrator, click the Configuration tab, and then click Server - All Server
Documents.
3. Select the server you are recertifying.
4. Choose Actions - Recertify Selected Servers.
5. Choose one:
v Click Supply certifier ID and password -- if you want to use a certifier ID and password instead of
the new server-based certification authority (CA). To change to a different certifier ID, click
Certifier ID, select the new ID, enter the password, and then click OK.
v Use the CA Process -- Click to use the Domino server-based certification authority (CA) to
recertify the server ID. Choose a CA-configured certifier from the list.
6. Accept the default certificate expiration date (two years from the current date), or enter a different
date.
7. (Optional) Enter a date in the field ″Only renew certificates that will expire before″ if you want to
limit which server IDs can be recertified.
8. (Optional) Click the check box ″Inspect each entry before submitting request″ if you want to view
the server ID before finalizing the recertification.
9. Click OK.
10. Select one of the following:
v OK -- to submit the recertification.

1326 Lotus Domino Administrator 7 Help

 v Skip -- if you are recertifying more than one server ID and you want to continue to the next server
ID without submitting a recertification for the current server ID.
v Cancel Remaining Entries -- to cancel this server recertification and recertifications for any other
server names you selected and have not yet submitted.
11. Review the processing statistics that appear and then click OK.

Note: You can use the @Certificate function to create a custom view of specific IDs for recertification
based on the ID name, issuer of the certificate, and expiration date. If you create a custom view, be sure
to include the Recertify Servers or an equivalent action in the Actions menu of the view.

For more information on the @Certificate function, see the Domino Designer Programming Guide.

Uninstalling a Domino partitioned server

You can remove all server partitions from a computer or you can remove just one server partition.

To remove all Domino partitions on a computer

To remove all server partitions from a computer, complete these steps:
1. Run the Uninstall program that comes with your operating system.
2. Delete the Domino data directories for those partitions.

To remove one Domino partition

1. Save any files you want, and then delete the Domino data directory for the partition that you want to
uninstall.
2. If the Domino partition used a unique IP address, disable support for the IP address. Do this only if
you added the IP address when you set up the partition. If the Domino partition used the computer
host name as its Domino server name, do not disable its IP address.
3. If the partitioned server used port mapping, edit the NOTES.INI file of the port-mapping partition so
that it no longer refers to the Domino partition you want to remove. If you are uninstalling the
port-mapping partition, set up another Domino partition to do the port-mapping.

Upgrading a server name to hierarchical

Use this procedure to upgrade a flat server name to a hierarchical server name. After upgrading a server
name to a hierarchical name, the server cannot be renamed.
1. From the Domino Administrator, Server view, select the server you are upgrading.
2. Choose Actions - Upgrade server to hierarchical.
3. Choose the new certifier ID.
4. Enter the password for the certifier ID and click OK.
5. (Optional) Enter the qualifying organizational unit.
6. Accept or change the certification ID expiration date.
7. Click Upgrade and then click OK.

Chapter 61. Maintaining Domino Servers 1327

1328 Lotus Domino Administrator 7 Help
Chapter 62. Using Activity Trends
This chapter describes Domino’s Activity Trends feature and explains how you use it to analyze resource
distribution and balance resources.

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.

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

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.

The Domino Change Manager provides workflow capability that creates resource-balancing plans and
implements database moves.The Domino Change Control database (DOMCHANGE.NSF) and Domino
Change Manager are part of the Domino server core functionality.

Activity Trends includes:

v Server profile definition -- For easy access to a named group of servers.
v Statistics profile creation -- For easy access to a named group of statistics.
v Activity trends charting -- You can chart a selected group of statistics for a single server or a group of
servers.
v Resource balancing -- Analyzes server resource use and creates recommendations for balancing the
servers based on specified resource goals.

Activity Trends uses these Domino server features:

v Activity logging -- To collect information that will be used for resource-balancing.
v Activity Trends -- To set up times for data collection and retention.
v Domino Change Manager -- To implement a workflow process in which changes made to the system
are controlled and approved.

1329
Setting up Activity Trends
The basic setup for Activity Trends includes these tasks:
1. 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.
2. 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 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.
3. Click the Activity Logging tab, and check ″Activity logging is enabled.″
4. Under Server Activity Logging Configuration, complete these fields:

Field Action
Enabled logging types 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 Check Yes to log ongoing session activity at midnight. This is required for Activity
Midnight Trends.

You must enable this field to enable Activity Logging.

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 Action
Enable activity trends collector Click yes to run the Activity Trends Collector.

Activity Trends Collector uses the raw data from activity

Activity trends collector database path
Time of day to run activity trends collector
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.

1330 Lotus Domino Administrator 7 Help

Field Action
Days of the week to collect observations Select the days for which you want to collect
observations. The default is Monday through Friday.

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 Action
Trends cardinal interval Enter the number of recent observations you want to use.
The default is 10.

When computing trended values, recent observations are

Observation time bucket (seconds)
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.
Specify the time in seconds for one bucket. The default is
300.

The observation time controls how many buckets you will

have for one 24-hour observation period.
Maximum observation list time 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.
Trends history interval Choose one:
v Daily
v Weekly (default)
v Monthly
v Trend Interval

7. Click the Retention tab. Keep the ″Use defaults″ field enabled. Documents are overwritten after the
retention period expires. The defaults are:
v Server history -- 366 days
v Server observations --15 days
v Database observations -- 10 days
v User observations -- 10 days
v Connection observations -- 10 days
v Inactive database trends -- 10 days
v Inactive user trends -- 28 days
v Inactive connection trends -- 28 days
v Run log -- 20 days
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.
Chapter 62. Using Activity Trends 1331
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.

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:

v Creating an Activity Trends statistics profile
v 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:

1332 Lotus Domino Administrator 7 Help

1. From the Domino Administrator, click the Server - Performance tab, expand the Activity Trends
section, and do one:
v Select a view in the Latest folder or Historical folder
v 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:
v Click Existing Server, and select from the list of available servers.
v Click Phantom (Resource Balancing only), and enter a name for the phantom server.
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.

Trends server profile

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:
v Click Existing Server, and then select from the list of available servers.
v 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:
v Click Save As, and enter a new profile name.
v Click Save to update the existing profile.

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.

Chapter 62. Using Activity Trends 1333

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 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:
v Select a view in the Latest folder or Historical folder
v 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:
v Click Existing Server, and select from the list of available servers.
v Click Phantom (Resource Balancing only), and enter a name for the phantom server.
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 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:
v Click Save As, and enter a new profile name.
v 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.

1334 Lotus Domino Administrator 7 Help

3. Select the statistic you want to remove, and click the red minus sign.
4. Click the document icon, and do one:
v Click Save As, and enter a new profile name.
v Click Save to update the existing profile.

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.

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:
v Latest folder - Server -- To view the set of data available for selected statistics on each selected
server.
v Latest folder - Database -- To view the databases on each selected server.
v Latest folder - User -- To view the users statistics for all databases on the selected servers.
v Latest folder - Connection -- To view information for a selected statistic from either the User or
Database charts.
v Historical folder -- Weekly
v 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.
v Source Only -- These servers cannot have any databases moved to them.
v Destination Only -- These servers cannot have any databases removed from them. A phantom server is
a Destination Only server and cannot be changed.
v Any -- These servers can have databases moved to or from them.

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.
Chapter 62. Using Activity Trends 1335
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

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:
v Search Local Activity Databases -- To search the Activity databases (ACTIVITY.NSF) on each server
on which Activity Trends is enabled.
v 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:
v 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.
v 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.
v Use Defaults -- To revert to previously stored custom defaults.
v Save as Defaults -- To save a custom set of defaults and override the system defaults.
v 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:

To set chart options:

1336 Lotus Domino Administrator 7 Help

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 Font Size Appearance

Chart Heading Font Default Sans Serif 12.00 Bold
Chart Axis Label Font Default Sans Serif 8.00 Plain
ChartLegend Font (when visible) Default Sans serif 8.00 Plain

5. Under Resource Balancing Display Options, check Yes to enable these options for Resource Balancing
view. The default is unchecked.
v Show actual values on Y-axis when displaying non-normalized data
v 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.
v Show actual values on Y-axis
v Show chart using 3D effect
8. Choose one of the following to set Charting defaults:
v Use Defaults -- To revert to previously saved custom defaults.
v Save as Defaults -- To save a custom set of defaults and override the system defaults.
v Reset Defaults -- To revert to the system defaults.

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.

Chapter 62. Using Activity Trends 1337

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 Description

AvgSpaceUsed Percentage of the disk space actually in use, as recorded by the
database activity data.
DiskSpace The number of bytes of disk space occupied by the database, as
recorded by the database activity data.
FullTextIndexSize Size of the full-text index for this database.
HTTP BytesFromServer The number of bytes sent from the database, as recorded by the user
session data.
HTTP BytesToServer The number of bytes sent to the database, as recorded by the user
session data.
HTTP RequestMsecs Request time, in milliseconds.
HTTP Requests The number of HTTP requests.
Notes BytesFromServer The number of bytes sent from the server, as recorded by the user
session data.
Notes BytesToServer The number of bytes sent to the server, as recorded by the user session
data.
Notes Connects The number of database connections, as recorded by the user session
data.
Notes DocumentsRead The database read count, as recorded by the database activity data.
Notes DocumentsWritten The database write count, as recorded by the database activity data.
Notes Transactions The number of transactions, as recorded by the user session data.
Replica BytesRead The number of bytes read, as recorded by the Replicator task.
Replica BytesWritten The number of bytes written, as recorded by the Replicator task.
Users 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.
4. Expand the Balancing section, and then click Goals.

1338 Lotus Domino Administrator 7 Help

5. Complete these fields to specify the primary goal:

Field Action
Statistic Name Select a statistic from the list. The default is Notes Transactions.
Tolerance Enter a percentage. The default is 10%.
Analyze Choose one:
v Trended Data (default) -- To analyze the resource balance based on trended
data.
v 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:
v Complete Day (24 hours) -- To analyze data gathered during a 24-hour
period.
v 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.
v Use Defaults -- To revert to previously saved custom defaults.
v Save as Defaults -- To save a custom set of defaults and override the system defaults.
v 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.

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.

Chapter 62. Using Activity Trends 1339

You can open the Server Profile Options dialog box from the Resource Balancing menu, or by clicking the
Server Profile Options button.

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:
v Pin listed databases -- To pin the listed databases so that they will not be moved.
v 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.
8. Next to the list of database names, do one:
v Choose Reset to return the list to its original set of databases.
v Choose Save as, and enter a name to save a new pin list.
9. Choose one:
v Use Defaults -- To revert to previously saved custom defaults.
v Save as Defaults -- To save a custom set of defaults and override the system defaults.
v 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:
v Edit the list of databases, and then click Save.
v 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:

v Light -- The top bin when graphed, has the lightest amount of activity.
v 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.
v Heavy -- The bottom bin when graphed, has the heaviest amount of activity.

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

1340 Lotus Domino Administrator 7 Help

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 25 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. 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:
v Minimize Moves -- To minimize the number of moves made, even though the balance may not be
as accurate when completed.
v Balance Moves and Accuracy -- To allow more moves, in an effort to reach a higher level of
accuracy.
v 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:
v Automatically Select Server -- to automatically locate the server in the domain that has the
Domino Change Control database (DOMCHANGE.NSF). This is the default.
v 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.

Chapter 62. Using Activity Trends 1341

 v 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:
v Light Bin -- Default is 30%
v Middle Bin -- Default is 40%
v Heavy Bin -- Default is 30%
7. For the field ″Enter server resource capacities as relative values when editing server properties,″ do
one:
v Check Yes (default) to specify server resource capabilities relative to other servers in the list.
v 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:
v Check Yes (default) to use the volume information, such as physical volumes and their sizes that
comprise the space available to Domino.
v 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:
v Use Defaults -- To revert to previously saved custom defaults.
v Save as Defaults -- To save a custom set of defaults and override the system defaults.
v Reset Defaults -- To revert to the system defaults.

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 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.
v Pin and unpin databases
v Change server properties or add a phantom server
v Filter out servers and their databases that you do not want displayed on the Available Databases tab

1342 Lotus Domino Administrator 7 Help

v 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.
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:
v Available Databases -- Lists the databases that are not pinned in the Master Pin List and are, therefore,
available to be moved
v Recommended Plan -- Shows the new source and proposed destination for the databases
v Current Profile -- Shows how the servers are currently balanced
v Projected Profile -- Shows how the servers will be balanced after the plan is carried out

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

Chapter 62. Using Activity Trends 1343

v Current -- The current value of the metric as recorded.
v 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.
v 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.
v Projected -- The calculated final value of the server’s resource, if the generated solution (plan) were to
be applied.
v 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.

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

1344 Lotus Domino Administrator 7 Help

v 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.
v Medium -- The medium bin is the middle bin when graphed, using a medium blue. This indicates the
bin with a medium amount of activity.
v 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).

Chapter 62. Using Activity Trends 1345

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:
v Set the server as ″source only″ to prevent Activity Trends from moving any databases to it.
v 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.

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.

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:
v Select a profile
v 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:

1346 Lotus Domino Administrator 7 Help

Field Action
Type Choose one:
v Real -- To identify a server that physically exists in the domain.
v 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:
v Any -- Databases can be moved to or from the server.
v Source Only -- This server will not have any databases moved to it.
v 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.″
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:
v All Servers
v Selected Servers
4. Check or uncheck one or more:
v Hide System Databases (default is checked)
v Hide Master Pin Databases (default is checked)
v Hide Databases appearing in Plan (default is unchecked)

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.

Chapter 62. Using Activity Trends 1347

Pinning or unpinning databases as you balance resources does not change the saved pin list. You cannot
unpin a system database or a 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:
v Select the databases that cannot be moved, and then click Pin.
v 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.
v Use Trended values -- to use trended statistics, instead of current statistics.
v 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.
v 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.

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:
v Maximize
v Maximum Width
v Maximum Height
v Restore

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.

1348 Lotus Domino Administrator 7 Help

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.

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

Chapter 62. Using Activity Trends 1349

v Increase the number of concurrent plans when you want many plans to execute at the same time.

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.
3. Click the Change Control tab, and complete these fields:

Field Action
Domain Change Server Choose the server that stores the Domino Change Control database
(DOMCHANGE.NSF).
Database file name 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.
Max. concurrent Enter the maximum number of messages that can be executed at the same time. The
messages default is 5. The recommended number is between 1 and 10.
Max. concurrent plans 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.
Max. concurrent Enter the maximum number of demands (for example, database moves) that can be
demands simultaneously processed. The default is 40. This number should be equal to or larger
than the ″Max. concurrent plans″ number.

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 Action
quit Stops the Change Manager and all plug-ins.
stop Stops the Change Manager and all plug-ins. Same as Quit.
exit Stops the Change Manager and all plug-ins. Same as Quit.
help Refers you to documentation.
? Refers you to documentation. Same as Help.
restart Stops and then restarts the Change Manager and all plug-in subsystems.
start plug-in Starts the plug-in. Currently, Control, Monitor, and RoboAdmin are the defined
plug-ins.
stop plug-in 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.
restart plug-in 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.

1350 Lotus Domino Administrator 7 Help

Option Action
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 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 Access level Role

Full Access Administrator Manager Change Admin

Administrator System Admin

(Listed in the Server document of the current server.) Plan Creator

Default No access No roles
LocalDomainServers Manager Plan Reader

Chapter 62. Using Activity Trends 1351

Name Access level Role
OtherDomainServers No access No roles
Anonymous No access No roles

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.

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:
v Create databases & templates
v 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.

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.

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

1352 Lotus Domino Administrator 7 Help

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

Chapter 62. Using Activity Trends 1353

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.

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:
v 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.
v 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:
v A plan
v A database move sequence
4. Under Execution Options, for the field Execution Method choose one:
v Sequential
v 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 Analysis tab.
2. Open the Domino Change Control - Plans view, and then choose one of the following views:
v By Status -- if you know the status of the plan you want to view
v By Author -- if you don’t know the status of the plan but you know who the author is
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.

1354 Lotus Domino Administrator 7 Help

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.
4. In the Basics section, complete these fields:

Field Action
Name Enter a unique name for the plan.
Categories (Optional) Select a category or enter a new category name.
Description (Optional) Enter a description of the plan.

5. Under Execution options, choose one:

v Sequential -- To execute each demand set (database move sequence) one at a time.
v Concurrent -- To move all demand sets at the same time.
6. In the field Activate Plan, do one:
v Choose ″Only between specified start and stop periods″ and specify a time during which the
request can be sent to the Administration Process.
v Choose ″Anytime after specified start″ and specify a time after which the request can be sent to
the Administration Process.
v Choose″ Anytime before specified end″ and specify a time by which the request must be sent to
the Administration Process.
v Choose ″At any time (after approval)″ to submit the request to the Administration Process any
time after the plan is approved.

Chapter 62. Using Activity Trends 1355

 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 Action
Approval profile Do one:
v Click ″Choose Profile″ and select the approval profile from
the list.
v 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.
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.
v Referenced constraints -- Lists the constraints that apply to this plan. Click Edit to add or remove
one of the constraints.
v 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.
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.
5. On the Basics tab, complete these fields:

Field Action
Name (unique) Enter a unique name for the profile.
Description (Optional) Enter a description.

1356 Lotus Domino Administrator 7 Help

Field Action
Category (Optional) Select a category or enter a new category name.
Members Select the names of users or groups to include in this
approval profile.

6. Click the Administration tab, and complete these fields:

Field Action
Owner By default, the owner is the person who creates this document.
Administrators Enter the names of users who can edit this document.
Prevent deletion Choose one:
v No (default) -- To allow a Change Administrator to delete the plan.
v Yes -- To prevent anyone except a Change Administrator from deleting the
plan.
Prevent design refresh Choose one:
v No -- To allow the upgrade of all template documents during a version
upgrade.
v 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.

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:
v Awaiting Approval -- To view plans that have been drafted and submitted, but have not been
approved by all approvers.
v Awaiting Commitment -- To view plans that have been fully approved, but have not yet been
committed for completion.
v Active Plans -- To view plans that have been fully committed and are being carried out by Change
Manager.
v 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:
v Constraints -- Specify when moves can be made.
v Variables -- Assign a common name that has a referenced value.
v Notification messages -- Create custom notification messages that are sent whenever the plan status
changes.

Chapter 62. Using Activity Trends 1357

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:

v During standard change windows
v Is after hours
v Not during change freeze period
v Not on workdays

The default constraints sets are:

v Major change
v Minor change
v Trivial change

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 Action
Name Enter a name. This name appears in the Setup view.
Unique name Enter a unique name. This is the name of the document you are defining.
Description 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.
1358 Lotus Domino Administrator 7 Help
5. On the Basics tab, complete these fields:

Field Action
Name Enter a name. This name appears in the Setup view.
Unique name Enter a unique name. This is the name of the document
you are defining.
Description 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.

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.
7. Select a Type:
v Text
v Number
v Time
v Boolean
8. For the field Special, do one:
v Choose Simple value, and then enter a Text value.
v Choose Formula, and then click Keywords and Variables and copy a text formula.
v 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.

Chapter 62. Using Activity Trends 1359

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.

1360 Lotus Domino Administrator 7 Help

Chapter 63. Improving Server Performance
This chapter describes ways you can improve the performance of your Domino server.

Improving Domino server performance

You can improve basic server performance and capacity, as well as the performance of these Domino
features:
v Agent Manager
v Databases and the Domino Directory
v Directory catalog
For more information on improving directory catalog performance, see the chapter ″Setting Up
Directory Assistance.″
v LDAP searches
For more information on improving LDAP searches, see the chapter ″Setting up the LDAP Service.″
v Mail
v Web server
For more information on improving Web server performance, see the chapter ″Setting up the Domino
Web Server.″
v Windows NT server
v UNIX server

For more information on performance, visit the Domino Performance Zone at

www.lotus.com/performance.

See the Notes.net column, ″Performance Perspectives″ for detailed information about performance issues.

For more information on improving network performance see the chapter ″Setting up the Domino
Network.″ For more information on database performance properties, see the chapter ″Improving
Database Performance.″

Tools for measuring server performance

Domino offers performance tools you can use to measure and evaluate server performance.

Activity Trends
Activity Trends, part of the Domino Administrator, 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 part of the Domino server, Activity Trends provides
a workflow that facilitates implementing the recommended changes.

For more information about using Activity Trends to improve server performance and capacity, see the
chapter ″Activity Trends.″

Domino Server.Load
Using Domino Server.Load, you run a script (a simulated workload) in your own environment to obtain
server capacity and response metrics. You can run a built-in script or create a custom script. Domino
Server.Load includes real-time control of the test environment and variables, such as the number of
simulated users. Using Domino Server.Load, you can evaluate the capacity of your servers and evaluate

1361
the requirements for additional CPU, memory, or disk storage upgrades. Server.Load can also be used to
determine the effect of changes to the machine, such as upgrading a device drive, an OS service pack, or
a Domino maintenance release.

Domino Server.Load is included as part of the Administrator client. For details about setting up and
working with Server.Load, see the chapter ″Using Server.Load.″

NotesBench
NotesBench is a collection of benchmarks (workloads) that simulate the behavior of workstation-to-server
or server-to-server operations. Vendors and other organizations use NotesBench to evaluate the
performance of various Domino and Notes platforms and configurations.

Using NotesBench, hardware vendors and business partners generate benchmark information, which they
can distribute to their customers. In turn, customers can use the benchmark information to evaluate
vendors, select configurations, and plan resource budgets.

To use NotesBench for testing, you must be a member of the NotesBench Consortium, which is an
independent, nonprofit organization dedicated to providing Domino and Notes performance information
to customers. The consortium requires that each member run the NotesBench tests in the same manner
and allows tests to be audited.

To view published data and test results, go to the NotesBench Web site at www.notesbench.org.

Improving basic server performance and capacity

This section contains suggestions for improving basic server performance and increasing server capacity.

Domino’s Activity Trends feature

Use Activity Trends, in the Domino Administrator, to collect and store activity statistics as current
observations and historical trends related to the server, databases, users, and connections of users to
databases. You can determine how database workload is distributed across servers and you can review a
recommended resource-balancing plan. You can also use a workflow, provided by Activity Trends, that
facilitates implementing the recommended changes.

For more information about using Activity Trends to improve server performance and capacity, see the
chapter ″Activity Trends.″

Improving server capacity and response time

These tips for improving server capacity and response time come from the analysis of NotesBench
reports, which are published by NotesBench Consortium members. Some of this information may derive
from earlier versions of Domino, and, therefore, may not be completely applicable to Lotus Domino 7.

Make sure your server memory matches the number of users you want to support. Most NotesBench
vendors use 300K to 400K per active user. They also set their NSF_BUFFER_POOL_SIZE to the maximum
for their memory configuration. This setting isn’t necessary, because the Domino server initially obtains a
third of available memory and grows only if necessary (depending on the load). You should use
published physical memory configurations as a ceiling for memory configuration decisions.
1. Make I/O subsystem improvements. For example you can:
v Move from EISA-based systems (such as, controllers) to PCI-based systems
v Exchange EISA/PCI boards for PCI-only boards (this way, lower speed EISA devices won’t decrease
the I/O throughput)
v Use stripping to balance the load across all drives in the array. Use hardware RAID, such as RAID
0+1, to improve performance and availability.

1362 Lotus Domino Administrator 7 Help

 v Use multiple I/O controllers to distribute logical volumes (and use file pointers to databases across
separate controllers). Make sure you have the latest BIOS for your I/O subsystem. This is an
inexpensive way to remove a likely throughput bottleneck.
2. Use faster disk drives.
3. Increase the stripe size. Refer to the NotesBench reports to see what the vendors use. NotesBench
vendors use a stripe size of 8K (Hewlett-Packard systems) or 16K (IBM NetFinity® reports). (The IBM
NetFinity report provides additional information on I/O settings such as IOQ Depth, Outbound
Posting, PCI Line Prefetch, and Address Bit Permitting.)
4. Use faster CPUs. NotesBench vendors have moved beyond the Pentium®, Sparc®, and PowerPC®
processors, which were in the 100Mhz to 200Mhz range, to higher speed processors. However, they
consistently use P6-based systems over the Pentium II systems for high-end Domino server loads. The
size of your Level 2 cache should match your expected user loads and the response time you want.
Vendors have moved from 256K to 512K, 1MB to 2MB Level 2 cache systems, especially on their
greater than two-CPU configurations.
5. Improve your network. NotesBench vendors have:
v Moved from 10Mbps cards and networks to 100Mbps configurations
v Used multiple LAN segments (one for each partition) to isolate network traffic, at the high-end user
loads
6. Change your network protocol to IP. Vendors initially used NetBIOS and SPX internally but have
unanimously moved to IP for their performance publishing efforts.
7. You can improve Web server performance by disabling HTTP server logging. Logging options are
stored in the Server document. In the HTTP server ″Enable logging to″ section are two fields, Log files
and DOMLOG.NSF. Disabling both of these fields improves Web server performance.
8. You can improve general server performance by disabling the type-ahead mail addressing feature.
(Type-ahead allows users to enter the first few characters of a user’s name; the server then completes
the rest of the name automatically.) To disable type-ahead on a server, open the server’s Configuration
Settings document in the Domino Directory. On the Basics tab, choose Disabled in the Type-ahead
field. Then save and close the document.

NOTES.INI settings that affect Domino server performance

Replicators
This setting specifies the number of Replicator tasks that can run concurrently on the server. The default
is 1. Typically, the number of replicators should equal the number of processors on the server. However,
hub servers can run more replicators.

Server_Availability_Threshold
This setting specifies the acceptable level (a percentage) of system resources available to a server. By
setting this value for each server in a cluster, you determine how the workload is distributed among
cluster members. The default is 0, which indicates a fully available state (workload balancing is disabled).
A value of 100 indicates the server is busy; the Cluster Manager then tries to redirect user requests to
more available cluster members.

Server_MaxUsers
This setting sets the maximum number of users that are allowed to access a server. When this number is
reached, the server state becomes ″MaxUsers,″ and the server stops accepting new Database Open
requests. The default is 0 (unlimited access to server by user). By setting a maximum number of users
allowed on the server, you can prevent server performance from degrading because of demand overload.

Server_Session_Timeout
This setting specifies the number of minutes of inactivity after which the server automatically terminates
network and mobile connections. The minimum recommended setting is 15 minutes. If you specify a
lower time, the server must reopen database server sessions too frequently, which slows server
performance. For best performance, the recommended time is 45 minutes.

Chapter 63. Improving Server Performance 1363

For mobile connections, X.PC has its own internal time out. If the X.PC time-out value is shorter than the
Server_Session_Timeout value, the X.PC time out takes precedence.

ServerTasks
This setting controls the tasks that the server runs. These tasks start automatically at server startup and
continue until the server is shut down. Improve performance by removing tasks that aren’t appropriate to
the server. Do not remove the Update task from a server. If you do so, the Domino Directory will not
update.

Translog_Status
This setting enables transaction logging for all Release 5 and later databases on the server. Default is 0
(transaction logging disabled). Set this to 1 to enable transaction logging. Transaction logging improves
the availability and reliability of the server.

Note: You must upgrade databases to Domino Release 5 or later format before they can use transaction
logging.

Improving partitioned server performance and capacity

You use the same set of tools to monitor partitioned servers as you use to monitor individual servers.
However, remember that a partitioned server can use a large amount of system resources, denying those
resources to other partitioned servers on the same computer. For example, the Indexer on one partitioned
server may be using a large percentage of the available CPU cycles, causing the other partitioned servers
to have a slow response time. Therefore, it is important to look at your operating system’s performance
monitor as well as the Domino statistics to determine which partitioned server is using the system
resources.

For more information about monitoring Domino servers, see the chapters ″Monitoring the Domino
Server″ and ″Using Log Files.″

Optimizing performance
If one partitioned server uses significant system resources, consider moving that server to a different
computer. If partitioned servers causes slow disk access, consider moving the Domino data directories of
the partitioned servers to separate disk drives.

Another way to limit access to a server is to limit the number of users who can use a partitioned server
at one time. To do this, you can use the Server_MaxUsers setting in the NOTES.INI file. When the server
reaches the number of users you specify, Domino denies additional user requests for access to the server.

For additional information about these NOTES.INI settings, see the appendix ″NOTES.INI File.″

Improving Agent Manager performance

The Agent Manager controls when agents run on a server. Every time an agent runs, it uses server
resources. To control when scheduled and event-triggered agents run, you specify settings in the Server
document and in the NOTES.INI file. Customizing when agents run may conserve server resources, but it
may also delay when agents run.

Controlling how often Agent Manager runs agents

These NOTES.INI settings affect how often the Agent Manager executes agents. In general, the more
frequently agents run, the sooner they perform their tasks. Running agents more frequently, however,
may increase demand on server resources and adversely affect overall system performance.

AMgr_DocUpdateAgentMinInterval
This setting specifies the minimum elapsed time, in minutes, between executions of the same document
update-triggered agent. This lets you control the time interval between executions of a given agent.

1364 Lotus Domino Administrator 7 Help

Default is 30 minutes. A longer interval can result in the agent running less often, reducing server
demand. If document update events are infrequent, you can reduce the delay.

Note: Setting this and other Agent Manager variables to zero does not completely eliminate the delay; a
built-in delay will always exist.

AMgr_DocUpdateEventDelay
This setting specifies the delay time, in minutes, the Agent Manager schedules a document
update-triggered agent after a document update event. The default is 5 minutes. The delay time ensures
the agent runs no more often than the specified interval, regardless of how frequently document update
events occur. When the agent executes, it will also process all additional events (if any) that occurred
during the interval. A longer interval results in the agent running less often, thus reducing demand for
server time. If document update events are infrequent, however, you can reduce the delay to ensure the
agent runs soon after the event occurs.

AMgr_NewMailAgentMinInterval
This setting specifies the minimum elapsed time, in minutes, between execution of the same new
mail-triggered agent. The default is 0 (no interval between executions). Similar to
AMgr_DocUpdateAgentMinInterval, entering an interval can result in the agent running less frequently.

AMgr_NewMailEventDelay
This setting specifies the time (in minutes) that the Agent Manager delays before scheduling a new
mail-triggered agent after new mail is delivered. The default is 1 minute. Similar to
AMgr_DocUpdateEventDelay, the delay time ensures the agent runs no more often than the specified
interval. When the agent executes, it will also process all additional events (if any) that occurred during
the interval. A longer interval results in the agent running less often, thus reducing demand for server
time. If document update events are infrequent, however, you can reduce the delay to ensure the agent
runs soon after the event occurs.

DominoAsynchronizeAgents
This setting specifies whether Web agents triggered by browser clients can run at the same time
(asynchronously). The default is zero (only one agent can run at a time). Set this to 1 to allow multiple
agents to run simultaneously. This can result in faster execution of agents. However, a high number of
agents executing at the same time can slow overall system performance. Open the Server document you
want to change, and click the Internet Protocols - Domino Web Engine tab. In the Web Agents section,
enable or disable the ″Run Web agents concurrently?″ option. For ″Web agent time-out (in seconds),″ the
default is 0 (no time-outs).

Controlling how quickly the Agent Manager queues agents

The Agent Manager periodically checks to see if it has any new agents that it needs to schedule. These
NOTES.INI settings control how quickly an agent gets into the schedule queue.
This setting specifies a delay (in minutes) between running of the Agent Manager’s scheduler. Valid
values are 1 minute to 60 minutes. The default value is 1 minute.
This setting specifies a delay (in minutes) between running of the Agent Manager’s check for untriggered
mail. Valid values are 1 minute to 1440 minutes (the number of minutes in a day). The default value is 60
minutes.

Controlling when the Agent Manager runs agents

When you create or modify an event-triggered agent, the Agent Manager schedules it to run immediately.
This ensures the agent can quickly process new documents. These NOTES.INI settings let you specify a
time interval between subsequent running of the agent. This can prevent repeated running of the agent --
for example, because of a rapid series of triggering events.

Scheduling an agent to run immediately means that it will execute as soon as possible. If there are many
agents ahead of it, it may not be executed right away.

Chapter 63. Improving Server Performance 1365

These settings control when the Agent Manager runs agents.

For more information, see the topic ″Controlling how often Agent Manager runs agents,″ earlier in this
chapter.
v AMgr_NewMailEventDelay
v AMgr_DocUpdateEventDelay
v AMgr_DocUpdateAgentMinInterval
v AMgr_NewMailAgentMinInterval

Monitoring the load on the Agent Manager

If your server attempts to schedule agents at a rate faster than the Agent Manager can run them, the
message ″AMgr: Agent scheduling is paused″ appears on the console. The Agent Manager will not
schedule any new agents until the server processes some agents that are already scheduled. Therefore, the
running of new agents may be slightly delayed.

Controlling how many concurrent agents are running

You can relieve a heavily loaded Agent Manager by allowing agents to run concurrently. To do this,
modify the ″Max concurrent agents″ field in the Server Tasks/Agent Manager section of the Server
document. Values greater than 1 allow more than one agent to run at the same time. Valid values are 1
through 10. Default values are 1 for daytime and 2 for nighttime.

An Agent Executive runs each concurrent agent. To see a snapshot of the Agent Manager status,
including the number of Agent Executives currently running, enter the command tell amgr status at the
server console. To see a list of scheduled agents, enter the command tell amgr schedule at the server
console.

Improving server performance using the configuration collector

Domino’s configuration collector provides snapshots of how the Domino server is configured. You can
use that configuration information to analyze recent changes made to the server’s configuration that have
impacted server performance.

Domino reads several documents during server initialization. These documents are the Server document,
Server Configuration document, All Server Configuration document, and the Group Server Configuration
document. Domino also checks the views of these documents for changes every five minutes. If
modifications have been made, Domino reads and saves the modified documents. When Domino reads a
document, a filename is constructed based on the document’s modification time and date and the server
name. There is a default prefix assigned to each of the server and configuration documents:
v Server document -- serverdoc
v Configuration Settings (Specific Server) document -- configspecific
v Configuration Settings (All Servers) document -- configall
v Configuration Settings (Server Group) document -- configgroup

For example, if a Server document is modified on August 2, 2004, at 4:05 PM, on a server named Sales,
the file name assigned to the document is serverdoc_sales_2004_08_02@16_05_20.dxl. The file is stored in
the diagnostic directory, IBM_TECHNICAL_SUPPORT located in Domino’s data directory. If
Domino/Data is the data directory, the path is
C:/Domino/Data/IBM_TECHNICAL_SUPPORT/serverdoc_sales_2004_08_02@16_05_20.dxl.

Improving database and Domino Directory performance

By default, the Domino Directory uses two database performance properties -- ″Document table bitmap
optimization″ and ″Don’t maintain unread marks″ -- to improve performance. The following NOTES.INI
settings can affect database and Domino Directory performance.

1366 Lotus Domino Administrator 7 Help

For more information on database performance properties, see the chapter ″Improving Database
Performance.″

NSF_Buffer_Pool_Size
This NOTES.INI setting sets the size of the NSF buffer pool, a section of memory used for buffering I/O
transfers between the NSF and NIF subsystems and disk storage. The number of server partitions, users,
size and number of views, and number of databases all affect how you should set the buffer pool
specification. The default value (determined automatically by the server) is usually sufficient, but if
Database Statistics indicate more memory is needed, increase the value a few megabytes at a time. You
can use a performance monitor to find out if a larger value is causing too much swapping or paging.
(NSF_Buffer_Pool_Size sets the buffer pool size in bytes; NSF_Buffer_Pool_Size_MB sets the size in
megabytes.)

NSF_DbCache_Maxentries
This NOTES.INI setting sets the maximum number of databases stored in the database cache (if enabled).
For short intervals, Domino stores up to 1.5 times the number entered for this setting. Increasing the
maximum number of databases improves performance but requires more memory.

Improving performance for users accessing the Web using the Web Navigator
There are several ways to improve performance:
v Speed up your access to Web pages by speeding up your server connection to the Internet. Contact
your Internet Service Provider to find out what options you have.
v Improve database performance by managing your database with the Purge and Refresh agents or any
other agents you may create for the database.
v Manage the number of users retrieving pages in the Web Navigator database by setting the maximum
number of concurrent retrievals (the number of Web pages the server retrieves at the same time). The
default maximum number of concurrent retrievals is 25. The number of concurrent retrievals that your
server allows depends on your specific system environment.

Show DBS command

The Show DBS command is a tool for monitoring the performance of a database. This command returns
the following information:
v Refs -- The number of times the database has been opened (the DBHANDLE count for the database).
v Mod -- Whether the database has been modified, but not yet flushed to disk.
v FDs -- The number of file descriptors currently being used for the database.
v LockWaits -- The number of times a user has had to wait for a lock on the database (read or write).
v AvgWait -- The average wait time in milliseconds for each wait.
v #Waiters -- The number of waiters currently on the database lock. (This number changes rapidly.)
v MaxWaiters -- The maximum number of waiters ever on the database lock.

Note: To display LockWaits and AvgWait values, you must temporarily add the setting
COLLECT_DB_LOCK_WAITS=1 to the server’s NOTES.INI file. Because this setting consumes server
resources, remove it after you view Show DBS statistics.

Tips for tuning mail performance

For more information on monitoring mail performance, see the chapter ″Monitoring Mail.″ For more
information on using multiple MAIL.BOX databases and disabling type-ahead addressing to improve
mail performance, see the chapter ″Customizing the Domino Mail System.″

Controlling message delivery

You set delivery controls in the Configuration Settings document on the Router/SMTP - Restrictions and
Controls - Delivery Controls tab, under Delivery Controls.

Chapter 63. Improving Server Performance 1367

Maximum delivery threads
This setting determines the maximum number of threads the Router can create to perform local mail
delivery. Increasing this value can improve message throughput for local deliveries. The ideal number
ranges from 3 to 25. This is determined by a formula, based upon the NSFBufferPoolSize. You can
increase or decrease the value based on the server configuration. Monitor Mail.Waiting over a period of
time. If there is a backlog over a period of time, increase the number. Monitor
Mail.Delivery.Threads.Total. If the value is less than Mail.Delivery.Threads.Max, set the value to the total.

Setting transfer limits

You set transfer limits in the Configuration Settings document on the Router/SMTP - Restrictions and
Controls - Transfer Controls tab, under Transfer Controls.

Maximum concurrent transfer threads

This setting determines the maximum number of concurrent transfer threads per destination. The default
is the value entered for ″Maximum transfer threads″ divided by 2.

Maximum transfer threads

This setting determines the maximum number of threads the mail Router can create to perform mail
transfers. Without this variable, the default is one thread per server port. Increasing this number creates
more threads to handle mail transfers. However, additional threads may increase the demand for server
processing time.

Setting the number of mailboxes

If there are a small number of users on a server, the default (1) is usually sufficient. For larger numbers of
users, set the number to 2 or higher. To determine the optimum number, enter SHOW STAT MAIL at the
server console. If MAIL.WaitingRecipients is large or increasing, adding a mailbox may improve
performance if the server resources are not overloaded.

You set the number of mail.boxes in the Configuration Settings document on the Router/SMTP -
Restrictions and Controls - Basics tab. Under Router/SMTP Basics, enter a value for ″Number of
mailboxes.″

For more information on creating multiple MAIL.BOX databases, see the chapter ″Customizing the
Domino Mail System.″

Setting IMAP session time-out

If the server supports IMAP users and has limited resources, it may free up server resources and improve
performance to set this to a value of 30 minutes or more.

For more information on IMAP settings, see the chapter ″Setting Up the IMAP Service.″

MinNewMailPoll
This setting determines how often workstations can contact the server to see if new mail has arrived for
the user. This setting overrides the user’s selection in the Mail Setup dialog box. You can increase the
mail polling interval if there are a large number of mail users on your server and you want to prevent
frequent polling from affecting server performance.

NoMsgCache
This setting disables per-user message caching by the IMAP task. This can improve capacity (number of
users) on a server by reducing memory consumption. However, response time for some user operations
may be slower.

POP3_Config_Update_Interval
This setting determines how often (per minute) the Domino server that runs the POP3 service updates its
configuration information. The default is 2 minutes.

1368 Lotus Domino Administrator 7 Help

Improving Windows 2000 server performance
In general, use the default settings for your Windows server. You may gain some performance
improvements by doing the following:
v Take care of fragmented disks. Run a defragmenter utility frequently on your disks, including the OS
disk to prevent performance degradation. Do this weekly on busy disks. You can use the defragmenter
that ships with Windows 2000, or use a defragmenter that automatically runs on a number of systems
at specified intervals.
v Use a separate pagefile disk. For best performance on all medium and large systems, use a separate
pagefile disk.
v Optimize performance for applications or background services.
– Windows 2000 -- In the Control Panel, select System - Advanced - Performance Options and select
Background services.
– Use the NTFS file system (NT File System). The NTFS file system has significant performance
advantages over FAT or FAT32. For best performance, format the disks with a cluster size of at least
4KB. Use a cluster size that is a little larger than the average file size on the disk. NTFS supports
these sizes: 512, 1024, 2048, 4096, 8192, 16KB, 32KB, and 64KB. For example, to use a 16KB allocation
size for formatting the NTFS volumes, at the command prompt enter (format
<drive>:/fs:ntfs/A:16K).
v RAID sets. When setting up data disk RAID sets, set the stripe size to be approximately equal to the
average logical disk transfer per second measured in Perfmon for the typical workload for the server.
Set the cache write policy to ″write back.″ Set the cache read policy to ″read ahead.″
v Balance the I/O bandwidth for each PCI bus. Distribute the network adapters and RAID controller
across multiple buses if your server has them. Do not put the RAID controller on a bus that has a
network adapter.
v Use LargeSystemCache. Windows 2000 has this disk-I/O cache. The default setting favors file sharing.
This uses more memory than the other settings. If server memory is a bottleneck, set the cache to favor
network applications, or, in extreme cases, set it to minimize memory. Otherwise, leave the default
setting.
To change the setting in Windows 2000, go to the Control Panel, click the ″Network and Dial up
Connections″ icon, click Local Area Connection. Right-click on the properties for a network connection,
and click ″File And Printer Sharing for Microsoft Networks.″
Choose one of the following:
– ″Maximize data throughput for file sharing″
– ″Maximize data throughput for network applications″
– ″Minimize memory used″

Improving UNIX server performance

NOTES.INI settings
Most NOTES.INI settings that affect Domino server performance apply to all UNIX platforms.

NSF_Buffer_Pool_Size_MB
Many machines that run UNIX have very large amounts of physical RAM. Use the parameters
NSF_Buffer_Pool_Size_MB or PercentSysAvailable Resources to control how much memory Domino is
allowed to use. Each Domino instance on a UNIX machine can reference a maximum of 4GB of RAM.

Disk and memory requirements

When a UNIX system runs Domino server software, the server must have enough disk space for program
and data files and enough memory to handle swapping and the number of processes. You can also
change several system parameters to improve server performance.

Chapter 63. Improving Server Performance 1369

System V Shared Memory
This is used on AIX and HP-UX. Run the ″ipcs -a″ command to list all shared memory segments used by
the Domino server. The maximum segment size is the default value of Notes_SHARED_DPOOLSIZE on
that platform.

Disk I/O tuning

Maintaining multiple file systems for operating system files, swap space, transaction logs, and data
improves overall server performance. Use RAID 0+1 hardware for the disk drives that the data files are
on. Keeping swap space on their own separate striped volumes improves server performance at high
loads on systems that have high swap rates. Transaction logging should be on its own disk drive for
improved server restart time, reliability, and availability.

Console and database logging

To improve server performance, limit the amount of information that is logged to the log file (LOG.NSF)
and the console.

For more information on controlling logging, see the chapter ″Using Log Files.″

Sources for improving server performance

The following links provide up-to-date information and recommendations. These links were current at
the time this documentation was created:
v Individual articles and the Performance Perspectives″ monthly column in the Lotus Developer Domain
at www-10.lotus.com/ldd
v NotesBench Consortium at www.notesbench.org
v Domino Performance Zone at www.lotus.com/performance
v IBM Redbooks at www.redbooks.ibm.com
v Solaris at www.lotus.com/dominosolaris
v Windows 2000 internals at www.sysinternals.com
v Hewlett-Packard at www.hp.com
v IBM performance pages for the following machines:
iSeries at www-1.ibm.com/servers/eserver/iseries/
xSeries at www.pc.ibm.com/ww/eserver/xseries/domino
zSeries at www-1.ibm.com/servers/eserver/zseries/

1370 Lotus Domino Administrator 7 Help

Chapter 64. Improving Database Performance
To optimize database performance, you can set properties for individual databases and configure the
database cache to improve overall database access time on a server. To keep database size to a minimum,
you can set database properties that save disk space, compact databases, set database size quotas, and
regularly delete inactive documents in databases.

Setting advanced database properties

Set advanced database properties to:
v Optimize database performance
v Set unread mark options
v Enable or disable replication of unread marks
v Enable or disable transaction logging
v Allow more fields in a database
v Allow soft deletions

Database properties that optimize database performance

Properly setting database properties can improve the performance of an active database. Setting database
performance properties on many databases or on one, large, active database can also improve server
performance. In addition, some of these property settings also help reduce the size of databases. Many of
these properties require knowledge of application design, and the database designer often sets these
properties when creating a database.

For information on designing applications, see the book Application Development with Domino Designer.

Display images after documents

To quickly display documents that contain images, select the Basics database property ″Display images
after loading.″ Then Notes users can read the text while the images load. If you don’t load images after
text, Notes loads images in the order in which they appear in a document; if an image appears first,
Notes loads it before displaying text. With large images or slow connections, loading images in order
may slow the display of the document.

This setting applies only when using Notes to view databases; Web browser settings control the display
of images to Web browser users.

Tip: Users also can specify ″Load images: On request″ in the Advanced section of a Location document
to display images only when users click them. For more information, see Lotus Notes 7 Help.

Prevent the use of stored forms

To ensure that a document always displays correctly, you can store the form with the document.
However, storing a form with every document uses system memory and may require as much as 20
times more disk space than not doing so. To save memory and disk space, you may want to prevent the
use of stored forms, especially if users experience performance problems when trying to read the
documents. To prevent the use of stored forms, deselect the Basics database property ″Allow use of stored
forms in this database.″ Before preventing the use of stored forms, make sure you understand how this
design feature works and how the database uses it.

1371
Setting unread mark options
Note: Access these database properties by choosing File - Database - Properties and then clicking the
details tab. (The icon on this tab is a beanie.)

The Database dialog box contains a set of Unread Mark Options that you can use to maintain or not
maintain unread marks, and to specify if unread marks with replicate to other servers. If you select the
database property, Don’t maintain unread marks, unread marks are not maintained for the database and
the replicate unread marks settings are disabled. If you do not select the database property, Don’t
maintain unread marks, the replicate unread marks settings are enabled. You can do one of the following:
v Choose Never -- Unread marks are never replicated
v Choose Clustered servers only -- Unread marks are replicated for databases residing on servers that are
cluster mates of the current server.
v Choose All Servers -- Unread marks are replicated for databases on all servers.

Don’t maintain unread marks

Maintaining unread marks in a database requires system resources and can significantly slow database
performance. For some databases, unread marks aren’t useful -- for example, reference databases such as
the Help databases provided with Domino, administration databases such as the Domino Directory, or
databases such as the log file (LOG.NSF) that are continually updated. In these types of databases,
consider disabling unread marks. To disable unread marks, select the Advanced database property ″Don’t
maintain unread marks.″

Note: Designing views that don’t display unread marks doesn’t improve database performance because
they are still maintained but not displayed.

If you select or deselect the ″Don’t maintain unread marks″ property, you must compact the database so
that the setting takes effect. Compacting in this case makes a temporary copy of the database, so your
system must have the disk space to make the copy.

Tip: You can also run the Compact server task with the -u or -U option to enable or disable this property
and then compact.

Replicate unread marks

Replicating unread marks requires system resources and can significantly slow database performance.
Replication of unread marks was primarily designed for mail databases.

For information about enabling replication of unread marks, see the chapter ″Maintaining Databases.″

Associate document tables with forms for view updates

When updating a view, Domino refers to tables of document information. These tables are stored
internally in the database. By default, during view updates and rebuilds, Domino searches each table for
documents that appear in the view being updated. To update views more efficiently, select the Advanced
database property ″Document table bitmap optimization.″ This property associates tables with the forms
used by the documents the tables contain. Then during a view update, Domino searches only the tables
associated with the forms used by documents in the view being updated. This significantly improves the
performance of view updates, especially updates of small views within large databases -- for example, the
Connections view in the Domino Directory.

This property only works for views that use Form= as part of the selection criteria. There’s a slight
performance cost to maintaining the table/form association; however, when updating small views in
large databases, the benefits offset the cost.

1372 Lotus Domino Administrator 7 Help

If you select or deselect the ″Document table bitmap optimization″ property, you must compact the
database so that the setting takes effect. Compacting in this case makes a temporary copy of the database,
so your system must have the disk space to make the copy.

Tip: You can also run the Compact server task with the -F or -f option to enable or disable this property
and then compact.

Prevent overwriting of deleted data

When data is deleted from databases, Domino, by default, overwrites the deleted data on disk with a
pattern. This pattern prevents an unauthorized user from using a utility to access the data. This
overwriting affects disk I/O and can affect database performance.

Preventing the overwriting of deleted data is appropriate in these circumstances:

v The data is already secure -- for example, the database is on a server in a locked room.
v Deleted space in the database is constantly reallocated -- for example, in a system database such as
MAIL.BOX.
v Data security isn’t an issue -- for example, in an informal discussion database.

To prevent the overwriting of deleted data, select the Advanced database property ″Don’t overwrite free
space.″

Don’t maintain ″Accessed (In this file)″ document property

The Document Properties box displays the property ″Accessed (In this file)″ which can show the date a
document was last modified or read. The Advanced database property ″Maintain LastAccessed property″
controls whether the ″Accessed (In this file)″ property is updated if the last document access was a read.
Maintaining the ″Accessed (In this file)″ property for reads causes disk I/O that wouldn’t otherwise
occur.

By default, the database property ″Maintain LastAccessed property″ is not selected, meaning the
″Accessed (In this file)″ property isn’t updated when the last document access was a read, only when the
last access was a document modification. Change the default behavior by selecting ″Maintain
LastAccessed property.″

You should select ″Maintain LastAccessed property″ if you use the document archiving tool, available in
the Database Properties box, to delete documents based on days of inactivity.

Disable specialized response hierarchy information

By default every document stores information that associates it with a parent document or a response
document. Only the @functions @AllChildren and @AllDescendants, which are often used in view
selection and replication formulas, use this stored information. Maintaining this information has a
significant, negative effect on database performance.

To improve database performance, disable the response hierarchy information in databases that don’t use
these @functions by selecting the Advanced database property ″Don’t support specialized response
hierarchy.″

Disabling the response hierarchy information has no effect on views and replication formulas that display
information hierarchically without using @AllChildren and @AllDescendants.

Disabling the response hierarchy information sets NotesDocument.Responses to 0 documents.

If you select or deselect the ″Don’t support specialized response hierarchy″ property, you must compact
the database so that the setting takes effect. Compacting in this case makes a temporary copy of the
database, so your system must have the disk space to make the copy.

Chapter 64. Improving Database Performance 1373

Tip: You can also run the Compact server task with the -h or -H option to enable or disable this property
and then compact.

Prevent headline monitoring

Users can set up headline monitoring to automatically monitor databases for information that interests
them. Monitoring a database this way affects performance, especially if many users do this. To prevent
users from monitoring a database, select the Advanced database property ″Don’t allow headline
monitoring.″ You can also use the Security section of a Server document in the Domino Directory to
control headline monitoring at the server level.

Allow more fields in a database

You can increase the number of fields in a database by selecting the advanced database property ″Allow
more fields in database″ which allows the database to contain up to 23,000 fields.

For a database without this option selected, all the field names in a database when concatenated cannot
exceed 64 kilobytes, which results in a database limit of approximately 3000 fields.

Use LZ1 compression for attachments

In Lotus Domino Designer, you can choose to compress attachments using the new LZ1 algorithm instead
of the Huffman algorithm. Because LZ1 compression can be performed quickly and efficiently, it is
favored over the Huffman method. However, if you are working in an environment that uses different
versions of client and server software (for example, a Lotus Domino Designer 6 client and a Domino 5
server) and you choose this option, attachments are automatically recompressed on the server using the
Huffman method. Note that recompressing has performance implications. For best performance, use LZ1
in primarily Domino 6 or more recent environments.

Note: The attachments in existing databases are not automatically compressed with the LZ1 algorithm
when you choose the LZ1 algorithm. Files that are attached after the LZ1 algorithm option is enabled are
compressed using the LZ1 algorithm. You can distinguish which compression algorithm is in use by
checking the $File field in the document properties.

For more information on the LZ1 algorithm, see the book Application Development with Domino Designer or
the Domino Designer 7 Help.

Limit the size of $UpdatedBy fields

Every document includes an $UpdatedBy field that stores, by default, the name of the user or server
associated with each document editing session. Storing a complete edit history consumes disk space and
slows view updates and replication. To conserve disk space and improve database performance, use the
Advanced database property ″Limit entries in $UpdatedBy fields″ to specify the number of entries that
the $UpdatedBy field can contain. When the $UpdatedBy field reaches this limit, the oldest entry is
removed to make room for the newest entry.

Limit the size of $Revisions fields

Every document includes a $Revisions field that stores, by default, the date and time of each document
editing session. Domino uses this field to resolve replication or save conflicts that occur when two users
simultaneously edit the same document on one replica or edit the same document on different replicas
between replications.

By default, the $Revisions field stores a history of up to 500 edit sessions, each of which requires 8 bytes
of disk space. Over time, $Revisions fields can grow large, taking up disk space and slowing view
updates and replication. To conserve disk space and improve database performance, use the Advanced
database property ″Limit entries in $Revisions fields″ to specify the number of entries that the $Revisions
field can contain. When the $Revisions field reaches this limit, the oldest entry is removed to make room
for the newest entry.

Consider limiting the entries in $Revisions fields on a database with all of the following characteristics:

1374 Lotus Domino Administrator 7 Help

v The database contains many documents.
v The database replicates often or has no replicas.
v The database contains documents that are not often edited.

A suggested upper limit is 10 entries in the $Revisions field. If you set the limit lower than 10, you run
the risk of increased replication or save conflicts.

Specify expiration time for soft deletions

When ″Allow soft deletions″ is selected, documents marked for deletion are held in the database for a
specified time before they are deleted. On the Advanced tab of the Database Properties box, you can
specify the number of hours documents are held before they are deleted from the database.

Setting database properties that optimize database performance

You can set database properties to optimize database performance and to reduce database size. Set
database performance properties by opening the Database Properties box on an existing database or as
you create a database.

Make sure you fully understand these database properties before changing their settings.
1. Make sure you have Designer or Manager access in the database ACL.
2. Do one of the following:
v Open a database and choose File - Database - Properties.
v As you create a new database, click the Advanced button.
3. Select or deselect properties listed in the table below.
4. After you select any of these properties, compact the database for the property to take effect:
v Don’t maintain unread marks
v Document table bitmap optimization
v Don’t support specialized response hierarchy

Tip: You can use the Compact task with specific options to enable or disable the above three
properties and then compact the database.

Improves
To optimize database Reduces
Property Tab performance/size performance? database size?
Allow use of stored forms in this Basics Deselect option Yes Yes
database
Display images after loading Basics Select option Yes No
Don’t maintain unread marks Advanced Select option Yes Yes
Document table bitmap optimization Advanced Select option Yes No
Don’t overwrite free space Advanced Select option Yes No
Maintain LastAccessed property Advanced Deselect option Yes No
Don’t support specialized response Advanced Select the option Yes Slightly
hierarchy
Don’t allow headline monitoring Advanced Select the option Prevents No
performance
degradation
Limit entries in $UpdatedBy fields Advanced Select the option and Yes Yes
specify the number of
entries $UpdatedBy
fields can contain

Chapter 64. Improving Database Performance 1375

 Improves
To optimize database Reduces
Property Tab performance/size performance? database size?
Limit entries in $Revisions fields Advanced Select the option and Yes Yes
specify a limit on the
number of entries
$Revisions fields can
contain. The suggested
limit is 10 entries.

Soft deletions
In some databases, deleting a document permanently removes it from the database. In other databases,
such as the Notes mail file database, deleting a document moves it into a Trash folder and stores it in a
state of ″soft deletion.″ From this folder, users can restore deleted documents by dragging them from the
Trash folder into another folder or by selecting Restore.

Deleted documents are not permanently removed until a specified expiration time or until the user
empties the Trash folder. By default, soft deletions are enabled for mail databases created from the
Domino 7 mail template (MAIL7.NTF). The default expiration time is 48 hours. You can turn soft
deletions on or off for any database and specify how long to retain soft deletions before removing them
from the database.

To display soft-deleted documents in other types of databases, you must create a view to list the
documents and provide users with an action programmed to un-delete documents and restore them to
the database.

For information on creating views to display soft-deletions, see the book Application Development with
Domino Designer.

Because deleted documents are not removed immediately from a database that has soft deletions enabled,
space in the database is not reclaimed as quickly as in a database that does not use soft deletions. If space
consideration is an issue, consider disabling soft deletions.

To enable or disable soft deletions for a database

1. From the Files tab of the Domino Administrator, select the database and choose Edit - Properties.
2. On the Advanced tab of the Database properties box, check ″Allow soft deletions.″
3. Set a value for ″Soft delete expire time in hours.″ The default is 48 hours. After that amount of time,
soft deletions are permanently removed from the database.

The database cache

To minimize delays that occur when users, servers, or API programs open and close databases on a
server, each server maintains a database cache. When a database closes and there are no users or
processes using the database, Domino puts the database in the cache so it can close it quickly. The
database remains in the cache until it’s opened again or for about 15 to 20 minutes, whichever comes
first. Databases in the cache can be opened quickly.

The database cache is available to the first process that starts on a machine and to any processes spawned
from it. If you run the Domino Administrator and the Domino server on the same machine -- a
configuration that is not recommended -- start the server before you start the Domino Administrator. If
you start the Domino Administrator first, it owns the cache and prevents the Domino server from using it
effectively.

1376 Lotus Domino Administrator 7 Help

Database cache size
By default, the number of databases that the cache can store simultaneously is the greater of these values:
v The value of the NSF_Buffer_Pool_Size setting in the NOTES.INI file, divided by 300K
v 25

To change this limit, add the NSF_DbCache_Maxentries setting to the NOTES.INI file or increase physical
memory. Increasing the database cache size improves system performance but requires additional
memory. The minimum number of databases allowed in the cache at one time is 25; the maximum is
2,000.

The actual number of databases allowed in the cache is 1.5 times the maximum allowed. This buffer
increases the chance that when a user opens a database from the cache, Domino can return the database
to the cache when the user closes it.

How databases are dropped from the cache

Databases are dropped from the cache by an ″ager″ thread that performs necessary writes, deallocates
memory, and completes other tasks to close databases. This process happens over a period of 15 to 20
minutes. Ideally, databases are dropped from the cache in time to allow new databases to be added
without exceeding the maximum databases allowed in the cache. However, if the maximum is exceeded,
one of the following occurs:
v If the number of databases in the cache is less than the maximum allowed times 1.5, when a database
is closed it is added to the cache, and the ager accelerates to reduce the number of databases to the
maximum allowed. This action may increase stress on the server I/O subsystem and increase
competition for cache resources.
v If the current number of databases in the cache is greater than or equal to the maximum allowed times
1.5, when a database is closed, Domino doesn’t put the database in the cache. Instead it uses the
slower, non-cache method to close the database. And when a user or process next opens the database,
Domino reads the database from disk rather than from the cache, causing the database to open more
slowly than if it were in the cache.

Monitoring the database cache

Monitor the effectiveness of the database cache by occasionally checking cache statistics. You can view the
following statistics by viewing Mail & Database Statistic Reports or by using the server command:
Show Stat Database.DbCache.*

For information on statistics reporting, see the chapter ″Monitoring the Domino Server.″ For more
information on server commands, see the appendix ″Server Commands.″

Statistic
Database.DbCache.CurrentEntries
Database.DbCache.HighWaterMark
Database.DbCache.Hits
Description
Number of databases currently in the cache. If this number
frequently approaches the value of
Database.DbCache.MaxEntries, increase the number of
databases the cache can hold.
Maximum number of databases in the cache during this
running of the server program. This number may be
artificially high because of startup activity, so it may not be a
genuine indicator of cache performance.
The number of times an ″InitialDbOpen″ is satisfied by
finding the database in the cache. A high ″hits-to-opens″ ratio
indicates that the database cache is working effectively. If the
ratio is low, increase the number of databases the cache can
hold.

Chapter 64. Improving Database Performance 1377

Statistic
Database.DbCache.InitialDbOpens
Database.DbCache.Lookups
Database.DbCache.MaxEntries
Database.DbCache.OvercrowdingRejections
Description
The number of times a user/server opened a database that
was not already being used by another user/server. For
example, if a user opens a mail file while it is being used by
the Replicator, this number does not increase. Compare this
number to Database.DbCache.Hits to gauge the effectiveness
of the cache.
The number of lookups to the database cache. A high
″Database.DbCache.Hit″ to ″Database.DbCache.Lookups″ ratio
means the database cache is effective. If the ratio is low,
increase the number of databases the cache can hold.
The number of databases the server can currently hold in its
cache at once. To change this value, use the NOTES.INI file
setting, NSF_DbCache_Maxentries, or increase physical
memory.
Number of times a database is not placed into the cache
when it is closed because Database.DbCache.CurrentEntries
equals or exceeds Database.DbCache.MaxEntries times 1.5.
This number should stay low. If it begins to rise, increase the
number of databases the cache can hold.

Managing the database cache

To change the number of databases the cache holds: If after monitoring the database cache you
determine that you should increase the number of databases the cache can hold, use the NOTES.INI file
setting, NSF_DbCache_Maxentries, as follows:
NSF_DbCache_Maxentries=value

Where value is the maximum number of databases allowed in the database cache at one time.

The alternative to using NSF_DbCache_Maxentries is to increase physical memory.

To show databases in the cache: Enter this command at the server console to display the names of the
databases currently in the cache:
dbcache show

To close databases in the cache: Enter this command at the server console to close all databases in the
cache:
dbcache flush

To disable the cache: By default, the database cache is enabled on a server. To disable the cache, add the
following NOTES.INI file setting:
NSF_DbCache_Disable=1

Controlling database size

Databases whose size is monitored and minimized show increased performance: database operations
require less I/O and fewer CPU resources; view rebuilding and updating is quicker; and memory and
disk space allocation is improved. The maximum database size is 64GB on Windows and UNIX. Use the
following methods to minimize and monitor the size of databases:
v Compact databases
v Set database size quotas to prevent databases from growing beyond a specified size
v Delete inactive documents using the document archiving tool or using agents
v Set database performance properties that also reduce database size

1378 Lotus Domino Administrator 7 Help

v Use replication settings to limit the size of a replica by replicating to it only what’s necessary
v Decrease the database purge interval to remove deletion stubs more often
v Disable the default user activity recording in databases
v Disable soft deletions in databases
For information on replication settings and the database purge interval, see the chapter ″Creating
Replicas and Scheduling Replication.″ For information on user activity recording, see the chapter
″Maintaining Databases.″

Tools for monitoring database size

This table summarizes the methods you can use to monitor database size and the information each
method provides.

Database Percent of
Monitoring method size View size Quotas used space**
Domino Administrator Files tab Yes No Yes No
Database - Sizes view of the log file (LOG.NSF) or logs in Yes Yes No Yes
the view
Logs in Miscellaneous Events view of the log file (LOG.NSF) No No Messages No
relating to
File statistic reports in the Statistics database Yes No No Yes

** Not always a reliable indicator of used space.

Monitoring database size

Use the following method to monitor database size and used space in a database.
1. Open the database and choose File - Database - Properties.
2. Click the Info tab (i) to see the size of the database.
3. Click % Used to display the percentage of database space in use.

Compacting databases
When documents and attachments are deleted from a database, Domino tries to reuse the unused space,
rather than immediately reduce the file size. Sometimes Domino won’t be able to reuse the space or,
because of fragmentation, can’t reuse the space effectively until you compact the database.

Styles of compacting
There are three styles of compacting:
v In-place compacting with space recovery
v In-place compacting with space recovery and reduction in file size
v Copy-style compacting

In-place compacting with space recovery only

This style of compacting recovers unused space in a database but doesn’t reduce the size of the database
on disk. Databases retain the same database instance IDs (DBIIDs), so the relationship between the
compacted databases and the transaction log remains intact. Users and servers can continue to access and
edit databases during compacting. This style of compacting is useful for databases that you expect to stay
the same size or to grow in size.

When you run Compact without specifying options, Domino uses this style of compacting on all
databases enabled for transaction logging. Domino also uses this style of compacting when you use the -b
option (case sensitive) when compacting any database.

Chapter 64. Improving Database Performance 1379

Tip: Use this compacting method the most frequently -- it is the fastest method and causes the least
system impact.

In-place compacting with space recovery and reduction in file size

This style of compacting reduces the file size of databases as well as recovers unused space in databases.
This style of compacting is somewhat slower than in-place compacting with space recovery only. This
style of compacting assigns new DBIIDs to databases, so if you use it on logged databases and you use a
certified backup utility, perform full backups of the databases shortly after compacting is complete. This
style of compacting allows users and servers to continue to access and edit databases during compacting.

When you run Compact without specifying options, Domino uses this style of compacting on databases
that aren’t enabled for transaction logging. Domino also uses this style of compacting when you use the
-B option. To optimize disk space, it’s recommended that you run Compact using the -B option on all
databases once a week or once a month.

Copy-style compacting
Copy-style compacting creates copies of databases and then deletes the original databases after
compacting completes, so extra disk space is required to make the database copies. This style of
compacting essentially creates a new database with a new database ID. If you use copy-style compacting
on logged databases (using the -c option), compacting assigns new DBIIDs, so if you use a certified
backup utility, you should perform full backups of databases shortly after compacting completes. When
you use copy-style compacting, users and servers can’t edit databases during compacting, and they can
only read databases if the -L option is used.

Domino uses copy-style compacting by default when you use an option with Compact to enable a
database property that requires a structural change to a database or when you run Compact on a
database that has a structural change pending that was initiated from the Database Properties box.
Enabling or disabling the database properties ″Document table bitmap optimization″ and ″Don’t support
specialized response hierarchy″ require structural database changes.

The following table compares the three styles of compacting.

In place, space
In place, space recovery with file
Characteristics recovery size reduction Copy-style
Databases that use it when compact runs Logged databases with Unlogged databases Databases with
without options no pending structural with no pending pending structural
changes structural changes changes
Databases you can use it on Current release Current release Current release (need
-c)
Relative speed Fastest Medium Slowest
Users can read databases during Yes Yes No (unless -L option
compacting used)
Users can edit databases during Yes Yes No
compacting
Reduction in file size No Yes Yes
Extra disk space required No No Yes

Renaming a copy-style compacted database

Domino attempts only once to rename a database that was copy-style compacted. You can request
successive attempts by specifying the value of the Num_Compact_Rename_Retries setting in the
NOTES.INI file. Domino tries to rename until it succeeds or the number of retries is exhausted. For
example, to request that Domino try once again to rename, specify Num_Compact_Rename_Retries=1; to
request that Domino try 5 more times to rename, specify Num_Compact_Rename_Retries=5.

1380 Lotus Domino Administrator 7 Help

If you have specified a value for the Num_Compact_Rename_Retries setting, Domino waits 30 seconds
before trying to rename a database that was copy-style compacted. You can request a different amount of
time to wait by specifying the value of the Compact_Retry_Rename_Wait setting in the NOTES.INI file.
For example, to request that Domino wait 2 minutes before trying to rename a database that was
copy-style compacted, specify Compact_Retry_Rename_Wait=120.

Domino enforces the following upper limit when trying to rename a copy-style compacted database:
Num_Compact_Rename_Retries x Compact_Retry_Rename_Wait <= 60 minutes

When to compact databases

It’s recommended that you compact databases weekly or monthly using the -B option to recover disk
space. If you use a certified backup utility, remember to run it after compacting is complete.

Also compact databases to:

v Enable or disable specific database properties -- for example, transaction logging
v Run the document archiving tool on server databases that are configured for document deletion and
archiving
v Fix corrupted databases
For information on transaction logging, see the chapter ″Transaction Logging and Recovery.″ For
information on the document archiving tool, see the topic ″Running the document archiving tool″ later
in this chapter.

Note: The Database - Sizes view of the log file (LOG.NSF), the File Statistic reports generated by the
Statistics Collector server task, and the Info tab (i tab) of the Database Properties box, all report the
percentage of used space in a database. These are often not accurate indicators of used space; therefore,
you shouldn’t use them.

Ways to compact databases

Use any of these methods to run Compact. Each of these methods allows you to customize how Compact
runs.
v Run Compact using the Compact tool in the Files tab of the Domino Administrator -- Use this method
to compact a few databases; you can select the databases to compact, but you can’t use the Domino
Administrator until compacting finishes
v Run Compact using the Task - Start tool in the Domino Administrator -- Use this method to compact
all databases on a server; you can continue to use the Domino Administrator during compacting and
you don’t have to remember specific command-line options
v Run Compact using a console command -- Use this method if you’re comfortable using command-line
options or to compact databases directly at the server when there isn’t a Domino Administrator client
running on the server
v Run Compact using a Program document -- Use this method to schedule compact to run at particular
times
v Run Compact on a Win32 platform -- Use this method if you are unable to run Compact at the server
console. This method requires that you use the ″n″ prefix. For example ncompact - C

Determining the file format of a database

Follow these steps to check the ODS (on-disk structure) and determine the file formats of databases
before compacting them.
1. From the Domino Administrator, in the Server pane on the left, select the server on which to run
Compact. Click the servers icon to expand the Server pane.
2. Click the Files tab.
3. Select the folder containing the files you want to check.
4. Look at the File Format column in the files window.

Chapter 64. Improving Database Performance 1381

Compact options
The following tables describe the options you can use with the Compact server task. The first column
lists the options as they appear when you run Compact using the Task - Start tool or the Files tab in the
Domino Administrator. The second column lists the equivalent command-line options that you use when
you run Compact using a console command or using a Program document.

Compact - Basics
Option
Compact only this database or
folder
(To specify databases to compact
using the Files tab, select the
databases in the files pane.)
Command-line equivalent Description
database path To compact a database in the Domino data
folder, enter the file name, for example
Specify any additional options SALES.NSF. To compact databases in a folder
after the database path. within the data folder, specify the database
path relative to the data folder. For example, to
compact all databases in the folder
DATA\SALES, specify SALES.

If you choose ″Compact all databases″ (or don’t

specify a database path at the command line)
Compact compacts all databases in the data
folder and in folders within the data folder.

For more information on database path, see the topic ″Running Compact using a console command″ later
in this chapter.

Compact - Options
Option
Compact database only if unused
space is greater than x percent
Discard any built view indexes
Keep or revert database to
previous format
Command-line equivalent Description
-S percent Compacts all databases with a specified percent
of unused space. For example, if you specify
10, databases with 10% or more recorded
unused space are compacted. Note that the
unused space calculation is not always a
reliable measure of unused space.
-D Discards built view indexes. Use this option to
compact databases just before you store them
on tape, for example. Does copy-style
compacting.
-R Compacts databases without converting to the
current release file format of the server that
stores the databases or reverts databases in the
current release file format to the previous
release file format. For example, on Domino 6
and more recent servers, this option compacts
Domino 5 databases without converting them
to the Domino 6 file format and converts
Domino 6 databases to the Domino 5 file
format. This option uses copy-style compacting.

1382 Lotus Domino Administrator 7 Help

Compact - Style
Option Command-line equivalent Description
In-place (recommended) -b Uses in-place compacting and recovers unused
space without reducing the file size, unless
there’s a pending structural change to a
database, in which case copy-style compacting
occurs. This is the recommended method of
compacting.
In-place with file size reduction -B Uses in-place compacting, recovers unused
space and reduces file size, unless there’s a
pending structural change in which case
copy-style compacting occurs. If you use
transaction logging, do full database backups
after compacting completes.
Copy-style -c Uses copy-style compacting. Use this option,
for example, to solve database corruption
problems.
Copy-style: Allow access while -L Enables users to continue to access databases
compacting during compacting. If a user edits a database
during compacting, compacting is canceled.
This is useful only when copy-style compacting
is done.
Copy-style: Ignore errors and -i Enables compacting to continue even if it
proceed encounters errors such as document corruption.
Only used for copy-style compacting.

Compact - Advanced
Option*
Document table bitmap
optimization: Off
Document table bitmap
optimization: On
Don’t support specialized response -h
hierarchy: Off
Don’t support specialized response -H
hierarchy: On
Enable transaction logging: Off
Enable transaction logging: On
Don’t maintain unread marks: Off
Command-line equivalent Description
-f Disables ″Document table bitmap optimization″
database property. Does copy-style compacting.
-F Enables ″Document table bitmap optimization″
database property. Does copy-style compacting.
Disables ″Don’t support specialized response
hierarchy″ database property; in other words,
support specialized response hierarchy. Does
copy-style compacting.
Enables ″Don’t support specialized response
hierarchy″ database property; in other words,
do not support specialized response hierarchy.
Does copy-style compacting.
-t Disables transaction logging.
-T Enables transaction logging. Use Compact - T
when a database is open or closed. If you use
Compact - T on a database that is closed,
logging is enabled but the Compact is not
logged until the database is opened; therefore,
logging is not available until you reopen the
database.
-u Disables ″Don’t maintain unread marks″
database property; in other words, maintain
unread marks.

Chapter 64. Improving Database Performance 1383

Option* Command-line equivalent Description
Don’t maintain unread marks: On -U Enables ″Don’t maintain unread marks″
database property; in other words, do not
maintain unread marks.

* Select ″Set advanced properties″ before you enable or disable any of these properties.

Compact - Archive
When you use the document archiving tool to archive and delete documents in a database, you can use
the following Compact options to archive documents if the database is located on a server and you’ve
chosen the advanced archiving option ″Automatically on server.″

Option* Command-line equivalent Description

Archive only
Archive and then compact
Delete and then archive
-A Archives and deletes documents from a
database without compacting the database.
-a Archives and deletes documents from a
database and then compacts the database.
-j Deletes documents from a database and then
compacts the database.

*The Compact tool in the Files tab of the Domino Administrator provides only the option ″Archive
database;″ this option archives and then compacts.

Running Compact using the Files tab

Use the Compact tool in the Files tab of the Domino Administrator to run Compact on specific databases.
The databases can be stored on a server or stored locally on a Domino Administrator client.
1. From the Domino Administrator, select the server in the Server pane that stores the databases you
want to run Compact on. If the Domino Administrator does not run on a server, you can select local
to run Compact on databases stored on the client. To expand the Server pane, click the servers icon.
2. Click the Files tab.
3. Select the databases on which to run Compact.
4. In the Tools pane at the right, select Database - Compact. Or drag the selected database(s) to the
Compact tool.
5. (Optional) Select options to control how Compact runs.
For information on the options available, see the topic ″Compact options″ earlier in this chapter.
6. Click OK.

Running Compact using the Task - Start tool

Use this method to compact many databases on a server. You can continue using the Domino
Administrator during compacting.
1. From the Domino Administrator, on the Server pane on the left, select the server on which to run
Compact. To expand the pane, click the servers icon.
2. Click the Server - Status tab.
3. In the Task pane on the right, click Task - Start.
4. Select Compactor.
5. Do one of the following:
v To run Compact with options (to control how Compact runs), click ″Show advanced options,″ click
Start Task, select options, and then click OK.
v To run Compact without options, click Start Task.
For information on the options available, see the topic ″Compact options″ earlier in this chapter.

1384 Lotus Domino Administrator 7 Help

Running Compact using a console command
1. From the Domino Administrator, on the Server pane on the left, select the server on which to run
Compact. To expand the pane, click the servers icon.
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 compact databasepath options
where databasepath specifies the files to compact
and options are Compact command-line options.

The following table illustrates how you can use databasepath to specify databases, folders, and subfolders.

To compact Example command Files compacted

A specific database in the Domino Load compact SALES.NSF DATA\SALES.NSF
data folder
All the databases in a folder relative Load compact SALES DATA\SALES\all databases
to the Domino data folder
A specific database in a folder Load compact SALES\USER1.NSF DATA\SALES\USER1.NSF
relative to the Domino data folder
All the files specified in a .IND file Load compact WEEKLY.IND DATA\SALES.NSF
created in the Domino data folder
Note: If you are using the -T flag to where WEEKLY.IND contains: DATA\DEV.NSF
specify a view, Indirect files (.IND)
cannot be used. SALES.NSF DATA\SALES\USER1.NSF

DEV.NSF DATA\SALES\NEW\all databases

SALES\USER1.NSF

SALES\NEW

Running Compact using a Program document

Use a Program document to schedule Compact to run at a regular time. For example, schedule Compact
to run with the -B option once a week. Remember to perform full backups of the databases after
compacting is complete.

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 you want to
modify.
3. Expand Server - Programs and then click Add Program.
4. On the Basics tab, complete these fields:

Field Enter
Program name Compact
Command line Command line options. Don’t specify ″load″ before the options.
Server to run on Server on which to run Compact
Comment Optional comments

Chapter 64. Improving Database Performance 1385

5. On the Schedule tab, complete these fields:

Field Enter
Enabled/disabled Enabled
Run at times Times to run Compact each day
Repeat interval of How soon to run Compact again after it completes
Days of week The days to run Compact

6. Click Save and Close.

For more information on the available command-line options, see the topic ″Compact options″ earlier
in this chapter.

Database size quotas

Set a database size quota to specify the maximum size a database can attain. When a database exceeds its
quota, the following message appears in the Miscellaneous Events view of the log file (LOG.NSF); a user
attempting to open the database sees it as well: ″Cannot allocate database object - database would exceed
its disk quota.″ Although a database may have reached its quota, a user may be able to add documents to
it if the database contains unused space -- that is, space that remains from deleted data.

In conjunction with setting a quota, you can specify that when a database reaches a certain size threshold,
this warning message appears in the Miscellaneous Events view of the log file: ″Warning, database has
exceeded its size warning threshold.″ For example, if the quota is 50MB, you might specify that the
warning appear when the database size reaches 45MB so you can take steps to reduce the size of the
database or move it to a server that has more disk space available.

Note: You can set quotas on user mail files, but, by default, when a mail file exceeds its quota, the
Router continues to deliver mail to it, and users can update existing mail views. This ensures that users
can continue to receive and read all mail sent to them. The quota is enforced only for other means of
increasing the size of the mail file -- for example, when a mail file reaches its quota, users can’t manually
add documents or views to it. However, you can customize routing to strictly enforce quotas on mail
files.

For more information on customizing mail, see the chapter ″Customizing the Domino Mail System.″

Database size limits

Databases can attain a maximum size of 64GB on Windows and UNIX.

Setting database size quotas

1. From the Domino Administrator, on the Server pane on the left, select the server that stores the
databases you want to set quotas for. To expand the pane, click the servers icon.
2. Click the Files tab.
3. Select the databases you want to set quotas for.
4. In the tools panel on the right, select Database - Quotas. Or drag the selected databases to the Quotas
tool.
5. Below ″Database size quotas,″ click ″Set database quota to x MB″ and specify a maximum size in
megabytes the selected databases can attain.
6. Below ″Quota warning thresholds,″ click ″Set warning threshold to x MB″ and specify a size in
megabytes at which a message appears in the log file (LOG.NSF).
7. Click OK. When processing is complete, a dialog box indicates how many databases were affected
and if any errors occurred. See the status bar for details.

1386 Lotus Domino Administrator 7 Help

Deleting inactive documents
Regularly delete inactive documents from databases to save disk space, to make it easier for users to find
information, and to improve database performance. This table compares the deletion methods available.

Mult. deletion Leaves

and Archive deletion
Deletion method capability? stubs*?
Create an archive settings document Yes Yes
Document archiving tool in the Database Properties box Yes Yes
″Remove documents not modified in the last x days″ replication setting No No
Agents Yes Yes

* Deletion stubs are markers that remain from deleted documents so that the documents are deleted in
other replicas of the database.

In addition to these methods, you can also create an API program that deletes documents.

For information on the ″Remove documents not modified in the last x days″ setting, see the chapter
″Creating Replicas and Scheduling Replication.″

To archive deleted documents

If you have disk space available and you want users to be able to access deleted documents, archive the
documents before deleting them. When doing so, follow these guidelines:
1. Determine an archive frequency based on the type of database. For example, you might archive an
infrequently accessed database, such as a company policy database, every three months. Archive a
heavily used tracking database, such as a customer call-tracking database, once a month or once a
week.
2. Notify users that you plan to archive the database.
3. In the About This Database document of the active database, post the archiving schedule and the
location of the archive database.
4. Archive the database when it is not in use and server traffic is low -- for example, on Sunday night.
5. After archiving is complete and you’ve deleted documents from the active database, compact the
active database.
6. If the database has replicas, replicate the active database when database use is light so that you
minimize user interruptions.
7. Limit access to the archive database. Assign Manager access in the database ACL to one or two users
and replicating servers. Assign Reader access in the database ACL to everyone else. By doing this, you
ensure that view indexes and full-text search indexes update only when archiving occurs.

To customize an archive database for fast access

Using an archive database ensures that users can continue to access the archived data. Use any of these
methods to make accessing the archive database fast and easy.

Note: Don’t customize an archive database used by the document archiving tool.

Remove unnecessary fields

Removing unnecessary fields makes the documents smaller and the views smaller and faster. For
example, although the active database might include fields for the customer name, phone number,
address, and fax number, the archive database might require only the customer name.

Chapter 64. Improving Database Performance 1387

Use only a few views and create a full-text index
Using only a few views improves view performance by keeping the total size of the view indexes to a
minimum. Providing a full-text index allows users to retrieve information easily.

Create buttons or agents in the active database

Buttons and agents allow users to quickly open the archive database when necessary.

To use an archive copy for statistical analysis

To analyze statistics within a database, create a view that generates statistics in an archive copy of the
database. For example, in an archive copy of a Call Tracking database, create a view that generates totals
for specific categories of call records and for all call records. Because archive databases usually contain
data that span a long period of time, they are ideal for performing statistical analysis.

Running the document archiving tool

If you selected the option ″Automatically on server,″ run the Compact task on the server that stores the
source database.
v Use the -A option to archive documents without compacting the source database.
v Use the -a option to archive documents and then compact the source database.

Viewing a document Archiving Log

If you set up the document archiving tool to log archiving information to an Archiving Log database, an
entry is created in the Archiving Log database when either the client or server finishes archiving. To view
this entry:
1. Open the entry in the Archiving Log database.
2. Click ″Archive statistics″ to display the date of the archive, the number of documents archived to the
Archive database, and the number of archived documents deleted from the original database.
3. Click ″Database/Server″ to display the location, title, and path for the original database and for the
Archive database.
4. Click ″Links to archived docs″ to use document links to access documents in the Archive database
that have been removed from the original database. This doesn’t apply if you selected the advanced
archiving option ″Delete matching documents without archiving them.″

Using an agent to delete and archive documents

Agents give you a very high degree of control over document deletion criteria. However, agents can be
slow to run.

The following procedure describes creating an agent using simple actions. You can also create agents
using Notes formulas, LotusScript, or Java.

When you run the agent, if Domino cannot copy all specified documents to an archive database -- for
example, if there is not enough disk space on the target folder -- the agent stops.

For more information on agents, see the chapter ″Agents.″ For more information on Notes formulas,
LotusScript, and Java see Domino Designer Programming Guide, Volumes 1 through 4.

To use an agent to delete and archive documents:

1. (Optional) To archive deleted documents, choose File - Database - New Copy to create a copy of the
database as the archive copy. Copy only the database design.
2. Open the database and choose Create - Design - Agent.
3. Type a name for the agent.
4. Below ″When should this agent run,″ click the arrow and select an option.
5. Below ″Which documents should it act on?″ click the arrow and select an option. Click Add Search,
specify the search criteria, then click OK.

1388 Lotus Domino Administrator 7 Help

6. (Optional) To archive deleted documents, on the bottom pane next to Run, select ″Simple action(s)″
then click ″Add Action.″ Then select ″Copy to Database″ and select the archive copy of the database
created in Step 1. Click OK and go to Step 8.
7. In the bottom pane next to Run, select ″Simple action(s)″ then click ″Add Action.″ Then select ″Delete
from Database.″
8. Close and save the agent. Then choose View - Agents, select the agent and choose Actions - Test to
simulate a run and test that it works correctly.
9. Save and close the agent if necessary.

Examples of using an agent to delete and archive documents

An agent that archives documents according to date modified: These selections create an agent that
copies all documents modified more than 60 days ago from the active database to an archive database
with the file name ARCHIVE.NSF. The agent deletes the archived documents from the active database
after all the documents have been copied.

When should this agent run? On Schedule Monthly

Which document(s) should it act on? All documents in the database

Add Action: @Function formula

Search for documents created more than 60 days ago

What should this agent run? Simple action: Copy to Database ARCHIVE.NSF

Simple action: Delete from Database

An agent that archives documents according to field status: These selections create an agent that
weekly copies all documents with a Status field set to ″Closed″ from the active database to an archive
database with the file name ARCHIVE.NSF. Then the agent deletes the archived documents from the
active database.

When should this agent run? On Schedule Weekly

Which document(s) should it act on? All documents in the database

Condition: by Field

Search for documents where field Status contains Closed

What should this agent do? Add Action: Copy to Database ARCHIVE.NSF

Add Action: Delete from Database

Allowing more fields in a database

You can increase the number of fields in a database by selecting the advanced database property ″Allow
more fields in database″ which allows the database to contain up to 23,000 fields.

For a database without this option selected, all the field names in a database when concatenated cannot
exceed 64K, which results in a database limit of approximately 3000 fields.

To allow more fields in a database:

1. Open the database and choose File - Database - Properties.
2. Click the Advanced tab.
3. Select ″Allow more fields in database.″

Chapter 64. Improving Database Performance 1389

1390 Lotus Domino Administrator 7 Help
Chapter 65. Using Server.Load
This chapter discusses Server.Load, a capacity-planning tool for the Domino server.

Server.Load
Server.Load is a capacity-planning tool that you use to run tests, also called ″scripts″ and ″workloads,″
against a targeted Domino server to measure server capacity and response metrics.

Server.Load supports any platform that is supported by the Domino Administrator client. The client runs
the Server.Load tests and generates the transactions that are presented to the server. A typical Server.Load
configuration has one or more client systems driving the server under test (SUT). Each client running
Server.Load generates a simulated user load of Notes transactions against the SUT, which reports server
statistics back to the client. If you configure multiple clients, you set up and run the test from each client
system.

You can run built-in scripts, create custom scripts from a library of commands, or submit commands
manually. For example, run the built-in R5 Simple Mail Routing script to simulate users on a Notes client
reading and sending mail. Or create a custom script to create and open a Notes mail database and
populate it with messages. To test or execute individual commands, you can use the manual command
line mode to delete documents from a database or issue remote server commands.

Using Server.Load, you have real-time control of the test environment and variables. Prior to running a
test, you can change test parameters, stop conditions, and existing script variables. You can also monitor
real-time server metrics. While the script is running, the Metrics window displays an immediate
characterization of server performance by updating metrics on a per-minute basis.

Server.Load agents
Server.Load includes a set of agents in the file NAMAGENT.NSF, which is initially installed in the data
directory on the Domino Administrator client. The first agent in this list -- Create NotesBench Mail
Person Documents -- is used to set up Person documents for the workloads and set the HTTP password.
The rest of the agents are used to repair and change the workload setup.

To use the agents, you must use Domino Designer to add them to the Domino Directory on the SUT.
v Create NotesBench Mail Person Documents
v Refresh All Documents
v Set HTTPPassword to ″NotesBench″
v Set Message Storage Format = MIME
v Set Message Storage Format = No Preference
v Set Message Storage Format = Notes
v Update ACL of MailDBs to include Owner (mail1, mail2, ...)

Agent to set up a workload: Create NotesBench Mail Person Documents

This agent prompts you for information required to create the necessary number of Person documents for
a workload. The following table describes the prompts and defaults.

Prompt Default
Starting value to create mail users 1.00
Number of users to create 1000.00

1391
Prompt Default
Number of Mailn.NSF files to create 1000.00
Starting Mailn.NSF file 1.00
Location for mail databases mail\
Mail domain Default is read from the server’s mail domain
Mail server directory is on Name of the server that stores the Domino Directory
Message storage format 2 (MIME)
Mail system 1 (NOTES)
Internet host name Host name of the server that stores the Domino
Directory

Agents to repair and change a workload setup

After you use the Create NotesBench Mail Person Documents agent, you may need to use the Refresh All
Documents agent to refresh the view in the Domino Directory.

If you have trouble connecting with HTTP-based workloads and the Person documents do not display
any encrypted passwords, use the Set HTTPPassword to ″NotesBench″ agent to reset the password in all
Person documents.

When you change to a different workload, you must remake all of the mail files, but you can use one of
these agents to change the mail type in the Person documents without having to recreate all of the Person
documents:
v Set Message Storage Format = MIME
v Set Message Storage Format = No Preference
v Set Message Storage Format = Notes
v Update ACL of MailDBs to include Owner (mail1, mail2, ...) -- Use this agent for a workload that has
authentication on.

Server.Load metrics and messaging statistics

As you run a test, you can view various script metrics and server statistic metrics and optionally store the
test output in a separate file. Server statistic metrics are generated by the Domino server. Script metrics
correspond to Server.Load command names and display the performance of particular commands. For
example, if you select the Add metric, the Metrics window displays the results of the Add command.

For more information on script commands, see the appendix ″Server.Load Command Language.″

Note: If the server runs Windows, you can also use the Windows Performance Monitor to measure
performance.

Database statistics
Statistic
Database.BufferPool.Reads
Database.BufferPool.Used
Database.BufferPool.Writes
Database.DbCache.CurrentEntries
Database.DbCache.HighWaterMark
Database.DbCache.Hits
Database.DbCache.InitialDbOpens
Description
Number of database buffer pool reads.
Number of bytes allocated in the buffer control pool.
Number of database buffer pool writes.
Number of entries in the database cache.
High water mark of the database cache.
Number of hits to the database cache.
Number of database opens done by the database cache.

1392 Lotus Domino Administrator 7 Help

Statistic Description
Database.NIFPool.Used Number of database NIF pools

System statistics
Statistic Description
Disc.c.Free (bytes) Free disk space in bytes on drive ’n’. When disk space is low,
compact, delete, or move databases. If problem persists, consider a
larger hard disk.
Disc.c.Size (bytes) Total size in bytes of drive ’n’.
Server.Trans.PerMinute Number of transactions that took place in the last minute. Useful to
monitor server use. If this number is consistently higher than that
of other servers and performance is a problem, redistribute the
server load to other servers.
Server.Users Number of users with sessions open on the server. Useful to
monitor overall server use. If this number is consistently higher
than that of other servers and performance is a problem,
redistribute the server load to other servers.

Mail statistics
Statistic Description
Mail.AverageDeliverTime Average delivery time of messages in seconds
Mail.AverageServerHops Average number of server hops for a delivered message.
Mail.AverageSizeDelivered Average size of message delivered, in K.
Mail.Dead Number of undeliverable messages in MAIL.BOX. Useful for
detecting problems with the Router. Check the server MAIL.BOX to
view the dead mail messages and determine the problem.
Mail.Delivered Number of messages received by the Router.
Mail.MaximumDeliverTime Slowest delivery time of messages in seconds.
Mail.MinimumServerHops Least number of server hops for a delivered message.
Mail.MaximumSizeDelivered Largest message delivered, in K.
Mail.MinimumDeliverTime Slowest delivery time of messages in seconds.
Mail.MaximumServerHops Most number of server hops for a delivered message.
Mail.MinimumSizeDelivered Smallest message delivered, in K.
Mail.TotalFailures Total number of mail failures.
Mail.TotalRouted Total number of recipients that mail has routed to since the server
started.
Mail.Waiting Number of outgoing mail messages waiting to be either delivered
locally or transferred in MAIL.BOX. Useful for detecting problems
with the mail Router.
Mail.WaitingRecipients Number of recipients awaiting either local delivery or transfer.

Network statistics
Statistic Description
NET.TCPIP.BytesReceived Amount of data received from client to server using TCP/IP
protocol.

Chapter 65. Using Server.Load 1393

Statistic Description
NET.TCPIP.BytesSent Amount of data sent from client to server using TCP/IP
protocol.
NET.TCPIP.Sessions.Established.Incoming Incoming sessions from client to server using TCP/IP protocol.

Per Minute Thread Statistics

These statistics are automatically provided and collected for every test.

Statistic
Avg. Trans (Per Thread)
Min. Trans (Per Thread)
Max. Trans (Per Thread)
Total Trans (All Threads)
Running Threads
Agg. Replications
Avg. Rsp. Time (ms)
Running time (min)
Description
The average number of transactions per thread.
The minimum number of transactions per thread.
The maximum number of transactions per thread.
The total number of transactions per thread.
The total number of all threads currently running.
The aggregate number of replications that occurred.
The average NRPC response time. This is the average response across all threads
and is the best overall value to track general server response curves.
Note: This value is not applicable to the Web Mail script
The total running time.

HTTP messaging statistics

When an HTTP workload is run in Server.Load, an HTTP messaging statistics window displays (in
addition to the metrics window). This table lists and describes the messaging statistics that display in
Server.Load:

Messaging Statistic Description

ConnectTime Minimum, maximum, and average number of milliseconds required to establish an
HTTP connection to the server.
SendTime Minimum, maximum, and average number of milliseconds to send HTTP data to the
server.
RecvTime Minimum, maximum, and average number of milliseconds to receive HTTP data from
the server.
TotalTime Total minimum, maximum, and average number of milliseconds to connect to the
server and to send and receive HTTP messages.
ActionsTime Minimum, maximum, average number of milliseconds to perform an HTTP action.
An HTTP action is an HTTP request that involves special work on the server to
process. For example, in the case of the iNotes Web Access workloads, an action is a
POST request that involves sending or deleting mail.
Kbytes/Page Minimum, maximum, and average number of kilobytes of data received per request.
Object/Page Minimum, maximum, and average number of objects (htm, jpg) of data received per
request.

1394 Lotus Domino Administrator 7 Help

Messaging Statistic Description
Totals v Kbytes = Total number of kilobytes of data received
v Pages = Total number of Web pages received
v Obj = Total number of Objects received
v Timeout = Total number of server timeouts, number of times the server was not
responding
v Drops = Total number of times the server dropped the connection, the number of
times unable to send or receive after successfully establishing an endpoint
v ActF = Total number of actions that fails, number of times unable to connect, send,
or receive after successfully establishing an endpoint for an Action request.
Act Total number of actions
Serr Total number of server errors
Cerr Total number of client errors
Hit/Min Average number of objects received per minute
Min Running Number of minutes that the test has been running

Monitoring Server.Load metrics

1. Click Execute from the main window.
2. Choose a script metric or server statistic metric.
3. Do one:
v Click Add Metric to add a metric to monitor.
v Click Delete Selected Metric to stop monitoring a metric.
4. (Optional) Click Browse next to ″Store the Metrics to this File″ and then choose a file to store the
metrics.

Tip: The Output monitor displays real-time test results, command-by-command, as the test runs. You can
see up to 64KB of data in the Output monitor.

Setting up clients and servers for Server.Load

To use Server.Load, you must install the Domino server on the server under test (SUT) and install the
Domino Administration client and the Server Load Utility on each client.

For information on installing the Domino server, see the chapter ″Installing and Setting Up Domino
Servers.″ For information on installing the Domino Administration client, see the chapter ″Setting Up and
Using Domino Administration Tools.″

To set up a SUT
1. Make sure that:
v The Domino server is installed and operational
v The server has adequate RAM, approximately 512KB per simulated user (thread) across all clients
used in the test
2. Make sure that you have Administrator access, Create database access, and access to run unrestricted
LotusScript and Java agents.
3. Make sure that the Server, Replicator, Router, and Update tasks are running on the Domino server.
Run additional tasks as required for individual tests.
4. Enable performance monitoring on the Domino server by issuing the Show Perf command.
5. Use Domino Designer to copy the file NAMAGENT.NSF to the Domino Directory. This file contains
agents that you use to set up and change workloads.

Chapter 65. Using Server.Load 1395

6. Disable all screen savers.

To set up a client
If you use multiple clients in a test, they all must have the identical hardware setup, and you must
complete the following procedure on each.
1. Make sure that:
v The Domino Administration client and Server.Load are installed and operational
v The client has access to the templates to use in the test
v The client has adequate RAM -- approximately 512KB per simulated user (thread)
2. Do the following to edit the Location document:
a. Choose File - Mobile - Edit Current Location.
b. Click the Mail tab, and complete these fields:

Field Action
Mail file location Choose On server
Mailfile Enter the path to the mail file -- for example
mail\mailfile.nsf

c. Click the Servers tab, and in the home/mail server section, enter the name of the SUT.

Note: If you edit the MailServer script variable before you run a test, you change the location of
the mail server for only that run. The next time you run Server.Load, the mail server listed in the
Location document is used.
d. Click Save and Close.
3. Make sure that you use a Notes ID that has administration access to the SUT.
4. Do the following to verify the connection to the SUT:
a. Start the Domino Administration client and verify that the Home/Mail Server field in the Location
document contains the fully distinguished SUT name -- for example, MailServer1/Acme.
b. Verify connectivity by running a trace from the client to the server. Select File - Preferences User
Preferences Ports.
c. Verify that the correct communication port is enabled, and click Trace.
d. Enter the name of the SUT in the Destination field and run the trace to verify that the client can
use the desired protocol to trace to the server.
e. If you cannot connect over TCP/IP, verify that TCP/IP has been enabled on the Domino server
and that the port is enabled in the Server document.
f. Verify that the port has been enabled at the operating system level.
g. Verify that TCP/IP is properly installed and enabled on the client and that you can use the ping
utility to access the Domino server by name -- for example, acme.iris.com -- and by IP address.
5. Disable all screen savers.

Built-in and custom Server.Load scripts

Server.Load includes a set of built-in scripts. You can also create a custom script from scratch.

Built-in scripts
The following table describes the scripts that are built into Server.Load.

1396 Lotus Domino Administrator 7 Help

To see the actual code of each script, see the appendix ″Server.Load Scripts.″
Script
Idle workload
Cluster Mail workload
R5 IMAP Workload
R5 Simple Mail Routing
R5iNotes Workload
R6 Mail workload
R6iNotes Workload
R6IMAP workload
R5 Shared Database
SMTP and POP3 Workload
Web Idle Workload
Web Mail Workload
Workload Data Collection
Description
Establishes the upper boundary of the number of sessions that a Domino server can
support. You can use the metric derived from this script to help you set up other
tests.
The Cluster Mail workload executes Notes transactions that model a cluster for
mail users at sites relying on a two-way Domino cluster for messaging.
Runs Notes transactions that model a server for mail users at sites that rely on
IMAP for communication. This test stresses the IMAP protocol by receiving
messages and exercises SMTP and LDAP by sending SMTP messages to recipients
and performing LDAP lookups on them. You use the IMAP Initialization Workload
script to initialize the SUT.
Simulates one or more Notes mail users performing basic mail operations such as
opening mail files, reading and categorizing documents, sending calendar and
schedule items, and composing multiple mail messages to multiple recipients. You
use the NRPC Mail Initialization Workload script to initialize the SUT.
The R5iNotes test represents an active user sending, retrieving, and deleting mail
from a browser. An average user runs this script four times an hour. Each time the
script runs, it checks and retrieves mail messages. Additionally, on each
NthIteration, which is one time in six for this workload, the user sends a mail
message to NumMessageRecipients other users on the server. The user schedules
an appointment, sends invitations to NumMessageRecipients other users, and
responds to one invitation that it finds in its own inbox.
The R6Mail workload models an active user on a client reading and sending mail,
using the calendar and scheduling features to schedule an appointment, send an
invitation, and send an RSVP to an invitation. An average user will run this script
four times per hour.
The R6iNotes test represents an active user sending, retrieving, and deleting mail
from a browser. An average user runs this script four times an hour. Each time the
script runs, it checks and retrieves mail messages. Additionally, on each
NthIteration, which is one time in six for this workload, the user sends a mail
message to NumMessageRecipients other users on the server. The user schedules
an appointment, sends invitations to NumMessageRecipients other users, and
responds to one invitation that it finds in its own inbox.
The R6IMAP workload executes Domino transactions that model a server for mail
users at sites that rely on IMAP mail for communication. Not only does this test
stress the IMAP protocol by receiving mail messages, but also exercises SMTP and
LDAP by sending SMTP messages to a number of recipients and performing LDAP
lookups on those recipients.
Simulates one or more active users performing database operations on the same
Discussion database. The script includes performing view operations, navigating
unread documents, adding users to the database, and updating documents.
Runs Notes transactions that model a server for mail users at sites that rely on
SMTP and POP3 mail for communication. You use the SMTP and POP3
Initialization Workload script to initialize the SUT.
Simulates users connecting to the default page or home page on a Domino Web
server.
Runs transactions that model a server for Web Mail users. The test simulates a Web
browser user sending, retrieving, and deleting Notes mail. You use the Web Mail
Initialization Workload script to initialize the SUT.
While a workload runs, the Workload Data Collection script, SHSTAT.SCR, collects
the data that is generated by the workload. This is a custom script.
Chapter 65. Using Server.Load 1397
Script
Workload Data Rollup
Cluster Mail Initialization
workload
R5IMAP Initialization
workload
R6IMAP Initialization
workload
iNotes Initialization workload
Description
The Workload Data Rollup script is adapted from the NotesBench data rollup
feature and allows test data from a group of test drivers and a SUT to be combined
into a single datafile for analysis. When a workload is complete, the Workload Data
Rollup script rolls up the performance data that was collected by the Workload
Data Collection script.
The Cluster Mail Initialization workload creates a mail database on the server and
populates the mail database with a number of notes scaled to the SUT. The Cluster
Mail Initialization and ClusterMail workloads are based on the NRPC mail
workloads, except the mail databases are created on two servers during
initialization so that failover performance can be tested.
The R5IMAP Initialization workload creates and populates the IMAP mail file with
SMTP messages, initializes the mail file, and then converts it to IMAP.
The R6IMAP Initialization workload opens a mail database on the server and
populates the mail database. The template, MAIL6.NTF, that is used to create the
mail databases should be specified in the NOTES.INI variable MailTemplate. The
mail file is converted for IMAP use. The mail databases are populated with the
number of notes (messages) specified in the NOTES.INI variable
NumMailNotesPerUser.
Domino Web Access (iNotes Web Access) is our next generation Web client for
Web-based access to Domino messaging and Personal Information Management
(PIM) capabilities.

The iNotes Initialization workload creates a set of mail databases on the server and
populates them with mail. The mail databases are populated with the number of
notes (messages) specified in the NOTES.INI variable NumMailNotesPerUser.
NRPC Mail Initialization The NRPC Mail Initialization workload prepares for the R5 Simple Mail Routing
workload workload and the R6 Mail Routing workload. The NRPC Mail Initialization
workload creates the mail databases for the R5 Simple Mail Routing workload and
the R6 Mail Routing workload.
SMTP and POP3 Initialization The SMTP and POP3 Initialization workload prepares for the SMTP and POP3
workload workload by creating the mail databases for the SMTP and POP3 workload.
Web Mail Initialization the Web Mail Initialization workload prepares for the Web Mail workload by
workload creating the mail databases for the Web Mail workload.

Custom scripts
You can use the Server.Load command language to build a script from scratch, copy a built-in script and
modify it, or use a sample script. Then by modifying only test parameters and script variables, you can
further customize the script without changing the actual script code. Script variables are environmental
values that are referenced through the NOTES.INI file. Test parameters control the number and creation
of simulated users, or threads; the number of times the test runs for each user; and the test duration. If
you create a script from scratch, you can test each line of code by entering it in the command line. In
addition, using the command line, you can issue remote server console commands.

NotesBench
A related performance tool, NotesBench is a collection of benchmarks, or workloads, for evaluating the
performance of Domino servers. To learn more about NotesBench, go to http://www.notesbench.org.

Tips for running a Server.Load test

1. Consider the number of simulated users you plan to assign to the SUT and evaluate how that number
relates to system limitations, such as disk space and memory. Server.Load creates one thread per
simulated Notes user. If, for example, you assign 100 users to one client system, 100 threads will run
the test script. Note that all threads run the specified test concurrently.

1398 Lotus Domino Administrator 7 Help

2. Set the Thread Creation Interval parameter to stagger the creation of each user. For example, a value
of 2 staggers the creation of each user by 2 seconds.
3. Plan to enter values for the Starting Thread No. and Max No. of Users parameters. The values you
enter depend on how many client systems and database users the test is simulating. For example, to
simulate 400 database users across 4 client systems, with 100 users spread across the 4 clients specify
these values when you run the test on each client.

Client Max. No. of Users Starting Thread No.

1.00 100.00 1.00
2.00 100.00 101.00
3.00 100.00 201.00
4.00 100.00 301.00

4. Simulate the behavior of actual users by providing pauses between commands in your script. Use the
built-in scripts as a reference point.
5. Be aware of both ramp-up and steady state. Ramp-up state occurs after all threads run at least one
iteration of the script. Steady state represents the server’s true, sustainable performance with
reproducible results. Steady state occurs when the number of Notes users on the server is equal to the
total simulated users across all clients.

Server.Load test parameters

Before you run a Server.Load test, you can modify any of these parameters, which are located on the Test
Parameters tab.

Field Action
Max No. of Users Enter the number of simulated users. Default is 1. Maximum
value for this setting is 1500.
Note: To verify that a script is running properly, run the test
the first time with only one simulated user.

If you are running the test on multiple clients, increment the

value of the Max No. of Users parameter when you run the
test on each client.

The client should not run at anything higher than 75% to 85%
CPU. If the client is running at 100%, reduce the number of
users.
Script Loop Count Enter the number of times the script runs per simulated user.
Default is 1.

To calculate total iterations, multiply Script Loop Count by

Max. No. of Users.
Note: For long-duration tests, enter a large value, and specify
No Time Limit in the Test Time Parameter field.

If a test uses the ScriptIterationLimit script variable, set both

the variable and the Script Loop Count to the same value.
Thread Creation Interval (sec) Enter the rate, in seconds, at which simulated users are
created. Default is 1

To calculate total ramp-up time, multiply Thread Creation

Interval by Max. No. of Users.
Starting Thread No. Enter the thread number that will start the test. Default is 1.
Note: If you use multiple clients in a test, you must stagger
the starting thread number -- for example, client 1 starts at
thread 1; client 2 starts at thread 101, and so on.

Chapter 65. Using Server.Load 1399

Field Action
Test Time Parameter Choose one:
v No time limit (default) -- To run the test indefinitely.
v Run between two time periods -- To run the test between
Start and Stop times that you enter in standard format (1:00
PM) or military format (13:00).
v Specify Total Test Time -- To run the test for a specific
number of minutes.
Build Recipient List using Name and Address Book Click Browse and select the Domino Directory or Personal
Address Book to use when building a list of recipients of the
test results.
Storage test output to Click Browse to choose the location to store test output.

Running a custom Server.Load script

If you create a custom script, use these steps to run it.
1. On the Domino Administrator client, start Server.Load.
2. In the Test Type field, choose Custom. Then click Browse and select the script you want to add; to
view or edit the script, choose Edit Script.
3. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
4. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
5. Click Execute.
6. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
7. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
8. Click Start Test.

Modifying a built-in Server.Load script

Rather than build a script from scratch, modify a copy of a built-in script. For example, to test replication,
you can edit the R5 Simple Mail Routing script to include the Replicate command.
1. On the Domino Administrator client, start Server.Load.
2. In the Test Type field, choose Built-in, and then choose the script to modify.
3. Click View Script, and a window containing the script code appears.
4. Copy the script to a text editor.
5. Use the Server.Load commands to customize the script.
For more information, see the appendix ″Server.Load Commands.″
6. Save the script as a text file.

Saving Server.Load settings

If you run a workload more than once, and you often use the same settings when running the workload,
use the Save Settings option on the Server.Load File menu to save the settings that you want to reuse.

To save Server.Load workload settings:

1. Start Server.Load.
2. Enter values in the fields on the Lotus Server.Load dialog box to run the workload of your choice.

Note: For information about completing the fields on the Lotus Server.Load dialog box, see the
information that pertains to the workload you are configuring in this section of the documentation.

1400 Lotus Domino Administrator 7 Help

3. Choose File - Save Settings.
4. To run the workload, click Execute.

Testing a Server.Load command

Using the Command Line Screen, you can test an individual Server.Load command. The results of each
command appear in an output window.
1. On the client system, start Server.Load.
2. In the Test Type field, choose Manual.
3. Click the Command Line Screen tab, enter a Server.Load command or a server command in the
Command Line field, and click Submit.

Changing a Server.Load script variable

To further refine a test, you can change the default values of script variables. Within a script, each
variable appears enclosed in square brackets [ ]. Each variable must have a value. After you edit a test
variable, its corresponding setting in the NOTES.INI file changes.
1. From the main window, click the Script Variables tab.
2. Locate the row containing the variable to change, and click the leftmost column.
3. Double-click the value of the variable to activate Edit mode, and then enter the new value.
4. Click next empty variable row.
5. Open the script so that Server.Load acknowledges the change.

Setting a Server.Load stop condition

You can control what happens if the SUT fails to respond appropriately during a test.
1. From the main window, click the Stop Conditions tab.
2. Do one:
v Choose ″If Total Number of Timeouts Exceeds″ and then enter the number of timeouts after which
the test will stop.
v Choose ″If Average Response Time Exceeds (msec)″ and then enter a number, in milliseconds, after
which the test will stop.

Running the built-in Server.Load workloads

Server.Load contain numerous built-in workloads and initialization workloads.

Server.Load initialization workloads

v Cluster Mail Initialization workload
v R5IMAP Initialization workload
v R6IMAP Initialization workload
v iNotes Initialization workload
v NRPC Mail Initialization workload
v SMTP and POP3 Initialization workload
v Web Mail Initialization workload

Server.Load workloads
v Cluster Mail workload
v R5IMAP workload
v R6IMAP workload
v R5iNotes workload
v R6iNotes workload
v Idle workload

Chapter 65. Using Server.Load 1401

v R6 Mail Routing workload
v R5 Simple Mail Routing workload
v R5 Shared Database workload
v SMTP and POP3 workload
v Web Idle workload
v Web Mail workload
v Workload Data Collection
v Workload Data Rollup

Cluster Mail Initialization workload

The Cluster Mail Initialization workload creates a mail database on the server and populates the mail
database with a number of notes scaled to the SUT. The Cluster Mail Initialization and ClusterMail
workloads are based on the NRPC mail workloads, except the mail databases are created on two servers
during initialization so that failover performance can be tested.

The Cluster Mail Initialization test automatically creates and sets up the mail databases and establishes
the settings listed below:
v Database ACL settings
– Default user is provided with Manager access
– Anonymous user is provided with Manager access
v Owner set = mail#

Prerequisites:
v The appropriate mail templates must exist on the driver.
v Two clustered servers are required for this test -- a primary server and a second server to test mail file
failover performance when the primary server is unavailable.

Using the ″Create NotesBench Mail Person Documents″ Agent: Use the ″Create NotesBench Mail
Person Documents″ agent to create Person documents. It is stored in NAMAGENT.NSF.
1. Use the ″Create NotesBench Mail Person Documents″ NAMAGENT.NSF agent on any platform to
create Person documents that use the mail*.nsf files (created by Mail Initialization) on the SUT as the
users’ mail files. Copy NAMAGENT.NSF to the Domino Directory and run it from there. See the
Using this Database Document in NAMAGENT.NSF for more information about using the agents.
2. Replicate the Domino Directory with newly created users to the second test server.

NOTES.INI settings on the child client drivers:

Variable Action
MailServer Enter the canonical name of the mail server -- for example,
CN=MailServer1/O=Acme.
nb_dbdir Enter a database directory relative to the Notes data directory.
Recommended value is mail\.
MailTemplate Enter the name of the mail file template.
NumMailNotesPerUser Enter the number of notes used to populate the mail file when the
mail file is created. Recommended value is 100.
NormalMessageSize Enter the size of the body of the message. Recommended value is
10000.
ClusterServer2 Enter the canonical name of the second mail server -- for example,
CN=MailServer2/O=Acme.

1402 Lotus Domino Administrator 7 Help

Running the test:
1. Start Server.Load.
2. In the field, Select Script, choose Cluster Mail Initialization, and then click Execute.
3. When the workload has completed, verify that all mail files have been created on both servers.
4. Proceed to the Cluster Mail workload.

Cluster Mail workload

The Cluster Mail workload executes Notes transactions that model a cluster for mail users at sites relying
on a two-way Domino cluster for messaging.

The Cluster Mail workload script models an active user sending and reading mail on a client. It contains
an average of eight minutes of waiting; therefore, an average user executes this script no more than seven
times per hour. For each iteration of the script, there are five documents read, two documents added, two
documents deleted, one view-scrolling operation, one database opened and closed, one view opened and
closed, and some miscellaneous operations. One message is sent to the recipients approximately every 90
minutes.

Messages that each driver user sends are delivered to mail users in the cluster. The updates are then
cluster-replicated to all replica copies of the users’ database. The ClusterMail test models reading,
submitting, delivering, and retrieving messages. As such, the mail users must have a corresponding
$Person entry in the Domino Directories on clients and servers in order to receive mail. Run the agent,
″Create NotesBench Mail Person Documents,″ to create these entries.

Since simulated users are connecting to the cluster, instead of to a specific server, they generate their mail
from the server they are currently failed-over to. Each iteration of the script provides an opportunity for
the user to fail-over to a different node depending on the availability of specific node resources.

See Administering Domino Clusters for options in setting cluster operations, such as number of nodes, node
availability, threshold values, and Single Copy Object Store usage.

Metrics Used: The measurements obtained by this test include:

v Throughput of completed Notes operations
v Average response time at maximum capacity
v Maximum number of mail users supported

The resulting capacity metric for a cluster under test is the maximum number of users that can be
supported before the average user response time becomes unacceptable.

Test Initialization: Complete the following steps to prepare for running the test:
1. Perform all the required ″setup″ procedures that apply to your configuration for this test, including
setting up the NOTES.INI file and the destination servers.
2. On the SUT, start the Domino server. The router, replicator, and update server processes must be
started. You can run additional server programs at your discretion.
3. Run the workload Cluster Mail Initialization to create replicas on the clustered server defined by
[ClusterServer2] in the test driver’s NOTES.INI file. The tester determines how many, and on which
node, replicas should be placed.

NOTES.INI settings on the test driver for the ClusterMail test: Enter the following values in each
child’s NOTES.INI file.

Chapter 65. Using Server.Load 1403

Variable Action
NBTestReset Enter one of the following to designate how to handle
existing documents at the start of the test:
v 1 -- To delete existing documents
v 0 -- To ignore existing documents
Note: The number of documents deleted is dependent
on the value set for the variable MaxDocToDelete.
MaxDocToDelete Enter the number of documents to delete when the test
starts. After deleting documents, the initial document
count is high.
NumMessageRecipients Enter the number of recipients for each message.
Recommended value is 3.
NthIteration Enter the frequency for how often a message is sent,
instead of the message being sent on every script
iteration, the message is sent once per n iterations of the
script. Recommended value is 6.

R5IMAP Initialization workload

The R5IMAP Initialization workload creates and populates the IMAP mail file with SMTP messages,
initializes the mail file, and then converts it to IMAP.
1. Make sure that you have already set up clients and servers for Server.Load.
For information, see the topic ″Setting up clients and servers for Server.Load″ earlier in this chapter.
2. Run the ″Create NotesBench Mail Person Documents″ agent to create the desired number of Person
documents in the Domino Directory. When prompted, set these variables:

Variable Setting
Message storage format 2 (MIME)
Mail system 6 (POP3/IMAP)

3. On the Domino Administrator client, start Server.Load.

4. In the Test Type field, choose Built-In, and then choose R5 IMAP Initialization Workload from the
list.
5. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for example, CN=MailServer1/O=Acme.
MailTemplate Enter the name of the mail file template -- for example, MAIL6.NTF.
nb_dbdir Enter the directory used to store mail files, relative to the data directory.
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.
MessageLineSize Enter the number of characters per line. Recommended value is 80.
RecipientDomain Enter the name of the domain containing the intended recipients -- for example,
acme.com.
SMTPHost Enter the fully qualified domain name of the Domino server that is running the SMTP
Listener task -- for example, server1.acme.com
ClientHost Enter the fully qualified domain name of the client -- for example, client1.acme.com
NumMailNotesPerUser Enter the number of documents to populate the mail file when it is created.
Recommended value is 100.

6. Start the IMAP task on the server.

1404 Lotus Domino Administrator 7 Help

 7. In the ″Build Recipient List using Name and Address Book″ field, enter the name of the SUT and its
Domino Directory in the format servername/org!!dominodirectory.NSF -- for example,
Server1/Acme!!NAMES.NSF.
8. Verify that the client and server experience no errors while creating mail files. If a mail file has not
been created, the test script creates the mail file during the first test iteration, but this adds overhead
on the server back end. As a rule, CPU on the client and SUT should not exceed 75%, and the
percentage of Disk Time on the Domino Server Data directory should not be a factor.
9. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
10. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information about stop conditions, see the topic ″Setting a Server.Load stop condition″
earlier in this chapter.
11. Click Execute.
12. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
13. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
14. Click Start Test.
15. Verify that the correct number of test mail files were created in the data directory. Each mail file is
named MAILn.NSF, where n is a number.
16. Complete the procedure to run the R5IMAP workload.
For more information about the R5IMAP workload, see the topic ″R5IMAP workload″ in this chapter.

R5IMAP workload
The R5IMAP workload models an active IMAP mail user logging in once, then receiving and sending
mail. The script contains an average of 15 minutes of waiting, so an average user will execute this test no
more than four times an hour. For each iteration of the script, IMAP mail messages are retrieved, one
SMTP message is sent, and a number of LDAP lookup requests are executed based on the value of the
NumMessageRecipients script variable. The SMTP messages sent by each test user are delivered to the
mail databases of other test users on the SUT.

The measurements obtained by this test are:

v Throughput of completed Notes operations
v Average response time at maximum capacity
v Maximum number of IMAP mail users supported

The resulting capacity metric for an IMAP server is the maximum number of users that can be supported
before the average user response time becomes unacceptable.

Hardware considerations: The following hard disk requirements apply to the SUT and, during some
tests, to the destination systems that receive mail from the SUT:

Initial or subsequent disk

requirement
Initial Disk Requirement
Subsequent Disk Requirement
Description
In Domino 6 or more recent, approximately 13MB on the SUT for each user (mail
database). In Domino 5, approximately 5.5MB.
Increase of 1MB an hour for the duration of the test. (This figure is not dependent
on the number of users.)

Increase of 100KB an hour as impacted by the value of the nthIteration setting in

the NOTES.INI file.

The growth rate of each database is a function of the ratio of the number of users
and recipients sending and receiving mail.

Chapter 65. Using Server.Load 1405

Tips for running the R5IMAP Workload test:
1. Use these server commands.

Command Description
Show Task Show either the Database Server task (Notes clients) or
IMAP task (IMAP users).
Show Stat IMAP Monitor message counters
Show Stat Mail Monitor message counters
Show Stat SMTP Monitor SMTP statistics
Show Stat LDAP Monitor LDAP statistics

2. Use an IMAP client, such as Outlook, to verify that the IMAP and SMTP server tasks are set up
correctly.
3. To minimize environment troubleshooting, put IP information -- for example, host information -- in
the \etc\hosts file or its equivalent on the SUT and driver directories.
4. From the SUT console, enter this command to display additional routing information:
Set Config Log_MailRouting=40

Running the R5 IMAP workload:

1. Make sure that you already completed the procedure to run the R5IMAP Initialization workload.
For more information about the R5IMAP Initialization workload, see the topic ″R5IMAP Initialization
workload″ in this chapter.
2. In the NOTES.INI file on the SUT, verify that the Server Tasks setting includes both IMAP and
LDAP.
3. On the Basics tab of the Server document for the SUT, make sure that the SMTP Listener Task is
enabled.
4. For optimal performance, create a Configuration Settings document in the Domino Directory and do
the following:
a. Set the ″Optimize LDAP queries″ field to Yes.
b. On the Router/SMTP Basics tab, set the ″Number of mailboxes field,″ to 2 or higher.
5. On the Domino Administrator client, start Server.Load.
6. In the Test Type field, choose Built-In, and then choose R5 IMAP workload from the list.
7. In the ″Build Recipient List using Name and Address Book″ field, enter the name of the SUT and its
Domino Directory in the format servername/org!!dominodirectory.NSF -- for example,
Server1/Acme!!NAMES.NSF.
8. Click the Test Parameters tab, and do the following:
a. For ″Thread Creation Interval,″ enter the rate, in seconds, at which simulated users are created.
The recommended value is 3 to 5 seconds.
b. If you are running the test on multiple clients, increment the value of the Starting Thread No.
parameter when you run the test on each client.
9. Click the Script Variables tab, and enter these values:

Variable Action
R5IMAPBreak Enter one of these:
v 1 -- To prevent the script from quitting if errors occur
v 0 -- To force the script to quit if errors occur

1406 Lotus Domino Administrator 7 Help

Variable Action
IMAPHost Enter the fully-qualified domain name of the SUT -- for example,
server1.acme.com
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.
MessageLineSize Enter the number of characters per line. Recommended value is 80.
NumMessageRecipients Enter the number of recipients for each message. Recommended value is 3.
RecipientDomain Enter the name of the domain containing the intended recipients -- for
example, acme.com.
SMTPHost Enter the fully-qualified domain name of the Domino server that is running
the SMTP Listener task -- for example, server1.acme.com
ClientHost Enter the fully-qualified domain name of the client -- for example,
client1.acme.com
NthIteration Enter the frequency for how often a message is sent. Instead of the message
being sent on every script iteration, the message is sent once per n iterations
of the script. Recommended value is 6.
R5IMAP_Loop_N Enter the number of times the inner loop of the script runs. Recommended
value is 35, resulting in approximately an 8-hour duration.
ScriptIterationLimit Enter the number of times the outer loop of the script runs. Recommended
value is 1.

10. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
11. Click Execute.
12. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
13. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
14. Click Start Test.

R6IMAP Initialization workload

The R6IMAP Initialization workload opens a mail database on the server and populates the mail
database. The template, MAIL6.NTF, that is used to create the mail databases should be specified in the
NOTES.INI variable MailTemplate. The mail file is converted for IMAP use. The mail databases are
populated with the number of notes (messages) specified in the NOTES.INI variable
NumMailNotesPerUser.

The R6IMAP Initialization workload automatically creates and sets up the mail databases and establishes
the settings listed below:
v Database ACL settings
– Default user is provided with Manager access
– Anonymous user is provided with Manager access
v Owner set = mail#

The MAILINIT workload opens a mail database on the server, populates the mail database, opens a
discussion database, and then populates the discussion database with a number of notes scaled to the
SUT.

Prerequisites:
v The mail template, MAIL6.NTF, must exist on the driver.
v All user passwords must be set to NotesBench because authenticated users are required.

Chapter 65. Using Server.Load 1407

Using the ″Create NotesBench Mail Persons Documents″ Agent: The agent that you use to create
Person documents is in NAMAGENT.NSF.
1. Run R6IMAPINIT to create the mail databases.
2. Use the ″Create NotesBench Mail Person Documents″ NAMAGENT.NSF agent on any platform to
create Person documents that use the R6IMAPINIT mail*.nsf files on the SUT as the users’ mail files.
Copy NAMAGENT.NSF to the Domino Directory and run it from there.

Running the R6IMAP Initialization workload:

1. Start Server.Load.
2. In the Select Script field, choose R6IMAP Initialization and then click Execute.

R6IMAP workload
The R6IMAP workload executes Domino transactions that model a server for mail users at sites that rely
on IMAP mail for communication. Not only does this test stress the IMAP protocol by receiving mail
messages, but also exercises SMTP and LDAP by sending SMTP messages to a number of recipients and
performing LDAP lookups on those recipients.

The R6IMAP workload models an active user retrieving and sending mail. An average user executes this
script no more than four times per hour. For each iteration of the script, there is a retrieval of IMAP mail
messages, one SMTP message sent, and ’n’ LDAP lookup requests based on the variable,
NumMessageRecipients. In sending messages, each user sends a mail message to NumMessageRecipients
not more than once every 15 minutes.

The SMTP messages sent by each driver user are delivered to the mail databases of other driver users on
the SUT.

Note: The R6IMAP workload makes use of the SMTP and LDAP protocols in addition to IMAP.

System information: A Notes client can run 1500 user threads per 512 MB driver. With less memory, the
number of threads must be decreased. You can experiment to see what the CPU and memory usage is on
your particular drivers for a given number of threads.

The number of users that can be supported by a server is limited by memory. On UNIX it is 4 GBs.

On an 8way Intel® Xeon(TM), Microsoft Windows server the resource limitation is often memory. The
maximum memory that the server can use is approximately 2.3GBs.

Domino SSL in the Server.Load R6IMAP workload: The Secure Socket Layer (SSL) is enabled for the
R6IMAP workload. Add the NOTES.INI setting, NB_SSL_OPTION=USE_SSL, to the client driver’s
NOTES.INI file to enable SSL. For example,
NB_SSL_OPTION=USE_SSL

To disable SSL in the R6IMAP workload, remove the NOTES.INI setting.

Time Requirements: The time required to run this test is six hours, minimum, after steady state verified.

Metrics: This test measures:

v Throughput of completed IMAP, LDAP, and SMTP operations
v Average response time at maximum capacity
v Maximum number of IMAP mail users supported

The capacity metric for an SMTP/IMAP server is the maximum number of users that can be supported
before the average user-response time becomes unacceptable.

Requirements:

1408 Lotus Domino Administrator 7 Help

v System under test (SUT)

Test Initialization:
1. Perform all the required ″setup″ procedures that apply to your configuration for this test, including
setting up the NOTES.INI file and the destination servers.
2. Run the R6IMAP Initialization workload to initialize and convert to IMAP mail files.
For information about the R6IMAP Initialization workload, see the topic ″R6IMAP Initialization
workload″ in this chapter.
For information about the IMAP service, see the chapter ″Setting Up the IMAP Service.″

Creating mail databases: Use the R6IMAP initialization workload to initialize the first database for
Domino 6 or use the IMAPINIT workload for Domino R5. Make sure that the latest MAIL6.NTF
(MAIL5.NTF for R5) is copied to the test driver before you create the first database and that the mail
template NOTES.INI setting is set on the child.

After you create your first mail database, open the database by performing a File - Open from the Notes
client or by using Microsoft Outlook®. Opening the database initializes several database fields and uses
less memory per user during the test.

NOTES.INI settings for the test driver for the R6IMAP workload: The following is an example of the
NOTES.INI settings for the test driver:

NormalMessageSize=10000

MailRecipientPercentUser=50

MailRecipientPercentVolume=50

MailRecipientBeginNumber=1

MailRecipientEndNumber=2000

; EndNumber should be set to maximum entries in Domino Directory

R5IMAP_loop_N=1000 (set to 56 to exit out of loop in 8 hours.)

NthIteration=6

ClientHost=hostname_of_the_client

SMTPHost=hostname_of_your_SMTP_server_under_test

LDAPHost=hostname_of_your_LDAP_server_under_test

IMAPHost=hostname_of_your_IMAP_server_under_test

RecipientDomain=name_of_your_domain

MessageLineSize=100

NumMailNotesPerUser=100

NumMessageRecipients=3

Chapter 65. Using Server.Load 1409

NOTES.INI settings for the R6IMAP SUT: The following are examples of the settings that can be
added to the server’s NOTES.INI file:

view_rebuild_dir=l:\temp\

Debug_Outfile=g:\server_debug\server_grigsby2k.txt

Server_Show_Performance=1

Mail_Number_of_mailboxes=2 (can be set in the Server document)

ServerTasks=Router,IMAP,LDAP

IMAP_Session_Timeout=60

Log_mailrouting=20. Set to 20 for minimal logging, or to 10 for no logging (minimizes logging while
testing). Set to 40 to display additional routing information on the console; for example, to verify that
messages are being routed by the Router and MTA tasks.

Note: The MailRecipientPercentUser and the Mail RecipientPercentVolume settings impact each other. If
MailRecipientPercentUser=20 and Mail RecipientPercentVolume=80, 80 percent of the messages are
addressed to 20 percent of the users.

Special instructions for the R6IMAP workload:

1. On the SUT, edit the Server document - Basics tab as follows, and then save and close the document.

Field Setting
Routing Tasks Select Mail Routing.
SMTP listener task Enable this setting.
Fully-qualified Internet host name For example, servername.iris.com

2. Open the Server Configuration document and click Edit document.

3. On the Basics tab, locate the field ″International MIME setting for this document,″ and click Enabled.
4. Edit the Router/SMTP tab as follows and then save and close the document.

Field Setting
SMTP used when sending message outside of the local Enable this setting.
Internet domain
SMTP allowed within the local Internet domain Select ″All messages″
Servers within the local Notes domain are reachable via Select ″Always″
SMTP over TCPIP
SMTP allowed within the local Internet domain Select ″MIME messages only″

Running the R6IMAP workload:

Note: Clear the memory on the client (reboot) before the start of this test.

Complete these steps to run the R6IMAP test.

1. If you have not already created mail databases, do so now using the R6IMAP Initialization workload.
2. On the SUT start the Domino server. The router, IMAP, LDAP, and SMTP server processes must be
started. You can run additional server programs at your discretion.

1410 Lotus Domino Administrator 7 Help

3. At the end of the test, Issue a SH STAT command at the SUT console prior to exiting the Domino
server.

Client Setup: Use the Lotus Notes 6 client for best results.

Open the Location document and modify these fields:

v On the Servers tab, in the home/mail server field, enter the server name followed by the domain
name. For example, Servername/IrisTS.
v On the Basics tab, enter the Internet mail address, for example, testnsf@servername.iris.com in the
Internet mail address field.

iNotes Initialization workload

Domino Web Access (iNotes Web Access) is our next generation Web client for Web-based access to
Domino messaging and Personal Information Management (PIM) capabilities.

The iNotes Initialization workload creates a set of mail databases on the server and populates them with
mail. The mail databases are populated with the number of notes (messages) specified in the NOTES.INI
variable NumMailNotesPerUser.

The iNotesInit test automatically creates and sets up the mail databases for the R5iNotes and R6iNotes
workloads and establishes the settings listed below:
v Database ACL settings
– Default user is provided with Manager access
– Anonymous user is provided with Manager access
v Owner set = mail#

Using the ″Create NotesBench Mail Persons Documents″ Agent: The agent that you can use to create
Person documents is in NAMAGENT.NSF.
1. Use the ″Create NotesBench Mail Person Documents″ NAMAGENT.NSF agent on any platform to
create Person documents that use the mail*.nsf files (created by iNotes Initialization) on the SUT as
the users’ mail files. Copy NAMAGENT.NSF to the Domino Directory and run it from there. See the
Using this Database document for more information about the agents in NAMAGENT.NSF.

Running the test:

1. Run iNotesInit to create the mail databases.
2. When the workload is complete, verify that all mail files have been created.
3. Run one of these tests:
The R6iNotes test, as detailed in the topic ″The R6iNotes workload″ in this chapter.
The R5iNotes test, as detailed in the topic ″The R5iNotes workload″ in this chapter.

R5iNotes workload
Domino Web Access (iNotes Web Access) is our next generation Web client for Web-based access to
Domino messaging and Personal Information Management (PIM) capabilities.

The R5iNotes workload represents an active user sending, retrieving, and deleting mail from a browser.
An average user runs this script four times an hour. Each time the script runs, it checks and retrieves
mail messages. Additionally, on each NthIteration, which is one time in six for this workload, the user
sends a mail message to NumMessageRecipients other users on the server. The user schedules an
appointment, sends invitations to NumMessageRecipients other users, and responds to one invitation that
it finds in its own inbox.

Metrics: This test measures:

v Throughput of completed HTTP operations

Chapter 65. Using Server.Load 1411

v Average response time at maximum capacity
v Maximum number of R5iNotes users supported before the average user response time becomes
unacceptable

Special considerations for this workload:

v The iNotes5 template (INOTES5.NTF) is available with the server, and must reside on the server in
order to work correctly.
v After users and mail files are created, run the ″Update ACL of Mail Dbs to include Owner mail1,
mail2,″ agent on the Domino Directory of the SUT to update the ACL of the mail databases. The owner
of the mail database must be named in the ACL.

NOTES.INI settings for the Notes client driver for the R5iNotes workload: Select the Script Variables
pane and then complete these fields:

Script Values Value to enter

MailServer Canonical Name of MailServer (for example, CN=MailServer1/O=Acme).
The MailServer line in the NOTES.INI is automatically updated when
editing the Location document.
nb_dbdir Database directory relative to the Notes data directory. To have all mail
files created in the data\mail\ directory set nb_dbdir=mail\. To have mail
files created in the data directory, enter a space.
ServerName!!MailTemplate Pointer to the template that resides on the server used for mail file
creation. For example, Servername/Acme!!inotes5.ntf
NumMailNotesPerUser Number of notes with which to populate the mail file upon creation. The
recommended value is 100.
NBTest Reset Define the variable to delete existing documents at the start of a test.
Possible values are:
v NBTestReset=1 -- To delete existing documents at the start of the test
v NBTestReset=0 -- To ignore existing documents at the start of a test

The number of documents deleted is dependent on the value set for the
variable MaxDocToDelete.
httphost The TCP/IP address or Hostname of the Domino Web Server.
NormalMessageSize Size of the body of the message. The recommended value is 10000.
Domain Notes Mail Domain Name of the Domino Server. For example, Acme.
Note: This value must match the value in the Mail Domain field of the
Location document on the client.

Setting up the Domino server for the R5iNotes workload:

1. Use Domino Designer to copy all agents from the database Server.Load Setup agents to the agents
view of the Domino Directory of the SUT.
See the ″Using This Database″ document of the Server.Load Setup Agents database for more
information about these agents.
2. Open the Domino Directory of the test server and run the agent Create NotesBench Person
Documents. In addition to creating the Person documents, this agent also sets the HTTP password.
3. Accept the default settings for the agent except where indicated in the table.

Setting Use this value

Starting value to Create Mail users 1 (the default value)
Number of Users to Create Enter the total number of test users you are creating. The
default = 1000.

1412 Lotus Domino Administrator 7 Help

Setting Use this value
Number of Mailn.NSF files to use Enter the total number of mail database files you are
creating. This is the same value as the value in the field
″Number of Users to Create.″ The default = 1000.
Starting Mailn.NSF file 1 (the default value)
Location for Mail Databases This value must match the value for nb_dbdir script
variable. Default = mail\
Mail Domain Default: Read from the server’s mail domain
Mail Server Default: Name of the server on which the Domino
Directory resides.
Message Storage Format 1 -- No preference
Mail System To select POP or IMAP, enter a value of 6. Default = 1
Internet Host name Default: Hostname of the server on which the Domino
Directory resides.

Server document settings for the R5iNotes workload: The Server document in the SUT’s Domino
Directory requires these settings:
v On the Basics tab in R5, or the Security tab in Lotus Domino 6 or more recent, enter the name of the
administrator in the ″Administrator″ field.
v On the Basics tab in R5 or the Internet Protocols tab in Domino 6 or more recent, in the field ″Optimize
HTTP performance based on the following primary activity″ choose Advanced (Custom Settings). This
field allows you to view/modify the number of HTTP threads and is usually set during installation.
The optimum setting for the number of HTTP threads requires some experimentation. On a large
machine, begin with the value of 100, then adjust up or down, accordingly.
v For Lotus Domino 6 or more recent, on the Internet Protocols - HTTP tab, locate the Timeouts section.
In the field ″HTTP Persistent Connections″ choose Disable.

NOTES.INI settings for the SUT: Open the NOTES.INI file on the SUT, and verify that HTTP is
included in the Server Tasks. To display additional data on the console, in the NOTES.INI file, use the
setting Log_MailRouting=40.

Access Rights settings: Open the ACL for the Domino Directory and ensure that the person designated
as administrator in the Server document is also designated Manager.

Running the R5iNotes workload: Be sure mail databases are available.

1. On the SUT, start the Domino server. The Router, Update, IMAP, LDAP, and SMTP server tasks must
be running. You can run additional server tasks if you wish.
2. Verify that iNotes mail files have been created. if not, create them now.
3. On the console at the SUT, enter a SH STAT command prior to exiting the Domino server at the end
of the test.

R6iNotes workload
Domino Web Access (iNotes Web Access) is our next generation Web client for Web-based access to
Domino messaging and Personal Information Management (PIM) capabilities.

The R6iNotes test represents an active user sending, retrieving, and deleting mail from a browser. An
average user runs this script four times an hour. Each time the script runs, it checks and retrieves mail
messages. Additionally, on each NthIteration, which is one time in six for this workload, the user sends a
mail message to NumMessageRecipients other users on the server. The user schedules an appointment,
sends invitations to NumMessageRecipients other users, and responds to one invitation that it finds in its
own inbox.

Chapter 65. Using Server.Load 1413

Metrics: This test measures:
v Throughput of completed HTTP operations
v Average response time at maximum capacity
v Maximum number of R6iNotes users supported before the average user response time becomes
unacceptable

Test Initialization: This test requires the following:

v Perform all the required ″setup″ procedures that apply to your configuration for this test, including
setting up the NOTES.INI file and the destination servers.

The console does not display Web users because they do not update the same counters as Notes clients.
Notes clients use the Database Server task, and Web users use the HTTP task. Use the show task
command to display each task at the server console.

To determine if mail is being delivered to the server, use this command at the console:
show stat Domino.Requests.*

To monitor message counters, use one of these commands at the console:

show stat HTTP
show stat mail

If authentication errors appear at the console, check that the password in the HTTP field of the Person
document in the Domino Directory on the SUT is set to NotesBench. If necessary, edit the Person
document in the Domino Directory. Use the agent ″Set HTTP Password to ’NotesBench’.″

Ensure that the mail template is compatible with the Domino release you are running. For Domino
Release 6, use the template iNotes6.NTF. In the NOTES.INI file of the test driver, enter Set
MailTemplate=iNotes6.NTF.

To display routing information on the console, include Log_MailRouting=40 in the NOTES.INI file on the
SUT.

Special Considerations for this workload:

v The iNotes6 template, INOTES6.NTF, is available with the server, and must reside on the server in
order to work correctly.
v After users and mail files are created, run the ″Update ACL of Mail Databases to include owner″ agent
on the Domino Directory of the SUT to update the ACL for the mail databases. The owner of the mail
databases must be named in the ACL.

Server document settings for the R6iNotes test: In the Server document, use these settings:
v In the ″Administrator″ field on the Basics tab, enter the administrator’s name, that is, the name of the
user that has been defined as the administrator. If you do not include the administrator’s user name,
any server commands issued by Probe are rejected.
v On the Internet Protocols - HTTP tab, set ″HTTP Persistent connections″ to ″Disabled.″
v On the Internet Protocols - HTTP tab (R5 Basics section), set the field ″Optimize HTTP performance
based on the following primary activity″ to Advanced (Custom Settings). This setting allows you to
view/modify the number of HTTP threads and is usually set during installation.

NOTES.INI settings for the R6iNotes test SUT: Check these NOTES.INI file settings:
v Verify that the Server Tasks setting in the NOTES.INI file on the SUT includes HTTP.
v The optimum setting for the number of HTTP threads requires some experimentation. Start with a
value of 100 on a large machine and adjust this up or down until you obtain the best results.

1414 Lotus Domino Administrator 7 Help

Access rights: The user that you designate as the administrator must have Manager access to the
Domino Directory in that directory’s ACL.

Authentication:
v By default, R6iNotes assumes that user authentication is required. For authenticated users, ACLs for all
mail databases and the Domino Directory must specify Manager access for the - Default - user. In the
NOTES.INI file of the test drivers and Probe, use the WebAuthenticationOff=0 (or not defined) setting.
v On the Agent Restrictions section of the Server document - Security tab, set the values of the following
properties to * (wildcard character).
– Run restricted LotusScript/Java agents
– Run unrestricted LotusScript/Java agents
v This allows anonymous users to run restricted Lotus Script/Java agents and run unrestricted Lotus
Script/Java agents.

Running the R6iNotes workload: R6iNotes requires authenticated users.

1. Create mail databases with the iNotesInit workload.
For information about the iNotes Initialization workload, see the topic ″iNotes Initialization workload″
in this chapter.
2. For authenticated users add each user to the ACL in their mail file. To do so, use the agent ″Update
ACL of mail dbs to include owner (mail1, mail2, ...)″ from the NAMAGENT.NSF.
3. Enter the SH STAT command at the SUT console before exiting the Domino server at the end of the
test.

NRPC Mail Initialization workload

Use the NRPC Mail Initialization workload to prepare for the R5 Simple Mail Routing workload and the
R6 Mail Routing workload. The NRPC Mail Initialization workload creates the mail databases for the R5
Simple Mail Routing workload and the R6 Mail Routing workload.
1. Make sure that you already set up clients and servers for Server.Load.
For information, see the topic ″Setting up clients and servers for Server.Load″ earlier in this chapter.
2. On the Domino Administrator client, start Server.Load.
3. Run the ″Create NotesBench Mail Person Documents″ agent to create the desired number of Person
documents in the Domino Directory. When prompted, set these variables:

Variable Setting
Message storage format 0 (NOTES)
Mail system 1 (NOTES)

4. In the Test Type field, choose Built-In, and then choose NRPC Mail Initialization Workload from the
list.
5. Click the Test Parameters tab, and do the following:
a. For ″Thread Creation Interval,″ enter the rate, in seconds, at which simulated users are created.
The recommended value is 3 to 5 seconds.
b. If you are running the test on multiple clients, increment the value of the Starting Thread No.
parameter when you run the test on each client.
6. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for example, CN=MailServer1/O=Acme.
nb_dbdir Enter a database directory relative to the Notes data directory. Recommended value is
mail\.

Chapter 65. Using Server.Load 1415

Variable Action
MailTemplate Enter the name of the mail file template.
NumMailNotesPerUser Number of notes used to populate the mail file when the mail file is created
(recommended value is 100)
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.

7. In the ″Build Recipient List using Name and Address Book″ field, enter the name of the SUT and its
Domino Directory in the format servername/org!!dominodirectory.NSF -- for example,
Server1/Acme!!NAMES.NSF.
8. Verify that no errors occur while creating mail files on the client and SUT. If a mail file is not
created, the test script creates the mail file during the first test iteration, a process that adds
overhead on the server back end. As a rule, CPU on the client and SUT should not exceed 75%, and
the percentage of disk time on the server’s data directory should not be a factor.
9. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
10. Click Execute.
11. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
12. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
13. Click Start Test.
14. Verify that the correct number of test mail files were created in the data directory. Each mail file is
named MAILn.NSF, where n is a number.
15. Complete the procedure to run the R5 Simple Mail Routing workload or the R6 Mail Routing
workload.
For information about running the R5 Simple Mail Routing workload and the R6 Mail Routing
workload, see the topics ″R5 simple Mail Routing workload″ and ″R6 Mail Routing workload″ in this
chapter.

R5 Simple Mail Routing workload

The R5 Simple Mail Routing workload models an active Notes mail user receiving and sending mail,
composing and sending meeting invitations, and scheduling appointments. The script contains an average
of 15 minutes of waiting; therefore, an average user runs this test no more than four times an hour.

For each iteration of the script, five documents are read, two documents are updated, two documents are
deleted, one view is opened and closed, one view-scroll is performed, one database is opened and closed,
and several other operations are performed. One message is sent to each active user approximately every
96 minutes; the same frequency is used for appointments and invitations.

Because mail routing and delivery are performed on the SUT, locate the destination addresses and the
active users’ mail files on the SUT.

Metrics: The measurements obtained by this test are:

v Throughput of completed Notes operations
v Average response time at maximum capacity
v Maximum number of mail users supported

The resulting capacity metric for a mail-only server is the maximum number of users that can be
supported before the average user response time becomes unacceptable.

Hardware considerations: The following hard disk requirements apply to the SUT and, during some
tests, to the destination systems that receive mail from the SUT:

1416 Lotus Domino Administrator 7 Help

Initial or subsequent disk
requirement
Initial Disk Requirement
Subsequent Disk Requirement
Description
In Domino 6 or more recent, approximately 13MB for each user (mail database). In
Domino R5, approximately 7.5MB.
Increase of 80KB for each user, per hour.

The R5 Simple Mail Routing test requires at least one client and the SUT. If you use multiple client
systems, identical hardware configurations are recommended.

Running the R5 Simple Mail Routing test:

1. Make sure that you have already completed the procedure to run the NRPC Mail Initialization
workload.
For information about the NRPC Mail Initialization workload, see the topic ″NRPC Mail
Initialization workload″ earlier in this chapter.
2. On the SUT, do the following:
a. Start the Calendar Connector task (Calconn).
b. In the Configuration Settings document on the Router/SMTP Basics tab, set the field ″Number of
mailboxes″ to 2 or higher.
3. In the Test Type field, choose Built-In, and then choose R5 Simple Mail Routing test from the list.
4. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
5. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for example, CN=MailServer1/O=Acme.
nb_dbdir Enter a database directory relative to the Notes data directory. Recommended value is
mail\.
MailTemplate Enter the name of the mail file template.
NBTestReset Enter one of these to control how to handle existing documents at the start of the test:
v 1 -- To delete existing documents
v 0 -- To ignore existing documents
Note: The number of documents deleted is dependent on the value set for the variable
MaxDocToDelete.
MaxDocToDelete Enter the number of documents to delete when the test starts. After deleting
documents, the initial document count is reset.
NumMailNotesPerUser Number of notes used to populate the mail file when the mail file is created
(recommended value 100)
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.
NumMessageRecipients Enter the number of recipients for each message. Recommended value is 3.
NthIteration Enter the frequency for how often a message is sent. Instead of the message being sent
on every script iteration, the message is sent once per n iterations of the script.
Recommended value is 6.
ScriptIterationLimit Enter the number of times the outer loop of the test script runs. Recommended value
is 1. This value must match the value in the Script Loop Count field on the Test
Parameters tab.

6. (Optional) Click the Stop Conditions tab to set a stop condition.

For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
7. Click Execute.
Chapter 65. Using Server.Load 1417
 8. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
9. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
10. Click Start Test.

R6 Mail Routing workload

The R6Mail Routing workload models an active user on a client reading and sending mail, using the
calendar and scheduling features to schedule an appointment, send an invitation, and send an RSVP to
an invitation. An average user will run this script four times per hour. Each script iteration reads five
documents, updates two documents, deletes two documents, scrolls a view once, opens and closes one
database, opens and closes one view, sends one memo to three recipients, and does three lookups on the
Domino Directory (when NthIteration=6). Every 90 minutes, the test schedules one appointment and
sends one invitation to the recipients. There are server name lookups, and messages are deposited in the
SUT mailbox.

Metrics: This test measures:

v Throughput of completed Notes operations
v Average response time at maximum capacity
v Maximum number of mail users supported

The resulting capacity metric for a mail-only server is the maximum number of users that can be
supported before the average user response time becomes unacceptable.

Requirements:
v System under test (SUT)

Test Initialization: If you have not already created mail databases, do so before running the test. Use the
NRPC Mail Initialization workload to create the mail files.

For information on the NRPC Mail Initialization workload, see the topic ″NRPC Mail Initialization
workload″ in this chapter.

NOTES.INI Settings for the test driver for R6Mail: The following is an example of the NOTES.INI
settings for the test driver:

NormalMessageSize=10000

MailServer=server/domain

MailTemplate=mail6.ntf

NthIteration=6

NumMessageRecipients=3

NumMailNotesPeruser=100

(optional)

NBTestReset=1

MaxDocToDelete=1000000

NOTES.INI settings for the R6 Mail SUT:

1418 Lotus Domino Administrator 7 Help

v Log_MailRouting. Set to 20 for minimal logging, or to 10 for no logging (minimizes logging while
testing.) Set it to 40 to display additional routing information on the console; for example, to verify that
messages are being routed by the Router and MTA tasks.
v ServerTasks. Specify Router, IMAP, and LDAP.
v IMAP_Session_Timeout. Set to 60.

Other suggested SUT settings include:

Mail_Number_Of_MailBoxes=2

Max_Users=10100

NSF_DBcache_Maxentries=10100

Server_Pool_Tasks=100

Server_Max_Concurrent_Trans=1000

MAILLOGTOEVENTSONLY=1

LOG_SESSIONS=0

LOG_MAILROUTING=10

SERVER_SHOW_PERFORMANCE=1

MAILUSERPROCESSES=0

No_Force_Activity_Logging=1

Server document settings for the R6 Mail Routing test: Be sure that the Basics tab of the Server
document uses these settings:
v Routing tasks: Mail Routing, SMTP Mail Routing
v SMTP listener task: Enabled
v Fully Qualified Internet host name: servername.company.com

Running the R6 Mail Routing test:

1. Make sure that you already completed the procedure to run the NRPC Mail Initialization workload.
For information about the NRPC Mail Initialization workload, see the topic ″NRPC Mail
Initialization workload″ earlier in this chapter.
2. On the SUT, do the following:
a. Start the Calendar Connector task (Calconn).
b. In the Configuration Settings document on the Router/SMTP Basics tab, set the field ″Number of
mailboxes″ to 2 or higher.
3. In the Test Type field, choose Built-In, and then choose R6 Mail Routing test from the list.
4. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
5. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for example,
CN=MailServer1/O=Acme.

Chapter 65. Using Server.Load 1419

Variable Action
nb_dbdir Enter a database directory relative to the Notes data directory. Recommended
value is mail\.
MailTemplate Enter the name of the mail file template.
NBTestReset Enter one of these to control how to handle existing documents at the start of
the test:
v 1 -- To delete existing documents
v 0 -- To ignore existing documents
Note: The number of documents deleted is dependent on the value set for the
variable MaxDocToDelete.
MaxDocToDelete Enter the number of documents to delete when the test starts. After deleting
documents, the initial document count is reset.
NumMailNotesPerUser Number of notes used to populate the mail file when the mail file is created
(recommended value 100)
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.
NumMessageRecipients Enter the number of recipients for each message. Recommended value is 3.
NthIteration Enter the frequency for how often a message is sent. Instead of the message
being sent on every script iteration, the message is sent once per n iterations of
the script. Recommended value is 6.
NB_Mail_FT_Search_Enabled Set this variable to ″Enabled″ to enable full text search while the workload is
running.
ScriptIterationLimit Enter the number of times the outer loop of the test script runs. Recommended
value is 1. This value must match the value in the Script Loop Count field on
the Test Parameters tab.

6. (Optional) Click the Stop Conditions tab to set a stop condition.

For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
7. Click Execute.
8. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
9. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
10. Click Start Test.

SMTP and POP3 Initialization workload

1. Make sure that you already set up clients and servers for Server.Load.
For information about setting up clients and servers for Server.Load, see the topic ″Setting up clients
and servers for Server.Load″ earlier in this chapter.
2. Run the Create NotesBench Mail Person Documents agent to create the desired number of Person
documents in the Domino Directory. When prompted, set these variables:

Variable Setting
Message storage format 2 (MIME)
Mail system 6 (POP3/IMAP)

3. On the Domino Administrator client, start Server.Load.

4. In the Test Type field, choose Built-In, and then choose SMTP and POP3 Initialization Workload from
the list.

1420 Lotus Domino Administrator 7 Help

 5. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for
example, CN=MailServer1/O=Acme.
nb_dbdir Enter a database directory relative to the Notes data
directory. Recommended value is mail\.
MailTemplate Enter the name of the mail file template.

6. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
7. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
8. Click Execute.
9. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
10. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
11. Click Start Test.
12. Verify that the correct number of test mail files were created in the data directory. Each mail file is
named MAILn.NSF, where n is a number.
13. Complete the procedure to run the SMTP and POP3 workload.
For more information about running the SMTP and POP3 workload, see the topic ″SMTP and POP3
workload″ later in this chapter.

SMTP and POP3 workload

The SMTP and POP3 workload models an active user receiving and sending mail over SMTP and POP3.
The script contains an average of 10 minutes of waiting, so an average user will run this test no more
than six times an hour.

During each iteration, the script checks for and retrieves POP3 messages. When sending messages, each
user sends a mail message to NumMessageRecipients not more than once every 20 minutes. Twenty
percent of the users receive eighty percent of the send mail messages. The SMTP messages sent by each
user are delivered to the mail databases of other users on the SUT.

Metrics: The measurements obtained by this test are:

v Throughput of completed Notes operations
v Average response time at maximum capacity
v Maximum number of SMTP/POP3 mail users supported

The resulting capacity metric for an SMTP/POP3 server is the maximum number of users that can be
supported before the average user response time becomes unacceptable.

To read the code in the test script, see the appendix ″Server.Load Scripts.″

Hardware considerations: The following hard disk requirements apply to the SUT and, during some
tests, to the destination systems that receive mail from the SUT:

Initial or subsequent disk

requirement Description
Initial disk requirement In Domino 6 or more recent, approximately 11.5MB on the SUT for each user (mail
database). In Domino 5, approximately 7.5MB.

Chapter 65. Using Server.Load 1421

Initial or subsequent disk
requirement Description
Subsequent disk requirement Increase of 100KB per hour for the duration of the test. This figure is not dependent
on the number of users.

Tips for running the SMTP/POP3 test:

1. To minimize environment troubleshooting, put IP information -- for example, host information -- in
the \etc\hosts file or its equivalent on the SUT and driver directories.
2. If authentication errors occur on the Domino server console, verify the password in the HTTP field of
the respective user’s Person document in the SUT’s Domino Directory; edit the Domino Directory if
necessary.
3. From the SUT console, enter this command to display additional routing information:
Set Config Log_MailRouting=40

Running the SMTP and POP3 Workload test:

1. Make sure that you already completed the procedure to run the SMTP and POP3 Initialization
workload.
For more information on running the SMTP and POP3 Initialization workload, see the topic
″Running the SMTP and POP3 Initialization workload″ in this chapter.
2. Run the ″Create NotesBench Mail Person Documents″ agent to create the desired number of Person
documents in the Domino Directory.
3. On the Domino Administrator client, start Server.Load.
4. In the Test Type field, choose Built-In, and then choose SMTP and POP3 Workload from the list.
5. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
6. Click the Script Variables tab, and enter these values:

Variable Action
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.
MessageLineSize Enter the number of characters per line. Recommended value is 80.
NumMessageRecipients Enter the number of recipients for each message. Recommended value is 3.
SMTPHost Enter the fully qualified domain name of the Domino server that is running the
SMTP Listener task -- for example, server1.acme.com
RecipientDomain Enter the name of the domain containing the intended recipients -- for example,
acme.com.
ClientHost Enter the fully qualified domain name of the client -- for example,
client1.acme.com
NthIteration Enter the frequency for how often a message is sent. Instead of the message being
sent on every script iteration, the message is sent once per n iterations of the
script. Recommended value is 6.
POP3Host Enter the fully qualified domain name of the Domino server running the POP3
task, in the format system.domainname -- for example, Server2.acme.com.

7. (Optional) Click the Stop Conditions tab to set a stop condition.

For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
8. Click Execute.
9. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
10. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.

1422 Lotus Domino Administrator 7 Help

11. Click Start Test.

Idle workload
The Idle workload establishes an upper limit of the number of sessions that a Domino server can
support. The test only establishes sessions between a client and server; no Notes transactions are carried
out. No resources other than those required to start a session are used.

The resulting capacity metric is the maximum number of user sessions that can exist concurrently. You
can use this metric to help set up and configure the test environment.

To read the code in the test script, see the appendix ″Server.Load Scripts.″

Running the Idle Workload test:

1. Make sure that you already set up clients and servers for Server.Load.
For information, see the topic ″Setting up clients and servers for Server.Load″ earlier in this chapter.
2. On the Domino Administrator client, start Server.Load by running SLOAD.EXE from the program
directory.
3. In the Test Type field, choose Built-In, and then choose Idle Workload from the list.
4. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for
example, CN=MailServer1/O=Acme
MaxSessions Enter the thread capacity of the client. The maximum is
1500.

5. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
6. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
7. Click Execute.
8. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
9. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
10. Click Start Test.

R5 Shared Database workload

The R5 Shared Database workload models active users performing shared database operations that
include performing view operations, navigating unread documents, reading documents, and adding or
updating documents in a shared database.

Metrics: The measurements obtained by this test are:

v Throughput of completed Notes operations
v Number of maximum users supported
v Average response time at maximum capacity
To read the code in the test script, see the appendix ″Server.Load Scripts.″

Hardware considerations: The following hard disk requirements apply to the SUT and, during some
tests, to the destination systems that receive mail from the SUT.

Chapter 65. Using Server.Load 1423

Initial or subsequent disk
requirement Description
Initial disk requirement 300MB to 400MB free space on the SUT
Subsequent disk requirement One-half of the mail test space requirement

Running the R5 Shared Database test:

1. Make sure that you already set up clients and servers for Server.Load.
For information about setting up clients and servers for Server.Load, see the topic ″Setting up clients
and servers for Server.Load″ earlier in this chapter.
2. On the Domino Administrator client, start Server.Load.
3. In the Test Type field, choose Built-In, and then choose R5 Shared Database test from the list.
4. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
5. Click the Script Variables tab, and enter these values:

Variable Action
MailServer Enter the canonical name of the mail server -- for example, CN=MailServer1/O=Acme
DiscussionDB Enter the name of the test discussion database
DiscTemplate Enter the name of the template used for the discussion database
NBTestReset Enter one to control how to handle existing documents at the start of the test:
v 1 -- To delete existing documents
v 0 -- To ignore existing documents
Note: The number of documents deleted is dependent on the value set for the
variable MaxDocToDelete.
MaxDocToDelete Enter the number of documents to delete when the test starts. After deleting
documents, the initial document count is reset.
NumMailNotesPerUser Enter the number of documents to create for each user to populate the database
initially.
DiscDbAddDocRate Enter the number of documents to add for each user.

6. (Optional) Click the Stop Conditions tab to set a stop condition.

For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
7. Click Execute.
8. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
9. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
10. Click Start Test.

Web Idle workload

The Web Idle workload models a Web browser user accessing the home page on the SUT. The script
contains a one-minute wait, so an average user runs this script approximately 60 times an hour.

Metrics: The measurements obtained by this test are:

v Average response time at maximum capacity
v Maximum number of Web Idle users supported

The resulting capacity metric for a Web Idle server is the maximum number of users that can be
supported before the average user response time becomes unacceptable.

1424 Lotus Domino Administrator 7 Help

To read the code in the test script, see the appendix ″Server.Load Scripts.″

Running the Web Idle Workload test:

1. Make sure that you already set up clients and servers for Server.Load.
For information about setting up clients and servers for Server.Load, see the topic ″Setting up clients
and servers for Server.Load″ earlier in this chapter.
2. On the SUT, make sure that the HTTP task is running.
3. On the Domino Administrator client, start Server.Load.
4. In the Test Type field, choose Built-In, and then choose Web Idle Workload test from the list.
5. Click the Script Variables tab, and for the ″HTTPHost″ variable, enter the TCP/IP address or host
name of the Domino Web server.
6. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
7. Click Execute.
8. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
9. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
10. Click Start Test.

Web Mail Initialization workload

1. Make sure that you have already set up clients and servers for Server.Load.
For information about setting up clients and servers for Server.Load, see the topic ″Setting up clients
and servers for Server.Load″ earlier in this chapter.
2. Run the Create NotesBench Mail Person Documents agent to create the desired number of Person
documents in the Domino Directory. When prompted, set these variables:

Variable Setting
Message storage format 2 (MIME)
Mail system 0 (SMTP/POP3)

3. On the Domino Administrator client, start Server.Load.

4. In the Test Type field, choose Built-In, and then choose Web Mail Initialization Workload from the
list.
5. Click the Script Variables tab, and enter these values:

Variable Action
NBTestReset Enter one of these to control how to handle existing documents at the start of the
test:
v 1 -- To delete existing documents
v 0 -- To ignore existing documents
Note: The number of documents deleted is dependent on the value set for the
variable MaxDocToDelete.
MailServer Enter the canonical name of the mail server -- for example,
CN=MailServer1/O=Acme.
HTTPHost Enter the TCP/IP address or host name of the Domino Web server
nb_dbdir Enter a database directory relative to the Notes data directory. Recommended value
is mail\.
MailTemplate Enter the name of the mail file template.
NormalMessageSize Enter the size of the body of the message. Recommended value is 10000.

Chapter 65. Using Server.Load 1425

Variable Action
NumMailNotesPerUser Enter the number of documents to populate the mail file when it is created.
Recommended value is 100.
Domain Enter the name of the Notes mail domain.

6. Verify that the client and server experience no errors while creating mail files. If a mail file has not
been created, the test script creates the mail file during the first test iteration, but this adds overhead
on the server back end. As a rule, CPU on the client and SUT should not exceed 75%, and the
percentage of Disk Time on the Domino Server Data directory should not be a factor.
7. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
8. Set a Server.Load stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
9. Click Execute.
10. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
11. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
12. Click Start Test.
13. Verify that the correct number of test mail files were created in the data directory. Each mail file is
named MAILn.NSF, where n is a number.
14. Complete the procedure to run the Web Mail workload.
For more information about running the Web Mail workload, see the topic ″Web Mail workload″ in
this chapter.

Web Mail workload

The Web Mail workload models an active Web Mail user using a browser to send, retrieve, and delete
Notes mail. The script contains an average of 15 minutes of waiting, so an average user runs this test no
more than four times an hour. For each iteration of the script, there is a check and retrieval of POP3 mail
messages. When sending messages, each user sends a mail message to the number of users specified by
the NumMessageRecipients variable, no more than every 15 minutes. The messages sent by each
simulated user are delivered to the mail databases of other simulated users on the SUT.

Metrics: The measurements obtained by this test are:

v Throughput of completed Notes operations
v Average response time at maximum capacity
v Maximum number of Web Mail users supported

The resulting capacity metric for a Web Mail server is the maximum number of users that can be
supported before the average user response time becomes unacceptable.

To read the code in the test script, see the appendix ″Server.Load Scripts.″

Hardware considerations: The following hard disk requirements apply to the SUT and, during some
tests, to the destination systems that receive mail from the SUT:

Initial or subsequent disk

requirement Description
Initial Disk Requirement In Domino 6 or more recent, approximately 13MB on the SUT for each user (mail
database). In Domino 5, approximately 5.5MB.

1426 Lotus Domino Administrator 7 Help

Initial or subsequent disk
requirement Description
Subsequent Disk Requirement Increase of 1MB an hour for the duration of the test. (This figure is not dependent
on the number of users.)

Increase of 100KB an hour as impacted by the value of the nthIteration setting in

the NOTES.INI file

The growth rate of each database is a function of the ratio of the number of users
and recipients sending and receiving mail.

Tips for running the Web Mail workload:

1. Use these server commands.

Command Description
Show Tasks Show either the Database Server task (Notes clients) or
HTTP task (Web users).
Show Stat Mail Monitor message counters
Show Stat Domino.Requests.* Monitor message counters

2. If authentication errors occur on the Domino server console, verify the password in the HTTP field of
the respective user’s Person document in the SUT’s Domino Directory; edit the Domino Directory if
necessary.
3. From the SUT console, enter this command to display additional routing information:
Set Config Log_MailRouting=40
4. Check that the database properties for the mail database:
v Web access: Use JavaScript when generating pages -- Must be checked.
v Allow soft deletions -- Must not be checked.
5. In the Server document on the Internet Protocols - HTTP tab, complete these fields:

Field Action
Optimize performance based on the following primary Choose Advanced (Custom Settings) to view and modify
activity the number of HTTP threads.
Number Active Threads Specify one active thread for every 10 Web Mail users.

6. Make sure that the administrator has Manager access to the Domino Directory.
7. Authentication
v By default, WebMail assumes user authentication is required.
v For authenticated users, Anonymous must have No Access and -Default- must have Manager
access. Use the WebAuthenticationOff=0 setting in the client’s NOTES.INI file.
v To run WebMail without authentication, Anonymous must have Manager access in the ACL of all
mail databases and the Domino Directory. Use the WebAuthenticationOff=0 setting in the client’s
NOTES.INI file.
v To run Web Mail with authentication, use the WebAuthenticationOff=0 setting in the NOTES.INI
file and run the Update ACL of MailDBs to include Owner (mail1, mail2, ...) agent on the SUT.

Running the Web Mail workload:

1. Make sure that you already completed the procedure to run the Web Mail Initialization workload.
For information about the Web Mail Initialization workload, see the topic ″Web Mail Initialization
workload″ earlier in this chapter.

Chapter 65. Using Server.Load 1427

 2. Run the ″Create NotesBench Mail Person Documents″ agent to create the desired number of Person
documents in the Domino Directory.
3. On the Domino Administrator client, start Server.Load.
4. In the Test Type field, choose Built-In, and then choose Web Mail Initialization Workload from the
list.
5. Click the Script Variables tab, and enter these values:

Variable Action
HTTPHost Enter the TCP/IP address or host name of the Domino
Web server
nb_dbdir Enter a database directory relative to the Notes data
directory. Recommended value is mail\.
WebPreferencesOff Make sure this is set to Off. If it’s On, the script sets the
mail database to be its own owner.

6. Click the Test Parameters tab. If you are running the test on multiple clients, increment the value of
the Starting Thread No. parameter when you run the test on each client.
7. (Optional) Click the Stop Conditions tab to set a stop condition.
For more information, see the topic ″Setting a Server.Load stop condition″ earlier in this chapter.
8. Click Execute.
9. (Optional) Select metrics to monitor.
For more information, see the topic ″Monitoring Server.Load metrics″ earlier in this chapter.
10. (Optional) In the ″Server to receive console commands″ field, enter the name of the SUT.
11. Click Start Test.

Workload Data Collection and Workload Data Rollup scripts

The Server.Load Workload Data Rollup feature is adapted from the NotesBench data rollup feature and
allows test data from a group of test drivers and an SUT to be combined into a single data file for
analysis. While a workload runs, the Workload Data Collection custom script, SHSTAT.SCR, collects
performance data from the SUT. When the workload is complete, the Workload Data Rollup script rolls
up the performance data.

Run the Workload Data Rollup Collection and Workload Data Rollup scripts on a system other than the
one that contains the test drivers that put the load on the SUT.

Note: The drivers that create the test load are referred to as ″regular″ test drivers in this document.

Setting up statistics collection before the workload run:

1. Create a folder to use as a Results directory and then set sharing privileges on that folder to allow the
client drivers to write to the Results directory.
2. On each test driver, map a drive to the Results directory on a system that will collect the data from all
drivers.
3. In the Workload Data Rollup driver’s NOTES.INI file, set ResultsDirectory= to a valid directory for
output files on a system. For example, if drive Z: is mapped to the results directory, the NOTES.INI
setting would be:
RESULTSDIRECTORY=Z:\
4. In the NOTES.INI of the driver running the Workload Data Collection script, set this NOTES.INI
variable:
NB_SaveCMDConsole=1
5. Set these Server.Load test parameters for the driver running the Workload Data Collection script:
number of users/threads = 1

1428 Lotus Domino Administrator 7 Help

 script loop count = 1

Note: This setting is not needed on the regular test drivers because the path to the Results directory
is specified using the Server.Load parameter ″Store the Metrics to this file.″
6. Click Execute to access the Metrics window.
7. Set the ″Store the Metrics to this file″ field to point to the ResN file in the results directory for each
regular test driver:
v Z:\Res1 -- for test driver 1
v Z:\Res2 -- for test driver 2

Note: Each results (metrics) file from the regular test drivers must have a unique numbered name
along and a ResultsDirectory path as shown above.
8. Set the ″Server to Receive Console Commands″ field in the Metrics window to blank on the Data
Collection Driver for the workload data collection and workload data rollup scripts. Server.Load does
not need to authenticate with a server for these scripts.

The Workload Data Collection script: Run the Workload Data collection script template as-is or
customize it for your specific use. You can add or remove groups of statistics to be collected from the
SUT as needed.
Beginloop
Console [Mailserver] sh stat platform
Console [Mailserver] sh stat server.*
Console [Mailserver] sh stat server.version.*
Console [Mailserver] sh stat server.time.start
Console [Mailserver] sh stat domino
Console [Mailserver] sh stat database
Console [Mailserver] sh stat disk
Console [Mailserver] sh stat mail
Console [Mailserver] sh stat mem
Console [Mailserver] sh stat NET
Console [Mailserver] platform time 10
Pause 60000
Rewind

Note: You can obtain a copy of this script, from the Using This Database document in nameagent.nsf.
Detach the script to a directory.

Using the Workload Data Rollup script to roll up collected data: Use the Workload Data Rollup script
to roll up collected data after you run the Workload Data Collection script.

For instructions about running the Workload Data Rollup script, see the topic Running the Workload
Data Rollup script.

Set these NOTES.INI settings on the driver running the Workload Data Rollup script:

NOTES.INI settings Description

NB_SteadyStateTime Enter the number of minutes that you want to disregard
in order to ensure you are getting steady state data. If
you do not set this variable, the default of 30 minutes
applies.

Chapter 65. Using Server.Load 1429

NOTES.INI settings Description
NB_MeasureTime Enter the number of minutes after steady state that the
rollup should read data (length of the real test). If you do
not set this variable, the default of 60 minutes is used. If
you specify a test length value greater than that which is
in the data file, Server.Load stops at the end of the file.
NB_SaveCMDConsole Set this value to zero (0) prior to running the Workload
Data Rollup script. If you do not set this value, and the
default value of 1 is used, the file is overwritten during
initialization.
NB_NumOfClients Note: Enter the number of regular drivers in the run.
The default is 20. If you have res files from an earlier run
in excess of the current number of files, set this variable
to prevent those extraneous res files from being used.
NB_Rollup Enter 1 to enable the Data Rollup Workload to run.

Generating output of per-command response times in Server.Load: You can use the NOTES.INI setting,
NB_Collect_Response_Times, to enable output of per-command response time. Add
NB_Collect_Response_Times=1 to the NOTES.INI file on the test driver. The resulting file is added to the
Results Directory and is assigned a file name RespTime_OutFile#, where # represents the driver number.

Use NB_Collect_Response_Times with the ResultsDirectory NOTES.INI setting. For example, the
NOTES.INI would contain these settings:
NB_Collect_Response_Times=1
RESULTSDIRECTORY=Z:\

The setting is for general use with all workloads and custom scripts. To disable response data collecting,
enter the NOTES.INI setting with a value of zero. For example,
NB_Collect_Response_Times=0

Running the Workload Data Rollup script:

1. Start Server.Load.
2. Click Built-In.
3. Select ″Workload Data Rollup″ from the Built-in scripts menu.
4. On the Test Parameters tab, use these test settings for the driver running Workload data collection:
number of users/threads = 1
script loop count = 1
5. In the Server.Load Metrics window, leave blank the ″Server to Receive Console command″ field, to
prevent the workload from trying to authenticate with a server.
6. Click Execute.

The data rollup output resides in the datafile NB_Domstat.csv containing the averaged client data, and
any relevant SH STAT data.

This file can be viewed using any text editor or spreadsheet program.

1430 Lotus Domino Administrator 7 Help

Chapter 66. Troubleshooting
Even with careful server maintenance, you may occasionally encounter unexpected system problems. This
chapter provides a server maintenance checklist, describes troubleshooting techniques, and offers
suggestions for solving common problems.

For information on performance-related issues, see the chapter ″Improving Server Performance.″

Troubleshooting
This section describes how to find and solve server problems.
v Troubleshooting the Domino system
v Troubleshooting tools

Troubleshooting tools
Domino provides several tools to help you troubleshoot problems. Most of the tools are available through
the Domino Administrator. The table below summarizes the available tools and indicates how each is
useful.

If you haven’t solved your problem after reading through the section that applies to the problem, you
may want to search the IBM Lotus Support Services Web site or call IBM Lotus Support Services directly
for help with troubleshooting your problem.

Tool
Server log file (LOG.NSF)
Domino Web server log file
(DOMLOG.NSF)
Server’s MAIL.BOX
Mail trace
ISpy
Mail reports
Mail tracking
Mail routing status
Mail routing topology maps
Mail routing events view in
the log file (LOG.NSF)
Shared Mail view in the log
file (LOG.NSF)
Network trace
Problems that the tool resolves How to access the tool
All problems From the Server - Analysis tab in the
Domino Administrator
Web server problems From the Server - Analysis tab in the
Domino Administrator
Mail routing problems From the Messaging - Mail tab in the
Domino Administrator
Mail routing problems From the Messaging - Mail tab in the
Domino Administrator
Slow mail; server problems Configured in the Monitoring Configuration
database on the Configuration tab in the
Domino Administrator
Mail user activity From the Messaging - Mail tab in the
Domino Administrator
Lost mail From the Messaging - Tracking Center tab
in the Domino Administrator
Undelivered mail From the Messaging - Mail tab in the
Domino Administrator
Mail routing problems between servers From the Messaging - Mail tab in the
Domino Administrator
Undelivered mail From the Messaging - Mail tab in the
Domino Administrator
Disk space usage From the Messaging - Mail tab in the
Domino Administrator
Connection problems In User Preferences. Choose File -
Preferences - User Preferences

1431
Tool
TCP/IP connection logging
Replication events in the log
file (LOG.NSF)
Replication history
Replication schedule
Replication topology maps
Monitoring Configuration
Database analysis
Administration Requests
database
Server commands
Problems that the tool resolves
Connection problems
Replication problems for a particular
server
Replication problems with a specific
database
Replication problems for a particular
server
Replication problems between servers
Server statistics and events you
specifically monitor
Database problems
Administration Process errors
Various
How to access the tool
Server console on a server with the setting
Log_Connections=1 added to its NOTES.INI
file
From the Replication tab in the Domino
Administrator
Under Database Properties. Choose File -
Database - Properties; or choose File -
Replication - History
From the Replication tab in the Domino
Administrator
From the Replication tab in the Domino
Administrator
Configured from the Configuration tab of
the Domino Administrator; view statistics
from the Server - Analysis tab in the
Domino Administrator
From the Files tab in the Domino
Administrator
From the Servers - Analysis tab in the
Domino Administrator
From the Servers - Status tab in the Domino
Administrator

Searching the IBM Lotus Support Services Web site

(www.ibm.com/software/lotus/support/)
You may want to search the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/ for a solution to your problem. You can search technical
documents in Knowledge Base and the FTP site with one natural language query or participate in
peer-to-peer discussions. In addition, you can make product suggestions and find information about
Lotus authorized support providers, support services, and support phone numbers.

Contacting IBM Lotus Support Services

If you don’t find a solution to your problem here or at the IBM Lotus Support Services Web site, you
may want to contact IBM Lotus Support Services. You can find information on how to contact IBM Lotus
Support Services at the IBM Lotus Support Services Web site, www.ibm.com/software/lotus/support/.

When you call IBM Lotus Support Services, you should have the following available to you:
1. The computer on which the problem occurred.
2. Any other people who are involved in troubleshooting the problem -- for example, server
administrators, database managers, network managers. You might want these people available when
you speak with a support representative.
3. Any pertinent information you gathered from troubleshooting the problem yourself prior to
contacting support.
4. If you have ScreenCam®, the movie or event that documents the problem.
5. If the problem involves the network, print out the PROTOCOL.INI, CONFIG.SYS, and STARTUP.CMD
files. Print out the network file directory, so that you can compare network file dates.
6. In addition, depending on the problem, be prepared to provide some of this information:

Required information Your system

Domino version(s)

1432 Lotus Domino Administrator 7 Help

Required information Your system
Operating system and version, including any patches or
fixpacks
Hardware, including the kind of CPU(s) and modems
installed, and the amount of RAM and hard disk space
Network operating system(s) and version(s), protocols,
and network driver version(s)
Network interface card(s)
Domino server names
File names, replica IDs, and ACLs for all databases
involved
Number of users who are affected by the problem --
that is, one user, several users, or all users
Number of servers that are affected by the problem --
that is, one server, several servers, or all servers
Changes to the configuration that were made before the
problem occurred -- for example, network, hardware, or
NOTES.INI changes
Error message(s), including the exact text of the
message(s)

For problems that involve more than one server on a network:

Required information Your system

Physical location of the servers -- for example, in
different cities or on FIRST DOMINO SERVERs or
WANs
Number of network segments contributing to the
problem -- that is, are both machines in the same
network segment or in segments separated by routers,
bridges, or switches
Number of Domino servers -- for example, mail hops
or replication hubs -- that are between the servers that
are having a problem

Troubleshooting the Domino system

Even with careful server maintenance, you may occasionally encounter unexpected system problems.

Domino provides a collection of tools that you can use for general troubleshooting. The IBM IBM Lotus
Support Services team provides additional troubleshooting assistance. These topics describe the available
troubleshooting tools and how to contact IBM Lotus Support Services:
v Table of troubleshooting tools
v Searching the IBM Lotus Support Services Web site (www.ibm.com/software/lotus/support/)
v Contacting Lotus Support Services

There is detailed troubleshooting information for these areas of Domino:

v Administration Process
v Administrator Client -- Troubleshooting
v Agent Manager and agents
v Database performance

Chapter 66. Troubleshooting 1433

v Directories
v Domino and DB2 configuration
v Domino Web Access
v Mail routing
v Meeting and resource scheduling
v Modems and remote connections
v Network connections over NRPC
v Network dialup connections
v Partitioned servers
v Passthru connections
v Platform statistics
v Replication
v Roaming users
v Server access
v Server-based certification authority
v Server crashes
v Server Health Monitoring
v Server.Load
v Smart Upgrade
v Transaction logging
v Web Server, Web Navigator, and the Web Administrator

Administration Process -- Troubleshooting

These topics describe how to troubleshoot common problems with the Administration Process.
v Administration Process -- Problems and error messages describes messages that appear in the
Certification Log or at the server console.
v How to troubleshoot the Administration Process provides steps for troubleshooting the Administration
process when it isn’t running as you expect.

You can also search for solutions to common problems on the IBM IBM Lotus Support Services Web site
at www.ibm.com/software/lotus/support.

Administration Process -- Problems and error messages: These errors may appear in the Certification
Log or at the server console. Some of these messages require that you correct a particular condition, while
others are only status messages.

Administration Process: retrying a request that could not be performed previously because another process was
modifying the document.: This message indicates that in processing separate requests, two threads of the
Administration Process simultaneously attempted to modify a document in the Domino Directory. As a
result, the Administration Process is retrying one of the requests. This is a status message; no action is
required.

Administration Process: Unable to access transfer context information.: This message indicates that the
Administration Process can’t access global information that is required to execute a specific task. Restart
the Administration Process, or, if necessary, restart the server.

Administration Process: Unable to create entry thread.: This message appears when the Administration
Process can’t create a thread to use to run Administration Process tasks. Restart the Administration
Process, or, if necessary, restart the server.

1434 Lotus Domino Administrator 7 Help

Insufficient memory - Admin’s request queue pool is full.: This message indicates that there is currently
inadequate memory for the Administration Process. To correct this, restart the server.

No Address book is present on this server; the Admin Process cannot continue without one.: This message
appears if you start the Administration Process on a server that doesn’t store a replica of the Domino
Directory. Create a replica of the Domino Directory on the server, and then start the Administration
Process again.

Removing viewname view notes in the Address Book.: This message appears when the Administration
Process deletes obsolete monitoring configuration documents from the Domino Directory. This is a status
message; no action is required.

Reporter: Could not locate view viewname.: This message appears when the Administration Process can’t
find obsolete monitoring documents in the Domino Directory. This is a status message; no action is
required.

The Administration Process cannot delete the database databasename at this time because it is in use by someone
else; will try again at time.: This message appears as the result of a Delete Unlinked Mail File request. The
message indicates that the Administration Process is retrying a request to delete a mail that was initially
unavailable because someone was accessing it. This is a status message; no action is required.

The Administration Process could not change or delete the name from the document because another process was
modifying it.: This message indicates that, in processing separate delete or rename requests, two threads
of the Administration Process attempted to modify the same document in a database. As a result, only
one request was processed, and the Administration Process is retrying the other. This is a status message;
no action is required.

The Administration Process does not have enough memory to compute the formulas required for request
processing.: This message indicates that there is currently inadequate memory for the Administration
Process. To correct this, restart the server.

The Administration Process is retrying a name change or deletion from the document.: This message appears as
the result of a rename or delete request. It indicates that the Administration Process is retrying a request
to rename or delete a name from a document that was initially unavailable because someone was
accessing the document. This is a status message; no action is required.

The certificate contained in the note was not issued by the selected certifier.: This message appears if you
choose Actions - Recertify Person or Actions - Recertify Server but you don’t select the original certifier. If
you don’t specify the original certifier when you choose this action, you can submit the request, but it
isn’t posted in the Administration Requests database. To correct this, choose the action again, and select
the original certifier.

The replica of the database moved by the Administration Process has not been initialized by the replicator.: This
message appears as the result of a Monitor Moved Replica request. It indicates that the Administration
Process is waiting for the replicator to initialize the replica at its new location before it deletes the
original. This is a status message; no action is required.

The selected certifier isn’t an ancestor of the entity to be updated.: This message appears if you attempt to
choose Actions - Request Move to new Certifier to move a person to a different hierarchy, but you don’t
select the original certifier. If you don’t specify the original certifier, you can submit the request, but it
isn’t posted in the Administration Requests database. To correct this, choose Request Move to New
Certifier again, and select the original certifier.

The selected certifier isn’t the target certifier in the move request.: This message appears if you choose
″Actions - Complete move for selected entries″ to attempt to complete moving user names to a different
hierarchy and the target certifier isn’t the one you specified when you originally chose Actions - Rename
Person - Request Move to New Certifier. If the target certifier you specified when completing the move is

Chapter 66. Troubleshooting 1435

wrong, select the user names in the Name Move Requests view of the Administration Requests database,
choose ″Actions - Complete move for selected entries″ again, and specify the correct target certifier. If you
specified the wrong target certifier when you originally chose Actions - Request Move to New Certifier,
repeat the action again, and specify the correct target certifier.

How to troubleshoot the Administration Process: A variety of error conditions can prevent the
Administration Process from working properly. For example, errors can occur when there isn’t enough
memory for the Administration Process; when you rename, delete, or recertify a user; or when you move
a user to a different hierarchy. Use these steps to troubleshoot the Administration Process:
1. Start the Administration Process on a server that does not store a replica of the Domino Directory.
2. Ensure that the Administration Process is set up correctly.
For more information, see the chapter ″Setting Up the Administration Process.″
3. If the Administration Process worked successfully in the past but isn’t working as expected now, try
to isolate what might have changed since it last worked successfully.
4. Check for these conditions and correct them if necessary:
a. The Administration Process (the AdminP task) must be running on all servers. To check this, enter
the Show Tasks command at the server console. Enable AdminP on any servers where it isn’t
already running.
b. An Administration Server must be specified for the Domino Directory. The administration server
for the Domino Directory is designated as such during first server setup in the domain.
c. Make sure that you specific an administration server for all databases. Each database must have an
administration server specified before a request can be made to the Administration Process.
d. The Domino Directory (NAMES.NSF) and the Administration Requests database (ADMIN4.NSF)
must replicate properly between the affected servers. These databases must replicate correctly
between the administration server of the Domino Directory and the servers where the databases
receiving the updates reside.
e. Each request in the Administration Requests database should have a corresponding response
document that shows that the Administration Process has completed the request. Correct any
errors indicated by a response document.
f. The Certifier documents must have the correct public key; the public key must match the key in
each CERT.ID.
For more information about correcting errors in the Administration Requests database, or for any
other information regarding the administration process, see the chapter ″Setting Up the
Administration Process.″

Administrator Client -- Troubleshooting

These topics describe how to troubleshoot problems related to using the Administrator client:
v Output data incomplete when running Administrator client on a remote console

Output data incomplete when running Administrator client on a remote console: There are two
situations in which data can be lost when you attempt to view output data using the Administrator client
from the Domino server remote live console. The displayed data appears incomplete because a portion of
the data is lost. Data can be lost in the following situations:
v The console output is buffered in a ring buffer as it is generated. When the remote live console
background thread fetches data, it may not fetch the data quickly enough. The ring buffer then loses
data.
v When the remote live console background thread fetches data, it posts the data to a network
asynchronous write -- itself a ring queue. If the asynchronous write queue entry is overwritten, data is
lost.

1436 Lotus Domino Administrator 7 Help

The following two statistics record the causes of data loss.

Statistic
server.RemoteConsole.AsyncQueueOverrun
server.RemoteConsole.BufferOverrun
Explanation
Number of times that the asynchronous queue request
was lost.
Number of times that data was lost because more
console output was generated than was sent over the
wire.

Agent Manager and agents -- Troubleshooting

These topics describe how to troubleshoot problems related to using Agent Manager and running agents:
v Tools for troubleshooting Agent Manager and agents describes tools you can use to troubleshoot Agent
Manager and agent.
v Agent manager and agents -- Problems and error messages describes problems that may occur when
the Agent Manager or an agent isn’t working as you expect.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Tools for troubleshooting Agent Manager and agents: Whenever an agent won’t run, check the Agent
Log to see when the agent last ran and whether it completed. For additional information, check the
server console or the Miscellaneous events in the log file (LOG.NSF) for messages from the Agent
Manager.

Server commands: Use these server commands to troubleshoot agents:

Tell amgr schedule
Tell amgr status
Tell amgr debug

For information on these commands, see the appendix ″Server Commands.″

Log file: To enable agent logging in the log file (LOG.NSF), edit the NOTES.INI file to include the
Log_AgentManager setting, which specifies whether or not the start of agent execution is recorded in the
log file and displayed on the server console. It’s important to monitor the server console or log for
information from the Agent Manager because error and warning messages generated by the Agent
Manager on behalf of the agent, as well as output -- for example, print statements -- generated by a
background agent, appear on the console and in the Miscellaneous events view of the log (LOG.NSF).

For more information on the Log_AgentManager setting, see the appendix ″NOTES.INI File.″

The Agent Log: The Agent Log is a view in a database that shows the last time an agent ran and
describes if the agent completed or not.
1. In the database, choose View - Agents.
2. In the Design view that lists all the agents, choose the agent.
3. Choose Agent - Log.
For more information on the Agent Log, see the book Application Development with Domino Designer.

Agent manager and agents -- Problems and error messages: These topics present suggestions for
troubleshooting certain problems you may encounter with the Agent Manager and/or agents:
v Agent Manager isn’t working as expected
v An agent isn’t running as expected
v An agent doesn’t run to completion

Chapter 66. Troubleshooting 1437

v An agent isn’t running at the expected times
v The Escrow agent isn’t working
v Users can’t create agents

Agent Manager isn’t working as expected: The Agent Manager may work or may not work efficiently.
1. The Agent Manager may not be scheduled to run. If the Agent Manager isn’t running, check the
″Start time/End time″ fields on the Server Tasks - Agent Manager tab in the Server document. Any
time not specified in these fields represents downtime. If necessary, adjust the times in these settings.
2. The demand for the Agent Manager may be too high. If the Agent Manager takes too long to run
agents, reschedule agents to run at night when system demand is usually low.
If the server runs Domino 4.6 or earlier, you can increase the ″Max % busy before delay″ field in the
Server document. Domino 5 and higher does not support this field.

Note: If you allocate more resources to the Agent Manager, fewer will be available to run other server
tasks.

An agent isn’t running as expected: In addition to the possibility that there are errors in the agent code,
an agent may fail to run properly because the agent has insufficient access or because the agent is not set
to run on the given server.
1. Insufficient access in the database ACL can prevent an agent from running properly. For example, a
user may design an agent that copies selected documents from database A to database B. If the user --
and by extension, the agent -- doesn’t have Author access in the ACL of database B, the agent runs,
but it is not allowed to copy the documents. To determine if this problem exists, examine the Agent
Log for access errors after the agent runs unsuccessfully.
2. If an agent won’t run on a particular server, check the Agent Restrictions on the Security tab of the
Server document. This section contains the ″Run personal agents,″ ″Run restricted LotusScript/Java
agents,″ and ″Run unrestricted LotusScript/Java agents″ fields that specify who has access to run
agents on the server. Although a user who has the appropriate access in the database ACL may be
able to create an agent on the server, without the appropriate access in the Server document, the user
can’t run the agent.
You should also check the Server Access section on the Security tab of the Server document. This
section contains the ″Only allow server access to users listed in this Directory,″ ″Access server,″ and
″Not access server″ fields, which allow and deny access to the server. Because an agent inherits the
access privileges of the person who creates it, the agent can’t run on a server for which its creator
does not have access.
3. Scheduling conflicts may prevent an agent from running. In the Server document, click the Server
Tasks - Agent Manager tab and check the ″Daytime Parameters Start time/End time″ and ″Nighttime
Parameters Start time/End time″ fields. Any time not specified in these fields represents downtime; if
a user creates a scheduled agent and specifies that it run during the server’s Agent Manager
downtime, the agent will not run. Compare these fields in the Server document to the time the agent
is scheduled to run. If a conflict exists, change the Agent Manager schedule on the server, or ask the
user to reschedule the agent.
4. If a LotusScript or Java agent terminates before completing its tasks, check the ″Max LotusScript/Java
execution time″ fields in the Server document. If a complex agent requires more time than is
scheduled, the Agent Manager terminates the agent before completion.
Ask the user to reschedule the agent to run at night, when the default maximum execution time is
longer; or increase the value of the ″Max LotusScript/Java execution time″ field in the Server
document, as needed. If neither of these solutions is practical, ask the user to rewrite the agent as
several smaller agents.

An agent doesn’t run to completion: When an agent doesn’t finish running, check the log file
(LOG.NSF), the server console, and the Agent Log for error messages.

1438 Lotus Domino Administrator 7 Help

1. If the agent runs to completion when you run it manually, but does not run when it runs in the
background, the agent code may contain commands -- such as, LotusScript user-interface methods --
that aren’t intended to run as background processes.
2. The ″Max LotusScript/Java execution time″ field in the Server document specifies how much time a
LotusScript/Java agent has to complete execution. If the agent exceeds this maximum, the agent
doesn’t finish, and the Agent Log records the termination. Review the agent code to make sure it
functions correctly -- for example, make sure that the code doesn’t run an infinite loop. If the code is
correct, consider increasing the execution time limits in the Server document. However, be aware that
increasing these settings may impact system performance because the Agent Manager will run for a
longer time to accommodate this agent.

An agent isn’t running at the expected times: If the agent is running, but not at or near the expected
times, the server may be busy with other tasks. To gather information about when the agent last ran and
if it completed successfully, check the agent log. Then check for these conditions and correct them, if
necessary.
1. Scheduling conflicts may prevent an agent from running. In the Server document, click the Server
Tasks - Agent Manager tab, and check the ″Daytime Parameters Start time/End time″ and ″Nighttime
Parameters Start time/End time″ fields. If the values in these fields don’t account for a portion of the
day, the Agent Manager will not run during that period. For example, if the daytime parameters are 8
AM and 5 PM and the nighttime parameters are 8 PM and 8 AM, Agent Manager will not run any
agents between 5 PM and 8 PM.
2. The NOTES.INI settings may be incorrect. Check these Agent Manager settings in the server’s
NOTES.INI file:
v Amgr_DocUpdateAgentMinInterval
v Amgr_DocUpdateEventDelay
v Amgr_NewMailAgentMinInterval
v Amgr_NewMailEventDelay
3. Edit the NOTES.INI file to include the Log_AgentManager setting and set it to 1. You can also enable
this setting in the Configuration Settings document in the Domino Directory.
4. For servers running Domino 4.6 or earlier, the ″Max % busy before delay″ setting may have been
exceeded. The ″Max % busy before delay″ setting on the Server Tasks - Agent Manager tab of the
Server document controls the maximum percent of time the Agent Manager spends running agents. If
the percentage of time is exceeded, a delay occurs before Agent Manager runs the next agent. After
the percentage falls below the threshold, Agent Manager resumes running agents.
For more information on NOTES.INI settings, see the appendix ″NOTES.INI File.″

The Escrow agent isn’t working: The Escrow agent won’t work if:
v There is no Person document containing the phrase Escrow Agent in the User name field.
v More than one Person document contains the phrase Escrow Agent in the User name field.
v The Escrow agent attempts to send encrypted mail to a recipient whose Person document doesn’t
contain a public key.

Users can’t create agents: If a user can’t create agents in a particular database, check the database ACL
to see if the user has the access level required to create agents in that database. To create personal agents,
a user must have at least Reader access to the database in which the agent will be created. To create
shared agents, a user must have at least Designer access.

Clusters - Troubleshooting
These topics include information about error messages and other problems that may arise when using a
cluster.
v Some database changes are not replicating quickly to other servers
v Client requests do not fail over for certain databases even though the replicas are listed in the Cluster
Database Directory
Chapter 66. Troubleshooting 1439
v Although you marked a database Out of Service, users can still open it
v The Cluster Database Directory includes two copies of the database documents for all the databases on
a particular server
v The value of the Replica.Cluster.Retry.Waiting statistic is greater than zero
v ″Cluster Replicator was unable to configure using Cluster Database Directory cldbdir.nsf: File does not
exist″
v ″Cluster Replicator was unable to configure using Cluster Database Directory cldbdir.nsf: Invalid
replica ID for cluster database directory. If cluster name changed, delete cluster database directory and
restart cldbdir task.″
v Private folders do not replicate from one clustered database to another
v ″HTTP Server Initialization error. Could not bind port 80. Port may be in use.″
v The Server Web Navigator does not fail over
v Clients receive the message ″Server Not Responding″ instead of failing over

Some database changes are not replicating quickly to other servers.: Use the following checklist to
troubleshoot problems related to slow replication between servers in a cluster. Check that the following
conditions exist:
v The Cluster Replicator is started on the server where the modified database is located. You can check
this on the Servers - Status tab of the Domino Administrator or by sending the following command
from the server console:
show tasks
v The modified database and its replicas on other servers are listed in all the Cluster Database
Directories.
v All replicas of the modified databases have the same Replica ID. To check this, open the Databases by
Replica ID view in the Cluster Database Directory.
v The Cluster Replicator is not encountering errors when it attempts to replicate to other servers in the
cluster. Check the Replica.Cluster.Failed and Replica.Cluster.Retry.Waiting statistics to see if error
conditions exist. Also, examine the Replication Events log documents generated by the Cluster
Replicator.
v The Cluster Replicator is able to keep up with the current server replication workload. Check the
Replica.Cluster.WorkQueueDepth and Replica.Cluster.SecondsOnQueue statistics to determine if there
is a backlog of replication requests. If so, consider starting an additional Cluster Replicator.
v Cluster replication is enabled for all replicas of the database. Open the Cluster Database Directory, and
check the left column for the letter ″X.″ Databases with the letter ″X″ in the left column have cluster
replication disabled.
v CLREPL_OBEYS_QUOTAS is set to 0 (zero) if you used this setting in the Configurations Settings
document or in the NOTES.INI file. When this setting is set to 1, cluster replication obeys the database
size quotas that were set by the database administrator. The Cluster Replicator will not push changes
to a replica if the changes would result in the replica exceeding its size quota. If
CLREPL_OBEYS_QUOTAS is set to 0 or is not present at all, the Cluster Replicator ignores database
size quotas.

Client requests do not fail over for certain databases even though the replicas are listed in the Cluster
Database Directory: When there are two or more replicas of a database on a server, the Cluster Manager
uses failover by path, not failover by replica ID. To ensure that client requests fail over correctly, do not
include multiple replicas of a database on the same server; or if you do, create the replicas using the
same names and paths as the replicas to which you want to fail over.

Although I marked a database Out of Service, users can still open it: The database that users can open
may be a replica on a non-cluster server. Marking databases ″out of service,″ ″in service,″ or ″pending
delete″ works only for databases that are in a cluster. In addition, new replicas of the databases do not
inherit these attributes, even in a cluster.

1440 Lotus Domino Administrator 7 Help

The Cluster Database Directory includes two copies of the database documents for all the databases
on a particular server: If the Cluster Database Directory on a server is deleted, the Cluster Database
Directory Manager recreates it and then populates it with a document for each database on the server.
These documents then replicate to the other servers in the cluster. Since each server in the cluster already
has documents for this server’s databases, their Cluster Database Directories will then contain two
documents for each database on this server. This is a temporary condition and causes no system errors.
The next time the server’s Cluster Database Directory Manager starts, it detects the problem and removes
the extra documents.

To avoid creating duplicate documents, replicate the Cluster Database Directory from another server to
the server on which the Cluster Database Directory was deleted before you restart the server.

The value of the Replica.Cluster.Retry.Waiting statistic is greater than zero: This statistic indicates that
the Cluster Replicator could not complete some replications, and these replications are waiting to be
retried. To see why the replications were not successful, force the Cluster Replicator to generate a
Replication Event Log document, which includes information about all the cluster replications waiting to
be retried. To force the Cluster Replicator to log this information, send the following command from the
server console:
tell clrepl log

To view the error conditions, examine each of the Log documents generated by this command (one for
each server being replicated to), and then correct the errors. You can sometimes correct the problem by
restarting a server that is currently unreachable. When the errors are corrected, cluster replication
succeeds, and the Replica.Cluster.Retry.Waiting statistic becomes zero.

″Cluster Replicator was unable to configure using Cluster Database Directory cldbdir.nsf: File does
not exist″: This message can occur for the following reasons:
v The Cluster Replicator cannot find the Cluster Database Directory.
This often occurs when you first add a server to a cluster and the Cluster Replicator starts before the
Cluster Database Directory Manager has created the server’s Cluster Database Directory. If this is the
cause of the problem, it will resolve itself.
v The Cluster Database Directory has been deleted.
Replicate the Cluster Database Directory from a different cluster server.

″Cluster Replicator was unable to configure using Cluster Database Directory cldbdir.nsf: Invalid
replica ID for cluster database directory. If cluster name changed, delete cluster database directory and
restart cldbdir task.″: The ClReplD field in the Server document In the Domino Directory does not
match the replica ID of the Cluster Database Directory. To fix this, you can delete the Cluster Database
Directory from this server and then replicate it from a different cluster server. If this doesn’t correct the
problem, remove the server from the cluster and add it to the cluster again.

Private folders do not replicate from one clustered database to another: Check the access control list
(ACL) of the databases to be sure that the User type of the servers is ″Server″ or ″Server group.″

″HTTP Server Initialization error. Could not bind port 80. Port may be in use.″: This message can
occur if you have conflicting IP addresses or port numbers when you attempt to start the Domino Web
server on a server that is running the ICM. The most likely cause is that the ICM and HTTP task are both
attempting to use the same IP address and TCP/IP port.

Check the Server document to ensure that the ICM and the HTTP server have been assigned different
TCP/IP port numbers or that the ICM is configured to use a different IP address than the HTTP server. If
the ICM and HTTP server are both using port 80, but on different IP addresses, make sure that you have
chosen ″Enabled″ in the ″Bind to host name″ field on the Internet Protocols - HTTP tab in the Server
document.

Chapter 66. Troubleshooting 1441

The Server Web Navigator does not fail over: Check the replica IDs of the Web databases (WEB.NSF)
on the servers in the cluster. If the replica IDs are not identical, the databases will not fail over to each
other. To fix this problem, replicate the Web database from one server to all the other servers in the
cluster.

This problem often occurs because the Web task creates the Web database when it first starts, if this
database doesn’t already exist. Therefore, it is a good idea to start the Web task on one cluster server
only, and then replicate the Web database to the other cluster servers before you start the Web task on
those servers.

Clients receive the message ″Server Not Responding″ instead of failing over: If a server becomes
unavailable while a database is open, failover does not occur. The user should reopen the database.
Reopening the database causes failover to occur if a replica exists on an available server in the cluster. If
the user was editing a document when the server became unavailable, the user can copy the document to
the replica.

″Server Not Responding″ can also appear when a user tries to send and save a message when the user’s
mail server is unavailable. The message is sent successfully because the mail router fails over. (The user
can see that the message was sent successfully by clicking the status history list in the status bar.)
However, saving a message or document does not cause failover. To save the message, the user can
reopen the database, which causes failover if a replica mail database exists on an available server. The
user can then copy the sent message to the replica.

Database performance -- Troubleshooting

The following topics suggest solutions to common performance problems associated with databases.

You can reduce database performance problems by using:

v Domino 6 databases, which are faster than databases created with earlier Domino releases
v Transaction-based logging and recovery
v Disk-tuning procedures, such as disk defragment and disk-space reallocation

Some of the recommended solutions involve changing the database design. You should always test
design changes on a template or a copy of the database before applying them to the production copy.

For more information on transaction logging, see the chapter ″Transaction Logging and Recovery.″

The topics in this section include:

v Users cannot access the database
v Users experience a delay when accessing the database
v Resolving conflicts when names are assigned to more than one access level
v Using Groups and Roles to determine what controls user access
v Using Find Note to analyze a document reported in the log file

Users cannot access the database: Users may not be able to access databases for the following reasons:

The server storing the database is temporarily down: Check with the Domino administrator and tell
users when the database is expected to be available again.

Users don’t have the appropriate access: Check the database access control list (ACL) to make sure
users have the necessary access to the database. Check with the Domino administrator to ensure users
have access to the Domino server that stores the database.

For more information on user access, see the chapter ″Controlling User Access to Domino Databases.″ For
more information on server access, see the chapter ″Controlling Access to Domino Servers.″

1442 Lotus Domino Administrator 7 Help

Server backup is occurring during work hours: Users may be unable to access a server that is being
backed up during work hours because a full backup may require significant disk I/O capacity. Ask the
Domino administrator to schedule backups to occur overnight, if possible.

Use a Domino 6-compliant backup program so users can access databases on a server that is being
backed up. Users can make changes to databases as a backup occurs because Domino provides a
point-in-time image of the database, beginning with the time the database backup starts.

The server is continuously updating a full-text index: If a database is large and active, database
performance can be slow if the server updates a full-text index too frequently. Change the full-text index
update frequency if necessary.

For more information on update frequency, see the chapter ″Setting Up and Managing Full-text Indexes.″

Users experience a delay when accessing the database: Users may experience a delay when accessing
databases for the following reasons:

The database is heavily used: View the user activity to see if the database is heavily used. This option
is on the Information tab of the Database Properties box. Check the server to see if its hardware and
memory are powerful enough to support the user activity for the database. If the server is not powerful
enough, you may need to upgrade hardware or memory on the server. You can also create an additional
replica of the database so all users are not always using the same one. If disk contention is a problem,
move the database to a less heavily used disk. For more information on the Database Properties box, see
Lotus Notes 6 Help.

There are too many views: If the database contains many views, consider consolidating some of them. You
can consolidate views by creating alternative collations in the same view, rather than using separate
views. Or, you can purge or delete view indexes. Database performance can suffer when a database
contains many views.

For information on managing view indexes, see the chapter ″Maintaining Databases.″ For more
information on improving view performance, see the book Application Development with Domino Designer.

View indexes are being refreshed too frequently: If the database is heavily used or contains many
documents, refresh view indexes less frequently, if possible.

For information on views, see the book Application Development with Domino Designer.

Unread mark processing may cause delays: Unread mark processing may cause delays after the database is
opened. It also creates disk contention, which slows down every operation on the database. Delays occur
as the unread marks in a database are updated while the database is opening. Disabling unread marks on
the database eliminates the delay.

For information on disabling unread marks, see the chapter ″Improving Database Performance.″

The database design is complex: A complex database design can cause performance problems. Work with
the designer to redesign or minimize performance problems.

For information on designing applications, see the book Application Development with Domino Designer.

Database performance properties are not being used: If feasible, set database properties to improve database
performance.

For information on setting database properties, see the chapter ″Improving Database Performance.″

Chapter 66. Troubleshooting 1443

The database cache needs adjustment: If you are a system administrator, monitor the database cache on the
server that stores the database to see if it’s working effectively. If necessary, increase the number of the
databases the cache can hold. The NSF buffer pool size may also need to be increased.

For more information on managing the database cache, see the chapter ″Improving Database
Performance.″

Resolving conflicts when names are assigned to more than one access level: It’s possible to assign
users or servers more than one level of access to a database. The following table describes access level
conflicts and resolutions.

Access level conflict Resolution

A name is listed in an ACL individually and as a
member of a group
A name is included in two or more groups
A name appears in an ACL and in access lists
associated with forms, views, or sections
The access level assigned to the individual name takes
precedence over the access level for the group, even if the
individual access level is lower than the group level.
The name receives the access of the group with the highest
access.
The ACL controls database access; design element access
lists refine this access to a lower level. For example, if a
user has Author access to a database but is not listed in the
access list for a form in the database, the user cannot use
the form to create a document.

For more information on creating access lists that refine access to specific design elements, see the book
Application Development with Domino Designer.

Using Groups and Roles to determine what controls user access: You can use the Groups and Roles
dialog box to troubleshoot database access problems. However, use this feature only on databases that
have the option ″Enforce a consistent Access Control List across all replicas of this database″ selected.
Otherwise, Notes does not display information in the Groups and Roles dialog box.

For example, if a group from the database ACL that you think has a user’s name does not appear in the
Groups and Roles dialog box, then this indicates that:
v The user name is missing from the group or spelled incorrectly
v A role that you thought was assigned to a user is not assigned

For more information on Groups and Roles, user access, and the ″Enforce a consistent ACL″ option, see
the chapter ″Controlling User Access to Domino Databases.″

Using Find Note to analyze a document reported in the log file: You can use the Find Note dialog box
in the Domino Administrator to analyze a document reported in the log file. If the log file reports a
problem with a document, you can display the properties for the document to help you to troubleshoot
the problem. The document can be in a single database or in a database replica. For example, you can use
Find Note to review the document properties for a document that cannot replicate.
1. Copy the hexadecimal Note ID (for example, NT201B2) of the reported document from the log file to
the Clipboard. Or write down the Note ID. You may also troubleshoot using the UNID, the universal
Note ID, a unique identifier used to locate the same document across database replicas.
2. In the Server list, select the server that stores the database containing the reported document.
3. Use the Files tab to select the database that stores the reported document.
4. Choose Tools - Database - Find Note.
5. Select one:
v by Note ID
v by Universal Note ID (UNID)

1444 Lotus Domino Administrator 7 Help

6. Paste or enter the Note ID or UNID from Step 1 into the ID field.
7. Click Find.
8. View the document details and properties in the Fields and Properties fields.

Domino and DB2 configuration -- Troubleshooting

The following topics suggest solutions to common problems and issues that may occur when using
Domino and DB2:
v Tools and methods for troubleshooting the Domino and DB2 configuration
v Resolving problems with user accounts and passwords on Domino with DB2
v DB2 Error Messages -- Troubleshooting

Tools and methods for troubleshooting the Domino and DB2 configuration: Use these tools and
methods to troubleshoot your Domino and DB2 configuration:
v Running the Extract and Reload NSFDB2 Tool
v Verifying DB2 parameters
v Verifying that the DB2 server is running

Running the Extract and Reload NSFDB2 Tool: Use the Extract/Reload Tools when Domino is unable to
recognize DB2 databases. For example, run the extract tool when DB2 database corruption causes a server
crash, the Domino server does not recognize the DB2 databases and you want to determine the cause of
the problem. After using the extract tool to extract files, you can send the files to the Support
organization to determine the cause of the problem.

The two tools are:

v EXTRACT.BAT -- Use this tool to extract the tables (files) to send to Support.
v RELOAD.BAT -- Support uses this tool to reload the files. The files can then be reviewed and the cause
of the problem determined.

The tool is distributed by support on an as-needed basis.

Running the tool to export tables for support: Complete these steps to extract the files to send to Support.
The Support organization can then use those files to determine the cause of the problem and to advise of
a solution for resolving the problem.
1. Run the scripts to extract the data.
2. Zip or compress the extracted files and send the archive to Support.

Support can unzip or decompress the archive and then review the log that is produced during the extract
operation to obtain information needed to reload the files. They can then run the reload script to access
the data and analyze it.

Manually exporting tables for Support: You can perform this operation manually, but we recommend you
run the scripts.

In this procedure, you export tables from a DB2-enabled Domino server. The Support organization can
then create an identical configuration when they import the tables to a destination Domino server with
DB2 enabled.

Exporting tables from the source server:

1. Extract the data that belongs to the NSF database in question by exporting the DB2 tables that hold its
data.
2. Open the Control Center in DB2. Choose Start - Programs - IBMDB2 - General Administration Tools -
Control Center.
3. Select the DB2 database that contains the NSF database that you want to extract.

Chapter 66. Troubleshooting 1445

4. Open Tables and sort by SCHEMA.
5. Export the following tables (use IXF format and specify the message file, directory, and file name for
the large objects (LOB)):

Note: Assume that the NSF database requiring attention is contained in the DB2 database DOMINO, is
named TEST.NSF and has a schema named TEST. The schema for the DOMINO DB2 database is named
DSCHEMA.
v DB2MAP
v NIFCTL
v NIFDATA
v NSFNOTE
v NSFOBJECT
v NSFOBJNAM
v NSFSLOT
v PROPERTIES

Where schema=TEST
v CATALOG

Where schema= DSCHEMA

Where nsfschema=TEST

Importing tables to a destination server: Import the tables to a Domino server with DB2 enabled. Assume
that there is no database named TEST on this destination server. The schema for the DB2 database named
DOMINO is DSCHEMA, the schema for the NSF database to be imported is TEST and the tablespace is
also named TEST. The metadata listed in the table is needed to create the configuration on the destination
server.

Setting Enter
Name TEST
Type Regular
Space management System
Page size 32Kb
Buffer pool DOMINO
Dropped table recovery Enable
Add container in this directory Add a container in directory <Drive>:\<Domino server data
directory> called TEST.DB2

1. Import these tables:

Note: LOB refers to large objects.

v DB2 => Import from F:\TEST\DB2MAP.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\DB2MAP.MSG REPLACE_CREATE into TEST.DB2MAP in TEST
v DB2 => Import from F:\TEST\NIFCTL.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\NIFCTL.MSG REPLACE_CREATE into TEST.NIFCTL in TEST
v db2 => Import from F:\TEST\NIFDATA.IXF OF IXF LOBS from F:\TEST MESSAGES
F:\TEST\NIFDATA.MSG REPLACE_CREATE into TEST.NIFDATA in TEST
v db2 => Import from F:\TEST\NSFNOTE.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\NSFNOTE.MSG REPLACE_CREATE into TEST.NSFNOTE in TEST

1446 Lotus Domino Administrator 7 Help

 v db2 => Import from F:\TEST\NSFOBJECT.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\NSFOBJECT.MSG REPLACE_CREATE into TEST.NSFOBJECT in TEST
v db2 => Import from F:\TEST\NSFOBJNAM.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\NSFOBJNAM.MSG REPLACE_CREATE into TEST.NSFOBJNAM in TEST
v db2 => Import from F:\TEST\NSFSLOT.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\NSFSLOT.MSG REPLACE_CREATE into TEST.NSFSLOT in TEST
v db2 => Import from F:\TEST\PROPERTIES.IXF of IXF LOBS from F:\TEST MESSAGES
F:\TEST\PROPERTIES.MSG REPLACE_CREATE INTO TEST.PROPERTIES in TEST
2. Import a row for the new database in Domino’s catalog:
v db2 => Import from F:\TEST\CATALOG.IXF OF IXF LOBS from F:\TEST MESSAGES
F:\TEST\CATALOG.MSG INSERT INTO DSCHEMA.CATALOG
Replace into DSCHEMA.Catalog in Domino

Verifying DB2 parameters: You can review DB2 parameters from the Domino server console, the DB2
command line processor, the server’s NOTES.INI file, and the Server document. To modify the DB2
parameters, edit the parameters in the Server document.

For information on modifying DB2 parameters in the Server documents, see the topic Setting and
modifying DB2 values in the Server document.

Viewing DB2 parameters from the Domino server console: From the Domino server console, view your
current DB2 parameters using this command
Sh config db*

Domino lists these DB2 parameters:

DB2DATABASE=
DB2DIRECTORY=
DB2INIT=
DB2INSTANCE=
DB2SCHEMA=
DB2SERVERDOCUPDATED=
DB2UDFPATH=
DB2UDFSERVER=
DB_CREATION_DEFAULT_TYPE=

Note: You cannot modify DB2 parameters using the sh config db* command. To modify DB2 parameters,
use the DB2 tab on the Server document.

Viewing DB2 parameters from the DB2 Command Line Processor: You can also view the DB2 parameters in
the Domino server’s NOTES.INI file or in the Server document. To modify the DB2 parameters, edit the
parameters in the Server document. For information on modifying DB2 parameters in the Server
documents, see the topic ″Setting DB2 values in the Server document.″

To verify DB2 parameters from the DB2 server, open the CLP and enter this command:
list db directory

The DB2 server lists these parameters:

Database alias
Database name
Database drive
Database release level
Database directory entry type

Chapter 66. Troubleshooting 1447

Catalog database partition number

Verifying that the DB2 server is running: Use this procedure to verify that the DB2 server is running.
1. Choose Start - Programs - IBM DB2 - Command Line Tools - Command Line Processor.
2. In the Command Line Processor (CLP) window, enter this command:
db2start

Resolving problems with user accounts and passwords on Domino with DB2:
v Password or account problems with OS account used to start DB2 services
v Problem with DB2 account used by Domino to communicate with DB2
v Cannot access DB2 enabled Notes database when working with DAVs

Password or account problems with OS account used to start DB2 services: If the user account that starts the
DB2 services is disabled on Microsoft Windows or if the password has expired, DB2 services will not
start when you reboot the computer and the Domino server displays errors because it cannot connect to
the DB2 server.
1. Start/restart the Domino server. The Domino server will start because the OS Account is not used
during Domino server server start up.
2. Reboot the Microsoft Windows computer that is running DB2 so that the DB2 service restarts.
Problems will be encountered when you attempt to restart the DB2 services.
When restarting the service without rebooting the computer, this error message displays.
Could not start the DB2 - DB0 service on Local Machine. Error 1069: The service did not start due to a logon failure.
When rebooting the computer running Microsoft Windows, the following errors are recorded in the
events log (EVENTS4.NSF)
®
Lotus Domino Server, Build V70_04212005NP, April 21, 2005
Copyright (c) IBM Corporation 1987, 2005. All Rights Reserved.
04/25/2005 11:15:02 AM A RM error occurred.: An error occurred accessing the db2 datasource.
DB2 CONNECTION ERROR: Domino unable to connect to DB2 database ’dominol’ as user ’mdnadmin’...
[IBM][CLI Driver] SQL1032N No start database manager command was issued. SQLSTATE=57019

The Microsoft Windows Event Properties/Logs contain these error messages for DB2 services:
The DB2 - DB2-0 service failed to start due to the following error:
The service did not start due to a logon failure.
The DB2DAS - DB2DAS00 service failed to start due to the following error:
The service did not start due to a logon failure.

Resolving the problem::

1. Re-enable the OS account and then restart the DB2 services.
2. Start the Domino server.

Password or account problem with DB2 account used by Domino to communicate with DB2: If the user account
that the Domino server uses to authenticate with DB2 on Microsoft Windows is disabled, or the password
expires, the Domino server starts but is not able to connect to the DB2 database.

When you start the Domino server, these errors display:

®
Lotus Domino Server, Build V70_04192005NP, April 19, 2005
Copyright (c) IBM Corporation 1987, 2005. All Rights Reserved.
04/22/2005 09:55:15 AM A RM error occurred.: An error occurred accessing the db2 datasource.
DB2 CONNECTION ERROR: Domino unable to connect to DB2 database ’dominol’ as user ’domino’...
[IBM][CLI Driver] SQL30082N Attempt to establish connection failed with security reason "19" ("USERID DISABLED or RESTRICT

1448 Lotus Domino Administrator 7 Help

Resolving the problem: Complete these step to resolve the account or password problem:
1. Restart the Domino server.
2. Re-enable the account or change the password. From the Domino Administrator client, use the Edit
DB2 Login feature. You are modifying the name and password that you entered in the DB2 server
enablement tool.

Cannot access DB2 enabled Notes database when working with DAVs: When using DAVs, if users encounter
problems while attempting to access a DB2 enabled Notes database, make sure that the ACL entry for
each user is identical to the first entry in the ″User Name″ field in that user’s Person document in the
Domino Directory on the Domino server.

DB2 Error Messges -- Troubleshooting: You may encounter one or more of these errors when using
Domino and DB2.

Note: Several of the messages that display on the user interface may use the term NSFDB2. An NSFDB2
is a DB2 enabled Notes database.
v Database cannot be created
v ICL must be an NSF not a DB2-backed database
v NSFDB2 databases require Domino 6.X or more recent
v Resolving error ″An RM error occurred. Unable to initialize DB2 services″
v Resolving error ″SQL30020N with Reason Code ″0x124C″(″0214″)″
v Resolving error ″SQL0956C Not enough storage is available in the application heap to process the
statement″
v Resolving error 0803N
v Resolving error ″failed to extend tablespace″
v Resolving errors when using SELECT
v Resolving error caused by starting DB2-enabled server twice
v Entry not found in index error message when creating a response document
v Creating a service dependency for Domino and DB2
v Use caution when deleting DB2 objects
v Domino does not connect to its DB2 database or has difficulty connecting

Resolving errors when using SELECT: If you are performing a SELECT statement using a DB2 Command
Line Processor (CLP) window, and you see any of the following errors, complete the procedure in this
topic.
SQL0443N Routine "ISREADER" (specific name "") has returned an error SQLSTATE with diagnostic text "The server is not re

If you use DB2 Access Views (DAVs) and if your environment’s configuration does not allow you to ping
your Domino server by name, edit the DB2 Access server’s Connection document after all related setup
steps are complete. To edit the DB2 Access Connection document, complete one of the procedures below.
1. (Recommended method) Complete the procedure Editing the DB2 Access server Connection
document.
2. In the field, Optional network address, enter the IP address of the DB2-enabled Domino server. Do
not enter the server name itself.

Or
1. From the Domino Administrator, click the Files tab.
2. Open the file, NAMES.NSF, for your DB2 Access server.
3. Open the DB2 Access server’s Connection document.
4. In the field, Optional network address, enter the IP address of the DB2-enabled Domino server. Do
not enter the server name itself.
Chapter 66. Troubleshooting 1449
5. Save the document.

Resolving error ″An RM error occurred. Unable to initialize DB2 services″: You may need to increase the DB2
MAXAPPLS configuration parameter if you do any of the following:
v Run multiple server add-in tasks such as LDAP, POP3, or CA.
v Add additional replicators or routers.
v Frequently run tasks such as replication or indexing from the server console.

If the error message ″An RM error occurred. Unable to initialize DB2 services″ displays after performing
any of the actions listed above, modify the value assigned to the DB2 configuration parameter,
MAXAPPLS.

When determining the value to set for MAXAPPLS, use these guidelines:
v Count each Server thread as one DB2 application. Use the Server document -- Basics tab -- Number of
active threads: field. The default is 40 for Win32.
v Count each HTTP thread as one DB2 application. Use the Server document -- Internet Protocols --
HTTP tab, Number of active threads: field. If enabled, the default for Win32 is 40.
v Other Server add-in tasks generally count as 2 DB2 applications. Some tasks have multiple threads.
v Finally, add 10 for other uses, for example, the DB2 Control Center or ″DB2 - CLP″ sessions.

In this procedure, you reset two DB2 configuration parameters, MAXAPPLS and MAXAGENTS.
1. Choose Start - Programs - IBM DB2 - Command Line Tools - Command Line Processor.
2. In the Command Line Processor (CLP) window, enter this command:
db2 update db cfg for <database name> using MAXAPPLS 100
3. Reset the DB2 configuration parameter MAXAGENTS to approximately 3 times the value of
MAXAPPLS, by entering the following in the CLP window:
db2 update dbm cfg for <database name> using MAXAGENTS 400

Resolving error ″SQL30020N with Reason Code ″0x124C″(″0214″)″: To resolve this error:
"SQL30020N with Reason Code "0x124C"("0214")"[Execution failed because of a Distributed Protocol Error ...]

Create a new replica of the problem database.

Resolving error ″SQL0956C Not enough storage is available in the application heap to process the statement″:
Domino acts as a client of DB2; therefore, DB2 must be configured to support the client demand placed
on it.

Depending on your configuration, you may need to adjust the DB2 database setting for DBHEAP. If you
encounter the error message ″SQL0956C Not enough storage is available in the application heap to
process the statement″ adjust the DBHEAP parameter to a greater value.

From a shell you can issue the command ″

update db cfg for your_dbname using DBHEAP value".

Resolving error 0803N: If a Domino Web Access client is trying to access an NSF file on a Domino server
that uses DB2 storage, some views and folders may be inaccessible to that client if they contain DBCS
characters, especially GB18030. The Domino server console displays this error:
SQL0803N
One or more values in the INSERT statement, UPDATE
statement, or foreign key update caused by a DELETE
statement are not valid because the primary key, unique
constraint or unique index identified by "1" constrains

1450 Lotus Domino Administrator 7 Help

table "DWA1.NSFOBJNAM" from having duplicate rows for
those columns. SQLSTATE=23505

Resolving error ″failed to extend tablespace″: Each Notes database is represented by several DB2 tables
stored in a DB2 tablespace.

When you enable a Domino server for DB2, you can specify the directory paths where DB2 creates
container files for the DB2 tablespaces. For example, you may see an entry similar to this in the Domino
server’s NOTES.INI file, or on the DB2 tab of the Server document in NAMES.NSF:
DB2DIRECTORY=H:\db2#I:\db2

It is possible for a physical drive to become full. For example, we will assume drive H in the sample
NOTES.INI and DB2 tab entry above is full. When a physical drive is full, the following error displays in
the Domino server console:
Failed to extend tablespace. DB2 NSF failure.: 5 - [IBM][CLI Dri - [DB2/NT] SQL0968C The file system is full. SQLSTAT

Resolving the problem: To resolve this problem, do the following in DB2 using either the DB2 Control
Center or DB2 Command Line Processor:
1. Create a container file on a drive other than the drive that is full.
2. Remove the container file from the drive that is full.
3. After container rebalancing completes, move the new container file to the drive from which you
removed the full container file.

For instructions on how to create a container file and how to remove a full container file, see the DB2
Information Center http://publib.boulder.ibm.com/infocenter/db2help/index.jsp.

Example: We are using tablespace USER1 with container FILE ’h:\db2\5.DB2NSF

Drive H is full.
1. Create a new container file on Drive I. Add 100MB (1GB) to drive I, as follows:
v Connect to Domino
v ALTER TABLESPACE USER1 ADD ( FILE ’I:\db2\5.DB2NSF’ 64000 )
v CONNECT RESET
2. After container rebalancing occurs, drop the new container file on drive H.
v Connect to Domino
v ALTER TABLESPACE USER1 DROP ( FILE ’h:\db2\5.DB2NSF’ )
v CONNECT RESET

Resolving error caused by starting DB2-enabled server twice: If you start the DB2-enabled server twice by
doing any of the following, an error message is generated.
v Starting the DB2 server when it is already running
v Clicking the shortcut icon too quickly and causing the server to start twice

Note: The error is not written to the server console; therefore, you must check the log file to see the error
message.

When the server is started twice, the log file, NSERVER.LOG, contains error messages similar to the
following:
[1098:0002-04C4] A RM error occurred
[1098:0002-04C4] DB2 Connection preallocation complete, availableCount=0
[1098:0002-04C4] 03/26/2004 10:58:01 PM Unable to initialize DB2 services. DB2-based nsfs will be unusable.
[1098:0002-04C4] Server exiting:: Partition d.org3.lotus.domino.data is already in use.

Chapter 66. Troubleshooting 1451

"Server exiting:: Partition d.org3.lotus.domino.data is already in use"
in server\init.c,ntsvmain.c ?

Resolving this error: To resolve this error, shut down and then restart the DB2 server.
1. Shut down the Domino server.
2. From the DB2 Command Line Processor (CLP), stop the DB2 server by entering this command:
db2stop force
3. Restart the DB2 server by entering this command:
db2start
4. Start the Domino server.

Entry not found in index error message when creating a response document: If you attempt to add a new
Response document to an existing Response-to-Response document at the View level or if the document
was open and you selected New Response to Main document, the following error message appears:
Entry not found in Index.

You cannot create the new Response document.

Database cannot be created: There are situations in which Domino with DB2 is unable to create the DB2
enabled Notes database. DB2 returns an error message indicating that the DB2 enabled Notes database
cannot be created. For example,
v If you are using a version of Notes/Domino released prior to Domino 6.0, DB2 cannot create the DB2
enabled Notes database. The following error is generated: NSFDB2 Databases require Notes/Domino
6.0 or later database versions.
v DB2 services are not available. May generate the following error: Domino server is not DB2-enabled or
DB2 services were unable to initialize when the server started up.

ICL must be an NSF not a DB2-backed database: The Internet Certifier List (ICL) must be an NSF, not a DB2
database. If the ICL is created as a DB2 database, the following error appears:
CA Process: Error initializing certifier context (CN=OAca/O=ibm) from ICL db IDStorage form: Error accessing IDStorage docu

Create the ICL prior to running the DB2 Server Enablement Tool and verify that NSF is selected in the
″DB Default Creation″ field on the DB2 tab of the Server document. To prevent the CA Process from
failing, the ICL must be created prior to running the DB2 Server Enablement Tool, and it must have a
database default creation type of NSF.

Creating a service dependency for Domino and DB2: If you are using a local configuration with
Domino and DB2 running on the same computer, you may want to create a service dependency in
Microsoft Windows. Creating a service dependency between Domino and DB2 ensures that when Domino
is configured to run as a service, the Domino service only starts after the DB2 service starts for that DB2
instance. This service dependency applies only to a local configuration of Domino and DB2. Before
creating the service dependency, read all of the information in this topic.

You need to be aware of the following information when creating the service dependency:
v The Registry subkeys for services are located in the following path. These subkeys control how services
are loaded.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Lotus Domino Server (Data)\
v Create a new value named Depend on Service and then enter REG_MULTI_SZ as the data type.
v In the Data dialog box enter the name of the service exactly as the name of the service appears in the
registry under the Services key. When the computer starts, it uses this entry to verify that the service or
services listed in this value are started before attempting to start the dependent service.
v After creating the dependency, shut down and restart your system. The service manager process loads
the dependency list when the system restarts.

1452 Lotus Domino Administrator 7 Help

For instructions on creating the service dependency, reference the following URLs

http://www.microsoft.com/windows2000/techinfo/reskit/en-
us/default.asp?url=/windows2000/techinfo/reskit/en-us/regentry/46710.asp

http://support.microsoft.com/default.aspx?scid=kb;en-us;193888

http://www.microsoft.com/resources/documentation/WindowsServ/2003/all/deployguide/en-
us/Default.asp?url=/resources/documentation/WindowsServ/2003/all/deployguide/en-us/46710.asp

Use caution when deleting DB2 objects: Use caution when deleting any DB2 objects such as tables,
views, or UDFs (User Design Functions) from DB2 because deleting DB2 objects causes Notes NSF to
become corrupt and not function.

NSFDB2 databases require Domino 6.X or more recent: You must have Server Administrator rights to
perform the following database tasks for databases with ODS version ODS41. The database will have a
file name extension of NS5 for ODS version ODS41 and will be stored in NSF format on a DB2-enabled
Domino server.
v Create a database replica of a database
v Copy a database
v Create a new database with an NS5 file name extension on a DB2-enabled Domino server.

If you do not have appropriate access rights, this message displays:

NSFDB2 databases require Notes/Domino 6.0 or later database version: <servername> <filename>’.

Note: An NSFDB2 is a DB2 enabled Notes database.

Compact database options are enabled for Domino and DB2: Several Compact options are
implemented for Domino and DB2 configurations. When the -B option is applied to a DB2 enabled Notes
database, it reclaims disk space through tablespace reduction. This is accomplished by a series of table
and index reorganizations in DB2, which attempt to lower the tablespace’s high water mark (HWM) so
that the tablespace can be reduced in size. The effect of the DB2 table and index reorganizations is more
significant if you run compact when Domino is not running. Space reclamation in DB2 is entirely
different than that which a Domino administrator is accustomed to. Performing compact -B on a DB2
enabled Notes database does not guarantee that any space can be reclaimed.

Running compact -B on a directory results in a single set of table and index reorganizations because
several DB2 enabled Notes databases can exist in a set of tables within a tablespace. The table and index
reorganizations for data in a DB2 enabled Notes database are deferred until compact is finished with
regular NSF processing.

Note: The Compact -b option does not have any impact on a DB2 enabled Notes database.

The Domino administrator should be familiar with the DB2 Database Analysis and Reporting Tool
(db2dart.) Db2dart is a DB2 utility that displays tablespace usage information, including what needs to be
done to best lower the HWM of a tablespace so that the tablespace can be reduced in size.

For more information about db2dart, go to the DB2 Information Center at

http://publib.boulder.ibm.com/infocenter/db2help/index.jsp.

NSFDB2 created with Domino 7 beta 1 may not work correctly with more recent Domino beta
releases: If DB2 services are down, all DB2-enabled Notes databases (NSFDB2 databases) that were
created using the beta 1 release of Domino 7 and DB2 display in the Domino Administrator client with
NSF icons, not DB2-enabled Notes databases icons. The DB2 enabled Notes database size is also incorrect.

Chapter 66. Troubleshooting 1453

Domino does not connect to its DB2 database or has difficulty connecting: If Domino and DB2 are
part of a local configuration on Microsoft Windows, and Domino has problems connecting to its DB2
database, or exhibits unusual behavior when attempting to connect, use the ″net user″ command to check
the status of the ID that Domino is using while attempting to connect to DB2. At the DOS prompt, enter
this command:
net user SomeUserID

You can also check the file, DB2DIAG.LOG, in the instance in which DB2 is installed. By default, DB2 is
installed in c:\Program Files\IBM\SQLLIB, and the default instance name is DB2. If you used all of the
defaults, check this path: c:\Program Files\IBM\SQLLIB\DB2\db2diag.log.

If DB2 is remote but is installed on a computer running Microsoft Windows, enter the ″net user″
command on the computer on which DB2 is installed.

Domino Web Access -- Troubleshooting

Soft Delete does not work in a mixed environment: In a mixed release environment, users who have a
database with soft delete enabled will have problems deleting documents in that database, if it is
replicated back to a 6.0 server that is running the older forms file (Forms5) and Template.

Spell check character set should match server OS: The Domino Web Access spell check functionality
will not work properly, unless the Domino server operating system character set is the same as the text
being checked. If this is not the case, the spell check engine may not correctly interpret some characters.

Text in some fields displays too small in localized versions: In some localized versions of Domino Web
Access on Mozilla Firefox on Linux, text in some of the fields, such as Search or cc: may appear too
small. This happens if the browser character encoding is set to Unicode (UTF-8) or Western (ISO-8859-1,
for example). Users can customize the browser Character Encoding set to the required language (View -
Character Encoding - Customize List).

Pop-up blockers prevent windows from opening: Pop-up blockers may prevent new windows from
launching, which makes Domino Web Access unusable. For example, users cannot create a new message
or calendar entry because they pop-up blocker prevents the new message or calendar entry form from
opening. Pop-up blockers are enabled by default on some browsers. To resolve this issue, users can either
disable pop-up blocking altogether, or add allowed sites, such as *.ibm.com, for example.

Users cannot open doc links on servers other than mail server: To allow users to open attached doc
links for documents that reside on servers other than the mail server, you must enable the field ″redirect
to resolve external links″ in the Server document or the Internet Site document (if configured). You must
also replicate the server’s catalog.nsf with that of the external server.

For information on finding links with the Redirect URL command, see the Chapter ″Setting up the
Domino Web Server″ in the Lotus Domino Administrator Help.

Attachments larger than 10MB are not allowed: By default Domino Web Access allows a maximum
attachment size of 50,000K (50MB), which you can increase by setting the ″Maximum attachment size
(kb)″ field in the Domino server Configuration Settings document on the Domino Web Access tab.
However, attachment size is based on two parameters that default to a 10,000K (10MB) limit independent
of this setting. So even though Domino Web Access allows for a larger attachment, the following two
settings must be increased to a value larger than the Domino Web Access maximum attachment setting
for users to be able to add attachments larger than 10MB.

In the Server or Web Site document, set these settings higher than the Domino Web Access ″Maximum
attachment size″ field:
v In the Server document -- Internet Protocols - HTTP - Maximum Size of Request
v In the Server or Web Site document -- Internet Protocols - Domino Web Engine - Maximum Post data

1454 Lotus Domino Administrator 7 Help

Directories -- Troubleshooting
These topics describe how to troubleshoot problems related to:
v Directory assistance
v Directory catalogs
v LDAP service
v Extended ACL

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Directory assistance -- Troubleshooting: These topics describe problems you may encounter with
directory assistance.
v Internet user authentication using a secondary Domino Directory or Extended Directory Catalog fails.
v Internet user authentication using an LDAP directory fails.
v Database authorization using groups in a secondary directory fails.
v Searches in a secondary Domino Directory configured in directory assistance fail.
v ″Directory assistance could not access Public Address Book on Server x, error is Server Not
Responding″.

Tip: To record at the server console detailed information about specific Web user authentication sessions
to help troubleshoot Web user authentication problems, use the NOTES.INI setting
WebAuth_Verbose_Trace.

Internet user authentication using a secondary Domino Directory or Extended Directory Catalog fails: To
authenticate Internet users registered in a secondary Domino Directory, make sure you complete these
steps:
1. Select ″Notes as the ″Domain Type″ in the Directory Assistance document.
2. Set ″Trusted for credentials″ to Yes for at least one naming rule in the Directory Assistance document.
The rule or rules should correspond to the names of the Internet users you want to authenticate.
3. Enter the secondary directory’s Domino domain in the ″Domain Name″ field. Do not enter: the name
of a condensed Directory Catalog, the name of the server’s primary domain, or a domain name that is
used in another Directory Assistance document. If you created the secondary directory manually and
it’s not associated with a Domino domain, make up a unique domain name.
4. If you use name-and-password authentication, and you choose the authentication option ″Fewer name
variations with higher security,″ make sure users provide either their hierarchical names or common
names for authentication rather than first names, last names, or short names only.
For more information on this server authentication option, see the chapter ″Setting Up
Name-and-Password and Anonymous Access to Domino Servers.″
5. If you include groups of users in database ACLs on the server that authenticates, store those groups
in the server’s primary Domino Directory and/or in one directory enabled for ″Group authorization″
in the directory assistance database.

Internet user authentication using an LDAP directory fails: To authenticate Internet users registered in a
remote LDAP directory, make sure you complete these steps:
1. Select LDAP as the ″Domain Type″ in the Directory Assistance document.
2. Specify a ″Domain Name″ that is not the Domino domain of the servers that use directory assistance
and that is not used in another Directory Assistance document.
3. (Recommended) Enter ″1″ as the search order.
4. Set ″Trusted for credentials″ to Yes for at least one naming rule in the Directory Assistance document
that corresponds to the names of the users to authenticate.
5. If the remote LDAP server requires a base DN, enter it in the field, ″Base DN for search.″

Chapter 66. Troubleshooting 1455

6. Select ″Notes clients/Internet Authentication/Authorization″ in the ″Make this domain available to″
field.
7. If you enabled ″Channel encryption,″ make sure you’ve configured SSL properly.
8. If the LDAP directory server doesn’t allow anonymous connections, make sure you’ve entered a user
name and password in the ″Optional Authentication Credential″ section of the Directory Assistance
document.
9. If the server authentication option ″More name variations with lower security″ is selected, make sure
the server has access to the LDAP directory attributes cn, uid, sn, givenName, and objectClass.
If the server authentication option, ″Fewer name variations with higher security″ is selected, make
sure the Web server has access to the LDAP directory attributes cn, uid, and objectClass.
For more information on the server authentication options, see the chapter ″Setting Up
Name-and-Password and Anonymous Access to Domino Servers.″

Database authorization using groups in a secondary directory fails: To search a secondary directory -- Domino
or LDAP -- for the members of groups listed in database ACLs, make sure you complete these steps:
1. Specify a ″Domain Name″ that is not the Domino domain of the servers that use directory assistance
and that is not used in another Directory Assistance document.
2. Set the ″Group Authorization″ field to ″Yes;″ enable this option in only one Directory Assistance
document.
3. Set ″Trusted for credentials″ to yes for at least one naming rule that represents the names within the
groups to search.
4. If the directory is a Microsoft Active Directory, choose ″Active Directory″ in the ″Type of search filter
to use″ field of the Directory Assistance document.
5. If the directory is a remote LDAP directory, when you add the name of a hierarchical group from an
LDAP directory to a Notes database ACL, use the LDAP format for the name, but use forward slashes
as delimiters (/) rather than commas (,). If the name of the LDAP directory group is not hierarchical,
in a Notes database ACL enter the value for the group name without the associated LDAP attribute.
For example, if the name of the LDAP directory group is cn=managers,ou=groups,o=acme, in the
database ACL enter cn=managers/ou=groups/o=acme. If the name of the group is cn=managers, in
the database ACL enter managers.
6. Select ″Notes clients/Internet Authentication/Authorization″ in the ″Make this domain available to″
field.
7. If the directory is a remote LDAP directory and you’ve enabled ″Channel encryption,″ make sure
you’ve configured SSL correctly.
8. If the directory is on a remote LDAP directory server that doesn’t allow anonymous connections,
make sure you’ve entered a user name and password in the ″Optional Authentication Credential″
section of the Directory Assistance document.
9. If the members of groups on a remote LDAP directory server change, stop and restart the Domino
server that connects to the LDAP server. This ensures that the Domino server flushes its group cache
and retrieves the most up-to-date group information.

Searches in a secondary Domino Directory configured in directory assistance fail: Make sure the domain
specified in the Domain Name field of the Directory Assistance document for the secondary directory is
different from the primary Domino Directory and any other directories configured in directory assistance.
If the Domain Name specified for the secondary Domino Directory is not unique, searches of the
secondary directory fail, and you see the message ″User xxx not found in any Name and Address Book.″

If the secondary directory is not associated with a Domino domain, be sure to enter a unique Domain
Name that is different from the primary domain of the servers that store the secondary directory.

Don’t enter the name of a condensed Directory Catalog in a Directory Assistance document.

1456 Lotus Domino Administrator 7 Help

″Directory assistance could not access Public Address Book on Server x, error is Server Not Responding″: When
you restart a server that uses directory assistance, the server attempts to access replicas of secondary
Domino directories that database links in directory assistance point to so that it can load information
about the replicas into memory. If the server can’t locate the replicas, this server console message appears.
To avoid this problem, in directory assistance documents, enter server names and file names for replicas,
rather than paste database links to the replicas.

This message may also appear when a server that uses directory assistance attempts to look up a name in
a secondary Domino Directory that is on an unavailable server. As a failover mechanism, you can specify
more than one replica of a secondary directory for directory assistance to use.

Directory catalogs -- Troubleshooting: These topics describe problems you may encounter with
directory catalogs:
v Names are missing from the directory catalog.
v Users can’t use type-ahead addressing to look up names in a condensed Directory Catalog.
v Domino isn’t searching a directory catalog on a server.
v Internet user name-and-password authentication using a condensed Directory Catalog fails.
v LDAP searches of a condensed Directory Catalog aren’t working.
v A directory catalog is not full-text indexed or the full-text index is corrupted.
v The User Setup Profile doesn’t push Mobile Directory Catalogs to users
v The Router is finding the same name in multiple directories even though ″Exhaustive lookup″ is
disabled..
v Users can’t do full-text searches of a condensed Directory Catalog.

Names are missing from the directory catalog: If names appear to be missing from the directory catalog, take
these steps to troubleshoot the problem.

Verify that the Dircat task is building the directories as intended:

1. Open the directory catalog on the server that aggregates it.
2. Select the Configuration Settings document, and then choose File - Document Properties.
3. Click the Fields tab -- the second tab -- in the properties box.
4. Select the Directories field and look in the box on the right. Verify that the Dircat task can access all
the directories specified in the box. Typically, this means making sure that the server that aggregates
the directory catalog also stores replicas of all the aggregated directories locally..
5. Select the Since field and look in the box on the right to see the date and time the Dircat task last ran
on all of the directories specified in the Directories field. If either of the following is true, run the
Dircat task again:
v If there are fewer time/date stamps than directories -- for example, if there are four directories in
the Directories field but only two time/date stamps -- when the Dircat task last ran, it attempted to
rebuild the source directory catalog but didn’t complete the task.
v If the time/date stamps are older than expected, the Dircat task may not have run to completion
when it last did an incremental update of the source directory catalog.

If the ″Remove duplicate users″ option is enabled, see if someone has deleted a duplicate entry from one of the full
Domino directories: If the ″Remove duplicate users″ option is enabled, the Dircat task doesn’t add into the
directory catalog all entries associated with an identical hierarchical name. Instead, the task adds an entry
from the first directory in which it encounters the name. Dircat searches directories in the order that
they’re specified in the ″Directories to include″ configuration field.

If someone removes a duplicate entry from the full Domino Directory that has already been the entry
used in the directory catalog, that name is removed from the catalog. For example, if the Acme East and
the Acme West directories both contain an entry with the name, Phyllis Spera/Acme, if ″Remove

Chapter 66. Troubleshooting 1457

duplicate users″ is enabled, and if Acme East is listed first in the ″Directories to include″ field, when
Dircat runs, it includes only the entry from Acme East. If someone then removes Phyllis Spera/Acme
from Acme East, the name is removed from the directory catalog the next time Dircat runs.

To correct the problem, make a minor change to the remaining entry -- in the above example, the entry in
Acme West. This change causes Dircat to add the entry to the directory catalog the next time it runs. You
can also correct the problem by clicking the ″Clear History″ button in the directory catalog Configuration
document, although this approach rebuilds the entire directory catalog.

Verify that the User Name fields have values: If there’s no value in the User Name (FullName) field in a
Person document, the Dircat task won’t build the entry in the directory catalog. Notes registration adds
values to User Name fields automatically, but if you created Person entries without using the Notes
registration program, check that the entries have values in this field.

Use Log_Dircat=1: If the above steps don’t solve the problem, add the NOTES.INI setting Log_Dircat=1,
which logs information about the Dircat task in the log file (LOG.NSF). Use the logged information to
help troubleshoot the problem.

For more information on the log file, see the chapter ″Using Log Files.″ For more information on the
NOTES.INI file, see the appendix ″NOTES.INI File.″

Users can’t use type-ahead addressing to look up names in a condensed Directory Catalog: Type-ahead
addressing looks up a name in a condensed Directory Catalog only if the order in which the user types
the name corresponds to the ″Sort by″ format configured for the directory catalog. For example, if the
configured ″Sort by″ format is ″Distinguished name,″ type-ahead looks up the name in a directory catalog
only when a user types the first name before the last name. Or, if the ″Sort by″ format is set to ″Last
name,″ type-ahead looks up the name in a directory catalog only when a user types the last name before
the first name.

Domino isn’t searching a directory catalog on a server: To search an Extended Directory Catalog that is not
integrated into its primary Domino Directory, a server must be set up to use a directory assistance
database that contains a Directory Assistance document for the directory catalog.

To search a condensed Directory Catalog, a server must store a local replica of the directory catalog. In
addition, you must specify the file name for this replica in either the Directory Profile or in the Basics
section of the Server document in the server’s primary Domino Directory.

For more information on directory catalogs, see the chapter ″Setting Up Directory Catalogs.″

Internet user name-and-password authentication using a condensed Directory Catalog fails: If you’re having
difficulty setting up a server to use a condensed Directory Catalog to look up names and passwords to
authenticate Internet users, take these steps to troubleshoot the problem.

Note: These steps do not apply to authentication using an Extended Directory Catalog.
1. Test that authentication using directory assistance alone is working.
v Temporarily disable the directory catalog. Remove the directory catalog file name from the server’s
primary Domino Directory. Remove the directory catalog file name from the Directory Profile and
from the Basics tab of the Server document; the file name is probably stored in only one of these
locations but if it is in both locations, remove the name from both.
v Restart the appropriate Internet protocol server task. For example, for a Web server, restart the
HTTP task.
v Verify that the server can authenticate to each secondary Domino Directory configured in the
directory assistance database that you want to use for authentication. If authentication fails, go to
step 2. If authentication is successful, go to step 3.

1458 Lotus Domino Administrator 7 Help

2. If you are trusting all the aggregated directories for authentication, make sure you’ve selected the
option on the Basics tab of the Server document: ″Trust the server based condensed directory catalog
for authentication with internet protocols.″
If you are trusting for authentication only some of the aggregated directories, make sure you’ve
created a Directory Assistance document for each of the directories to trust in which the users to
authenticate are registered. In each Directory Assistance document, verify that you’ve done the
following:
v Set ″Trusted for credentials″ to Yes for at least one naming rule in the Directory Assistance
document. The rule or rules should correspond to the names of the Web users you want to
authenticate.
v Enter the secondary directory’s Notes domain in the ″Domain Name″ field. Do not enter: the name
of the directory catalog, the name of the server’s primary domain, or a domain name that is used in
another Directory Assistance document. If you created the secondary directory manually and it’s
not associated with a Notes domain, make up a unique domain name.
v In the Replicas tab of the Directory Assistance document, make sure one of the replicas specified is
the same replica of the secondary directory specified in the ″Directories to include″ field in the
directory catalog Configuration document.
Do not specify a replica of the directory catalog.
3. In the ″Directories to include″ field of the directory catalog Configuration document, specify a replica
of each secondary Domino Directory that contains the users you want to authenticate. Do not include
the name of an LDAP directory in the ″Directories to include″ field.
4. In the ″Additional fields to include″ field of the directory catalog Configuration document, do the
following:
v If you are accessing mail over HTTP, add the HTTPpassword field.
v If you are also accessing mail over IMAP/POP3, add MailServer, MailFile, and MailSystem fields in
the ″Additional fields to include″ field.
5. Run the Dircat task to build the directory catalog.
6. If the server on which you ran the Dircat task is not the server doing the authentication, make sure
you’ve created a replica of the populated directory catalog on the server, added the directory catalog
file name to either the Directory Profile or the Basics tab of the Server document, and then restarted
the server.
7. If you use name-and-password authentication, and you choose the server authentication option
″Fewer name variations with higher security,″ make sure users provide either their hierarchical names
or common names for authentication rather than first names, last names, or short names only.
For more information on the server authentication option, see the chapter ″Setting Up
Name-and-Password and Anonymous Access to Domino Servers.″
8. If you include groups of users in database ACLs on the server, store those groups in the server’s
primary Domino Directory and/or in one directory configured in the directory assistance database
that is enabled for group authorization.

LDAP searches of a condensed Directory Catalog aren’t working: If the LDAP service isn’t searching a local
condensed Directory Catalog as expected, make sure the directory catalog has a functioning, full-text
index. The LDAP service always use the directory catalog full-text index to process searches. The LDAP
service can return the error ″LDAP error ’DSA is unwilling to perform’ (0x35)″ when attempting to search
a directory catalog that is not full text indexed. If necessary, delete and then re-create the full-text index.

A condensed Directory Catalog is not full-text indexed or the full-text index is corrupted: When you first create
a condensed Directory Catalog, you must manually create a full-text index for it; you are prompted to
create the index when you create the database. When you replicate the directory catalog however,
Domino automatically creates the full-text index on the replica. If you create a copy rather than a replica,
you must manually create the full-text index on the copy.

Chapter 66. Troubleshooting 1459

The full-text index can become corrupted if there is not enough disk space to build the index or if you
shut down the Notes or Domino Administrator client before the index is entirely built. To correct the
problem, delete and then recreate the full-text index.

User Setup Profile doesn’t push Mobile Directory Catalogs to users: To use a User Setup Profile to set up
mobile directory catalogs on Notes clients, you must paste a database link of a replica of the directory
catalog in the ″Mobile directory catalogs″ field of the User Setup Profile. The Notes clients don’t receive a
replica of the mobile directory catalog until the User Setup Profile replicates to the users’ mail servers
and the users authenticate with the mail servers.

Router is finding the same name in multiple directories even though the ″Exhaustive lookup″ setting is disabled:
By default, the Router configuration option ″Exhaustive lookup″ -- available on the Router/SMTP - Basics
tab of a Configuration Settings document -- is disabled. If you keep this default setting, once the Router
finds a name, it doesn’t continue its search to other secondary Domino directories. Disabling exhaustive
lookups is a way to improve Router performance .

By design, disabling ″Exhaustive lookup″ does not apply to a directory catalog. The Router always
searches the primary Domino Directory and the entire server directory catalog, even if the exhaustive
lookup setting is disabled. This is intended behavior since the Router can use the directory catalog to, in
effect, quickly search multiple secondary directories rather than having to take the performance hit of
searching these directories individually. These exhaustive lookups allow the Router to ensure there are no
duplicate recipient names that might prevent the message from getting to the right person.

The Router returns a delivery failure when it finds a name associated with more than one directory entry
and the entries do not have the same Mail server, Mail file, or Domains specified. To avoid such delivery
failures when duplicate entries actually represent the same person (for example, when someone’s name
and directory location within the organization have changed but you want to allow people to address
mail using the original name), make the entries in the Mail server, Mail file, and Domain fields identical
for each entry.

Users can’t do full-text searches of a condensed Directory Catalog: A condensed Directory Catalog doesn’t
support direct full-text searches by users, only indirect full-text searches via LDAP, mail addressing, and
so on.

LDAP service -- Troubleshooting: These topics describe problems you may encounter with the LDAP
service:
v Name and password authentication fails for LDAP clients connecting to the LDAP service
v LDAP searches are slow
v Anonymous LDAP users can’t search certain fields
v ″LDAP Server: Initialization failure: The full text index needs to be rebuilt″
v LDAP searches don’t return a cn attribute
v LDAP error ″Insufficient Access″ returned on an LDAP Add operation
v LDAP clients can’t connect to the server over SSL when the server uses a self-signed Domino server
certificate
v ″LDAP Schema: Failed exporting″ error

Name and password authentication fails for LDAP clients connecting to the LDAP service: To authenticate
using name-and-password security some LDAP clients, for example Microsoft Internet Explorer and
Notes clients with LDAP accounts, first do an anonymous search to retrieve the distinguished names
used for the authentication, so that users don’t have to specify the distinguished names themselves. To
enable such clients to authenticate using names and passwords, you must enable anonymous access, as
well as name and password authentication, for the LDAP service port the clients use to connect. You

1460 Lotus Domino Administrator 7 Help

must also allow anonymous read access to the attribute(s) the clients use to search the directory
anonymously to retrieve the distinguished names. Attributes typically searched for are cn, uid, sn,
givenname, or mail.

For information on anonymous access and the LDAP service, see the chapter ″Setting Up the LDAP
Service.″

LDAP searches are slow: If LDAP searches are slow, do the following on the replica of the primary
Domino Directory. If you extend LDAP searches to secondary Domino Directories, also do the following
on each replica of the secondary directory.
1. Create a full-text index for the directory.
2. If you’ve created a full-text index for the directory and performance is still slow, consider editing the
value of these LDAP configuration fields:
v ″Maximum number of entries returned″ limits the number of entries that the LDAP server can
return. By default there is no limit, but you might set a limit of 100 entries, for example.
v ″Timeout″ limits the amount of time that LDAP searches can take. By default, there is no limit, but
you might set a limit of 60 seconds, for example.
v ″Minimum characters for wildcard search″ increases the number of characters that users must enter
before the first wildcard in a substring search filter. The default is 1. Don’t specify 0 unless the
directory is very small; specifying 0 can result in slow searches.
For more information on improving LDAP service performance, see the chapter ″Setting Up the LDAP
Service.″

Anonymous LDAP users can’t search certain fields: Make sure you’ve enabled the fields for anonymous
access, using the domain Configuration Settings document or the database ACL/extended ACL. Keep in
mind that you configure fields for anonymous access separately for the LDAP service’s primary Domino
Directory and for each secondary Domino directory the LDAP service serves.

For more information on anonymous LDAP search access, see the chapter ″Setting Up the LDAP Service.″

″LDAP Server: Initialization failure: The full text index needs to be rebuilt″: If the LDAP service setting
″Automatically Full Text Index Domino Directory″ is set to Yes in a domain Configuration Settings
document, this message can appear on a server running the LDAP service if the full-text index for the
primary Domino Directory is corrupted and requires rebuilding. The LDAP service shuts down after
displaying the message. To correct the problem:
1. Use the Exit or Quit command to shut down the Domino server.
2. At the operating system prompt, issue one of the following commands from the Domino program
directory to run the updall task and rebuild the directory full-text index:
v On UNIX type: updall directory.nsf -X
where directory.nsf is the file name of the primary Domino Directory.
3. Restart the server.

LDAP searches don’t return a cn attribute: If you add a Person document to the Domino Directory without
using Notes registration, and you enter a hierarchical name in the FullName (User name) field, the
leftmost part of the distinguished name does not automatically become the cn (common name) attribute
value. You must add the common name as a second value in the FullName field to define a cn attribute
for the entry.

This is also true for groups and servers. if you add a Group or Server document to the Domino Directory
without using Notes registration, you must add the common name as a second value in the ListName or
ServerName fields

Person documents created through Notes registration automatically have a second value added to the
FullName field to define the cn attribute.
Chapter 66. Troubleshooting 1461
LDAP error ″Insufficient Access″ returned on an LDAP Add operation: If you see this error in response to an
LDAP Add operation, do the following:
1. Verify that the option ″Allow LDAP users write is set to ″Yes″ in the LDAP section of the
Configuration Settings document for that Domino Directory.
2. Verify that the LDAP user has the necessary access in the Domino Directory database ACL and
extended ACL, if an extended ACL is used.
3. If the LDAP user has Author access in the ACL, verify that the LDAP user has the proper Creator
Role ([UserCreator], [GroupCreator], [ServerCreator] for the type of entry being added.
4. Verify that Form Properties are correctly set to allow the LDAP user to create documents with the
form used to add the entry.

LDAP clients can’t connect to the LDAP service over SSL when the server uses a self-signed Domino server
certificate: If the server that runs the LDAP service uses a self-signed Domino certificate, non-Notes
LDAP clients can only perform LDAP searches over SSL if they first connect to the Domino server over
SSL using a different protocol (for example HTTPS or IMAP). The client software then presents a warning
dialog stating that the server’s self-signed certificate is not issued by a trusted Certificate Authority and
gives the users the option to accept the certificate. The users must accept the certificate before they can
perform LDAP searches over SSL.

″LDAP Schema: Failed exporting″ error: If you use the tell ldap exportschema command when the Domino
LDAP Schema database (SCHEMA.NSF) is open, schema exporting fails and the LDAP service returns
this error. Close the database before using this command.

LDAP service and remote search operations: Additional steps may be required to guarantee that a Domino
LDAP service running on one Domino server can successfully search another server’s Domino Directory.
When extended access is enabled for the remote directory, or when the search request comes from an
authenticated LDAP client, in order to do the remote search, the database ACL on the remote directory
must grant the server that receives the LDAP request at least Reader access, defined through a ″Server″
or ″Server group″ entry. By default, the LocalDomainServers and OtherDomainServers groups have the
required access in the Domino Directory ACL, so no special configuration is required for the normal case
where both servers are in the same domain.

Extended ACL -- Troubleshooting: These topics describes situations you may encounter when using
extended ACLs:
v The access specified for subject is different than the subject’s actual access.
v The Target box doesn’t show documents.
v I can’t change a subject’s access to a target.
v Notes and Web users are getting unexpected results when accessing the directory
v ″Extended access controls are enabled in this domain. You must modify the Domino Directory on a
version 6 or later Domino server.″
v Allowing users to see column values when extended ACLs are used
v LDAP service and remote search operations
v Maximum Internet name and password settings with Extended Access
v NAMELookups to remote directories with Extended Access warnings

The access specified for subject is different than the subject’s actual access: The access you see set for a subject
at an extended ACL target may not reflect the actual, effective access the subject has. For example, there
may be access set for another subject that takes precedence. Or the database ACL may not actually allow
the access that has been set for the subject in the extended ACL. Click Effective Access in the ″Extended
access at target″ dialog box to find out more about what is controlling a particular user’s access to an
extended ACL target.

1462 Lotus Domino Administrator 7 Help

The Target box doesn’t show documents: The Target box in the ″Extended Access at: target″ dialog box
shows documents below the target categories only if ″Show only containers″ is not selected. Using
categories as targets rather than individual documents is recommended.

Documents show under a target category only if there names are defined through a FullName, ListName,
or ServerName field. Access set at the / (root) controls access to documents that don’t use FullName,
ListName, or ServerName fields.

I can’t change a subject’s access to a target: To modify a subject’s privileges to a selected target, you must
have Manager access in the directory database ACL, or Editor access and the Administer privilege to the
selected target. If you do not have the required access, a subject’s privileges are grayed out.

In addition, if Show All is selected next to ″People, Servers, Groups″ in the ″Extended access at: target″
dialog box, the list of subjects includes those whose privileges to the selected target are inherited from a
higher target with the scope ″This container and all descendants″ selected. When you select such a
subject, the subject’s privileges are grayed out. In this case you can change the subject’s privileges at the
higher target and have the current target inherit the changes. Or you can add the subject to the current
target with new privileges that override the inherited privileges at the current target.

Notes and Web users are getting unexpected results when accessing the directory: If you are controlling the
access of Notes and Web users, be aware of the following issues. These issues do not apply to access
through other means, such as access through LDAP operations or through the Notes applications, except
where indicated.
v If you deny a Notes or Web user access to a field in a document, when the user opens the document,
the document does not show the field and the text (TRUNCATED) shows in the tab of the document.
In addition, the user is unable to edit the document, even if the user has write access to the fields in it.
v If you deny a Notes or Web user access to a field in a document that a view uses to sort the document,
the name of the document is blank in the view. The user can still select the document to open it.
v To delete a document, a Notes or Web user must be able to see the document in a view. To see a
document requires Browse access to the document.
v To create a document, a Notes or Web user or a Notes application must have Create access to the
document as well as Write access to the fields to which the user/application will add values.

″Extended access controls are enabled in this domain. You must modify the Domino Directory on a version 6 or
later Domino server.″: This message indicates that you have attempted to modify a Domino Directory or
Extended Directory on a server running a previous release and the directory has the Extended Access
feature enabled. When Extended Access is enabled, changes to a replica of the directory on a server
running a previous release cannot replicate to a Lotus Domino 6 server, and so you should make the
changes to a replica on a Lotus Domino 6 server instead.

Allowing users to see column values when extended ACLs are used: If you use an extended ACL to prevent
users from reading a field in documents, and if a column formula in a view uses the field, the user will
not see values in the column. To allow a user to see values in a view column when extended ACLs are
used, make sure the user has read access to all of the fields used in the column formula.

Maximum Internet name and password settings with Extended Access: The default database ACL setting on a
Domino Directory for ″Maximum Internet Name & Password″ is Editor. When Extended Access is
enabled, this setting affects authenticated LDAP searches. If an entry in the database ACL is set higher
than Editor access (for example, Manager), that user’s access to the database will be lowered to Editor
when authenticating with their Internet password.

In order for authenticated LDAP searches for entries with Manager access to override Extended Access
restrictions, set ″Maximum Internet Name & Password″ to Manager by selecting File -> Database ->
Access Control -> Advanced.

Chapter 66. Troubleshooting 1463

NAMELookups to Remote Directories with Extended ACLs: NAMELookups to Remote Directories with
Extended Access enabled may issue warnings when the remote Domino server does not have extended
access enabled, but the remote Domino Directory does.

When a Domino server tries to access a remote Domino Directory that has Extended Access enabled
through Directory Assistance, the remote server must know about this directory being accessed. In other
words, the directory indicated in Directory Assistance on the first server must either be the Primary
Directory on the remote Domino server (typically names.nsf), or a local secondary directory configured
through Directory Assistance on that same remote server.

If you attempt to access the remote directory without the remote server knowing of the remote directory,
the first attempt will generate the following message on the first Domino server:
WARNING: NAMELookups from this server to the remote Domino Directory is prohibited.

This additional security requirement applies only when there are remote Domino Directories with
Extended ACLs enabled. Correct this error by creating a Directory Assistance document
for the remote server.
on

Mail routing -- Troubleshooting

A variety of error conditions can prevent Domino from properly sending and delivering mail. These
topics describe solutions to common mail routing problems and provide detailed information on
troubleshooting general mail routing problems:
v Tools for troubleshooting mail routing
v How to troubleshoot mail routing provides steps for troubleshooting when mail routing isn’t occurring
as you expect.
v Mail routing -- Problems and error messages describes problems and errors that users may experience
when they try to send mail.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Tools for troubleshooting mail routing:

Delivery Failure Reports: Users should always try to resend a memo for which they receive a Delivery
Failure Report. To help users troubleshoot delivery failure, ask them to use Steps 1 - 3 below to send you
a copy of their mail database. Sending you a copy of their mail database preserves the field properties of
the reports, which you analyze as a means of troubleshooting.
1. The user creates a new mail database on the workstation. From the menu, choose File - Database -
New. Be sure to use the current (MAIL6.NTF) mail template.
2. The user copies a Delivery Failure Report from the original mail file and pastes it into the new
database.
3. The user attaches the new mail database to a mail message and sends it to you.
4. You open the mail database attached to the mail message and select a Delivery Failure Report.
The Delivery Failure Report identifies the reason the delivery failed and the routing path over which
the message was sent. Use this information to further investigate the problem.

Mail trace: To troubleshoot mail routing or test mail connections, trace a mail delivery to test whether a
message can be successfully delivered without actually sending a test message.
1. From the Domino Administrator, click the Messaging - Mail tab.
2. If necessary, click Tools to display the tool bar.
3. From the tool bar, click Messaging - Send Mail Trace.

1464 Lotus Domino Administrator 7 Help

4. Complete these fields, and then click Send:

Field Enter
To The mail address of a particular user
Subject The subject of the trace
Send delivery report from Choose one:
v Each router on path to receive a delivery report from each router on the path
v Last router only to receive a delivery report from the last router only

Mail routing topology maps: Mail routing topology maps are useful to track mail routing problems
between servers.
1. From the Domino Administrator, click the Messaging - Mail tab.
2. Choose one:
v Mail routing topology by connections
v Mail routing topology by named networks

Undelivered mail: From the Domino Administrator, click the Messaging - Mail tab, then select Mail
routing status. You can also check for undelivered mail in the mail routing events view in the log file
(LOG.NSF).

Mail routing event generators: Using a mail routing event generator, you can test and gather statistics on
mail routes.

For more information on probes, see the chapter ″Monitoring the Domino Server.″

Mail routing -- Problems and error messages: These topics describe common problems and errors
related to sending and/or receiving mail:
v User can’t receive any mail, including mail sent by users whose mail files are on the same server
v ″File is in use by another process″
v ″NAMES.NSF does not contain a required view″
v ″No route found to Domain x from Server y″
v ″Router: Possibly no DOMAIN set...″
v ″Server Error: File Does Not Exist″
v ″User name is not unique″
v ″User not listed in the Public Address Book″
v Users unexpectedly required to include @domainname after each address

User can’t receive any mail, including mail sent by users whose mail files are on the same server: If a
user can’t receive any mail, including mail sent by other users whose mail files are on the same mail
server, check the Mail Routing Events view of the workstation’s log file for deliveries. Also, check the
MAIL.BOX file on the user’s workstation to see if mail is being trapped there. Modify the
Log_MailRouting setting in the NOTES.INI file to log more detailed mail routing information on the
console and in the log file.

″File is in use by another process″: If the recipient’s mail file or the MAIL.BOX file on the sending or
receiving server is being backed up, Domino generates the message ″File is in use by another process.″
Wait for the backup to complete, and then resend the message.

″NAMES.NSF does not contain a required view″ appears when sending mail to users on the same mail
server: If all users on the same mail server can’t send or receive mail and they receive the message
″NAMES.NSF does not contain a required view,″ you need to update the design of the Domino Directory.

Chapter 66. Troubleshooting 1465

Choose File - Database - Replace design. When you customize the design of the Domino Directory, the
design must be uniform across all replicas. Note that there are two templates: PUBNAMES.NTF, for the
Domino Directory, and PERNAMES.NTF, for the Personal Address Book. Be sure to use the
PUBNAMES.NTF template when working with the Domino Directory.

For more information on updating the design of the Domino Directory, see the appendix ″Customizing
the Domino Directory.″

″No route found to Domain x from Server y″: If users can’t send mail to another domain and receive a
message such as ″No route found to Domain x from Server y,″ make sure that each domain’s Domino
Directory has a Connection document from one of its servers to a server in the other domain. If a
Connection document doesn’t exist, create one. If there is a Connection document, make sure the
information contained in it is correct.

″Router: Possibly no DOMAIN set; use SET CONFIG DOMAIN=name to set it; or replace the Name
and Address Book design.″: If this message appears on console and then the Router shuts down, the
Server document may contain errors. In the Server document, verify that the domain is set, and that the
ServerKeyFileName (or KeyFileName) both refer to the server ID for that server. If necessary, make
corrections to the Server document. Also check that the Location document that you’re using refers to the
correct server ID. If necessary, edit the Location document so that it refers to the correct server ID.

″Server Error: File Does Not Exist″: This message occurs when a user tries to read a message that is
linked to an active shared mail file that has been improperly moved to a different directory, partition, or
hard drive.

For information on creating and enabling a shared mail database, see the chapter ″Setting Up Shared
Mail.″

″User name is not unique″ in a Delivery Failure Report: Check the Domino Directory for multiple
occurrences of the recipient’s name. There may be more than one Person document for a user, or a user
and a group may have the same name.

″User not listed in the Public Address Book″ appears with returned mail: If the recipient’s name is
misspelled, mail is returned to the sender, along with the message ″User not listed in the Public Address
Book.″ If the domain name is misspelled, mail is returned with the message ″No route found to domain
name from server name.″ Check the Domino Directory for the correct spelling of the names, and resend the
document.

Users unexpectedly required to include @domainname after each address: If users report that they
can’t send mail to another domain unless they include @domainname after each address, configure
directory assistance and directory catalogs to include the directories from the other domains.

How to troubleshoot mail routing: When dead or pending mail indicates a problem with mail routing
or when users have problems sending or receiving mail, use these tips to gather information, identify the
problem, and then correct it.
1. Analyze any Delivery Failure Reports.
2. Trace the mail delivery route.
3. Check the Domino Directory for errors that affect mail.
4. Check the sender’s and/or recipient’s workstation(s) for errors that affect mail.
5. Checking the server for errors that affect mail.
6. Check the shared mail setup.

Checking the Domino Directory for errors that affect mail: The Domino Directory is the source of
many conditions that prevent mail from routing properly. Check for these conditions and correct them, if
necessary.

1466 Lotus Domino Administrator 7 Help

1. Check the replication history of the Domino Directory to ensure that changes to it are replicating
properly. Make sure the Domino Directory’s ACL provides servers with at least Editor access. Check
for messages in the Administration Requests database, and verify that the Administration Process is
set up and working properly.
Mail problems occur if replication of the Domino Directory throughout the domain isn’t occurring
correctly. For example, if you move a user’s mail file and the change recording this move on the
Person document does not replicate, a mail message could bounce back and forth between two
servers and eventually be returned to the sender. Alternatively, the message could become dead mail
if the maximum hop count is exceeded.
2. Look for and correct any of these problems with Person documents:
v There’s no Person document for the recipient in the Domino Directory. If necessary, register the
recipient to create one.
v The mail recipient’s name, mail server, or mail file is incorrect or is spelled incorrectly. Correct the
entries, if necessary.
v There are multiple occurrences of the recipient’s name in the Domino Directory. There may be more
than one Person document, or a user and a group may have the same name. You can add a middle
initial to one of the user names if two users share the same name. You can modify a group name if
it’s duplicate of another.
v The recipient receives mail through a gateway. Make sure the recipient’s Person document contains
a forwarding address.
3. Check the Server documents of the sender’s and recipient’s mail servers. Make sure that the names of
the server, domain, and Notes named network are spelled correctly.
4. Check Connection documents for mail routing. If two servers are in different Notes named networks
(or domains) or don’t have a third server that has a Notes named network in common with both
servers, then you must create pairs of Connection documents to enable mail routing back and forth.
For servers in the same Notes named network, mail routing is automatic so you don’t need
Connection documents.
To check mail routing connections, from the Domino Administrator, click the Messaging - Mail tab.
You can see mail routing topology by connections or by named networks. Look for servers that can’t
reach a server in another Notes named network or domain. Then check the Domino Directory for
these problems, and edit or create the documents as necessary:
v Missing Connection documents. Make sure that each domain’s Domino Directory has a Connection
document from one of its servers to a server in the other domain.
v A misspelled Notes network or domain name in the Connection document.
v An incorrect phone number (for dialup connections) in the Connection document.
v A missing selection for ″Mail Routing″ in the Tasks field of the Connection document.
5. If mail routing occurs through a non-adjacent or foreign domain, check that the Domino Directory
contains a correctly set up Non-adjacent or Foreign domain document. For a non-adjacent domain,
verify that a Connection document to the intermediary, or ″middle,″ domain also exists.
6. If your organization uses cascading address books, be sure that the Names setting in the NOTES.INI
file contains the correct names of the cascading address books.

Checking the sender’s and/or recipient’s workstation for errors that affect mail: Check for these
conditions and correct them, if necessary.
1. Check the User Preferences (File - Preferences - User Preferences). Check the settings for Mail -- for
example, the Mail Program field may be set to None, which disables all mail for the user. Check the
settings under ports; the port(s) necessary to send mail may be disabled. For more information on
User Preferences, see Lotus Notes 6 Help.
2. Check the user’s Personal Address Book for a missing view. If a view is missing, replace the design of
the Personal Address Book. Choose File - Database - Replace Design, and specify the Personal
Address Book template, PERNAMES.NTF, not the Domino Directory template, PUBNAMES.NTF.
Replacing the design deletes any nonstandard private views but does not affect the data.

Chapter 66. Troubleshooting 1467

 For more information on replacing the design of a template, see the book Application Development with
Domino Designer.
3. Check if the user is using the appropriate Location document. For example, a mobile user who is
working in the office may be attempting to use a Location document that is for use only when the
user works at home. Another possibility is that the Location document may contain incorrect
information. To check the current Location document, from the workstation, choose File - Preferences -
Location Preferences.
Check that the sender’s workstation is set up with the correct mail server and mail file names. Choose
File - Preferences - Location Preferences, and verify the settings in the Home/mail server and Mail file
fields.

For more information on Location documents and on specifying a mail server and a mail file, see Lotus
Notes 6 Help.

Checking the server for errors that affect mail: Check for these conditions and correct them, if
necessary.
1. Verify that the sending and receiving servers have a certificate in common.
a. From the Domino Administrator, click the People & Groups tab.
b. From the tool bar, click Certification - ID file.
c. Choose the appropriate server ID file, and click Open.
d. Click Certificates to display the certificates held by the server.
e. Repeat for the second server.
f. Recertify one or both server IDs, as necessary.
2. Make sure there’s enough memory and disk space on the recipient’s mail server. Add memory to the
server, and/or increase the disk space for swapping. Add disk space to the server.
3. Check for a corrupt mail file. On rare occasions a recipient’s mail file may become corrupted. Do one
of these:
v Run the Fixup task. Use this task if the database is in Domino 5 or higher format and you’re not
using transaction logging, or if the database is in Domino 4 format.
v Run the Fixup task with the -J option. Use this task if the database is in Domino 5 or higher format
and you are using transaction logging. If you use a backup utility certified for Domino 5 and you
run Fixup -J, perform a full backup of the database as soon as Fixup finishes.
4. Check for a missing or incorrect Domain setting in the NOTES.INI file. At server startup, the Router
sends the message ″Mail Router started for domain x″ to the console and to the log file. To see if the
NOTES.INI file on the sender’s and recipient’s mail server includes a Domain setting, enter this
command at the console:
Show Configuration Domain
Then verify that the domain name is correctly spelled. To add the Domain setting or correct the
spelling of the domain name, enter this command at the console:
Set Configuration Domain = DomainName
where DomainName is the name of the mail server’s Notes domain.
5. Check for a corrupt MAIL.BOX on the server. Do one of these:
v Run the Fixup task. Use this task if the database is in Domino 5 or higher format and if you’re not
using transaction logging, or if the database is in Domino 4 format.
v Run the Fixup task with the -J option. Use this task if the database is in Domino 5 or higher format
and you are using transaction logging. If you use a backup utility certified for Domino 5 and you
run Fixup -J, perform a full backup of the database as soon as Fixup finishes.
If the corruption still persists, shut down the server and rename MAIL.BOX -- for example, rename it
to BADMAIL.BOX. Then restart the server to generate a new MAIL.BOX file, and copy any
uncorrupted documents from BADMAIL.BOX to MAIL.BOX.

1468 Lotus Domino Administrator 7 Help

6. Check for problems with modem connections.
For more information on errors that affect mail, see the topic ″User can’t receive mail, including mail
sent by other users whose mail files are on the same mail server″ earlier in this chapter.

Checking the shared mail setup: Check for these conditions and correct them, if necessary.
1. Verify that shared mail is enabled. To determine if a mail file or individual mail files in a directory
use shared mail, enter this command at the console:
Load Object Info USERMAIL.NSF
where USERMAIL.NSF is the name of a user’s mail file or the name of a directory that contains mail
files.
If you enter a directory name, the information that appears describes each mail file in the directory.
2. Check for a corrupt shared mail file. If you suspect the shared mail file is corrupt, you can restore the
file.
3. Verify that there’s enough disk space available for the shared mail file. If there isn’t, you can purge
obsolete message from a shared mail file.
4. Make sure the user’s mail file hasn’t been unlinked from the shared mail file. If necessary, relink the
mail file.
For more information about shared mail, see the chapter ″Setting Up Shared Mail.″

Meeting and resource scheduling -- Troubleshooting

These topics describe how to troubleshoot problems with scheduling meetings and reserving rooms.
v Meeting and resource scheduling -- Problems and error messages describes problems and errors that
users may experience or that are reported in the log file.
v How to troubleshoot Schedule Manager errors reported in the log provides steps for troubleshooting
Schedule Manager errors reported in the log file.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Meeting and resource scheduling -- Problems and error messages: These topics describe problems and
errors that occur with scheduling meetings or resources:
v Free time information isn’t available
v ″No resource/room found for time and/or capacity requirements″
v ″Can’t Find User in Name and Address Book″
v ″Cannot perform this action locally″

Free time information isn’t available: If, while scheduling a meeting, a user can’t look up free time for
a particular invitee because the invitee’s schedule is grayed out in the Free Time dialog box or if no
users’ free time information can be accessed and the message ″No scheduling information for the
requested users could be found at this time″ appears, use these tips to troubleshoot the problem.
1. Check that the invitee’s name is spelled correctly on the meeting invitation. If the invitee belongs to a
different domain, be sure to specify the invitee’s full hierarchical name, including the domain name.
2. Check that Domino 4.5 or higher is installed on the invitee’s mail server.
3. Make sure that the mail server is running. Free-time lookups fail if Domino cannot access the free
time database on the invitee’s mail server because the server is unavailable. If the server isn’t running,
the user can still complete invitation processing, including sending and receiving meeting-related
messages. Also, lookups for other invitees with free time databases on other servers still work.
4. Check that the Schedule Manager task is running on the mail server.
5. Check that the invitee saved his or her Calendar Profile after upgrading the design to the Domino 4.5
or higher mail template.

Chapter 66. Troubleshooting 1469

6. Check that the user is included in the list of users who can read the invitee’s Free time Schedule in
the Calendar Profile.
7. Check that the free-time lookup finds schedule information for users whose mail servers are in a
foreign or adjacent domain. If the free-time lookup fails, make sure a valid Domain document exists.
In addition, check the Calendar Server field in the Domain document to make sure a valid calendar
server has been defined for the domain.
8. Check that the mail servers are running the same protocol. The mail servers must run the same
protocol so that the servers can connect to each other to perform a free-time lookup.

″Can’t Find User in Name and Address Book″: If this message appears, the entry used in the
$BusyName field in a calendar entry for the Note ID reported in the log doesn’t exist in the Domino
Directory. This situation typically arises when a user leaves the company and the Domino Directory no
longer contains a Person document for the user. To resolve this error, find the document associated with
the NoteID, and delete the document.

To find the note ID and the document associated with it, see the topic ″Troubleshooting Schedule
Manager errors reported in the log″ later in this chapter.

″Cannot perform this action locally″: This message appears when you try to create a Site Profile in the
Resource Reservation database locally on the server. To avoid this message, when you open the Resource
Reservation database, specify the actual server, instead of ″Local.″

″No resource/room found for time and/or capacity requirements″: The message ″No resource/room
found for time and/or capacity requirements″ may appear when a user creates a reservation in the
Resource Reservation database. This message indicates that the Site Profile name for that particular
resource includes a comma -- for example, Acme, East. Re-create the Site Profile name without the comma
-- for example, Acme East.

Troubleshooting Schedule Manager errors reported in the log: Schedule Manager errors in the log
(LOG.NSF) report information about databases that may have a mismatch among the entry used in the
$BusyName field in a calendar entry, the name listed in BUSYTIME.NSF, and the name in the Domino
Directory. Use this procedure to determine a mismatch.
1. Open the database reported in the log.
2. Choose Create - View.
3. In the View Name field, enter a name for the view -- for example, NoteID.
4. In the View Type field, select Shared.
5. In the ″Select a location for the new view″ field, select where you want the view to appear.
6. Click OK.
7. Choose View - Design.
8. Under Recent Databases, click Views.
9. Double-click the new view that you created. If you placed the view under an existing view, the new
view’s name will include the name of the parent view -- for example, Inbox\NoteID.
10. Select the first column in the view, and choose Create - Insert new column.
11. Choose Design - Column Properties.
12. In the Title field, enter a name for the column -- for example, NoteID -- and press ENTER.
13. In the formula pane, for Display, select Formula.
14. Delete anything that currently appears in the Formula pane and enter the formula:
@NoteID
15. Click the check mark in the formula pane to accept the new formula.
16. Press ESCAPE, and click Yes to save the design.
17. Press ESCAPE to close the Designer.

1470 Lotus Domino Administrator 7 Help

18. Refresh the view so that all of the Note IDs appear in the database.
19. Find the Note ID that the Schedule Manager reported in the log, and select that document in the
view.
20. Choose File - Document Properties.
21. Click the Fields tab.
22. Scroll through the fields in the left box and search for a $BusyName field.
23. Compare the information in the $BusyName field to the entries in the BUSYTIME.NSF file and the
Domino Directory. Make any corrections.

Modems and remote connections -- Troubleshooting

A variety of conditions can prevent a modem from providing a remote connection that works. These
topics describe common problems and errors and provide specific suggestions for troubleshooting
modems and remote connections.
v Tools for troubleshooting modems and remote connections describes tools that you can use to help
troubleshoot modem and remote connection problems.
v How to troubleshoot modems and remote connections describes steps for trying to solve problems with
a modem or remote connection.
v Modems and remote connections -- Problems and error messages describes problems and errors that
users or Domino servers may encounter while using a modem and a remote connection to a Domino
server.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Tools for troubleshooting modems and remote connections:

Logging modem I/O: To record modem phone call information in the log (LOG.NSF), you must enable
logging. Recording modem calls is useful when you troubleshoot modem connections.
1. Choose File - Preferences - User Preferences and select Ports.
2. Select the port for which you want to log call information.
3. Choose COM Options, and then choose Log modem I/O.
4. Click OK twice.

Reading the message in the log file for a long setup string: When you customize a modem command file, you
may include long setup strings. If a long setup string contains an error, it may be difficult to determine
which command or parameter caused the problem.

To isolate the problematic command or parameter, split the setup string in half, and enter a new
Setup=AT command on the line immediately following the first half of the setup string. Try to make the
connection again, and then check the log to determine which half of the setup string is causes the error.
Continue splitting the setup string in half until you locate the command or parameter that causes the
problem.

How to troubleshoot modems and remote connections: A server or workstation may not be able to
connect properly through a dialup modem connection to another server or workstation. As a result, there
may be problems transferring information -- for example, mail might not route between two servers
connected by a modem. Use these tips to troubleshoot both sides of the modem connection:
1. Restart the modem and the remote server or workstation. Doing this usually helps when the modem
is behaves erratically -- for example, if the modem dials invalid phone numbers, refuses legitimate
modem commands, flashes the LEDs in irregular patterns, or displays other unusual behavior.
2. Make sure that the modem is the correct type and model for the server or workstation. If you think
the hardware is damaged, replace the damaged part with one that you know is working. Make one
change at time so that you can evaluate the effect.

Chapter 66. Troubleshooting 1471

 3. Check the modem configuration. Check the DIP switch settings, the telephone line, and option
buttons on the modem.
4. Verify that you’re dialing the correct number. If you’re dialing from an office that requires it, be sure
to precede the phone number with a 9 followed by a comma. Also, be sure to include a 1 and the
area or country code. If you’re sure of the number, contact the remote server administrator to
determine what the problem is.
5. Disable call-waiting. You can temporarily disable call-waiting for tone dialing by entering *70 as a
prefix for the number you dial. For pulse-dialing, enter 1170 as the prefix. Alternatively, you can
permanently disable call-waiting.
6. Unplug other telephone extensions before you make an outgoing call. You’ll lose the connection if
someone attempts to use an extension on the line you’re dialing out on.
7. Make sure that you’re using an analog line. If the phone system is digital and your modem is
analog, you won’t get a dial tone. Contact your local phone company for an analog line.
8. Check the COM port, hang-up, dial time-out, and hardware flow control settings. Port speed and
hardware flow control settings should be the same for modems that are trying to connect. To check
these settings, choose File - Preferences - User Preferences, select Ports, select the COM port you
want to check, and click COM options.
9. Check the modem command file. Make sure that it’s the correct one for your modem. Make sure it
uses the correct syntax and is free of any spelling errors, missing command parameters, and
incorrect settings or responses. Check the operating system time stamp and last revision date of the
file to make sure you’re using the correct version of the file. To do this, use a file manager such as
Windows Explorer. Make sure you specified the correct directory for the file -- for example, the
Notes\Data\Modems directory.
10. Check the Connection document in the Domino Directory. Make sure the fields in the Connection
document contain the correct information for a dialup modem connection.
11. Check the Miscellaneous Events view in the log (LOG.NSF). Sometimes modems that use the same
modem standards can’t connect to each other because of the way the manufacturer implemented the
standard. Contact the modem manufacturer to resolve the problem.
12. Check the Phone Calls view in the log. Numerous CRC or retransmission errors indicate that one or
both modems detect transmission errors. A damaged RJ-11 cord and/or poor phone line quality may
cause these errors. Try another cord and ask the phone company to check the phone line.

Modems and remote connections -- Problems and error messages: These topics provide suggestions for
troubleshooting problems you may encounter with modems and remote connections:
v Data isn’t transferring between two servers using a null modem
v The dialup server cycles through port speeds without initializing the modem
v Valid commands in the modem command file are ignored

Data isn’t transferring between two servers using a null modem: If you connect two servers with a
null modem cable and the servers make a connection but data does not transfer between them, try these
tips to solve the problem:
1. Replace the modem cable or port with one that you know works correctly.
2. Change the port speeds. Choose File - Preferences - User Preferences and select Ports. Select the port
you want to modify, and then select COM Options. Select a port speed that matches the port speed of
the other modem.

The dialup server cycles through port speeds without initializing the modem: If the log (LOG.NSF)
indicates that the server continuously cycles through port speeds without initializing the modem, the
server isn’t able to connect to or synchronize with the modem. Try these tips to solve the problem:
1. Turn the modem on and off to reset it.
2. Check the cable connection from the server to the modem. Make sure that the cable is attached to the
correct port and isn’t damaged.

1472 Lotus Domino Administrator 7 Help

3. Make sure the communication port is correctly configured.
4. Specify a lower port speed. Choose File - Preferences - User Preferences and select Ports. Select the
port you want to modify, and select COM Options. Select a lower port speed.
5. Replace the serial card and RS-232 interface card with one that you know works.

Valid commands in the modem command file are ignored: You may notice this problem if you check
the log and find that OK responses are missing after one or more valid commands. Try these tips to solve
the problem:
1. Make sure letters in the AT commands in the modem command file are either all uppercase or all
lowercase. Many modems do not recognize mixed-case commands.
2. Make sure that commands in a long setup string do not exceed the character limit for the modem.
Use the Setup=AT command at the beginning of each line to split the setup strings into smaller
sections.

Platform statistics -- Troubleshooting

These topics describe common problems with monitoring statistics. You can also search for solutions to
common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.
v Platform statistics are not fully initialized
v Setting up platform statistics on Windows 2000 systems
v System configuration issue for platform statistics on Windows 2000 systems

Platform statistics are not fully initialized: Platform statistics take a few minutes to initialize upon
Domino server startup. If you issue a Show Stat Platform command before initialization, you get the
following message:
Platform not in statistics table

Wait a few minutes and then issue the Show Stat Platform command again.

Setting up platform statistics on Windows 2000 systems: On Windows 2000 systems, your server must
be configured properly to collect network or Logical Disk statistics. Using software RAID is not
recommended. To set up your system for platform statistic collection:
1. Enable Logical Disk counters using the diskperf command:

Windows NT command Description

diskperf -y Enables the performance counters.
diskperf Provides status or help information.

Windows 2000 command Description

diskperf -y Enables the performance counters.
diskperf /? Provides help information.
diskperf Provides status or verifies that it has already been
enabled.

2. On Windows NT, enable network counters using the following steps:

a. Enable the SNMP service
b. During installation of the SNMP service, enable the physical layer property for SNMP. The SNMP
server enables the Network Interface Object and begins collecting network statistics for platform
statistics.
3. Restart the system so that the settings will take effect.

Chapter 66. Troubleshooting 1473

Troubleshooting system setup: During system setup, you may receive one or more of the following system
messages.

SNMP is not enabled:

Platform Stats Informational: Please see online help to enable SNMP service in order to monitor network performance.

The probable cause for this message is that platform statistics detected that the Network Interface Object
was not enabled. Enable the SNMP service.

Logical disk counters are not enabled:

Platform Stats Informational: Please execute diskperf.exe -y to enable Logical Disk performance counters.

The probable cause is that platform statistics detected that the logical disk counters were not enabled.
Enable logical disk counters.

Platform statistics do not appear to be enabled:

Platform not in Statistics Table

Type the following command:

sh perf

The system now displays this message:

Server Performance Monitoring is now enabled.

When the statistics are ready to be displayed, the system displays the following message, where n is the
number of current transactions or users.
n Transactions/Minute, n Users

You can now reissue the sh stat platform command.

nnotes.dll is set to the wrong path:

Platform: Notes DLL directory is different from executable directory.

Upon Domino startup, the path to the nnotes.dll is not set or is set incorrectly. Multiple installations of
Domino may exist on the system and an earlier installation of Domino is being invoked. Make sure that
nnotes.dll is set to this path:
HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\notestat\\Performance\\Library

Perfmon was incorrectly installed:

Platform Stats Informational: MMC incorrectly installed. Please reinstall Win2K server to enable data collect
ttto

Perfmon, the performance monitoring package was incorrectly installed when the system was upgraded.
Reinstall the Win2K server.

Note: If you need additional information regarding enabling the SNMP server, refer to your Windows
2000 System Administration Reference Guide.

System configuration issue for platform statistics on Windows 2000 systems: On Windows 2000, an
error may occur when loading certain performance dlls. If they do not function properly or take too long
to pass data, the operating system automatically adds a value to the following Performance registry
subkey where TypeOfPerfService may be PerfProc, PerfOS, or NoteStat:
HKEY_LOCAL_MACHINE\SYSTEM\Services\CurrentControlSet\<TypeOfPerfService>\Performance.

When the error occurs, the value for the variable ″Disable Performance Counters″ is set to 1, which
disables performance counters for statistics such as CPU utilization

1474 Lotus Domino Administrator 7 Help

(Platform.System.PctCombinedCpuUtil) or Memory (Platform.Memory.PagesPerSec). These counters are
found under the services PerfOS, PerfDisk, PerfProc and PerfNet.

If these statistic counters cannot be located, you may get the following error message, printed to both the
event log and the console:
Platform Stats: _PSHandleDefaultCmd() Unable to set up default counters error =..."

Although the system may have set the ″Disable Performance Counters″ variable under a period of
extreme stress on the system, once it has been set, this variable continues to disable all performance
counters relating to its.dll, until it is manually set back to zero or deleted.

To reset the default counters, search the registry for the phrase ″Disable Performance Counters.″ If it
occurs under PerfOS, PerfDisk, PerfProc or PerfNet, manually set it back to zero or delete the entire
variable.

Network dialup connections -- Troubleshooting

This topic describes how to troubleshoot a network dialup connection problem. You can also search for
solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

If a user installed, set up, and created Connection documents for a network dialup connection, but the
user can’t connect to it, check for these conditions and correct them, if necessary.
1. Make sure the workstation and/or server has been set up with the remote access client software. If
the software hasn’t been set up, users will get the message ″Error initializing remote LAN service.″
Install the network dialup client software on the server and/or workstation, and then try connecting.
2. Make sure the remote server is accessible. If the modem is busy or the server is unavailable, the
server can’t answer calls.
3. Make sure that the user has the necessary privilege to use a network dialup connection to dial into
the server. If necessary, modify the user’s privileges. Also, make sure that the user is using the correct
user ID password.
4. Trace the connection to the server. Check the resulting information for indications that the Connection
document isn’t properly configured. For example, common mistakes in the Connection document
include not listing the current location or failing to enable the specified port(s).

Note: Information from a trace is recorded in the Miscellaneous Events view of the log. In the Trace
Connections Log Options field, you can set the level of detail to record. For maximum information,
choose Full Trace Information.
5. Use the dialing method provided by the network dialup client to make the network dialup
connection. If the connection fails, check for the correct configuration and check the modem for
problems.
6. If the connection is successful, while the connection is still active, switch to the Notes workstation or
Domino server and attempt to connect to the destination server. At this point, the workstation or
server should be connected to the LAN. You can temporarily set the Usage priority field of the
network dialup Connection document to Low to force the connection over the LAN before using the
Connection document.
7. If the previous step succeeds, drop the connection, switch to the Notes workstation, and choose File -
Mobile - Call Server to call the remote access server. If you previously set the Usage priority field of
the network dialup Connection document to Low, reset the priority to Normal.
8. Make sure you’re using the correct Connection document. Then, make sure the information in the
Connection document is correct.

After a successful modem connection, cannot establish session with server: The server is down.

The port is not configured on the Domino server.

Chapter 66. Troubleshooting 1475

The modem file on the server does not contain the correct connect string.

RAS is currently using the port that the Notes Direct Dialup connection is attempting to call on the
destination server.

Modem does not respond: The modem is not turned on or is not connected.

The modem software is not configured properly.

COM device is in use: You try to access a server using Notes Direct Dialup and your server has RAS
running and only one COM port.

You cannot create a RAS connection: RAS is not configured and/or started on the destination server.

Dial Up Networking is not configured properly on the client.

The modem software is not configured properly.

Error messages: This section lists common error messages displayed on the server console or at the
Notes client, and provides information on what caused the error and how to recover from it.

Modem command files contains illegal character: You selected the wrong modem.

Select the correct modem file from the COM options - Modem type drop down box.

The selected modem command file only allows speeds as high as XXX: The configured modem speed
exceeds the supported speed.

Check the maximum modem speed for your modem and configure it in the COM options - Maximum
Port Speed.

Excessive Port or CRC errors on the last connection. Try enabling hardware flow control on the port or
reducing the maximum speed settings: The configured modem speed exceeds the supported speed.

Enable flow control on the Notes client and Domino Server.

Reduce modem speed on the machine with Port and/or CRC errors.

Communications port unit number is not within valid range.: You have too many ports configured.

Set the valid number of ports on your system. Notes and Domino accept up to 64 ports.

No dialtone: The modem is not receiving a dial tone.

Check the phone line. Make sure that line is active and plugged into the modem properly.

If you are in Europe, make sure that you have disabled ″wait for dial tone before dialing″ in the COM
options box.

Testing network connections using the ping utility: After you establish an Internet connection, you
should ensure that the connection works properly. Run this test before you actually connect the Domino
server to the Internet.

If you have a direct connection to the Internet, the easiest way to test the connection is to use the ping
utility, which asks another computer if it is running and confirms that the protocol software can respond.

1476 Lotus Domino Administrator 7 Help

Even if you can use the ping utility successfully, the Domino server might not be running. When you use
the ping utility to contact another computer, make sure you attempt to contact a computer that is not in
your immediate domain. If you can use the ping command to successfully contact a computer in another
domain, you verify that your router is working properly.

If you connect to the Internet through a proxy server, try to use the ping utility on your proxy to test the
network connection.

To use the ping utility, type ping at the CONSOLE prompt, followed by the domain name. For example,
type:
ping xyz.com

If successful, the ping utility returns a message in a format similar to the following:
64 bytes from 130.000.00.00: 1cmp_seq=4, time=0, ms

Tracing a network connection: To test a connection to a server, use the Trace command, which provides
detailed information about each step in a server connection. Using the results of a trace command, you
can troubleshoot network connection problems.

When you attempt to connect to a server, network trace information automatically appears on the status
bar of a Notes workstation or on the server console, depending on where you initiated the connection
attempt. You can use the NOTES.INI Console_LogLevel setting to control the level of detail that messages
on the status bar contain.

To trace a connection, you can enter this command at the console:

Trace servername

To test whether you can connect to a server through a specific port:

Trace port!!! servername

For more information about the Trace command, see the appendix ″Server Commands.″

Network connections over NRPC -- Troubleshooting

If you are unable to connect to a server, do the following before you refer to any of the port-specific
troubleshooting procedures in this section:
1. Trace the attempt to connect to the server by doing one of the following:
a. From a Notes workstation:
Choose File - Preferences - User Preferences - Ports.
Click Trace.
Specify the server you want to connect to.
In the ″Trace options″ and ″Notes Log options″ fields, select ″Full trace information.″
Click Trace.
b. On a server console, enter:
Trace servername
where servername is the hierarchical name of the server you want to connect to, for example,
Mail01/Cleveland/Acme.
2. If the requesting system didn’t try to connect on a specific Notes network port that you want to use,
check that the port is enabled.
3. If the port is enabled, make sure that the server is not down.
4. If the server is running, check whether you have a local Connection document for it, and if so, check
that the port you want to use is selected in that document.

Chapter 66. Troubleshooting 1477

5. If you still cannot connect, it is probably because no address can be found for the server in the given
protocol. Create or modify a local Connection document to include the server’s protocol-specific
network address.
For more information on ports and Connection documents on Notes workstations, see Lotus Notes
Help.
For more information on server ports and server name-to-address resolution, see the chapter ″Setting
Up the Domino Network.″
6. If you still cannot connect, see the procedures that apply to the ports you have enabled:
v Troubleshooting TCP/IP for NRPC

Troubleshooting TCP/IP problems for NRPC: These topics describe how to troubleshoot problems with
TCP/IP:
v Tools for troubleshooting TCP/IP
v Common TCP/IP error messages on Domino servers
v Common TCP/IP error messages on Notes clients or Domino servers
v How to troubleshoot a TCP/IP problem
v TCP/IP frame types

If you can’t solve your problem, record all of THE FOLLOWING INFORMATION (gathered as you
performed the steps in the preceding topics) before contacting IBM Lotus Support Services
(www.ibm.com/software/lotus/support/):
1. Exact quoted error messages
2. TCP stack name and version number (or operating system and version if the TCP/IP stack is included
in the operating system)
3. IP configuration information
4. IP address and host name of Domino server
5. Server document
6. Host file
7. Tracert information (with number of hops)
8. Ping packet size

Note: It is recommended that customers prepare a network diagram for escalation.

Tools for troubleshooting TCP/IP:

Connection logging: When connection logging is enabled on a server, the server console displays the name
of the Notes network port for TCP/IP, the IP address of the requesting system, and the IP address of the
destination server for each connection.

To enable connection logging, add the following setting in the server’s NOTES.INI file:
Log_Connections=1

TCP/IP error messages -- Server only: These sections describe common error messages on a Domino server
offering NRPC services over TCP/IP.

Error on Listen function: The requested TCP/IP port is in use on this system.: This message could indicate one
of the following problems:
v UNIX systems. You have failed to assign different IP addresses to each partition on a Domino
partitioned server, or you have failed to follow the port mapping setup instructions properly, and you
attempt to start the additional partition. You may need to stop the server currently running, so that the
new server you are setting up can finish accessing the setup server for its copy of the Domino
Directory.

1478 Lotus Domino Administrator 7 Help

 For more information about setting up IP addresses or port-mapping properly, see the chapter ″Setting
Up the Domino Network.″

Note: Failing to configure partitions properly on Windows systems does not generate an error on
startup, but will generate operational problems.
v Windows 2000 and XP systems. It is possible for an application or system service to be assigned an
ephemeral port number as its local port number that conflicts with the Domino listening port. Restart
the system so that the process using TCP port number 1352 can release it.
When a system running TCP/IP makes each outbound connection, the TCP software automatically
selects a local port number and assigns it to the connection. This is required in the TCP architecture so
that the server can return packets to the client. This same port number cannot be used by any other
outbound or listening socket until it is freed. Port numbers in the range 1 - 1024 are called reserved
ports because they are reserved for well-known system services. The TCP software never uses reserved
ports when it must select a client-side port number at random. Rather, it selects at random a number
from a range above 1024 called the ephemeral port range. The Internet authority uses the low-end
range above 1024 to assign port numbers to registered applications such as Lotus Notes/Domino’s
NRPC services, which use 1352. Microsoft uses the ephemeral port range of 1024 - 5000. Therefore,
when a server on a Windows system makes an outbound connection, the ephemeral port number
chosen might be 1352. When this happens and Domino is started, the NRPC port fails to bind. Often,
on startup, servers on Windows systems make outbound connections to the NetBIOS session service
well-known port and keep these connections active until the system is restarted. This is the cause of
the problem.

Note: Most UNIX systems use an ephemeral port range that is at the top-end of the range of ports,
such as 45000 - 65000, so that there is not likely to be a conflict between the ephemeral port number
chosen and registered port numbers.
To determine if this is the cause of the problem, run Netstat -n -a. If what you see is similar to one of
the following examples, the system is using port number 1352 and the Domino server cannot start. To
solve this problem, restart the system.
Example 1: Netstat -n -a output of the Domino server active on the local system using port 1352 as a
server
Proto Local Address Foreign Address State
TCP 10.20.4.137:1352 0.0.0.0:0 LISTENING

Example 2: Netstat -n -a output of the local system accessing an external system using port 1352
ephemerally
Proto Local Address Foreign Address State
TCP 10.20.4.137:1352 10.30.10.1:139 ESTABLISHED

To prevent future ephemeral bind conflicts on Windows systems, use the following instructions to add a
registry value that forces TCP to skip port 1352 when it selects an ephemeral port number:

Run Regedt32 (not Regedit -- Regedit does not support the data type required for the value) and enter
the following:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
Value Name: ReservedPorts
Data Type: REG_MULTI_SZ
Value: 1352-1352

Tip: To protect additional ports, you can enter a range (such as 1025 - 1050) or multiple ranges separated
by spaces.

Chapter 66. Troubleshooting 1479

Note: In Windows 2000 and XP, Netstat might report an additional line showing the local and remote
ports and addresses in the established state, or a second line showing the client-side port in the listening
state. This is only a different method of reporting listening ports -- not a network bug.

Insufficient TCP sockets are available. Consult your vendor’s TCP/IP documentation to increase the
maximum number of sockets.: You have reached a TCP/IP socket limitation. To see how many active
TCP/IP sessions the server system has open, use Netatat with the -n switch (to disable reverse DNS
lookups) and output the listing to a file. Import the listing to a spreadsheet and count the total number of
connections. Then break the connections down by their state (Established, Time_Wait, Close_Wait,
Fin_Waitn). You should be able to support more than 2,000 concurrent connections. If not, review your
operating system and TCP/IP stack settings with the operating system and TCP/IP stack vendor. If you
have a large number of Close_Wait sessions, you may have network-level problems. If you have a
buildup of Time_Wait sessions with HTTP services, review your TCP/IP stack’s settings to see if the stack
offers a setting to time out Time_Wait sessions sooner.

As a temporary solution or if you can’t make any alterations to the system or TCP/IP stack, you can limit
the number of NRPC sessions the server will support concurrently, but there will be a performance cost
for doing so. To limit the number of concurrent NRPC sessions, do one of the following:
v Edit the portname_MaxSessions setting in the NOTES.INI file to limit the number of sessions that can
run on this port.
v Edit the Server_MaxSessions setting in the NOTES.INI file to limit the total number of active sessions
the server can have.

Listener task for port <portname> is suspending for 20 seconds due to listen errors.: See the message ″Error on
Listen function″ earlier in this topic.

The remote TCP/IP host is not running the Domino server, or the server is busy.: The server is
currently not running, or the server can’t accept another TCP/IP connection or Domain session. Start the
server, or verify that it is running. Check the server to determine if its workload is unacceptably heavy.

The TCP/IP protocol stack reported that it ran out of memory. Consult your network documentation to
increase configured memory, or reduce Notes connections by limiting clients (see
SERVER_MAXSESSIONS parameter in Notes Admin Guide).: This error can occur when your server
system’s resources are not correctly sized for the number of inbound and outbound connections or when
events push the server into resource starvation.
v If system memory appears to be low, increase it.
v If you are using Windows NT, you may be encountering a page file limit. Both Domino and the
TCP/IP stack use shared memory. If the page file is not large enough or the number of pages exceeds
what the operating system can provide, this error appears. Upgrade the operating system to Windows
2000 with Service Pack 2.
v If inbound client and server connections or the server’s own outbound connections seem to be
experiencing network stability problems, verify the health of the network by using Netstat with the -n
switch (to disable reverse DNS lookups) and output the listing to a file. Import the listing to a
spreadsheet and count the total number of connections. Then break the connections down by their state
(Established, Time_Wait, Close_Wait, Fin_Waitn). You should be able to support more than 2,000
concurrent connections. If not, review your operating system and TCP/IP stack settings with the
operating system and TCP/IP stack vendor. If you have a large number of Close_Wait sessions, you
may have network-level problems. If you have a buildup of Time_Wait sessions with HTTP services,
review your TCP/IP stack’s settings to see if the stack offers a setting to time out Time_Wait sessions
sooner.

As a temporary solution or if you can’t make any alterations to the system or TCP/IP stack, you can limit
the number of NRPC sessions the server will support concurrently, but there will be a performance cost
for doing so. To limit the number of concurrent NRPC sessions, do one of the following:

1480 Lotus Domino Administrator 7 Help

v Edit the Port_MaxSessions setting in the NOTES.INI file to limit the number of sessions that can run
on this port.
v Edit the Server_MaxSessions setting in the NOTES.INI file to limit the total number of active sessions
the server can have.

Unable to locate the Domain server’s TCP/IP host. The TCP/IP domain name server may be down.:
Use the ″ping’ command to verify that DNS is running.

Unexpected TCP error. See the Notes log file on this system for error code.: Look in the log file to see
the reported error code or codes. KnowledgeBase lists many of the error codes. If you find an error code
that isn’t in KnowledgeBase, report it to IBM Lotus Support Services.

TCP/IP error messages -- Client or server: These sections describe common error messages on a Notes client
or Domino server using NRPC services over TCP/IP.

Network operation did not complete in the specified amount of time.: The connection pathway between the
client or server system and the target server was unable to sustain the session. This happens when a
system is accessing a remote server over a slow or very congested WAN. Possible solutions to this
problem are:
v Instead of users’ accessing server-based mail or application files on the remote server, have them
replicate the database files to their local systems.
v Review your server-to-server replication and mail routing architecture across the WAN. It is best to use
a hub-and-spoke design, and use Connection documents in Domino to connect the servers, mirroring
the hub-and-spoke architecture. Use Notes name networks (NNNs) only at each isolated local site and
then use Connection documents to interconnect the sites from the hub location.

If this error occurs over a LAN, you may be experiencing frame and/or packet sizing problems because
you have a mixed-topology network or because your network routers’ routing tables are converging. In
these cases, the network pathway to or from the target Domino server cannot forward the TCP/IP packet
stream.

If you are using a remote VPN connection across the Internet, with some VPN client software you can
encounter packet sizing issues on the Notes client or Domino server and/or with the firewall system’s
VPN services.

The connection has timed out.: The establishment of the connection took longer than the expected default
of 5 seconds. This can happen when the connection is over a dial-on-demand ISDN modem connection,
remote bridge, or router. From the Port Setup dialog box, increase the TCP/IP connection-time-out
interval. On a normal LAN, it is best to enter a value of no greater than 10 seconds, as the client or server
won’t retry the connection until the timer has expired.

To access the Port Setup dialog on a Notes client, use File - Preferences - User Preferences and click Ports.
To access this dialog box for a Domino server, use the Domino Administrator’s Configuration tab and
select Server - Setup Ports from the Tools pane.

Once in the Port Setup dialog box, select the TCP/IP port and click the port name Options button.

The server is not responding. Possible explanation.: Variations of this error can occur when name-to-address
resolution has completed on the local system, but the server would not respond to that address. The
causes of this error include:
v The Notes Name Service cache in the current Location document contains a numeric IP address that it
originally obtained from the Server document (Net Address field) of the target Domino server, and the
Server document has since been updated with a new IP address. Using only host names in the Net
Address field makes this error less likely to occur, as host names usually don’t change.

Chapter 66. Troubleshooting 1481

v The contents of the Net Address field returned by the Notes Name Service is not the active address,
either because of a typographical error, or because there is more than one enabled Notes network port
for TCP/IP and the port listed first in the Server document is offering a different FQDN than the
second. In this case, if you are trying to connect through the port listed second, the connection fails.
v The address returned by DNS or hosts files is not the correct address or is not correct for this location.

To resolve problems associated with this error, follow all the steps in the topic ″How to troubleshoot
TCP/IP problems in NRPC″ later in this chapter. To resolve problems involving advanced TCP/IP
configurations (more than one enabled port), see the chapter ″Setting Up the Domino Network.″

The Remote server is not a known TCP/IP host.: This message appears if the translation from server
name to TCP/IP address fails. Follow these steps to troubleshoot the problem:
1. Verify that the server name is correct.
2. If you use a local hosts file for name resolution, enter the server’s IP address and host name in the
hosts file. If the server name does not match the TCP/IP host name, which is also known as the fully
qualified domain name, enter the server name as an alias for the host name. For example, for the
Domino server Red/Sales/Acme, enter:
130.103.40.1 red.acme.com red

Note: Insert a tab between com and red.

For TCP/IP for the Macintosh, the host name and alias definitions should look like this:
red.acme.com A 130.103.40.1
red CN red.acme.com

Note: Verify that the ordering of the name lookup services is ″Host″ first and ″DNS″ second;
otherwise, the hosts file entries may not be used when you expect them to be (excluding the NetBIOS
Name Service).
3. If you use the Network Information Service (NIS) for name resolution, ask the UNIX system
administrator responsible for the NIS domain to register the server’s IP address and host name. If the
server name does not match the TCP/IP host name, request that the server name be registered as an
alias for the host name.
4. If you’re using DNS for name resolution, ask the administrator responsible for the DNS domain to
register the server’s IP address and host name. If the server name does not match the TCP/IP host
name, request that the server name be registered as an alias (CNAME) for the host name and place
the host name in the TCP/IP port’s Net Address field in the Server document. For example, for a
Domino server named Sales/Boston/Acme with a host name of app01 for the A record, the CNAME
record would be sales. The Net Address field contains either the simple host name, app01, or the
FQDN, app01.acme.com. In the case of port mapping, each port-mapped server’s common name is
added as a CNAME to the A record for the base port-mapping server.
For more information on DNS resolves, see the topic ″Checking TCP/IP name resolution in NRPC″
later in this chapter, as well as the chapter ″Setting Up the Domino Network.″

How to troubleshoot TCP/IP problems in NRPC: To troubleshoot a network problem when using NRPC
services over TCP/IP, do the following in the order shown:
1. Check connectivity.
2. Check name resolution.
3. Check network layout (large LAN or WAN issues).

Checking NRPC connectivity in TCP/IP: Notes connectivity relies on TCP/IP communication. The first step
in troubleshooting TCP/IP is to verify basic TCP/IP configuration and connectivity.

1482 Lotus Domino Administrator 7 Help

For Notes and Domino to work properly with TCP/IP, the protocol stack on each computer must already
be configured properly. Ensure that the brand and version of the protocol stack is certified for use with
this version of Lotus Notes/Domino. For more information, see the protocol service provider’s
documentation.

Use the PING executable to verify IP-level connectivity. The PING command is available in all Windows
and UNIX environments.
1. From the server, ping the server itself by numeric IP address.
For example, at a DOS prompt, type:
PING 131.103.50.159
and press ENTER.
This step confirms the following:
v TCP/IP is installed and configured with a correct address.
v If any other computer has the same IP address. A computer’s IP address must be unique on a
network segment; that is, only one computer on a network segment can have a particular IP
address.
If this fails, TCP/IP is not set up properly on the local machine. Contact the site’s network
administrators for technical assistance.
2. From the server, ping the destination computer (the Notes workstation) by numeric IP address. This
indicates if the path to the remote host is clear and whether you can communicate with IP through
network routers. If this fails, continue to Step 3.

Tip: To obtain the IP address of a Notes workstation, from the workstation use the commands shown
in the table in Step 6.
3. From the workstation, ping the workstation by its own numeric IP address. If this fails, continue to
Step 4.
4. Ping the server from the server itself by its DNS fully qualified domain name (FQDN) to verify that it
was added to the network correctly; then ping the server from the workstation by FQDN.
For example, type:
PING iodine.lotus.com
5. Ping the server by DNS alias name from the server itself to verify it was added to the network
correctly. Then ping the server from the workstation. Ideally the server host alias names all should be
the same as the Domino server names. Sometimes the server’s FQDN may differ from the Domino
server’s. That is when the alias name is used, being the same as the Domino server’s name.
For example, type:
PING Iodine
If you reach this point and the connection is failing between workstation and server, try creating a
Connection document in the Personal Address Book of the workstation. This document contains the
numeric IP address of the destination server. It is best to resolve IP addresses by DNS or hosts files
and not by Connection documents.

Note: WINSOCK.DLL is the Windows Sockets interface provided with TCP/IP network software for
Microsoft Windows. If you’re using an incorrect (or incorrectly placed) version of WINSOCK.DLL,
Notes may exhibit problems related to WINSOCK.
6. If pinging by numeric address succeeds, but pinging by the alias name fails, the problem’s source is in
name resolution and not in physical network connectivity. The following table list the commands you
use (depending on the operating environment the server or workstation uses) to gather the following
information about the system’s IP configuration:
v IP address
v Host name
v If present, the default gateway

Chapter 66. Troubleshooting 1483

 If new information appears when the computer is restarted, record the information and call IBM
Lotus Support Services.
After you’ve gathered this information, perform the procedure titled ″Checking TCP/IP name
resolution in NRPC.″

Operating system Command/location to use Explanation

Macintosh Control Panel, TCP/IP, Load
Ping, ″TCPIP Config″ window
UNIX/Linux ipconfig <interface name> or
ifconfig <interface name>
Windows 2000/XP ipconfig (or see the Network
settings in Control Panel)
Not applicable
Different switches or commands may be required for
each UNIX platform; consult a UNIX expert if
necessary.
Issue this command at a prompt, or see the Network
settings in Control Panel.

Checking TCP/IP name resolution in NRPC: If checking connectivity using an IP address appears to work,
you need to check name-to-IP-address resolution. Name-to-IP address resolution within an organization’s
private network space usually takes one of two forms: locally stored hosts files or the Domain Name
System (DNS). WINS Name Resolution or LMHOSTS resolution are not supported by Lotus
Notes/Domino.
1. Check for illegal characters in the hosts file.
v Make sure there are no illegal characters (such as a space or a letter) in the numeric IP address;
only numbers should appear. Each section of a dotted decimal numeric IP address should be no
longer than three numbers, and there should be four sections to an address (for example,
19.99.21.217).
v Make sure there are no illegal characters in the Names fields; only alphabetic characters, numbers
and dashes (-) should appear. Spaces are not allowed. Underscores (_) are mapped as spaces within
Notes, and should be avoided.
v Some IP stacks will not accept underscore characters.
v Make sure there is only one correctly named hosts file being used. Rename any other hosts files on
the computer (except the current one).
v Note any recent changes made to the hosts file. Confirm that the information in the hosts file is
correct. The target machines that a computer may contact must be defined in the local hosts file.

Operating System Location Explanation

Macintosh Macintosh System Folder Not applicable
UNIX/Linux /etc/ Not applicable
Windows 2000 system32 directory Root directory might vary
Windows XP windows\system32\drivers\etc\ The OS directory might be renamed

2. Look at the Server document and determine if the first part of the server’s fully qualified domain
name (FQDN) in the TCP/IP port’s Net Address field is the same as the server’s common name. For
example:
FQDN = mailhub1.lotus.com Server common name = Mailhub1
If this is not the case, a name resolution alias is required in the hosts file or DNS table.

Note: If the first part of the FQDN is the same as the server common name, the problem may be
within DNS. For more information, see the vendor’s documentation for the DNS server.

3. If the Server document has changed recently, restart the server in order for the changes to take effect.

1484 Lotus Domino Administrator 7 Help

After you finish checking name resolution, see the topic ″Checking a TCP/IP network pathway″ later in
this section.

Checking a TCP/IP network pathway: If checking name resolution did not solve the problem, check each
network pathway. Be sure to record the information you gather.

Using the Trace Route utility: Use the TRACERT command to determine what network pathway lies
between the source and destination systems. This command determines the route from one host to
another through the network, and displays an ordered list of the routers in the path with the IP addresses
of the near-side interface of the routers.

Note: A dedicated Trace Route utility may not be available on all platforms, and your firewalls are most
likely blocking the ICMP sub-protocol of IP. Consult the site administrator to see if there is an equivalent
for your platform.

To use TRACERT, type the following at the prompt:

TRACERT servername -d

Where -d tells the command not to resolve addresses to host names.

For example, the results of the TRACERT command might look like this:
C:\>tracert paran -d
Tracing route to santa.north.com [118.111.90.204]
1 10 ms 10 ms 10 ms elves.north.com [118.111.200.211]
2 <10 ms 10 ms <10 ms rdeer.north.com [118.111.29.2]
3 <10 ms 10 ms 10 ms santa.north.com [118.111.90.204]
Trace complete.

In this example, there are two IP routers between the workstation and the server (three, minus the first
one which reported itself, leaving two).

Checking the Maximum Transmission Unit (MTU): Each end-node system and router port on the network
has the ability to control the size of the TCP/IP packet. Each NIC (port) can have its MTU set to a
different value, and each topology has a different default value. The network administrator can increase
or decrease this setting to meet the requirements of the network. MTU traffic issues are handled at the
TCP/IP level and not within Notes workstations or Domino servers.

If any of the following situations exist, suspect an MTU problem, and contact your network
administrator:
v There is a mixture of Ethernet and Token-Ring or FDDI network topologies on the LAN/WAN.
v There are routers between the source and destination of traffic that could be set up with an incorrect
MTU size.
v You are using VPN services across the Internet.
v ATM is being used with emulation [LANE].

TCP/IP frame types: Most UNIX, AS/400, or S/390 systems offer both frame types for 802.3 (Ethernet) to
Ethernet V2 (DIX) and SNAP by default. You can remove the SNAP frame support if you have a routed
network with Token-Ring or FDDI topologies where the router will translate the frame types (free up
non-needed resources).

With Windows-based TCP/IP protocol services, the default frame type for 802.3 (Ethernet) network
topology is v2 DIX and for Token-Ring and FDDI it is SNAP over LLC.

Chapter 66. Troubleshooting 1485

With Novell ODI-based TCP/IP protocol services, all systems using the TCP/IP protocol on 802.3
Ethernet should be using the same frame type. The table below lists the frame types compatible across
the different LAN topologies.

LAN topology and frame Novell compatible

services Novell frame types frame types * Comments
Ethernet v2 (DIX) Ethernet_II Not applicable Recommended for TCP/IP
IEEE 802.3 (Ethernet) Not applicable Not applicable Not applicable
SNAP Ethernet_SNAP Token-Ring_SNAP and Not applicable
FDDI_SNAP
IEEE 802.5 (Token-Ring) and Not applicable Not applicable Not applicable
FDDI
SNAP Token-Ring_SNAP & Ethernet_SNAP Required for TCP/IP for
FDDI_SNAP Token-Ring and FDDI networks

* If the bridge or router offers frame translation, other combinations may be possible.

Note: If using a NetWare server as a TCP/IP router, make sure that the NetWare and Domino server
systems are using the same common frame type for TCP/IP and that only one frame type is being used
to support the TCP/IP protocol in a flat or bridged network.

Partitioned servers -- Troubleshooting

These topics describe solutions to common problems and errors that may occur with partitioned servers.
v ″Server exiting: partition number xx is already in use″
v ″Server not responding″

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

″Server exiting: partition number xx is already in use″: This message appears when you try to start
more than one server in a partition. To correct this, stop all processes associated with the partition. If that
fails, restart the system.

″Server not responding″ connecting to a partitioned server: This message may appear if a partitioned
server uses TCP/IP port mapping.
1. If the destination server is sharing a network interface card with a port-mapping server, check that the
port-mapping server is running. Domino can’t establish a connection to a server sharing the
port-mapping server’s IP address unless the port-mapping server can redirect the traffic to the port
the destination server is listening on.
2. Make sure that the port-mapping information in the NOTES.INI file is in the correct order. In the
port-mapping server’s NOTES.INI file, there are entries that reference the other partitioned servers on
the computer. If the lines containing the port-mapping information are out-of-order, Domino displays
the message ″Server not responding″ or ″Server’s name changed.″ Edit the port-mapping server’s
NOTES.INI file, and make sure that the partitioned servers are listed in numerical order, as in this
example:
TCPIP_PortMapping00=
TCPIP_PortMapping01=
TCPIP_PortMapping02=
TCPIP_PortMapping03=
After modifying the NOTES.INI, stop and restart the server so that the changes take effect.

1486 Lotus Domino Administrator 7 Help

 Note: When setting the NOTES.INI variables for Port Mapping, do not include a zone in a port
mapped address. The zone is only valid locally.
3. Make sure that the port number appended to the destination server’s IP address matches the port
number in the NOTES.INI file on the destination server. Also, verify that the server name and
organization are correct.
For example, this setting in the port-mapping server’s NOTES.INI file assigns the destination server’s
IP address and port number:
TCPIP_PortMapping00=CN=Server1/O=Org1,198.114.89.123:13520
The destination server’s NOTES.INI file contains:
TCPIP_TcpIpAddress=0,198.114.89.123:13520

Passthru connections -- Troubleshooting

If passthru isn’t working as expected, check these conditions and correct them, if necessary. You can also
search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Tip: To record connection problems in the log, set the Log Options field (in the Trace Connections dialog
from the Domino Administrator) to Full Trace Information.
1. Verify that the passthru server is running Domino 4.x or higher. The destination server can run Notes
3 or Domino 4.x or higher.
2. Check the Server document to ensure that the server is enabled for passthru. The ″Route through
field″ on the Security tab in the Server document restricts who may use a server as a passthru server.
By default, this field is blank, which prevents use of the server as a passthru server. You can also
create a new passthru Connection document that names a different server that allows passthru to the
destination server.
You can also use the ″Access this server″ field in the Server document to restrict who can use passthru
to access a server. If this field is blank on the destination server, the server does not allow passthru
access. Only the users, groups, and servers explicitly named in this field have passthru access. Note
that this field does not restrict general access to the server, which is controlled by fields on the
Security tab of the Server document.
3. Make sure that the Connection document is properly configured. Check the log for the message
″Unable to find any path to ServerName,″ which indicates that there may not be enough information in
the Domino Directory to determine how to reach the destination server or that the information in the
Domino Directory is incorrect -- for example, server names might be misspelled.
For more information on setting up and tracing connections, see the topic ″Tracing a network
connection″ earlier in this chapter, as well as the chapter ″Setting Up Server-to-Server Connections.″

Remote Server Console -- Troubleshooting

This topic describes how to troubleshoot a situation when the server console output in not complete.
v Administrator client on the remote live console -- output data appears incomplete

Administrator client on the remote live console -- output data appears incomplete: There are two
situations in which data can be lost when you attempt to view output data using the Administrator client
from the Domino server remote live console. The displayed data appears incomplete because a portion of
the data is lost. Data can be lost in the following situations:
v The console output is buffered in a ring buffer as it is generated. When the remote live console
background thread fetches data, it may not fetch the data quickly enough. The ring buffer then loses
data.
v When the remote live console background thread fetches data, it posts the data to a network
asynchronous write -- itself a ring queue. If the asynchronous write queue entry is overwritten, data is
lost.

Chapter 66. Troubleshooting 1487

The following two statistics record the causes of data loss.

Statistic
server.RemoteConsole.AsyncQueueOverrun
server.RemoteConsole.BufferOverrun
Explanation
Number of times that the asynchronous queue request
was lost.
Number of times that data was lost because more
console output was generated than was sent over the
wire.

Replication -- Troubleshooting
These topics describe how to troubleshoot replication.
v Tools for troubleshooting replication describes tools you can use for troubleshooting replication
problems.
v Replication - Problems and error messages describes problems and errors that users or Domino servers
may experience during replication.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Tools for troubleshooting replication: Database access control list problems, server crashes, protocol
problems, and incorrectly configured Connection documents are common causes of replication errors. Use
these tools to troubleshoot replication.

Cluster replication: The log file (LOG.NSF) provides helpful information for troubleshooting replication
problems within a cluster.

Log file: To access the log, from the Domino Administrator, click the Servers - Analysis tab and select
the log file for the server you want to check. Then check for replication problems in these views:
v Miscellaneous events
v Phone calls
v Replication events

Tip: You can also check replication events from the Replication tab in the Domino Administrator.

Edit the NOTES.INI file to include the Log_Replication setting, which allows you to display detailed
replication information in the log.

Monitoring Configuration: The Monitoring Results database (STATREP.NSF) is a repository for

pre-configured and custom statistics. It is created when you load the Collect task, if it doesn’t already
exist. You can set alarms for some of these statistics. For example, you might set an alarm to generate a
Failure report when more than three attempted replications generate an error. You can also report
statistics to any database designed for this purpose, although typically the database is the Monitoring
Results database (STATREP.NSF).

Note that you can edit the NOTES.INI file to include the Repl_Error_Tolerance setting, which increases
the number of identical replication errors between two databases that a server tolerates before it
terminates replication. The default tolerance is 2 errors. The higher the value, the more often messages
such as ″Out of disk space″ appear.

If you run the Event task on a server, you can set up an Event Monitor document to report replication
problems. You can also create a Replication Monitor document that notifies you if a specific database fails
to replicate within a certain time. To view events from the Domino Administrator, click the Server -
Analysis tab, click Statistics - Events, and then view the desired report.

1488 Lotus Domino Administrator 7 Help

Replication history: The replication history for a database describes each successful replication of a
database. To view the replication history of a database, select a database icon and choose File - Database -
Properties (or File - Database - Replication - History).

Replication schedules: You can see a graphical representation of the replication schedules of the servers in
your Domino system. To view replication schedules, from the Domino Administrator, click the
Replication tab.

For more information on viewing replication schedules, see the chapter ″Creating Replicas and
Scheduling Replication.″

Replication topology maps: Create a replication topology map to display the replication topology and
identify connections between servers. To view replication topology maps, from the Domino
Administrator, click the Replication tab. You must load the Topology maps task before you can view a
replication topology map.

For more information on viewing replication topology maps, see the chapter ″Creating Replicas and
Scheduling Replication.″

Replication -- Problems and error messages: These topics describe how to troubleshoot replication
problems.
v Replication isn’t occurring between two servers
v Scheduled replication isn’t occurring between two servers
v One database isn’t replicating between two servers
v Database replica does not contain all the documents it should
v Database replica is not receiving design changes
v Changes to the database title do not replicate
v Database replicas are different sizes
v The database stops replicating and the option Enforce a consistent ACL is selected
v The database replica has not received ACL changes
v The new replica contains the ACL of the source server but you did not copy the ACL
v You see the message ″Database is not fully initialized yet″
v Deletions are not replicating
v Unexpected deletions occur in a replica
v Deleted documents reappear

Replication isn’t occurring between two servers: When two servers can’t replicate any of the databases
between them, these messages may appear in the log:
v ″Unable to replicate with server x: Server Not Responding″
v ″Unable to replicate with server x: The Notes server is not a known TCP/IP Host″
v ″Unable to replicate with server x: Your address book does not contain any cross certificates capable of
authenticating the server″
v ″Unable to replicate with server x: The server’s address book does not contain any cross certificates
capable of authenticating you″
v ″Unable to replicate with server x: You are not authorized to use the server or remote server″

Check for the following conditions and correct them, if necessary:

1. Create Connection documents that list Replication in the Tasks field. Unless you enable multiple
replicators on the server, make sure that replication schedules don’t overlap.
2. Verify that the servers have a certificate in common. To verify certificates, check the server ID files.
a. From the Domino Administrator, click the People and Groups tab.

Chapter 66. Troubleshooting 1489

 b. From the tool bar, click Certification - ID file.
c. Choose the appropriate server ID file and click Open.
d. Click Certificates to display the certificates held by the server.
e. Repeat Steps a through d for the second server.
f. Recertify one or both server IDs, as necessary. If the servers don’t have a certificate in common,
you can also cross-certify them.
3. Make sure the server is available. Check the log for the message ″Unable to replicate with server x :
Server not responding,″ which indicates that one server can’t connect to another server for replication
or that server x is unavailable.
4. Check the Miscellaneous Events view of the log to see if a network error message occurred when the
server attempted to connect to the other server.
5. Check the Phone Calls view of the log to see if two servers are unable to use dialup connections.

Scheduled replication isn’t occurring between two servers:

1. Check that the server names are spelled correctly in the Connection documents.
2. Make sure that multiple Connection documents don’t have overlapping schedules for the same task in
the same direction. If multiple Connection documents have overlapping schedules, correct the
schedules or enable multiple replicators on the server.
3. If many users access a server or if a server performs many tasks, it takes longer for Domino to build a
list of the databases that two servers have in common, a task that occurs just prior to replication. If
building the list takes a long time, a scheduled replication may be delayed. Check server load
statistics and, if necessary, replicate only specific databases, remove obsolete databases from the
servers, and/or move some databases to another server. You can also reduce the number of users who
access the server or reduce the number of tasks the server performs.
4. Make sure that the server has adequate disk space. If it doesn’t, remove obsolete databases and/or
move some databases to another server.

One database isn’t replicating between two servers: When replication occurs correctly between two
servers but one database doesn’t replicate correctly, these symptoms might occur:
v The message ″Unable to replicate xxx.nsf″ appears in the log file.
v Users report that documents are different on each replica.

To correct this problem, try these tips.

1. Check if the database ACL is set up incorrectly. The message ″Access control is set to not allow
replication″ in the log file indicates that the servers do not have the correct access to perform
replication. Give the servers enough access in the database ACL to replicate changes. A server must
have:
v Editor access to replicate changes to documents
v Designer access to replicate changes to views and forms
v Manager access to replicate ACL changes
If replication occurs through a passthru server, the passthru server must also have the necessary
access to pass along changes.
2. Check the log file for an ″Unable to copy document″ or similar message. This message indicates a
corrupted database. To correct the problem, do one of the following:
v Run the Fixup task. Use this task if the database is in Domino 5 or higher format and if you’re not
using transaction logging, or if the database is in Domino 4 format.
v Run the Fixup task with the -J option. Use this task if the database is in Domino 5 or higher format
and you are using transaction logging. If you use a backup utility certified for Domino 5 and you
run Fixup -J, perform a full backup of the database as soon as Fixup finishes.

1490 Lotus Domino Administrator 7 Help

3. Check the log file for a ″Replication is disabled″ message, which indicates that the database is not
enabled for replication. To enable replication of the source database, choose File - Replication -
Settings - Other and deselect ″Temporarily disable replication.″
4. Check if the ″Enforce a consistent Access Control List″ option has been set on a replica. Sometimes
replication cannot occur because this option has been set, but the server storing the replica lacks the
appropriate access to replicate the ACL. If this is the case, give the server Manager access in the
database ACL.
5. Make sure there have been recent changes to the database. Replication occurs only when there are
changes to replicate.

Database replica does not contain all the documents it should: If none of the following explanations
apply, try clearing the replication history. Clear replication history using the File - Replication - History
dialog box in the Notes client.

For more information on replication history, see the chapter ″Maintaining Databases.″

Replicas are different sizes: If changes made to one replica have not yet replicated, the content of replicas
may be different until replication occurs.

The source server has insufficient access: The source server access in a destination replica ACL determines
what the destination replica can receive from the source server. Give the source server higher access in
the destination replica ACL if necessary. The following message in the server log file (LOG.NSF) indicates
insufficient server access:
Access control is set to not allow replication

For more information on the log file, see the chapter ″Using Log Files.″

There is no destination server in an access list: Access lists allow only a subset of people and servers in
the ACL to access documents. If such access lists exist, add the destination server to them in the source
server replica. If the access list uses a role to define access, add the destination server to the role on the
source server replica.

For more information on server access, see the chapter ″Creating Replicas and Scheduling Replication.″

An intermediate server has insufficient access: If replication between a source and destination server
occurs through an intermediate server, make sure the source and destination server replica ACLs give the
intermediate server high enough access to replicate all changes.

For more information on server access, see the chapter ″Creating Replicas and Scheduling Replication.″

Replication settings are filtering documents: Some replication settings act as filters that screen out
documents and features. Check the replication settings.

For more information on replication settings, see the chapter ″Creating Replicas and Scheduling
Replication.″

The server is out of disk space: Check to see if the database is a Domino 4 database and has exceeded
the maximum database size. Ask your Domino administrator to resolve disk space problems and if
necessary, consider moving a replica to another server or deleting databases on the server.

Older documents weren’t replicated to a new replica: When the replica was created, the date specified for the
replication setting option ″Only replicate incoming documents saved or modified after″ is later than it
should have been. This option is on the Other panel of the File - Replication - Settings dialog box in the
Notes client. Create a new replica with an earlier date specified.

Chapter 66. Troubleshooting 1491

Database replica is not receiving design changes: To receive design changes from a source server, the
database replica on the destination server must give the source server at least Designer access and the
source server replica must give the destination server at least Reader access.

Changes to the database title do not replicate: If the replication setting ″Do not send changes in
database title & catalog info to other replicas″ is set on the source server replica, the title won’t replicate.
Deselect this setting to replicate a database title. This setting is on the Send panel in the File - Replication
- Settings dialog box in the Notes client.

For more information on this replication setting, see the chapter ″Creating Replicas and Scheduling
Replication.″

Database replicas are different sizes: Database replicas may be different sizes for the following reasons:

Replication settings: Some replication settings cause one replica to receive only a subset of documents
and features from another replica.

Access control list: The ACL prevents a replica from receiving all documents or design elements from a
source replica.

Read ACLs or reader names fields: A destination server isn’t included in a Read ACL or Reader Names
field and therefore doesn’t receive all documents from a source server replica.

View indexes: A view is used in one replica but not in another, and the replica containing the unused
view is smaller because no index is built for the unused view.

Personal agents, views, or folders: These features used on one replica, but not another, can cause a size
disparity between the replicas.

Deletions are not replicated: Check these replication settings in File - Replication - Settings in the Notes
client:
v On the Advanced panel, the Deletions option under ″Replicate incoming″ is not selected.
v On the Send panel, the ″Do not send deletions made in this replica to other replicas″ option is selected.

Unused space: One replica has been compacted while another has not been compacted.

The database stops replicating and the option Enforce a consistent ACL is selected: If a user changes a
local or remote server database replica’s ACL when the ″Enforce a consistent access control list across all
replicas of this database″ option is selected, the database stops replicating. This option is found on the
Advanced panel of the Access Control List dialog box. The message in the log file is:
Replication cannot proceed because cannot maintain uniform access control list on replicas

The database replica has not received ACL changes: To receive ACL changes from a source server, the
database replica on the destination server must give the source server Manager access and the source
server must give the destination server at least Reader access.

For more information on server access, see the chapter ″Creating Replicas and Scheduling Replication.″

The new replica contains the ACL of the source server but you did not copy the ACL: A replica stub
is an empty replica that has not yet been populated with documents. When you select File - Replication -
New Replica, Notes creates a replica stub and populates it with documents, either immediately or at the
next scheduled replication, depending on the option you select.

For more information on server access, see the chapter ″Creating Replicas and Scheduling Replication.″

1492 Lotus Domino Administrator 7 Help

Somebody modified the access control list on the source server before initial replication occurred: If
you create a replica stub and somebody modifies the ACL on the source server before initial replication
occurs, the ACL on the source server becomes the most recent one and replicates to the replica stub.
Simply opening the Access Control List dialog box on the source server replica and then closing it can
cause this problem.

The server times are not synchronized: If you create a complete replica immediately (rather than
creating a replica stub) and the time on the source server is later than the time on the destination server,
the new replica contains the ACL from the source server.

You see the message ″Database is not fully initialized yet″:

A replica stub on a workstation hasn’t been manually replicated: If users create replica stubs on their
workstations and don’t populate them with documents according to a schedule, they must manually
replicate to populate the database replica with documents.

The server storing the replica stub doesn’t have adequate access to pull information: If you rely on
scheduled replication to populate a replica stub, the server storing the replica stub must have at least
Reader access in the source server replica ACL to pull the documents from the source server.

For more information on server access, see the chapter ″Creating Replicas and Scheduling Replication.″

An appropriate Connection document between two servers isn’t in place: If you rely on scheduled
replication to populate a replica stub on a server with documents from a replica on another server, a
correctly-configured Connection document must exist between the two servers storing the replica and the
replica stub. Confirm with your Domino administrator that an appropriate Connection document exists.

Replication is disabled: Notes cannot populate a replica stub if replication is disabled on the source or
destination server replica. To check if replication is disabled for the database, see if the ″Temporarily
disable replication″ option is deselected. This option is found on the Other panel of File - Replication -
Settings in the Notes client.

Deletions are not replicating:

Servers don’t have adequate access to the database: To receive document deletions, the ACL on a
destination server replica must give the source server Editor access or higher and have the access level
privilege ″Delete documents″ selected.

A replication setting is preventing deletions from replicating: Check these replication settings in File -
Replication - Settings in the Notes client:
v On the Send panel, the option ″Do not send deletions made in this replica to other replicas.″ A source
server doesn’t send deletions to another replica if this setting is selected.
v On the Advanced panel, the Deletions option under ″Replicate incoming.″ A replica doesn’t receive
deletions if this setting is not selected.

Unexpected deletions occur in a replica: Check these replication settings in File - Replication - Settings
in the Notes client:
v On the Advanced panel, deselect ″Replicate incoming: Deletions″ to prevent a database from receiving
deletions made in other replicas.
v On the Other panel, select ″Do not send deletions made in this replica to other replicas″ to prevent a
database from sending deletions

Unexpected deletions may also occur for any of the following reasons:

There is a new replication formula in place: A new replication formula overrides previous formulas
and removes documents that don’t match the formula.

Chapter 66. Troubleshooting 1493

A replication setting is automatically removing older, unmodified documents: The replication setting
″Remove documents not modified in the last [ ] days″ removes older, unmodified documents. If the
specified number of days is low, consider increasing the value. This option is on the Space Saver panel of
the File - Replication - Settings dialog box in the Notes client.

Deleted documents reappear:

A purge interval prevents replication of deletions: When a document is deleted, it leaves behind a
deletion stub. When the database replicates, Notes uses the deletion stub to identify and delete the same
document in the replica.

To save disk space, Notes purges deletion stubs that remain from document deletions according to the
replication setting ″Remove documents not modified in the last [ ] days.″ If Notes purges the deletion
stubs before they have a chance to replicate, deleted documents can reappear after the next replication.
This option is on the Space Saver panel of the File - Replication - Settings dialog box in the Notes client.

A document edit writes over a document deletion:

v When the same document is modified on different servers between replication sessions, the document
that was modified most frequently takes precedence, or if both documents are modified only once, the
one modified most recently takes precedence.
v If a document is edited multiple times on one server and deleted on another server between replication
sessions, the edited document takes precedence because it underwent the greatest number of changes,
even if the deletion was the most recent change.
v If somebody deletes a document on one server and then someone else updates the document on
another server once between replication sessions, the edit overrides the deletion because both
documents were updated once and the edit occurred after the deletion.

Roaming Users -- Troubleshooting

This topic describes how to troubleshoot a roaming user configuration.
v Using NOTES.INI settings to troubleshoot roaming user configurations.

Using NOTES.INI settings to troubleshoot roaming user configurations: You can use two NOTES.INI
settings to collect information when troubleshooting a roaming user problem. After setting up a roaming
user or upgrading a Notes user to a status of roaming user, add these two NOTES.INI variables to the
NOTES.INI file on the Notes client. The Notes client will generate debug codes to the file specified in the
Debug_Outfile setting. You can then provide this information to Support to assist you in resolving
problems.
debug_outfile=path to a file
debug_roaming=1

Server-based certification authority -- Troubleshooting

These topics describe common problems with the server-based certification authority and the CA process.
You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Problems when you create or modify a certifier: If you have problems creating or modifying a
server-based CA -- for example, the CA process doesn’t load when you issue the command Tell Load CA
or returns an error -- check the following:
v The administrator’s location document must point to the server on which the CA process is running.
v The mail file location on the Mail tab of the administrator’s location document must point to the server
on which the CA process is running.
v The administrator’s public key must be in the Domino Directory for the server specified in the location
document.
v CA administrators must have at least Editor access to the master Domino Directory for the domain.

1494 Lotus Domino Administrator 7 Help

CA process takes a long time to make changes to a certifier: When you create a new certifier, make
changes to an existing one, or revoke a certificate, the changes usually take place by the time the CA
process refreshes itself. Sometimes the process takes longer, because:
v The CA process has to create or update the CA configuration documents, and, in the case of Internet
certifiers, post a CRL.
v The CA process may be running on a server other than the one that hosts the master Domino
Directory, adding replication delays to the process.
v Replication of the Administration Requests database can add delays. A request or change may be
approved on one replica, but the change has to be replicated to other servers in the domain.

To see the results of any CA process operation immediately, at the server console type:
tell adminp process all

Then
tell ca refresh

Then
tell ca stat

to see if the changes have been processed. You may need to repeat the process more than once.

For more information about configuring and using a server-based CA, see the chapter ″Setting Up a
Domino Server-Based Certification Authority.″

Server access -- Troubleshooting

These topics describe how to troubleshoot server access problems and errors:
v The administrator can’t enter commands at the server
v Users can’t see a new server in the list of servers
v ″Server not responding″
v ″You are not authorized to access the server″ or similar problems

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

The administrator can’t enter commands at the server: If an administrator can’t run the workstation
program on the server, run stand-alone server programs, or use the Load, Tell, or Set Configuration
commands, the console has been password-protected.

Use the Set Secure command at the console or use the Domino Administrator to clear the password.

For information on using the Set Secure command, see the appendix ″Server Commands.″

Users can’t see a new server in the list of servers: If users can’t see a new server when they try to add,
create, copy, or replicate a database, make sure that the Domino Directory contains a Server document for
the new server and that the information in the document is accurate and correctly spelled. If no Server
document exists, create one and then make sure that the new Server document replicates to all servers in
the domain. If a Server document exists and contains accurate information for the new server, check the
log file on both the user’s home server and the inaccessible server to see if there are network problems.

″Server not responding″: The message ″Server not responding″ may appear when you install a client or
try to open any database on a particular server.
1. Check that the Domino server and the network are running.

Chapter 66. Troubleshooting 1495

2. Check if the server has been renamed or recertified. When a user tries to open a database on a server
that has been recertified or renamed, the message ″Server not responding″ may appear. Users should
use the new server name to open the database.
3. Check the Server document for an invalid or nonexistent host name as the Notes RPC proxy. From the
Domino Administrator, click the Configuration tab and open the appropriate Server document. Click
the Ports - Proxies tab. A Domino server that is configured to use TCP/IP can’t transfer mail or
initiate replication with another server in the local domain if the host name is invalid or nonexistent.
In addition to ″Server not responding, ″ ″No Path Found to Server″ and ″Proxy Reports that the
Connection Request Failed″ messages may appear.
A Domino server configured to use a Notes RPC proxy attempts to route all outbound connection
requests through the listed proxy, whether or not the proxy exists. Because most Domino systems
don’t use an RPC proxy, this field should generally be left empty.

Note: If full trace logging is enabled in the NOTES.INI file, the log file records detailed information
about failed attempts to connect to a remote server. The PassThru_LogLevel is typically set 0 to
minimize unnecessary logging.
4. If you’re using NetBIOS, make sure it’s configured properly and that it’s running on the workstation
or server. The workstation and the server must use the same version of NetBIOS, and the server must
be enabled for sufficient NetBIOS sessions.
Also, filters might prevent broadcast traffic from Notes from crossing a bridge or router. Bridges and
routers are often configured to suppress broadcast traffic by default, and NetBIOS uses broadcasts to
communicate on networks.

″You are not authorized to access the server″ or similar problems: When users or servers get a ″not
authorized to access the server″ message, try these tips to identify and then fix the problem.
1. Check the Domino Directory .
2. Check the server ID.
3. Check that the user has the proper certification to access the server.
4. Check for network or hardware problems.

Checking the Domino Directory for errors that affect server access: Many conditions that prevent
proper access to servers can be traced to the Domino Directory.
1. Verify that these fields in the Server document contain the correct information and spelling. For each
change you make, be sure to save the Server document before attempting to access the server again.

Field on the Network

Configuration tab Check this
Server name Make sure that the full hierarchical server name is spelled correctly.
Domain name Make sure that the name is spelled correctly.
Port If a COM port is listed, remove it. X.PC COM ports are only handled in the ports
configuration section.
Notes Network Make sure that at least one Notes Network is enabled. Each port requires a unique
Notes network name.

Field on the Restrictions

tab Check this
Access server Delete the contents of this field if it contains any information. Only those names or
groups listed in the field are allowed to access the server.
Not access server Delete the contents of this field if it contains any information. The users or groups listed
in the field are not allowed to access the server.

1496 Lotus Domino Administrator 7 Help

2. Make sure the Server document isn’t corrupted. To determine if it is corrupted, create a new Server
document and use it instead of the old one. If the new Server document resolves the problem, it’s
likely that the original Server document is corrupted. Be sure to create a backup of the original Server
document by either copying and pasting the original into another Server document or by backing up
the database.
After you create the new Server document, copy the public key into it.
3. Verify that the Certified public key in the server ID file is the same as the Public key. To do this, copy
the certified key and paste it into a text file, and then compare the two key values, which should be
the same. If the values differ, the server ID was probably created with the same name based on a
different Certifier key. Before altering the key, create a backup of the Domino Directory.
4. Check Group documents in the Domino Directory for correct user and server names. In particular,
check the Group documents for groups listed in the ″Access server″ and ″Not access server″ fields in
the Server document. In addition, be sure to check the Group Type setting of these Group documents.
The Group type assigned to a group can affect server access.
5. Resolve any replication or save conflicts in the Groups and People views.
6. Make sure that all views in the Domino Directory are updated and not damaged. To rebuild all of the
views in that database, enter this command at the console:
Load updall names.nsf -r
If you suspect that the Domino Directory is corrupted, do one of the following:
v Run the Fixup task. Use this task if the database is in Domino 5 or higher format and if you’re not
using transaction logging, or if the database is in Domino 4 format.
v Run the Fixup task with the -J option. Use this task if the database is in Domino 5 or higher format
and you are using transaction logging. If you use a backup utility certified for Domino 5 and you
run Fixup -J, perform a full backup of the database as soon as Fixup finishes.
In addition, if you suspect a corrupted Domino Directory, try using a backup of the Domino Directory
(if one is available), or create a new replica of the Domino Directory.
7. Replace the design of the Domino Directory. Select File - Database - Replace Design. This ensures that
the Domino Directory is using the correct template file (PUBNAMES.NTF).
8. Check Server document form in the Domino Directory for customizations that are not supported.
For information about supported customizations, see the appendix ″Customizing the Domino
Directory.″
9. Make sure that passthru is properly enabled on the Server document.
For information about enabling passthru, see the topic ″Passthru -- Troubleshooting″ earlier in this
chapter.

Checking the server ID for a problem that affects server access: When the message ″You are not
authorized to access that server″ appears, the problem can sometimes be the server ID.
1. Check for a damaged server ID. If a server ID is damaged, the Domino server may start, but users
won’t be able to access it. Also, the message ″Server Error: Damaged ID″ appears when you start the
Domino server.
If the server ID was recently recertified, the ID may have been damaged if the Domino server wasn’t
shut down before the server ID was recertified or merged.
If you suspect that the server ID is damaged, you can replace the server ID with a new ID.
2. Verify that the server has all of the required certificates.
a. From the Domino Administrator, click the People and Groups tab.
b. From the tool bar, click Certification - ID file.
c. Choose the appropriate server ID file and click Open.
d. Click Certificates to display the certificates held by the server.
e. Recertify the server ID, if necessary.

Chapter 66. Troubleshooting 1497

3. Check for a ″Public Key...″ message that appears when the server starts. Verify that the public key
stored in the Server document matches the public key stored in the server ID. To do this, copy the
ID’s public key to the clipboard, and then paste it to another application -- for example, into Windows
Notepad -- so that you can compare it with the public key in the Server document. Be sure to perform
a full backup of the Domino Directory before altering the key.

Replacing the server ID: If you suspect that the server ID is damaged, replace it with a backup of the
ID. If you don’t have a backup of the server ID available, create a new server ID. Be sure to use the same
name on the new ID as you used on the old ID.
1. Shut down the Domino server.
2. Rename the old server ID -- for example, Server.OLD. You must rename the ID to force the ID file to a
new location on the hard disk.
3. Copy the backup (or new) server ID to the correct location on hard drive. ID files are typically located
in the Notes\Data directory.
4. Restart the server.

Copying the public key:

1. From the Domino Administrator, click the People and Groups tab.
2. From the tool bar, click Certification - ID Properties.
3. Select the ID file you want and click Open.
4. Click Your Identity - Your Certificates - Other Actions.
5. Click Mail - Copy Certificate (Public Key), then click Copy Certificate to copy the entire public key to
the clipboard.
6. Paste the public key into the associated document -- for example, into a new Server document.

Server crashes -- Troubleshooting

When a server crashes, the simplest solution is to restart it; however, you might want to find out why it
crashed so that you can avoid future crashes. These topics describe how to troubleshoot a server crash.
v How to troubleshoot server crashes provides steps for collecting information about and troubleshooting
server crashes.
v Server crashes -- Problems and error messages describes problems and errors that relate to server
crashes.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

How to troubleshoot server crashes: The most common causes of server crashes are the following:
v Low or depleted system resources
v High server workload
v Software problems
v Network problems
v Changes to network or operating system environments
v Changes in hardware configuration -- for example, upgraded NICs -- or software configuration

Use these steps to troubleshoot a server crash. If, after completing these steps, you haven’t resolved the
problem, consult your technical support representative.
1. Collect system information:
v Domino server version
v Operating system version (SYSLEVEL information if the operating system is OS/2, by typing
SYSLEVEL at an OS/2 prompt).
v Network type and version; network protocol(s) and version(s) (including file dates)

1498 Lotus Domino Administrator 7 Help

 v System level patches
v Server hardware
v Names of API programs and tasks, gateways, backup programs, executable scripts, third-party
programs, and so on.
2. Note any changes to these elements of the Domino environment. If possible, revert to the previous
configuration to determine if the problem still occurs.
v Operating system changes -- for example, did you upgrade the operating system or apply a new
patch?
v Network changes -- for example, did you add a new router or upgrade the network software or
firmware?
v Network interface card (NIC) changes -- for example, is the NIC new, or is the NIC software
driver old and the operating system new?
v Domino changes -- for example, did you upgrade to a new release of Domino or migrate new
users?
v Other hardware or software changes.
3. For an OS/2 server crash, check for a crash screen. Collect all codes that are displayed and check
them against the table of OS/2 server error codes.
For information on these codes, see the topic ″Domino OS/2 server crashes″ later in this chapter.
4. If the last message on the console starts with the word ″Panic,″ record the entire message.
5. If possible, capture the last screen displayed on the console or save the Console Log file.
6. Stop all tasks running on the Domino server, and then stop the Domino server.
7. If an NSD log file was created, verify the time and date of the file, which should coincide with the
time and date of the crash. If necessary, IBM Lotus Support Services will use this file to identify
where the crash occurred.

Note: If a crash doesn’t produce an NSD log file, the server may be out of disk space or memory.
8. Restart the server.
9. Check the Miscellaneous Events view in the log. Record all entries that occurred immediately before
and after the crash. To do this, double-click the appropriate entry to open it. In particular, look for an
NSF file in the entry, which may indicate where the crash occurred. If a particular database appears
to have caused the crash, check the replication history of that database for additional information.
10. Collect these configuration files:
v NOTES.INI -- All platforms
v Windows diagnostics file

Server crashes -- Problems and error messages: These topics describe problems and errors that may
cause a server crash:
v Corrupt database causes a server to crash
v Corrupt view causes a server to crash
v Server crashes while updating a database index
v The Router task causes the server to crash
v Domino OS/2 server crashes

Corrupt database causes a server to crash: If an ″Unable to copy database,″ ″Unable to copy document,″
or similar message appears in the Miscellaneous Events view of the log, a database is corrupted. Do one
of the following to correct the problem:
v Run the Fixup task. Use this task if the database is in Domino 5 or higher format and if you’re not
using transaction logging, or if the database is in Domino 4 format.

Chapter 66. Troubleshooting 1499

v Run the Fixup task with the -J option. Use this task if the database is in Domino 5 or higher format
and you are using transaction logging. If you use a backup utility certified for Domino 5 and you run
Fixup -J, perform a full backup of the database as soon as Fixup finishes.

Note: The Fixup task can take a significant amount of time to run on a large database or on the entire
server.

For more information on using Fixup to repair corrupted databases, see the chapter ″Maintaining
Databases.″

Corrupt view causes a server to crash: If a server crash seems related to a corrupt database view, run
the Updall task on the database with the -r option:
Load updall databasename -r

Note: The Updall task can take a significant amount of time to run on a large database. It will also take a
significant amount of time if you run Updall without specifying the database name, which forces the task
to run on all databases on the server.

Server crashes while updating a database index: If a server crashes while updating a database index,
do the following:
1. Run the Updall task on the database with the -r option to fix a damaged database index:
Load updall databasename -r

Note: The Updall task can take a significant amount of time to run on a large database. It will also
take a significant amount of time if you run Updall without specifying the database name, which
forces the task to run on all databases on the server.
2. If Updall does not fix the problem, use this procedure:
a. Make a replica of the corrupted database. Be sure to give the replica a new file name.
b. Delete the original corrupted database.
c. Use the original database file name to rename the new replica.
d. Restart the server.

The Router task causes the server to crash: In many cases, a crash occurs while a particular task is
running. You can often determine the task from the crash screen or from the NSD log file. If the crash is
related to the Router task, there could be a problem with MAIL.BOX.
1. Rename MAIL.BOX.
2. Restart the server. The server will automatically create a new MAIL.BOX.
3. Copy and paste the messages from the old MAIL.BOX to the new MAIL.BOX.

Domino OS/2 server crashes: If an OS/2 server crashes, a message resembling the following appears:
Trap 000C Internal Processing error at Location #nnn:nnn
Trap 000D CS=nnnn IP=nn xxxxx
CSLIM = nnnn

where nnnn represents error locations and addresses.

Crashed network drivers or an OS/2 problem may cause this error. Record the addresses and report them
to your network administrator. Then restart the server.

Codes that display when an OS/2 server crashes: When an OS/2 server crashes, the console displays an error
code. Record the code.

1500 Lotus Domino Administrator 7 Help

Code Meaning Cause
0 Divide error The software is bad.
1.00 Debug exceptions The software is bad. Record all addresses.
2.00 NMI interrupt Stands for non–maskable interrupt. The software is bad. Record all
addresses.
3.00 Breakpoint There is a software problem. Record all addresses.
4.00 Overflow The software is bad. Record all addresses.
5.00 Bound range exceeded There is a software problem. Record all addresses.
6.00 Invalid opcode There is a software problem. Record all addresses.
7.00 Coprocessor not The software is expecting a math coprocessor, and one isn’t installed.
available
8.00 Double fault Two traps occurred at the same time. Record all addresses.
9.00 Coprocessor segment There is a software problem. Record all addresses.
overrun
A/10 Invalid task state There is a software problem. Record all addresses.
segment
B/11 Segment not present There is a software problem. Record

all addresses.
C/12 Stack exception There is a software problem. Ignore this code if it follows a code D/13.
D/13 General protection There is a software problem or a corrupted database.
F/15 Coprocessor error There is a bad coprocessor chip.

NSD log files: NSD log files can help determine the cause of a server or workstation crash. A program
called NSD (nsd.exe for W32 platforms, nsd.sh for Unix platforms) creates these files in the Domino data
directory (for a server) or in the Notes data directory (for a workstation). The files contain information
about the tasks which were running when it crashed as well as general system information.

Server Health Monitoring -- Troubleshooting

These topics describe common problems with Server Health Monitoring. You can also search for solutions
to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Deleted server not removed from Health Monitoring view: When a Domino server is deleted from the
domain using the Configuration - All Server Documents view - Delete Server action, all references to the
server are removed from the views in the Domino Administrator Client, with one exception:
Configuration - Health Monitoring - Server Components view. The deleted server remains listed in this
view under the category: ″The Domain of the following servers has not yet been determined but will be
determined″. In addition, if you manually delete the server document in this view, it will return.

To permanently remove the deleted server from the Configuration - Health Monitoring - Server
Components view, perform the following steps:
1. From the Domino Administrator, open the Server - Monitoring view.
2. Select Administration - Refresh Server List menu item. Refresh the list for the domain from which the
server was deleted. The deleted server no longer appears in this view.
3. From the same view, click Stop to disable the Domino Administrator Server Monitor.
4. From the Configuration - Health Monitoring - Server Components view, delete the Server Component
document for the deleted server.

Chapter 66. Troubleshooting 1501

5. From the Files tab in the Domino Administrator, open the Health Monitoring database
(DOMMON.NSF). Delete the current health report document for the deleted server as well as any
Response documents for that health report document.
6. (Optional) Delete the historical health reports for the deleted server as well as any associated
Response documents.
7. Open the Server - Monitoring view and click Start to enable the Domino Administrator Server
Monitor, or, exit and then re-launch the Domino Administrator.

Server.Load -- Troubleshooting
The dynamic link library NNOTES.DLL could not be found in the specified path: Check to see if
SLOAD.EXE was copied to the Notes program directory. Copying SLOAD.EXE to the Notes program
directory should resolve the issue.

″Error detected on ’changeto’: ’No such port known’ (0x0A25)″: This message appears when you use a
custom script. Enable the port by choosing File - Preferences - User Preferences and selecting Ports.

″Error in NIFFindView″ messages: Adding documents to a folder that does not exist returns the
following:
Error in NIFFindView
add 10 -f $ABC
Error in NIFFindView: 0x0404--Entry not found in index
’add’ summary: Added 10 notes

Although it states that 10 notes (documents) were added, no documents were actually added. Create a
folder before adding documents.

″Error in NSFItemAppend: 0x013B--Memory allocation request exceeded 65,000 bytes″: This message
appears when you attempt to add a document containing a non-summary text item that is larger than
65KB. Do not create non-summary items that exceed 64KB.

″Cannot create greater than 512 sessions, sessions count reduced to 512.″: The value supplied for
Server_MaxSessions was greater than the limit of 512 for the NT platform. The session count will be
reduced to 512, and the built-in Idle Workload will continue to open 512 sessions to the Domino server.

Smart Upgrade -- Troubleshooting

These topics describe problems encountered when using Smart Upgrade.
v Smart Upgrade Tracking Reports are not being created
v Using the Smart Upgrade Log file for troubleshooting

Smart Upgrade Tracking Reports are not being created: If you are having problems with Smart
Upgrade, verify that you have enabled Smart Upgrade Tracking.

For information about enabling Smart Upgrade Tracking, see the chapter ″Upgrading Notes Clients.″

If you are not seeing any Smart Upgrade Tracking reports add the following NOTES.INI variables to the
NOTES.INI file on the server that you are using to run Smart Upgrade. If Smart Upgrade fails, you can
use the information that is generated and stored by these NOTES.INI settings to provide Support with
information that they can use to resolve any Smart Upgrade problems you may be having.
v Debug_Outfile --Specifies the file name to which to send all console output, so that it can be sent to
IBM Support for analyis.
v Debug_ThreadID -- Prepends all console output with the Process ID and Thread ID of the thread that
generated the output.

1502 Lotus Domino Administrator 7 Help

v Debug_Smart_Upgrade -- Use this variable to enable all Smart Upgrade messages to be sent to the
console, either for the Domino server or on the Notes client. You will see additional tracing on the
Domino server for Smart Upgrade when this variable is set.

If the information that is generated after setting the Debug_Smart_Upgrade NOTES.INI setting indicates
that a kit is not available for the user, check the Smart Upgrade database to determine whether a kit has
been configured. If a kit has been configured but the user is not being notified, use the USER.ID of the
Notes Client user and open the Smart Upgrade database to determine if that user can access the kit. If
not, add the user to the Allowed Users and Server field on the Administration tab of the Smart Upgrade
Kit document.

For more information about these NOTES.INI variables, see the Appendix ″NOTES.INI File.″

Using the Smart Upgrade Log file for troubleshooting: When a Smart Upgrade attempt is made from
the Notes Client using the File - Tools - Notes Smart Upgrade menu option or when Smart Upgrade is
initiate due to automatic prompting that occurs in the Notes Client, a Smart Upgrade Tracking file is
generated in the following directory for that Smart Upgrade session.
datadirectory\IBM_TECHNICAL_SUPPORT\SmartUpgrade

When the file is created is named SmartUpgrade.log, but when the Smart Upgrade session is complete,
the file is copied to new log file with a new file name. The information in this file is useful when
troubleshooting Smart Upgrade problems. This file is also used by the Smart Upgrade Tracking feature
when the feature is enabled. The file name is composed of several variables as shown:
SmartUpgrade_ADMIN1450_2005_07_05@13_21_08.log

Where
v SmartUpgrade is the first component of the new file name
v ADMIN1450 is the OS machine name and is added after SmartUpgrade_
v 2005_07_05@13_21_08 are the date and time, respectively.
v The file name extension .log is appended to file name.

The SmartUpgrade.log file is then truncated to zero (0) length until the next Smart Upgrade session.

Transaction logging -- Troubleshooting

These topics describe common problems with transaction logging. You can also search for solutions to
common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Invalid transaction log path: If Domino cannot access the transaction log path, the server console
displays error messages indicating: the invalid log path, databases requiring media recovery or Fixup,
and a panic.
1. Check the log path to make sure it exists.
2. Check that the server has write access to the log path.
3. If the log path is correct and the device is good, restart the server. The problem should be fixed and
you do not need to continue to step 4.
4. If log path is correct but the device is bad, replace the device on the log path, or edit the
TRANSLOG_Path setting in NOTES.INI to point to a different log path.

Note: If you edit the TRANSLOG_Path setting when you restart the server, be sure to make the same
edit to the ″Log path″ field in the Server document. Otherwise, Domino reverts to the old path upon
the next server restart.
5. Restart the server. Domino creates new log files and a control file, and assigns new DBIIDs to all
Domino 5 or higher databases.

Chapter 66. Troubleshooting 1503

6. If ″Automatic fixup of corrupt databases″ is set to Yes in the Server document, the Fixup task runs on
the databases that require media recovery or Fixup. Otherwise, you must run the Fixup task manually.
7. Perform full database backups.

Transaction log damaged or corrupted: If the transaction log appears to be damaged or corrupted, the
server console displays error messages indicating: the log is damaged, databases requiring media
recovery or Fixup, and a panic.

The error may occur because of a failed read from or write to the transaction log.
1. Restart the server to correct the error. If the damaged log error does not appear again, the log is not
damaged.
2. Stop the server again so it shuts down cleanly.
3. Perform full database backups.
4. Restart the server.
If you continue to received the damaged log error, the active transaction log is damaged or
corrupted.
5. Delete the transaction log files and the control file.
6. Restart the server. Domino creates new log files and a control file and assigns new DBIIDs to all
Domino 5 or higher databases.
7. If ″Automatic fixup of corrupt databases″ is set to Yes in the Server document, the Fixup task runs
on the databases that require media recovery or Fixup. Otherwise, you must run the Fixup task
manually.
8. Perform full database backups.
If the error occurred during media recovery, an archived log file may be corrupted.
9. Restart the server to correct the problem, and then stop the server so it shuts down cleanly.
10. While the server is down, use the third-party backup utility to perform media recovery. If the
archived log still cannot be used, allow database backups to be restored without the transactions in
the corrupted log.
11. Perform full database backups.
12. Restart the server.

Web server, Web Navigator, and the Web Administrator -- Troubleshooting

There are a variety of Web server, Web Navigator, and Web Administrator problems you may encounter.
v Web server -- Problems and error messages describes problems and errors that may occur with the Web
server.
v Web Navigator -- Problems and error messages describes problems and errors that may occur with the
Web Navigator.
v Web Administrator -- Problems and error messages describes problems and errors that may occur with
the Web Administrator.

You can also search for solutions to common problems on the IBM Lotus Support Services Web site at
www.ibm.com/software/lotus/support/.

Web server -- Problems and error messages: These topics describe how to troubleshoot some common
Web server problems and errors:
v Users can’t see a list of files on a Web server or access a database
v Users can’t access a Domino Web server via the Internet
v Users are prompted multiple times for their name and password
v The browser displays ″Error 403 - Directory Browsing error - Access forbidden″

1504 Lotus Domino Administrator 7 Help

Users are prompted multiple times for their name and password: You can configure Domino Web sites
so that Domino authenticates and asks Web users for their credentials only once when they access
different locations. Like other Web servers, Domino adheres to the HTTP authentication model. When a
user accesses a page on a Domino Web site, the browser keeps track of user credentials, based on the
realm that the Domino server sends to the browser. A realm is a string, which is typically a URL path,
that the server sends to indicate the location, or path, for which the user has been authenticated.

For example, if your server name is www.acme.com, then www.acme.com is the top-level realm and
www.acme.com/doc, www.acme.com/hr, and www.acme.com/marketing are the lower-level realms. If a
user authenticates with the server when accessing the home page for www.acme.com, then the user is
authenticated for www.acme.com and all lower-level realms.

However, if the user accesses www.acme.com/doc first, enters a name and password and is
authenticated, and then accesses www.acme.com/hr, Domino prompts the user for credentials again. This
second prompt occurs because the browser examines the list of realms for which Domino has successfully
authenticated the user and finds www.acme.com/doc in the browser realm list. Since www.acme.com/hr
is not a subdirectory of www.acme.com/doc, Domino requires the user to enter credentials again.

To prevent users from being prompted multiple times for their names and passwords, direct them to
access and authenticate with the highest level realm that they need to access. This way, Domino asks
users for their credentials only once during the browser session.

If a Web site includes a link to a site on another server and that site requires authentication, users will be
prompted again for their credentials.

Users can’t access a Domino Web server via the Internet: A firewall server often prevents users from
accessing a Domino Web server via the Internet. If you have a direct Internet connection, you can ping
the Domino server to see if you can access it. If you can ping the server but still can’t access it, telnet to
the server on port 1352 (see your telnet documentation for details on how to do this). If connecting with
telnet fails, the firewall server may be blocking the TCP port.

Users can’t see a list of files on a Web server or access a database: When users try to use the
OpenServer command to display a list of files on a Web server and the message ″Database browsing not
allowed″ appears, make sure the option ″Allow HTTP clients to browser databases″ is enabled in Server
document for that server.

If users try to access a database and the message ″Unauthorized exception″ appears, make sure they have
the appropriate access in the database ACL.

Browser receives error message ″Single Sign-on not Configured″ when accessing an SSO enabled
server: Verify that a Web SSO Configuration document exists for either a Web Site or for the Server
document and is enabled in the Session Authentication field. If using Web Site documents, the Web SSO
Configuration documents appear in the Internet Sites view for the specified web site. Otherwise, the Web
SSO Configuration documents appear in the Web Configurations view. You should also verify that the
Web SSO Configuration document is encrypted for the server to which the browser is connecting, by
checking the document to see that the server is listed in the participating server field.

If the Server document’s public key does not match the public key in the server ID file, then the
decryption of the Web SSO document will fail. This could happen if the ID file was created multiple
times and didn’t update the Server document correctly. Usually there is an error on the server console
indicating that the public key does not match the server ID. If this happens, then SSO fails because the
document could be encrypted with a public key for which the server does not possess the corresponding
private key necessary for decryption. The way to correct this is to copy the public key out of the server
ID, paste it into the Server document, and then recreate the Web SSO document.

Chapter 66. Troubleshooting 1505

Debugging session-based authentication problems: In session-based authentication, a cookie is created
on the Web server. Sometimes when the browser returns the cookie it doesn’t work and authentication
fails. Administrators need to be able to see the calls that the Web server is making to deny the cookie, or
to see whether the server even received it.

The NOTES.INI variable WebSess_Verbose_Trace should be used for troubleshooting both single server
and multi-server (as in single sign-on) session-based authentication problems. Setting
WebSess_Verbose_Trace=1 enables a Domino Web server to record, at the server console, detailed
information about specific Web session-based authentication sessions, such as unauthorized,
unauthenticated, or session expiration information.

After you correct the problem, make sure to disable this setting -- remove it or set it to 0 -- because using
it slows Web server performance.

″Error 403 - Directory Browsing error -- Access forbidden″: Check the Server document for an entry in
the Home URL or Default Home page fields. To display a home page on the Web server, one or both of
these fields must contain an entry.

Web Navigator - Problems and error messages: These topics describe how to troubleshoot some
common Web Navigator problems and errors:
v Users can’t send mail to the Internet from a mailto URL
v ″TCP/IP host unknown″ and ″Remote system not responding″.
v ″URL Access Denied″ message trying to open certain Web pages.
v ″The Web Navigator Retrieval process is not running″ trying to open a Web page.

Users can’t send mail to the Internet from a mailto URL: For users to send e-mail to the Internet, you
must set up mail routing to the Internet.

″TCP/IP host unknown″ and ″Remote system not responding″: Messages such as ″TCP/IP host
unknown″ and ″Remote system not responding″ usually indicate problems with the TCP/IP setup. If you
have a direct Internet connection and are able to use the IP address to ping the remote host successfully,
the Web Navigator may not be running. If you use host names instead of actual IP addresses in
Connection documents, there may be a problem with name resolution. To fix this problem, check the
hosts file to verify that your domain name system (DNS) can resolve the name to the IP address. If you
do not have a DNS, add the entry to the server’s local hosts file, which maps host names to IP addresses.
The hosts file is usually located in the same directory as the protocol software. It has a format similar to:

IP Host IP Fully Qualified Domain

Domino server name name Name IP Address Comment
Salt/Sales/Acme salt salt.usa.com 123.3.12.24.5 #Salt server
Pepper/Support/Acme pepper pepper.usa.com 123.3.12.678 #Pepper server

If the host name is the Domino server’s common name, then the hosts file or DNS will require an alias
link as shown here:

IP Fully
IP Host Qualified IP Alias name
Domino server name name Domain Name entry IP Address Comment
Red/Marketing/Acme ruby ruby.usa.com red within the host 123.3.12.212 #Red server
file or red CNAME
ruby for the DNS

1506 Lotus Domino Administrator 7 Help

 IP Fully
IP Host Qualified IP Alias name
Domino server name name Domain Name entry IP Address Comment
Purple/IS/Acme violet pepper.usa.com purple within the 123.3.12.83 #Purple server
host file or purple
CNAME violet for
the DNS

″URL Access Denied″ message trying to open certain Web pages: If users try to open a Web page and
a ″URL Access Denied″ message appears, check the ″Internet Site Access Control″ section under Server
Tasks - Web Retriever in the Server document for the Web Navigator server to see if you prevented access
to that Internet server.

″The Web Navigator Retrieval process is not running″: When users try to open a Web page within the
database, they will get this message if:
v The Web task stopped running or hasn’t been started on that server. To resolve this problem, start the
Web task on the server the runs the Web Navigator.
v The server specified in the InterNotes field in either their current Location document or the Server
document for their mail server is not a server running the Web task. To resolve this problem, specify
the correct server name.

Web Administrator -- Problems and error messages: These topics describe how to troubleshoot some
common Web Administrator problems and errors:
v Unable to log in to the Web Administrator
v New policies do not appear as an option when registering users

Unable to log in to the Web Administrator: Make sure you have the proper access level and roles in
the ACL for the Web Administrator database.

For information on access to the Web Administrator, see the chapter ″Setting Up and Using Domino
Administration Tools.″

When you start the Web Administrator, Domino asks you for your name and Internet password, which
are stored in your Person document. You must enter that name and password to access the database. If
the Internet Access security setting in the Server document is set to ″less name variations, more security.″

You may need to re-create the database. The Web Administrator must be created and configured by the
HTTP server to work properly. Do not attempt to use File - Database - Replace Design or Refresh Design.

To re-create the database: Domino creates the Web Administrator database the first time that the HTTP task
runs on a server. Keep in mind that deleting the database deletes existing administrator preferences.
1. Enter this command at the console:
tell http quit
2. Delete WEBADMIN.NSF.
3. Enter this command at the console:
load http

Note: Do not try to refresh the database from the File menu using File - Database - Replace Design or
Refresh Design.

New policies do not appear as an option when registering users: If a policy that has been recently
created does not appear as an option during user registration, reload the Web Administrator so that the
new policy is available.

Chapter 66. Troubleshooting 1507

Overview of server maintenance
As a Domino administrator, a major part of your job is maintaining each server that you administer. You
need to ensure that:
v The server is backed up regularly.
v Users can access the server quickly and consistently.
v Mail is routed properly.
v Administration Process requests are carried out.
v Databases are replicating correctly.
v Server hardware is functioning.
v Databases are active and maintained (a task you share with the manager of each database).

You can use a server maintenance checklist to schedule these tasks.

Server maintenance checklist

This table lists the server maintenance tasks that you should complete daily, weekly, or monthly to ensure
that a server runs efficiently.

Task Frequency
Back up the server Daily, weekly, monthly
Monitor mail routing Daily
Run Fixup to fix any corrupted databases * At server startup and as needed
Monitor shared mail database (MAILOBJ.NSF) Daily
Monitor Administration Requests database Weekly
(ADMIN4.NSF)
Monitor databases that need maintenance Weekly
Monitor replication Daily
Monitor modem communications Daily
Monitor memory Monthly
Monitor disk space Daily, weekly, monthly
Monitor server load Monthly
Monitor server performance Monthly
Monitor Web server requests Monthly
Monitor server first domino servers Daily

* If the database is in Domino 5 or later format and you are not using transaction logging, you can use
the Fixup task to repair the corrupted database. If the database is in Domino 5 or later format and you
are using transaction logging, you cannot run the Fixup task on that database, because the Fixup task
interferes with the way transaction logging keeps track of databases. Instead, you must restore the
corrupted database from a backup. You can run the Fixup task on databases that are in Domino 4.x and
earlier format.

Backing up the Domino server

You have two choices for backup procedures. You can use the traditional method of making backup
copies of files, or you can use transaction logging.

For information on transaction logging, see the chapter ″Transaction Logging and Recovery.″

Guidelines for backing up a Domino server: Back up all Domino server data files including databases,
template files, the NOTES.INI file, and ID files. Following your company’s standardized backup

1508 Lotus Domino Administrator 7 Help

procedures, back up files directly to tape or to a file server and then to tape. Never rely only on
replication as your method of database backup. A damaged or accidentally changed database may
replicate, and then your only recourse is to recover the database from a server backup tape.

Follow these guidelines to back up a Domino server:

1. Domino requires that these files be open when it runs: LOG.NSF, NAMES.NSF, MAIL.BOX and the
server ID file. If your backup utility cannot back up open files, you must shut down the server before
you create the backup file.
2. Copy the server ID file to a disk, and store the disk in a secure place.
3. Make a replica of the Domino Directory on a workstation and keep it up-to-date by replicating the
local replica with the server replica. Then if the Domino Directory becomes corrupted, you can
quickly restore it by creating a new replica from the local workstation replica. Even if you do this,
continue to back up the Domino Directory to tape. Never do this when transaction logging is used.
4. If your system uses a shared mail database, back up the shared mail database(s) along with user mail
files.

Chapter 66. Troubleshooting 1509

1510 Lotus Domino Administrator 7 Help
Appendix A Server Commands
You can use server commands to perform all administration tasks. This appendix describes how to enter
server commands and provides complete information on using each server command.

Domino server commands

This list briefly describes the Domino server commands that are available.

Note: This appendix also contains a separate list of Domino and DB2 server commands, that is, server
commands that used only in a configuration consisting of Domino with DB2.

Command Description
Broadcast Sends a message to specified users or to all users of this server.
Dbcache Disable Disables the database cache when you need exclusive access to a file in it.
Dbcache Flush Closes all databases that are currently open in the database cache.
Dbcache Show Displays the names of the databases currently in the cache.
Drop Closes one or more server sessions.
Exit Stops the server. This command is identical to Quit.
Help Displays a list of server commands with a brief description, arguments (if any), and the
proper syntax for each.
Load Loads and runs a specified server task or program on the server.
Platform Controls the platform statistics data at the console.
Pull Forces a one-way replication from the specified server to your server.
Push Forces a one-way replication from your server to specified server.
Quit Stops the server. This command is identical to the Exit server command.
Replicate Forces replication between two servers (the server where you enter this command and the
server you specify).
Restart Port Disables transactions (or messages) on the specified port and then re-enables the port after
a brief delay.
Restart Server Stops the server and then restarts the server after a brief delay.
Restart Task Shuts down and then restarts a specified server task.
Route Initiates mail routing with a specific server.
Save Saves a specified note in dxl format to the data directory.
Set Configuration Adds or changes a setting in the NOTES.INI file.
Set Rules Reloads the server’s mail rules.
Set SCOS Activates or deactivates a shared mail database.
Set Secure Password-protects the console.
Set Statistics Resets a statistic that is cumulative.
Show Agents Displays the name of agents in the database you specify.
Show AI Displays the history of the expansion factor and the availability index (AI). Suggests a
good value for the NOTES.INI variable Server_Transinfo_Range=.
Show Allports Displays the configuration for all enabled and disabled ports on the server.
Show Cluster Displays the local server’s cluster name cache.

1511
Command Description
Show Configuration Displays the current value for a NOTES.INI setting.
Show Directory Lists all database files in the data directory and identifies multiple replicas of a database.
When used with the argument, -unread, shows detail on whether databases have
replication of unread marks set.
Show Diskspace Displays the amount of space, in bytes, available on the disk drive (Windows) or file
system (UNIX).
Show Heartbeat Indicates whether the server is responding.
Show Memory Used for OS/2.
Show Monitors Reports the amount of memory being used by monitors.
Show Opendatabases Displays a list of open databases on the server and detail information for the databases.
Show Performance Displays the per minute user/transaction values when the Domino Server is running.
Show Port Displays traffic and error statistics, and resources used on the network adapter card or
communications port.
Show Schedule Shows the next time that a server task will run. Includes these arguments:
Show SCOS Displays information about shared mail databases and reloads the shared mail
configuration.
Show Server Shows server status information.
Show Stat Displays Domino server statistics for one or more of the following: disk space, memory,
mail, replication, and network activity.
Show Stat Platform Displays individual and cumulative platform statistics for all servers including one or
more of the following: logical disk, paging file, memory, individual network, process, and
system.
Show Tasks Displays the server name, the Domino program directory path, and the status of the active
server tasks.
Show Transactions For each type of transaction, displays the total number of NRPC transactions, the
minimum and maximum duration of the transaction, the total time to perform all
transactions, and the average time to perform the transaction.
Show Users Displays a list of all users who have established sessions with the server.
Show Xdir Provides information about each directory a server uses for name resolution.
Start Consolelog Enables console logging.
Start Port Enables transactions (or messages) on the specified port.
Stop Consolelog Disables console logging.
Stop Port Disables transactions (or messages) on the specified port.
Sucache refresh Forces a dynamic reloading of the Smart Upgrade configuration information, displays the
state of the Domino server’s Smart Upgrade cache information, and displays Smart
Upgrade statistics gathered when the Domino server was restarted.
Sucache show Displays the current state of the Domino server’s Smart Upgrade cache as well as some
statistics gathered since the Domino server was restarted.
Tell Issues a command to a server program or task.
Trace Tests a connection to a server.

Broadcast
Syntax: Broadcast ″message″ [usernames or database]

Broadcast ″(!) message″ [usernames or database]

1512 Lotus Domino Administrator 7 Help

Description: Sends a message to specified users, users of the specified database or to all users of this
server. Use this command to warn users when a server is brought down for maintenance. By default, the
message you enter appears in the user’s status bar. To display the message in the middle of the user’s
screen, precede the message with (!).

Examples:

Broadcast ″Server ACME will be down in 10 minutes″ -- Sends a warning message about impending
maintenance on server ACME to all users on this server.

Broadcast ″(!) Server ACME will be down in 10 minutes″ -- Sends the same warning message as shown in
the example above, but this message displays in the center of the user’s screen. Note that parentheses ()
are entered as part of the command string.

To broadcast a message from the Domino Administrator

You can send messages directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. In the left pane, select ″Server Users″ to display the list of current users in the middle pane.
3. (Optional) In the middle pane, select the users to whom you want to send the message.
4. If necessary, click Tools to display the tool bar, and then click User - Broadcast Message.
5. Complete these fields, and then click Send:

Field Action
Broadcast a Choose one:
message to v ″Selected user″ to send the message to the users you selected in the middle pane of the Server -
Status tab.
v ″All connected users″ to send the message to all users with active sessions on the Domino server.
v ″All users of a database″ to send the message to all users of a particular database. Enter the
directory string for the database in the field.
Broadcast this v Enter the text of the message you want to send.
Message
Show as Click this check box to display the broadcast message in a dialog box on the users’ workstation.
dialog box on
users’
workstation

Dbcache Disable
Syntax: Dbcache disable

Description: The database cache keeps databases open. Use this command to disable the database cache
when you need exclusive access to a file that might be in the database cache. For example, to run an
application such as a virus checker or backup software, disable the cache. To re-enable the dbcache,
restart the server.

For more information on the database cache, see the chapter ″Improving Database Performance.″

Dbcache Flush
Syntax: Dbcache flush

Description: Closes all databases that are currently open in the database cache. Use this command before
maintaining databases to flush databases from the cache.

Appendix A Server Commands 1513

For more information on the database cache, see the chapter ″Improving Database Performance.″

Dbcache Show
Syntax: Dbcache show

Description: Displays the names of the databases currently in the cache. use this command to see if the
database cache has a database open. Applications that cannot get exclusive access to a database may fail
if the database is in the database cache.

For more information on the database cache, see the chapter ″Improving Database Performance.″

Drop
Syntax: Drop username

Description: Closes one or more server sessions. To visually confirm which sessions are dropped, you
must enter the Log_Sessions=1 setting in the server’s NOTES.INI file.

For information on Log_Sessions, see the appendix ″NOTES.INI File.″

Examples:

Drop ″Sandy″ -- Closes the current session running under the user name Sandy.

Drop ″Lee″ ″Fran″ -- Closes the sessions running under the user names Lee and Fran.

Drop All -- Closes all server sessions.

To drop sessions from the Domino Administrator

You can drop sessions directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. In the left pane, select ″Notes Users″ to display the list of current users in the middle pane.
3. (Optional) In the middle pane, select the user sessions you want to drop.
4. If necessary, click Tools to display the tool bar, and then click User - Drop.
5. When prompted as to whether you want to drop the user, click OK.

Exit
Syntax: Exit

Description: Stops the server. This command is identical to Server - Shutdown.

Before you use Exit to stop the server, use the Broadcast server command to warn users so they can
finish their current tasks before you stop the server.

If you stop a server while it’s replicating databases or routing mail, these tasks resume at the next
scheduled interval after you restart the server. Replication or mail routing continues until the databases
are fully replicated and until the complete mail message is transferred or returned to sender.

Tip: You can also stop the server from the Domino Administrator. From the Domino Administrator, click
the Server - Status tab, and then click Server - Shutdown.

Help
Syntax: Help

1514 Lotus Domino Administrator 7 Help

Description: Displays a list of server commands with a brief description, arguments (if any), and the
proper syntax for each.

Load
Syntax: Load programname

Description: Loads and starts a specified server task or program on the server. You can start a server
add-in program or one that takes a command line for additional data, such as a backup program. The
program you run must be on the server’s search path.

Use the Load command to run a program until it completes or, if the program runs continually, until you
stop the server. Where applicable, you can include arguments that determine how the program runs.

Note: Most server commands support the arguments ″-?″ and ″/?″ to display online help. For example,
you could enter one of these to obtain help for the server command Load Compact:
Load Compact -?
Load Compact /?

Examples:

Load Fixup -- Loads and runs the Fixup server task.

Load Object Info OBJECT.NSF -- Loads and runs the Shared Mail Manager and passes along arguments
that execute the Info task.

For more information, see the appendix ″Server Tasks.″

To load a task from the Domino Administrator

You can load a task directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. If necessary, click Tools to display the tool bar, and then click Task - Start.
3. Under ″Start new server tasks,″ select the task you want to load.
4. (Optional) Uncheck ″Show advanced options″ if you do not want to specify advanced options. The
box is checked by default for tasks which do have additional options.
5. Click OK.

Platform
Syntax: Platform <main argument> [<optional arguments>]

Description: Controls the platform statistic feature at the console. Platform statistics that are affected by
the reset command are:
v Fixed -- These statistic values 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 a
platform reset command is issued.
v Primary -- These are the individual statistic metrics on which secondary statistics are derived. For
example, a total paging file utilization statistic (Platform.PagingFile.TotalPctUtil) forms the basis for the
secondary average and peak statistics values (Platform.PagingFile.TotalPctUtil.Avg and
Platform.PagingFile.TotalPctUtil.Peak).
v Secondary -- Statistic values that are a combination of, or are derived from primary statistics.

Appendix A Server Commands 1515

Arguments:

Arguments Description
Time [<sampling period>] Used with an optional argument, changes the sampling period to the specified
value in minutes. If not used, displays the current sampling rate. Default is 1
minute.
Reset Resets the value of primary statistics to zero, and gathers new set of metrics.
Reset Interval Enable Resets all values each time a new sampling period begins. Uses the sampling
period defined using the Time argument.
Reset Interval Disable Disables the Reset Interval Enable command.
Pause Pauses the collection and update of performance data.
Resume Resumes the collection and update of performance data.

For more information on monitoring platform statistics, see the chapter ″Monitoring the Domino Server.″

Examples:

Use Platform Time <n> to start a new performance data monitoring session with a sampling period of n
minutes. This means that the statistic value can change every n minutes. For example:
platform time 5

Use the Platform Reset command so that prior existing values are not used in calculating minimum,
average, or maximum values. You may want to use this command when platform statistics have been
accumulating overnight and you want to clear out the accumulation. For example:
platform reset

Use the Platform Reset Interval Enable command to reset all values each time you begin a new sampling
period. For example:
Platform Reset Interval Enable

Pull
Syntax: Pull servername [databasename]

Description: Forces a one-way replication from the specified server to your server. You can also replicate
a single database from the specified server to your server by including the database name on the
command line. The initiating server receives data from the named server, but doesn’t request that the
other server pull data from it. This forces a server to replicate immediately with the initiating server,
overriding any replication scheduled in the Domino Directory. Enter the server’s full hierarchical name, if
applicable.

You can pull changes immediately if an important database, such as the Domino Directory, has changed
or if a database on your server is corrupted or has been deleted.

For replication to succeed, make sure that:

v The Domino Directory contains a Server document for each server in the domain.
v The Domino Directory contains a Connection document to connect to a remote server.
v Each server’s ID file contains a certificate that the other server recognizes and trusts.
v Database ACLs allow replication, and the source server has sufficient access in the ACLs to replicate
changes. If you’re using server access lists, servers must have proper access in the Server document.

If the server is currently replicating, Domino queues the Pull server command until the current task
completes.
1516 Lotus Domino Administrator 7 Help
To check the status of the Replicator before using Pull, enter this command at the console:
Show Tasks

The server displays one of the following messages:

v If the server isn’t replicating, the word ″Idle″ appears next to the Replicator task.
v If the server is replicating, a message such as ″Replicating CONTRACT.NSF from
MARKETING\CONTRACT.NSF″ appears.

Examples:

Pull Marketing\Acme -- Forces one-way replication with the server Marketing.

Pull Marketing\Acme NAMES.NSF -- Forces one-way replication of the NAMES.NSF file from the server
Marketing.

To replicate from the Domino Administrator

You can replicate directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. If necessary, click Tools to display the tool bar, and then click Server - Replicate.
3. Under ″Which server do you want to replicate with,″ enter the name of the server to replicate with, or
select the server name from the list.
4. For ″Replication style,″ choose Pull.
5. Choose one:
v Selected database -- to select a specific database to replicate. Click the database button and select a
database from the list.
v All databases in common -- to replicate all databases that both servers have in common. This is the
default setting.
6. Click Replicate.

Push
Syntax: Push servername [databasename]

Description: Forces a one-way replication from your server to the specified server. You can also replicate
a single database from your server to the specified server by including the database name on the
command line. The initiating server sends data to the named server, but doesn’t request data in return.
This forces a server to replicate immediately with the initiating server, overriding any replication
scheduled in the Domino Directory. Specify the server’s full hierarchical name, if applicable.

In effect, the Push server command is the functional opposite of the Pull server command .

Examples:

Push Marketing\Acme -- Forces one-way replication with the server Marketing.

Push Marketing\Acme NAMES.NSF -- Forces one-way replication of the NAMES.NSF file to the server
Marketing.

To replicate from the Domino Administrator

You can replicate directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. If necessary, click Tools to display the tool bar, and then click Server - Replicate.

Appendix A Server Commands 1517

3. Under ″Which server do you want to replicate with?,″ enter the name of the server to replicate with,
or select the server name from the list.
4. For ″Replication style,″ choose Push.
5. Choose one:
v Selected database -- to select a specific database to replicate. Click the database button and select a
database from the list.
v All databases in common -- to replicate all databases that both servers have in common. This is the
default setting.
6. Click Replicate.

Quit
Syntax: Quit

Description: Stops the server. This command is identical to the Server - Shutdown command. However,
the Quit server command differs from the Tell server command, which you use to stop a particular server
task without stopping the server.

If you stop a server while it’s replicating databases or routing mail, these tasks resume at the next
scheduled interval after you restart the server. Replication or mail routing continues until the databases
are fully replicated and until the complete mail message is transferred or returned to the sender.

Before you use the Quit server command to stop the server, use the Broadcast server command to warn
users to finish their current tasks before you stop the server.

Tip: You can also stop the server from the Domino Administrator. From the Domino Administrator, click
the Server - Status tab. From the tool bar, click Servers - Shutdown.

Replicate
Syntax: Replicate servername [databasename]

Description: Forces replication between two servers (the server where you enter this command and the
server you specify). Use the server’s full hierarchical name. If the server name is more than one word,
enclose the entire name in quotes. To force replication of a particular database that the servers have in
common, specify the database name after the server name. The initiating server (where you’re currently
working) first pulls changes from the other server, and then gives the other server the opportunity to pull
changes from it. You can use this command to distribute changes quickly or to troubleshoot a replication
or communication problem.

Note: The existing replication schedule between the servers determines how the second server responds
to this command. If this replication falls within the timeframe that the second server replicates with the
initiating server (based on calling schedules and the repeat interval), the second server pulls changes.
Otherwise, it waits for the next scheduled replication time.

If the server is already replicating when you issue the command, Domino queues the command until the
current replication ends. To check the status of the Replicator, enter this command at the console:
Show Tasks

The server displays one of the following messages:

v If the server isn’t replicating, the word ″Idle″ appears next to the Replicator program.
v If the server is replicating, a status line, such as ″Replicating CONTRACT.NSF from
MARKETING\CONTRACT.NSF,″ appears.

1518 Lotus Domino Administrator 7 Help

To optimize resources Domino only replicates what is necessary. For example, if the servers recently
replicated and no changes have since been made to any databases on either server, the servers don’t
replicate when you enter a Replicate command. Also, the replication is two-way only if databases on both
servers changed since the last replication. If databases on only one of the servers changed, the replication
is one–way.

To force replication in only one direction, use the Pull or Push server commands.

Examples:

Replicate Marketing\Acme -- Initiates replication between your server and the Marketing/Acme server.
The server console displays messages indicating when replication begins.

Replicate Marketing\Acme NAMES.NSF -- Initiates replication of NAMES.NSF between your server and
the Marketing\Acme.

To replicate from the Domino Administrator

You can replicate directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. If necessary, click Tools to display the tool bar, and then click Servers - Replicate.
3. Under ″Which server do you want to replicate with?,″ enter the server you want to replicate with, or
select the server you want from the drop-down list.
4. For ″Replication style,″ choose Push Pull.
5. Choose one:
v Selected database -- to select a specific database to replicate. Click the database button and select a
database from the list.
v All databases in common -- to replicate all databases that both servers have in common. This is the
default setting.
6. Click Replicate.

Restart Port
Syntax: Restart Port portname

Description: Disables transactions (or messages) on the specified port and then re-enables the port after a
brief delay. The command lets you stop and start a port without stopping the Domino server.

When you are supporting Internet servers that rely on TCP/IP, you can restart the TCP/IP port and the
Internet ports enter a waiting state. The Internet ports suspend and keep checking for the TCP/IP port.
You will see the following when using restart port TCPIP:
>restart port tcpip
06/28/2002 12:34:08 PM LDAP Server: Listener failure: Request failed because the requested port is inactive
06/28/2002 12:34:08 PM LDAP Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted
06/28/2002 12:34:11 PM POP3 Server: Listener failure: Request failed because the requested port is inactive
06/28/2002 12:34:11 PM POP3 Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted
06/28/2002 12:34:11 PM SMTP Server: Listener failure: Request failed because the requested port is inactive
06/28/2002 12:34:11 PM IMAP Server: Listener failure: Request failed because the requested port is inactive
06/28/2002 12:34:11 PM SMTP Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted
06/28/2002 12:34:11 PM IMAP Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted
06/28/2002 12:34:28 PM LDAP Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted
06/28/2002 12:34:29 PM Port TCPIP was successfully disabled
06/28/2002 12:34:31 PM POP3 Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted

Appendix A Server Commands 1519

06/28/2002 12:34:31 PM SMTP Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted
06/28/2002 12:34:31 PM IMAP Server: Suspended, waiting 20 seconds for Notes Port Driver [TCPIP] to be restarted

To see a list of ports you can restart, issue the console command Show Configuration.

Example:

Restart Port TCP -- Disables and re-enables the port named TCP.

Restart Server
Syntax: Restart Server

Description: Stops the server and then restarts the server after a brief delay.

If you stop a server while it’s replicating databases or routing mail, these tasks resume at the next
scheduled interval after you restart the server. Replication or mail routing continues until the databases
are fully replicated and until the complete mail message is transferred or returned to the sender.

Before you use Restart Server to stop the server, use the Broadcast server command to warn users to
finish their current tasks before you stop the server.

Tip: You can also use the Domino Administrator to restart the server. From the Domino Administrator,
click the Server - Status tab and use the tool Server - Restart.

Restart Task
Syntax: Restart Task taskname

Description: Shuts down and restarts a specified server task.

Example: The following command shuts down and restarts the LDAP task:
Restart Task LDAP

Tip: You can also use the Domino Administrator to restart a task. From the Domino Administrator, click
the Server - Status tab and use the tool Task - Restart.

Route
Syntax: Route servername

Description: Initiates mail routing with a specific server. The Route command overrides any mail routing
schedules that you create in the Connection documents in the Domino Directory. Use the Route command
for servers that are configured for Pull, Pull Push, Push, or Push Wait routing in the Connection
document. Use the server’s full hierarchical name, if applicable. If the server name is more than one
word, enclose the entire name in quotes. To route to all pending destinations, use Route *.

Use the Route command to troubleshoot mail problems and to send mail to or request mail from a server
immediately.

If no mail is queued for routing, Domino ignores the Route command. Use the Tell Router Show
command to check for messages pending for local delivery or to check for messages held because a mail
file is over quota. To check which servers have mail queued, use this command at the console:
Tell Router show

Examples:

1520 Lotus Domino Administrator 7 Help

Route Marketing\Acme -- Sends mail to the Marketing server in the Acme domain. The server console
displays messages indicating when routing begins.

Route * -- Sends mail to all pending destinations.

Route [$LocalDelivery] -- Overrides the next scheduled retry time and attempts local delivery
immediately.

To route mail from the Domino Administrator

You can route mail directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. If necessary, click Tools to display the tool bar, and then click Server - Route Mail.
3. Under ″Route mail with server,″ enter the name of the server you want to route mail to, or select the
name of the server from the list.
4. Click Route.

Save
Syntax: Save noteid <noteid in hexadecimal format>

Description: Exports a document (noteid) from the Domino Directory (NAMES.NSF) to dxl format and
saves the dxl file to the Domino data directory.

When the file is successfully saved, a message in this format appears:

NOTE 22D6 saved in file C:\Domino\Data\noteid_22D6_sname_2002_06_23@16_22_00.dxl

Where
v 22D6 is the noteid
v sname represents the server name
v 2002_06_23 represents the date
v 16_22 represents the time

Set Configuration
Syntax: Set Configuration setting

Description: Adds or changes a setting in the NOTES.INI file.

Tip: You can also use the Domino Administrator to add or change many settings in the NOTES.INI file
using the Configuration Settings document.

Example:

Set Configuration Names = Names,Westnames -- Sets the NOTES.INI Names setting to specify that
Domino search both the Names and the Westnames Domino Directories.

For more information about using the Configuration Settings document to set NOTES.INI settings, see the
appendix ″NOTES.INI File.″

Set Rules
Syntax: Set Rules

Description: Reloads the server’s mail rules, enabling new rules to take effect immediately.

Appendix A Server Commands 1521

Server mail rules enable administrators to filter messages based on content in the message headers or
body. At startup, the server retrieves these rules from the Configuration document and registers them as
monitors on each MAIL.BOX database in use. The Server task checks to see if the server’s mail rules need
to be reloaded every 5 minutes. New rules take effect only after the server reloads the mail rules.

Set SCOS
Syntax: Set SCOS Databasename [Active | Inactive]

where Databasename is the full pathname to a shared mail database.

Description: Activates or deactivates a shared mail database. The Shared Mail tab of the Server document
lets you specify the delivery status and availability for all shared mail databases in the directory. Using
the Set SCOS command, you can change the availability of an individual shared mail database.

Example: Set SCOS C:\LOTUS\DOMINO\DATA\SCOS1\SM000004.NSF INACTIVE

Prevents new messages from being deposited in the shared mail database SM000004.NSF. Users still have
access to previously-delivered messages in the database.

Set Secure
Syntax: Set Secure currentpassword

Description: Password-protects the console.

After you password-protect the console, you can not use the Load, Tell, Exit, Quit, and Set Configuration
server commands or other programs that aren’t run automatically through Program documents in the
Domino Directory or through the NOTES.INI file. Console security remains in effect until you clear the
password by entering a second Set Secure command with the same password.

Even if the console is password-protected, keep the server physically secure to prevent breaches of
security at the operating system level.

Examples:

Set Secure abracadabra -- Password-protects the console if no password is currently in effect. In this case,
the new password is ″abracadabra.″

Set Secure abracadabra sesame -- Changes the existing password ″abracadabra″ to ″sesame.″

Set Secure abracadabra -- If the console is already protected by a password -- in this case ″abracadabra″ --
entering a second Set Secure command with the same password clears the password.

To secure the console from the Domino Administrator

You can secure the console directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. If necessary, click Tools to display the tool bar, and click Server - Secure console.
3. Do one of the following:
v To set a password, select ″Set″ at the bottom of the box, then complete these fields, and click OK:

Field Enter
Console Password The password you want to set
Verify The same password, again

1522 Lotus Domino Administrator 7 Help

 v To clear a password, select ″Clear″ at the bottom of the box, then under ″Password,″ enter the
password and click OK.
v To change a password, select ″Change″ at the bottom of the box, then under ″Password,″ enter the
old password and click OK. Then complete these fields, and click OK:

Field Enter
Password The new password you want to set
Verify The same, new password, again

Set Statistics
Syntax: Set Statistics statisticname

Description: Resets a statistic that is cumulative. Statisticname is a required parameter that names the
statistic to be reset. You can’t use wildcards (*) with this argument.

For more information on monitoring statistics, see the chapter ″Monitoring the Domino Server.″

Example:

Set Stat Server.Trans.Total -- Resets the Server.Trans.Total statistic to 0

Show Agents
Syntax: Show Agents database name [-v]

Description: The Show Agents server command shows all agents available in the database. The verbose
mode ([-v]) shows all agents and script libraries in the database as well as detail information on both.

Examples:

Show Agents DatabaseName.nsf

Show Agents -v DatabaseName.nsf

Show AI
Use this command after running a server under load.

Syntax: Show AI

Description: The Show Availability Index server command shows the history of the expansion factor and
the availability index. It also shows a suggested value for the NOTES.INI variable.
Server_Transinfo_Range.

Example:

Show AI

Show Allports
Syntax: Show Allports

Description: Displays the configuration for all enabled and disabled ports on the server.

Example:

Appendix A Server Commands 1523

The following example shows the output that appears on the server console when you issue the Show
Allports command.
Show Allports
Enabled Ports:
TCPIP=TCP,0,15,0,,12320,
SPX=NWSPX,0,15,0,,12320,
LAN0tcpip=NETBIOS,0,15,0,,12322,
LAN1nb=NETBIOS,3,15,0,,12322,
LAN2ipx=NETBIOS,7,15,0,,12322,
Disabled Ports:
LAN6=NETBIOS,6,15,0,,12320,
LAN8=NETBIOS,8,15,0,,12320,
COM1=XPC,1,15,0,,12326,38400,,hyaccv34.mdm,60,15
LAN1=NETBIOS, 1, 15, 0
LAN2=NETBIOS, 2, 15, 0
LAN4=NETBIOS, 4, 15, 0
LAN5=NETBIOS, 5, 15, 0
COM2=XPC,2,15,0,
COM3=XPC,3,15,0,
COM4=XPC,4,15,0,
COM5=XPC,5,15,0,

Show Cluster
Syntax: Show Cluster

Description: Displays the local server’s cluster name cache, which includes a list of all cluster members
and their status, based on information received during the server’s cluster probes.

For more information on server clusters, see Administering Domino Clusters.

Example:

This example displays the cluster name cache of the Mars server, which is in the Planets cluster, which is
in the Solarsys domain.
Show Cluster
Cluster Information
Cluster name: planets/solarsys, Server name: mars/solarsys
Server cluster probe timeout: 1 minute(s)
Server cluster probe count: 2604
Server cluster probe port: NetBEUI
Server availability threshold: 10
Server availability index: 98 (state: AVAILABLE)
Server availability default minimum transaction time: 3000
Cluster members (2)...
server: mars/solarsys, availability index: 98
server: saturn/solarsys, availability index: BUSY

Show Configuration
Syntax: Show Configuration setting

1524 Lotus Domino Administrator 7 Help

Description: Displays the current value for a NOTES.INI setting. Use the Show Configuration and Set
Configuration server commands together to ensure that you correctly set the NOTES.INI settings.

Wildcards are allowed.

Examples:

Show Configuration Domain -- Displays the server’s domain

Show Configuration * -- Displays all the configuration information for the server

Show Configuration ???? -- Displays any variable that is exactly 4 characters long

Show Directory
Syntax:

Show Directory

Show Directory -argument

Description: Lists all database files (for example, NSF and NTF) in the data directory and specifies
whether the data directory contains multiple replicas of a database. This command works only for the
data directory; you can’t specify another directory.

Tip: From the Domino Administrator, click the Files tab to view a list of all database files in the data
directory.

Arguments:
-unread -- Shows the database name; software version; modification time; status of unread marks
replication (off or on); and whether unread marks replicated to all servers, never replicated, replicated to
clustered servers, or if the software version does not support replicating unread marks. Sample output is
shown here:

DbName Version Logged ---Modified Time---- Unread Marks Replicate Unread Marks

e:\notefile\mail.box V6:43 N/A 07/11/2003 05:10:13 PM Off

e:\notefile\r63mail.ntf V4:20 N/A 01/18/2003 01:47:54 PM On Min V6:43 required

e:\notefile\maillist.ntf V4:20 N/A 05/29/2003 01:45:21 PM On Min V6:43 required

e:\notefile\mailxx.ntf V4:20 N/A 07/11/2003 01:04:02 AM On Min V6:43 required

e:\notefile\mail\xx1.nsf V6:43 N/A 07/11/2003 05:09:43 PM On All servers

e:\notefile\mail\xx2.nsf V6:43 N/A 07/11/2003 12:41:05 PM On All servers

e:\notefile\mail\xx3.nsf V6:43 N/A 07/11/2003 03:01:58 PM On All servers

You can also use the Show Directory command to check which databases have transactional logging
enabled.

To see only logged databases, enter this command at the console:

show dir *log

Appendix A Server Commands 1525

To see only unlogged databases, enter this command at the console:
show dir *nolog

For more information, see the chapter ″Transaction Logging.″

Show Diskspace
Syntax: Show Diskspace location

Description: Displays the amount of space, in bytes, available on the disk drive (Windows), or file system
(UNIX). If you do not specify a location, Domino displays the space available on the disk or file system
containing the Domino program directory. If available disk space is low -- for example, under 10MB --
free up disk space by deleting documents, databases, and other files that you don’t need.

Note: The Domino server starts before drives are mapped. Therefore, when you use the command, the
drives aren’t visible. To see the mapped drivers, stop and restart the Domino server or put the Domino
server in the Startup group.

Domino makes calls to the network ″redirector″ on the system it’s on.

Tip: You can also display the amount of available space by using the Domino Administrator. From the
Domino Administrator, click the Files tab. If necessary, click Tools, and then from the tool bar, click Disk
Information.

Examples:

How you enter the Show Diskspace command depends on the server’s operating system.

On a Windows 2000/2003 server, enter this command to display available space on Drive C:
Show Diskspace C

On a UNIX server, enter this command to display available space in the /USR directory of a file system:
Show Diskspace /USR

On a UNIX server, enter this command to display available space in the current directory:
Show Diskspace

Show Heartbeat
Syntax: Show Heartbeat

Description:

The Show Heartbeat server command indicates whether the server is responding.

Example:

Show Heartbeat

The server responds with a message such as:

elapsed time: #### seconds

Show Memory
Syntax: Show Memory

1526 Lotus Domino Administrator 7 Help

Description: The Show Memory server command displays the amount of RAM available on a server,
plus the amount of swap memory available on the boot drive of the Domino server. If the number shown
here and the number shown when you enter a Show Diskspace command are almost equal, the server
may need more RAM.

Examples:

Show Memory -- The server responds with a message such as:

Memory Available (including virtual): 12.17578125 Mbytes

Show Monitors
Syntax: Show Monitors

Description: The Show Monitors console command reports the amount of memory being used by
monitors.

When system mail rules or headlines are used on a Domino server, the server keeps in memory the list of
databases affected so that when a note is updated, databases which must react to note updates can
quickly be found and the action taken. By default, if the action involves a programmatic check, such as a
system mail rule, the code to perform that check is cached as well. On a server with many monitors, the
memory required to cache the code to perform the monitoring may be so large that normal server
operations are affected.

Show Opendatabases
Syntax: Show Opendatabases

Description: The Show Opendatabases server command displays a list of the open databases on the
server as well as the statistics shown in the example below.

Example: Show Opendatabases

Returns a list of databases in the format shown below:

Database Name Opens|Modi-| File | Sem |Avg Wait|Wait-| Max
|fied |Handles|Waits| (ms) | ers |Waiters
C:\Lotus\Domino\Data\statrep.nsf 1 Y 1 0 0 0 0
C:\Lotus\Domino\Data\events4.nsf 10 N 2 0 0 0 1
C:\Lotus\Domino\Data\mail.box 1 N 1 0 0 0 0
C:\Lotus\Domino\Data\busytime.nsf 1 N 1 0 0 0 0
C:\Lotus\Domino\Data\log.nsf 1 Y 1 0 0 0 0
C:\Lotus\Domino\Data\names.nsf 91 N 16 0 0 0 8

Show Performance
Syntax: Show Performance

Description: Displays the per minute user/transaction values when the Domino Server is running. To
stop showing performance, enter Show Performance a second time.

Show Port
Syntax: Show Port portname

Appendix A Server Commands 1527

Description: Displays traffic and error statistics and the resources used on the network adapter card or
communications port. portname can be any configured port -- for example, LAN0tcpip, SPX, LAN1nb,
LAN2ipx, TCPIP, COM1, or COM2..

Tip: To check port status from the Notes workstation program, choose File - Preferences - Notes
Preferences - Ports. Highlight the port and select Show Status. To check the port status from the Domino
Administrator, click the Server - Status tab, and then click Servers - Port Information. Highlight the port,
and select Show Status.

Example:

Show Port LAN0tcpip -- Displays the status of LAN0tcpip. As information appears, press PAUSE to stop
the scrolling, and press ENTER to resume scrolling. Note that using PAUSE at the console stops server
operation. Users can’t access the server until you resume the display.

Show Schedule
Syntax:

Show Schedule servername/taskname/destination

Show Schedule -argument

Description: Shows the next time that a server task runs. Output includes the type of task and the time it
next runs. If you enter a location as an argument, the workstation replication schedule for that
destination appears.

Arguments:

-Agents -- Shows which agents are scheduled to run next

-DDM -- Shows the Domino Domain Monitoring (DDM) probes that are scheduled to run

-Replication -- Shows the next scheduled replication time and the replication type

-Mailrouting -- Shows the next scheduled mail routing time

-Programs -- Show which programs are scheduled to run

Examples:

Show Schedule -- Displays a list of all scheduled tasks

Show Schedule Fixup -- Shows when the Fixup task is scheduled to run next

Show Schedule -Mailrouting

> sh sched -mail
Scheduled Type Next schedule
CN=Masterlock/OU=Server/O=Web Mail Routing
CN=MServer0/OU=Server/O=Webadmi Mail Routing
xTest1 Mail Routing 08/02/2002 02:00:00 PM

Show SCOS
Syntax: Show SCOS [All]

1528 Lotus Domino Administrator 7 Help

Description: Shows single copy object store (shared mail) information and reloads the shared mail
configuration.

Examples:

SHOW SCOS -- Displays summary information about the configured shared mail directories.

Sample output:
Shared mail: Enabled for delivery and transfer
Directory Availability Requested Actual Max Size
c:\lotus\domino\data\scos1
open for delivery 5 5 2048
c:\lotus\domino\data\shared
open for delivery 3 6 9000
Totals 8 11 11048

SHOW SCOS ALL -- Displays information about each shared mail database within a configured directory,
as well as summary information about each shared mail directory.

Sample output:
Directory: c:\lotus\domino\data\scos1 - open for delivery
Number of delivery databases requested: 5.
Number of databases: 5
Maximum Directory Size: 2048 MB
Database Availability State Size
sm000001.nsf Active Enabled 14.68 MB
sm000002.nsf Active Enabled 0.37 MB
sm000003.nsf Active Enabled 0.37 MB
sm000004.nsf Active Enabled 0.37 MB
sm000005.nsf Active Enabled 14.68 MB
Total Database Disk Size in Directory: 30.50 MB
Total Database Disk Available in Directory: 2017.50 MB
Total Database Internal Free Space for Directory: 0.33 MB

Show Server
Syntax: Show Server

Description: Shows server status information including the server name, data directory on the server,
time elapsed since server startup, transaction statistics, and the status of shared, pending, and dead mail.

Tip: To view server information from the Domino Administrator, open the Domain bookmark in the
bookmark bar on the left, right click on a server, and then choose Server Properties.

Output Description
Server name Name you gave to the server during the setup procedure.
Server directory Directory where the Domino data files are stored.
Elapsed time Days, hours, minutes, and seconds since the server was started.
Transactions Total number of times the server was used since the server started. Transactions include:
opening a database, closing a database, writing to a database, routing mail to a database,
and reading from a database.

Appendix A Server Commands 1529

Output Description
Transactions/minute Total number of transactions on this server in the past minute and the past hour. ″Peak″
is the highest number of transactions per minute since the server started.
Peak # of sessions Maximum number of sessions (users and servers connected at one time) since the server
started.
Pending mail Number of mail documents waiting to be routed to other servers and users.
Dead mail Number of undeliverable mail documents that have been returned to the server. If there
are any dead mail documents, check MAIL.BOX to release them.
Database server The database server performs remote database operations and all client transactions, such
as opening, closing, reading, and writing to Notes databases; performing console
commands; and listening on serial and network ports for user requests to connect to a
specific database.
Replicator The Replicator performs database replication between this server and other servers and
workstations. The Replica task runs the Replicator.
Router The Router routes mail between users on this server and on other servers. The Router
task runs the Router.
Indexer The Indexer builds indexes, or views, of all databases and keeps track of changes to
databases. The Update task runs the Indexer.

Show Stat
Syntax: Show Stat statisticname

Description: Used without the optional statisticname argument, displays a list of server statistics for disk
space, memory, mail, replication, and network activity. To display a single statistic, enter the name of the
statistic as the optional argument. To display only a subset of statistics, add a group of statistics as an
optional argument by using an asterisk (*) as a wildcard.

You can enter this command at the server console to display statistics for the local server or at the remote
server console to display statistics for a remote server.

For more information on statistics, see the chapter ″Monitoring the Domino Server.″

Tip: To view server statistics from the Domino Administrator, click the Server - Statistics tab.

Examples:

Show Stat -- Displays a complete list of statistics

Show Stat Database -- Displays statistics for all statistics of the type Database.x.x

Show Stat Disk.C.* -- Displays all disk statistics for drive C

For a list of statistics, see the Advanced - Names & Messages - Statistic Names view of the Monitoring
Configuration database (EVENTS4.NSF).

Show Stat Platform

Syntax: Show Stat Platform statisticgroup

Description: Used without the optional statisticgroup argument, displays a list of platform statistics for
logical disk, paging file, memory, network activity, processes running, and system activity. To display
only a subset of statistics, add a group of statistics as an optional argument by using one of the qualifiers.
You can enter this command at the server console to display statistics for the local server or at the remote

1530 Lotus Domino Administrator 7 Help

server console to display statistics for a remote server.

Statistic Group Qualifier

Network network
Logical disk logicaldisk
Memory memory
Paging file pagingfile
Platform platform
Process process
System system

For more information on platform statistics, see the chapter ″Monitoring the Domino Server.″

Examples:

Show Stat Platform -- Displays a complete list of platform statistics

Show Stat platform.logicaldisk.* -- Displays all the platform statistics in the logical disk group

To display a single statistic, enter the name of the statistic as the optional argument instead of the
wildcard (*).

For a list of all platform statistics, see the Advanced - Names & Messages - Platform Statistic Names view
of the Monitoring Configuration database (EVENTS4.NSF).

Show Tasks
Syntax: Show Tasks

Description: Displays the tasks on the server, and describes the activity of the task. Idle tasks are
indicated.

Example: Show Tasks displays the task activity or idle, such as the following sample output.
Agent Manager Executive ’1’: Idle
HTTP Server Listen for connect requests on TCP Port:80
SMTP Server Control task
Schedule Manager Idle
LDAP Server Control task
Directory Indexer Idle

Tip: You can also use the Domino Administrator to view a list of active tasks. From the Domino
Administrator, click the Server - Status tab.

Show Transactions
Syntax: Show Transactions

Description: When the Domino Server is running, displays the following for each type of transaction: the
total number of NRPC transactions (Count), the minimal duration of the transaction (Min), the maximum
duration of the transaction (Max), the total time to perform all transactions (Total), and the average time
to perform the transaction (Avg). All times are reported in milliseconds. This command identifies
transactions that require excessive amounts of time.

Appendix A Server Commands 1531

Note For Internet Protocol Servers -- for example, SMTP, POP3, IMAP, HTTP -- use the Show Stat
command to monitor statistics. For example, enter these commands at the server console:
SH STAT SMTP
SH STAT POP3
SH STAT IMAP
SH STAT LDAP
SH STAT Domino (for HTTP Server stats)
SH STAT DIIOP

Example: Show Transactions displays transaction information

Show Trans
Function Count Min Max Total Average
ILLEGAL 600 0 313 2029 3
OPEN_DB 997 0 1410 212142 212
CREATE_DB 200 15 516 15266 76
GET_SPECIAL_NOTE_ID 600 0 562 3684 6
OPEN_NOTE 604 0 781 2710 4
UPDATE_NOTE 59818 0 9280 8501055 142
SET_SPECIAL_NOTE_ID 200 15 328 5825 29
DB_INFO_GET 4 0 16 32 8
DB_MODIFIED_TIME 4 0 0 0 0
DB_REPLINFO_SET 207 0 188 3391 16
DB_REPLINFO_GET 58352 0 1270 62246 1
ALLOC_OBJECT 200 0 391 7172 35
REALLOC_OBJECT 200 0 672 7158 35
READ_OBJECT 600 0 453 1436 2
WRITE_OBJECT 9946 0 1500 274834 27
ALLOC_UPDATE_OBJECT 9359 0 1750 529877 56
FREE_UPDATE_OBJECT 184 0 16 95 0
REMOTE_CONSOLE 3211 500 4000 1620479 504
CLOSE_DB 3 0 31 31 10
CLOSE_COLLECTION 604 0 500 8744 14
OPEN_COLLECTION 605 0 17410 2258889 3733
READ_ENTRIES 3 188 1110 1892 630
NAME_LOOKUP 2 32 47 79 39
NAME_GET_AB 2 0 0 0 0
GET_NAMED_OBJECT_ID 3 0 31 46 15
POLL_DEL_SEQNUM 1 0 0 0 0
SERVER_AVAILABLE_LITE 1 16 16 16 16
START_SERVER 982 15 2500 82666 84
GET_UNREAD_NOTE_TABLE 601 0 1250 143566 238
SET_DBOPTIONS 400 0 609 3448 8
FINDDESIGN_NOTES 600 0 531 1424 2

Show Users
Syntax: Show Users

1532 Lotus Domino Administrator 7 Help

Description: Displays a list of all users who have established sessions with the server, whether the users
are actively working in databases or not, the names of databases that each user has open, and the elapsed
time, in minutes, since the databases were last used.

Tip: You can also use the Domino Administrator to view the status of active users. From the Domino
Administrator, click Server - Status. Then select Database Users. A list of users displays in the middle
panel.

Example:

Show Users -- Displays user information -- for example:

User name Databases open Minutes since last used

Susan Salani MAIL\SSALANI.NSF 6
Alan Jones NAMES.NSF 4
Derek Malone MAIL\DMALONE.NSF 11

Show Xdir
Syntax: Show Xdir

Description: Provides information about each directory a server last used for name resolution. The
output displays the following columns of information.

DomainName The DomainName columns displays the name of the domain in which a directory resides.
If a directory is configured in the directory assistance database, the ″Domain Name″ field in the Directory
Assistance document for the directory determines the directory’s domain name.

DirectoryType

The DirectoryType column shows the type of directory. A directory can be one of these types:
v Primary -- Primary Domino Directory stored locally
v Configuration -- Configuration Directory stored locally
v Remote Primary -- Primary Domino Directory stored remotely used by a server with a Configuration
Directory
v Secondary -- Extended Directory Catalog, secondary Domino Directory, or remote LDAP directory
configured in the directory assistance database.

The DirectoryType column also shows the type of domain a directory is within (Notes or LDAP). If a
directory is a remote LDAP directory configured in the directory assistance database, the directory type is
″LDAP.″ Any Domino Directory or Extended Directory Catalog is the directory type ″Notes.″

ClientProtocol

The ClientProtocol column displays the client protocol, Notes and/or LDAP, for which the directory is
enabled. For a directory configured in a directory assistance database, the value of the ″Make this domain
available to″ field in the Directory Assistance document for the directory determines what appears in this
column.

This column always shows ″Notes″ for a Configuration Directory. Usually a Primary or Remote Primary
directory show ″Notes & LDAP″ as the client protocols. An exception is if the primary directory is
configured through directory assistance and is disabled for LDAP clients; in this case only ″Notes″ shows
as the enabled client protocol.

Appendix A Server Commands 1533

Replica/LDAP Server

The Replica/LDAP Server column shows:

v The file name of a local Domino Directory
v Server path and file name of a Domino Directory accessed over the network
v The host name of a remote LDAP directory server and the port used

Note: If a server uses a condensed Directory Catalog, Show Xdir also displays the text ″Directory Catalog
’filename″ in use,″ where filename is the file name of the local directory catalog.

Start Consolelog
Syntax: Start Consolelog

Description: Enables output to the console log file.

Example:

Start Consolelog

The Start Consolelog and the Stop Consolelog server commands enable and disable console logging just
as the NOTES.INI variable CONSOLE_LOG_ENABLED does. The difference between the server console
commands and the NOTES.INI settings is that the console commands are in effect for the current server
session only, whereas the NOTES.INI settings are ″permanent″ and take effect each time the server is
started.

For more information on CONSOLE_LOG_ENABLED, see the appendix ″NOTES.INI File.″

1534 Lotus Domino Administrator 7 Help

Start Port
Syntax: Start Port portname

Description: Enables transactions (or messages) on the specified port. Use this command after you
disable the port with the Stop Port command.

Example:

Start Port TCP -- Enables the port named TCP.

Stop Consolelog
Syntax: Stop Consolelog

Description: Disables output to the console log file.

Example:

Stop Consolelog

The Start Consolelog and the Stop Consolelog server commands enable and disable console logging just
as the NOTES.INI variable CONSOLE_LOG_ENABLED does. The difference between the server console
commands and the NOTES.INI settings is that the console commands are in effect for the current server
session only, whereas the NOTES.INI settings are ″permanent″ and take effect each time the server is
started.

For more information on CONSOLE_LOG_ENABLED, see the appendix ″NOTES.INI File.″

Stop Port
Syntax: Stop Port portname

Description: Disables transactions (or messages) on the specified port. This command allows you to make
changes to the port that take effect immediately without stopping the Domino server. When you’re
finished making changes to the port, use the Start Port command to re-enable it. To see a list of ports you
can disable, issue the console command Show Configuration.

Example:

Stop Port TCP -- Disables the port named TCP.

Sucache refresh
Syntax: Sucache refresh

Description: Forces a dynamic reloading of the Smart Upgrade configuration information, displays the
state of the Domino server’s Smart Upgrade cache information, and displays Smart Upgrade statistics
gathered when the Domino server was restarted. For example, the following is an example of the output
that is generated by the sucache refresh command:
Server.SmartUpgrade.Database = smupdate.nsf
Server.SmartUpgrade.Database.ReplicaID = 006D4604:85256B83
Server.SmartUpgrade.Governor = Enabled
Server.SmartUpgrade.Users.Allowed = 3
Server.SmartUpgrade.Users.Current = 0
Server.SmartUpgrade.Users.Maximum = 10
Server.SmartUpgrade.Users.Peak = 1

Appendix A Server Commands 1535

Server.SmartUpgrade.Users.Rejected = 0
8 statistics found

The Server.SmartUpgrade.Users.Maximum =10 value is the maximum concurrent number of Smart

Upgrade attempts that are allowed when the Smart Upgrade Governor is enabled based on the Domino
server’s configuration.

The Server.SmartUpgrade.Users.Rejected is the number of Smart Upgrade attempts that were rejected on
this Domino server because the server was already at the maximum concurrent number allowed in the
configuration.

Sucache show
Syntax: Sucache show

Description: Displays the current state of the Domino server’s Smart Upgrade cache as well as some
statistics gathered since the Domino server was restarted. For example, the following is an example of the
output that is generated by the sucache show command:
Server.SmartUpgrade.Database = smupdate.nsf
Server.SmartUpgrade.Database.ReplicaID = 006D4604:85256B83
Server.SmartUpgrade.Governor = Not Enabled
Server.SmartUpgrade.Users.Allowed = 3
Server.SmartUpgrade.Users.Current = 0
Server.SmartUpgrade.Users.Peak = 1
6 statistics found

Server.SmartUpgrade.Users.Allowed = 3 statistic indicates the number of Smart Upgrade attempts that

have been allowed on the server since the Domino server was started.

Server.SmartUpgrade.Users.Current = 0 statistic indicates there are no outstanding Smart Upgrade

attempts in progress.

Server.SmartUpgrade.Users.Peak = 1 statistic indicates the peak number of concurrent Smart Upgrade

attempts that occurred at any given time since the Domino server was started

Tell
Syntax: Tell serverprogram

Description: Issues a command to a server program or task. The command is especially useful for
stopping a server task without stopping the server.

Note: Most server commands support the arguments ″-?″ and ″/?″ to display online help. For example,
you could enter one of these to obtain help for the server command Tell Amgr:
Tell Amgr -?
Tell Amgr /?

Example:

Tell Router Quit -- Stops only the Router task. All other tasks on the server continue to run.

Specialized Tell commands

Some Tell commands are common to all server tasks -- for example, Tell task Quit. Other Tell commands
are unique to a particular task. These tasks have unique Tell commands:
v Administration Process

1536 Lotus Domino Administrator 7 Help

v Agent Manager
v Certificate Authority Process
v Change Manager
v Cluster Replicator
v DIIOP
v Directory Cataloger
v LDAP
v Router
v Schedule Manager
v SMTP Server
v Statistic Collector
v Web Navigator
v Web Server
For more information on these Tell commands, see the appropriate sections below.

To enter a Tell command from the Domino Administrator

You can enter a Tell command directly from the Server - Status tab in the Domino Administrator.
1. From the Domino Administrator, click the Server - Status tab.
2. Select a task in the top pane.
3. If necessary, click Tools to display the tool bar, and then click Task - Tell.
4. Select the options you want and click OK.
5. (Optional) Click Console to see the response to the Tell command.

To stop a task from the Domino Administrator

You can stop a server task from the Domino Administrator. This is the same as using the Tell command
to quit a task.
1. From the Domino Administrator, click the Server - Status tab.
2. Select the task(s) you want to stop from the top pane of the Server - Status tab.
3. If necessary, click Tools to display the tool bar, and then click Task - Quit.

Administration Process Tell Commands

This table describes additional Tell commands you can use with the Administration Process.

Command Result
Tell Adminp Process All Processes all new and modified immediate, interval, daily, and delayed
requests.

This command doesn’t override timed requests execution time.

Tell Adminp Process Daily
Tell Adminp Process Delayed
Tell Adminp Process Interval
Tell Adminp Process New
Processes these requests:
v All new and modified daily requests to update Person documents in the
Domino Directory.
v Any outstanding ″Rename Person in Unread List″ requests.
Processes all new and modified delayed requests. These are requests that are
usually carried out according to the ″Start executing on″ and ″Start executing
at″ settings in the Server document.
Processes all immediate requests and all requests that are usually processed
according to the Interval setting in the Server document.
Processes all new requests.

Appendix A Server Commands 1537

Command
Tell Adminp Process People
Tell Adminp Process Time
Tell Adminp Show Databases
Tell Adminp Quit
Result
Processes all new and modified requests to update Person documents in the
Domino Directory.
Processes all new and modified requests to delete unlinked mail files.
Displays (and records in the server’s log file) this information:
v The databases that a particular administration server updates
v The locations in the database where it updates Reader and Author fields
in the databases it updates
v The databases that don’t have an administration server assigned to them
Stops the Administration Process on a server.

Agent Manager Tell commands

Command Result
Tell Amgr Cancel Cancels the scheduled agent that is currently running. Specify the agent to be canceled
by entering these arguments:

″db name″ ’agent name’

Example: Tell Amgr Cancel ″DatabaseName.nsf″ ’AgentName’

Note: You can use the Tell Amgr Schedule command to determine which agents can be
canceled.
Tell Amgr Debug Displays either the current debug settings for the Agent Manager or lets you set new
ones. When using this command to set debug values, you can use the same flags used
by the Debug_AMgr command in the NOTES.INI file. These settings take effect
immediately; you do not need to restart the Agent Manager or the server.

The following are Tell Amgr Debug parameters:

v c -- To output agent control parameters
v e -- To output information about Agent Manager events
v l -- To output loading reports
v m -- To output agent memory warnings
v p -- To output agent performance statistics
v r -- To output agent execution reports
v s -- To output information bout AMGR scheduling
v v -- Verbose mode, outputs more messages regarding agent loading, scheduling and
queues
v * -- To output all of the above information
Tell Amgr Run Runs the agents that you designate with these arguments:

″db name″ ’agent name’

Example: Tell Amgr Run ″DatabaseName.nsf″ ’AgentName’

Tell Amgr Pause Pauses scheduling of agents
Tell Amgr Quit Stops the Agent Manager on a server.
Tell Amgr Resume Resumes scheduling of agents.

1538 Lotus Domino Administrator 7 Help

Command Result
Tell Amgr Schedule Shows the schedule for all agents scheduled to run for the current day. In addition, the
command shows the agent trigger type, the time the agent is scheduled to run, the
name of the agent, and the name of the database on which the database runs. Checking
the Agent Manager schedule lets you see if an agent is waiting in one of the Agent
Manager queues.

Agent Manager queues:

E - Agents eligible to run

S - Agents scheduled to run

V - Event-triggered agents waiting for their events to occur

Trigger types:

S - Agent is scheduled to run

M - Agent is a new mail-triggered agent

U - Agent is a new/updated document-triggered agent

Tell Amgr Status This command shows a snapshot of the Agent Manager queues and displays the Agent
Manager settings in the Server document.

Certificate Authority process tell commands

This table describes additional Tell commands you can use with the Domino CA process.

Command Result
tell ca quit Stops CA process.
tell ca stat Displays summary information for the certifiers using the CA process; this includes the
certifier’s number, its hierarchical name, certifier type (Notes or Internet), whether it is
active, and name of the ICL database.
tell ca show queue Display a list of pending certificate requests, revocation requests, and configuration
certifier number modification requests for a specific certifier, using its number from the results of the ″tell ca
status″ command. You can also use * to show this information for all certifiers that are
using the CA process.
tell ca activate certifier Activate a certifier if the certifier is created with ″Require password to activate certifier,″ or
number password use this for any certifier that has been deactivated. Activation is enabled during CA setup
and creation. Activate a specific certifier by entering its number from the results of the ’tell
ca status’ command. Or you can actually unlock all server ID/password-protected certifiers
at one time with this command, if you specify ″*″ for the certifier number. The CA process
then prompts you for the password for each certifier.
tell ca deactivate Deactivate a certifier. You will need to activate it again in order for it to process any
certifier number request. Use * to deactivate everything, or deactivate a specific certifier by entering its
number from the results of the ’tell ca status’ command.
tell ca lock idfile Lock all certifiers that were set up with a lock ID, as specified during CA setup.
tell ca unlock idfile Unlock all certifiers using the ID and password that comprise the lock ID. The lock ID is
password specified during CA setup.
tell ca CRL issue Issue a non-regular (immediate) CRL for a specific certifier, where certifier number is the
certifier number number of the certifier specified in the results of the ″tell ca status″ command.
tell ca CRL push Push a certifier’s latest regularly scheduled CRL to the Domino Directory, where certifier
certifier number number is the number of the certifier specified in the results of the ″tell ca status″
command.

Appendix A Server Commands 1539

Command Result
tell ca CRL info Display CRL information for a specified certifier, where certifier number is the number of
certifier number the certifier specified by the ’tell ca status’ command. Use s or S for regularly scheduled
[s/S/n/N] CRLs, and n or N for non-regularly scheduled (immediate) CRLs.
tell ca refresh Force the CA process to refresh its list of certifiers. As a result:
v newly configured certifiers will be added to the CA process
v previously unlocked certifiers will need to be unlocked again
v previously activated certifiers may need to be activated again, if the activation password
has changed
v the Notes certifier ID file in idstorage will be updated with the latest certificate
information
tell ca help List tell ca options

Change Manager tell commands

You can use the Tell Change Man command at the console to control the Domino Change Manager. The
following options are available.

Option Action
quit Stops the Change Manager and all plug-ins.
stop Stops the Change Manager and all plug-ins. Same as Quit.
exit Stops the Change Manager and all plug-ins. Same as Quit.
help Refers you to documentation.
? Refers you to documentation. Same as Help.
restart Stops and then restarts the Change Manager and all plug-in subsystems.
start plug-in Starts the plug-in. Currently, Control and Monitor are the defined plug-ins.
stop plug-in Stops the plug-in. Currently, Control and Monitor are the defined plug-ins.
Note: Alternatively, you can also use the forms plug-in stop, plug-in quit and
plug-in kill.
restart plug-in Stops and then starts the plug-in. Currently, Control and Monitor 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.
control process Requests the ″PlanControl″ (control) plug-in to process and check all plans.

Cluster Replicator Tell commands

Command Result
Tell Clrepl Log Records information in the server log (LOG.NSF) immediately, instead of waiting for the
next log interval.

The log includes information about all cluster replications waiting for retry. Use this
command when the Replica.Cluster.Retry.Waiting statistic is non-zero, indicating that some
replications could not be completed and are awaiting a retry.

After you correct the errors -- for example, by restarting the server that was unavailable --
the Cluster Replicator will succeed on its next retry and the Replica.Cluster.Retry.Waiting
statistic will return to zero.

1540 Lotus Domino Administrator 7 Help

Command Result
Tell Clrepl Quit Stops all instances of the Cluster Replicator on a server.

Disabling the Clrepl task on one server only prevents replication from that server to other
servers; it doesn’t prevent replication to the server from other cluster servers.

DIIOP Tell commands

This table describes additional Tell commands you can use with Domino IIOP.

Command
Tell DIIOP Dump Config
Tell DIIOP Show Config
Tell DIIOP Log=n
Result
Provide a list of the configuration data that DIIOP is using from the Domino
Directory. Using dump the configuration is written to the file diiopcfg.txt in the
server’s data directory.
Provide a list of the configuration data that DIIOP is using from the Domino
Directory. Using show the configuration is displayed on the server console.
This command determines the amount of information the DIIOP will log about it’s
operation. Valid values for n are as follows:

0 Show Errors & Warnings only

1 Also show informational messages

2 Also show session init/term messages

3 Also show session statistics

4 Also show transaction messages

Tell DIIOP Refresh
The setting of this command is saved in the NOTES.INI variable DIIOPLogLevel. Any
change that is made to the DIIOP log level will be used the next time the server is
restarted.
Use this command to reload the configuration data that DIIOP is using from the
Domino Directory and from notes.ini. By default DIIOP incorporates changes from the
Domino Directory every 3 minutes or as often as specified in the NOTES.INI
parameter:

DIIOPConfigUpdateInterval

Tell DIIOP Show Users
Or
Tell DIIOP Show Users D
The Refresh command will force DIIOP to look for changes in the configuration and
apply them immediately.
Show all the current active users known to the DIIOP task. This list is similar to the
server console command ″show tasks″ but it includes more information. Appending
″D″ to this tell command the list of current users will also include the databases the
user has open and along with a count of objects that are in use.
Example:

tell diiop show users d

UserName ClientHost IdleTime ConnectTime SessionId

Anonymous 9.95.74.178 0:00 0:00 SN00048DE22

perf/user1.nsf

Objects in use: Databases: 1 Views: 0 Documents:0 Items: 0 Others: 0

Users: 1, Network Connections: 1

Appendix A Server Commands 1541

Directory Cataloger Tell commands
This table describes additional Tell commands you can use with the Directory Cataloger (Dircat task).

Command Result
Tell Dircat Pause The Dircat task finishes aggregating the directory catalog it is currently processing, and
then goes idle. Use this command before shutting down a server that is in the middle of
Dircat processing.
Tell Dircat Resume Resumes a Dircat task that is paused.

LDAP Tell commands

This table describes additional Tell commands you can use with the LDAP server task.

Command Result
Tell LDAP Quit Stops the LDAP task on a server.
Tell LDAP ReloadSchema When run on the Domino Directory administration server, the schema daemon
updates the LDAP service in-memory schema with any new schema changes
defined with Domino Directory forms or with the Domino LDAP Schema
database. The schema daemon then publishes the updated schema into the
Schema database, and then replicates the Schema database to others servers in
the domain that run the LDAP service.

Tell LDAP Showconfig
Tell LDAP Showconfig Debug
Tell LDAP VerifyDIT
When run on a subordinate server in the domain that runs the LDAP service,
the schema daemon replicates the Schema database from the administration
server, if it detects changes on the administration server replica. The schema
daemon then loads the updated schema now published in its local Schema
database into memory.
Shows:
v LDAP service settings from the LDAP tab of the Configuration Settings
document.
v LDAP service port settings
v Status of LDAP Activity Logging (enabled or disabled.)
Shows current NOTES.INI settings related to the LDAP service, as well as the
information shown by Tell LDAP Showconfig.
Verifies that each component of a distinguished name in a directory that is
visible through Notes has an entry in the directory that represents the
component as an object class. If the LDAP service finds a component of a
distinguished name without a corresponding object class entry, it creates an
appropriate entry for the object class in the hidden view ($LDAPRDNHIER).
Creating such entries ensures that LDAP clients can successfully use an object
class in a search filter to search for any entry in the directory.

Also purges duplicate entries in the directory.

Runs on any primary, central, or secondary Domino Directory or Extended

Server Directory Catalog for which the server running the LDAP service is the
administration server.

Router Tell commands

The table below describes other Tell commands you can use with the Router task.

Command Result
Tell Router Delivery Stats Shows Router delivery statistics.

1542 Lotus Domino Administrator 7 Help

Command
Tell Router Compact
Tell Router Show Queues
Tell Router Exit
Tell Router Update Config
Tell Router Quit
Schedule Manager Tell commands
This table describes additional Tell commands you can use with Schedule Manager.
Command
Tell Sched Stats
Tell Sched Show username
Tell Sched Validate
Result
Compacts MAIL.BOX and cleans up open Router queues. You can use
this command to compact MAIL.BOX at any time. If more than one
MAIL.BOX is configured for the server, each MAIL.BOX database will be
compacted in sequence.
By default, MAIL.BOX is automatically compacted at 4 AM.
Shows mail held in transfer queues to specific servers and mail held in
the local delivery queue.
Stops the Router task on a server.
Updates the server’s routing tables to immediately modify how messages
are routed. This removes the 5 minute delay before a Router
configuration change takes effect.
To determine the best route for delivering a message to its destination,
the Router creates routing tables, which map a path to the destination.
The routing table derives information from variables in the NOTES.INI
file and from the Configuration Settings, Domain, Connection, and Server
documents in the Domino Directory. The command does not update the
routing tables with changes made to the Global Domain document.
By default, mail the router automatically refreshes its configuration every
5 minutes to absorb changes made in its sources. In previous versions of
Domino, you had to restart the router task to update the routing tables
after making changes in the sources documents.
The command is case insensitive.
CAUTION:
If the Tell Router Update Config command is initiated on an R5 server,
it loads shared mail. The Tell Router U portion of the command loads
shared mail on R5 servers.
Stops the Router task on a server.
Result
Displays totals of reservations and appointments in the free time database.
Displays the specified user’s schedule on the server console. Use this
command to investigate problems in the free time database.
Immediately validates a free time database on a server.
Validation occurs by default at 2 AM; however, you can use this command to
force it to occur sooner. Another way to force validation is to stop and restart
the Schedule Manager.
Validation can take some time. You must issue this command at all servers
where mail files have been removed and/or added to ensure that old free
time information is removed and new free time information is added to the
free time database on the server.
Don’t use this command when you add a new user. The Administration
process creates Person documents for users in the Domino Directory before
creating their mail file on their mail server. Schedule Manager watches for
database creations and automatically picks up new users’ mail files.
Appendix A Server Commands 1543
Command Result
Tell Sched Validate username Validates the information for the specified user.

This command is faster than using the Tell Sched Validate command because
it allows you to validate individual users, rather than validating all of the
data on a server.
Tell Sched Quit Stops the Schedule Manager task on a server.

SMTP Server Tell commands

This table describes additional Tell commands you can use with SMTP Server.

Command Result
Tell SMTP Update Config By default, whenever you restart the SMTP service, and
at two-minute intervals thereafter, the SMTP service
automatically checks the NOTES.INI file, Configuration
Settings document, and Server document to see if any
settings have changes. If the service detects that settings
have changed, it rebuilds its internal configuration to
incorporate the changes.

The ″Tell SMTP Update Config″ server console command

will manually trigger such a service update. Using the
console command allows Administrators to immediately
put into effect changes to the SMTP configuration
without disrupting normal service operation.

Statistic Collector Tell Commands

Command Result
Tell Collector Collect Runs a statistic collection on all the servers specified and generates statistic
reports.
Tell Collector Quit Stops the Collect task on a server.

Web Navigator Tell commands

This table describes additional Tell commands you can use with the Web Navigator.

Command Result
Tell Web Help Lists all the Web Navigator server console commands.
Tell Web Refresh Refreshes all the Web Navigator global settings. Use this command if you edit the
Administration document while the Web server task is running.
Tell Web Quit Stops all running copies of the Web Navigator.

Web Server Tell commands

Command Result
Tell HTTP Dump Config Dumps the HTTP configuration to a text file so that you can see how the
server is configured.

1544 Lotus Domino Administrator 7 Help

Command
Tell HTTP Refresh
Tell HTTP Restart
Tell HTTP Show File Access
Tell HTTP Show Security
Tell HTTP Show Users
Tell HTTP Show Virtual Servers
Tell HTTP Quit
Trace
Syntax: Trace servername
Description: Use the Trace command to test a connection to a server. This command shows detailed
information about each server hop and is useful in troubleshooting network connection problems. This
command works the same way as ″Trace connections,″ when you choose File - Preferences - Notes
Preferences in the Notes client.
Result
Refreshes the Web Server before the normal refresh. You can specify the refresh
cycle interval in the Server document.
During a Web Server refresh cycle, all of the configuration information
contained in the Web Site documents, and documents attached to Web Site
documents (file protection, authentication realms, and rules) is updated on the
server.
Refreshes the Web server with changes made to settings in the:
v Server document for the Web Server
v File Protection, Virtual Server, and URL Mapping documents in the Domino
Directory.
v NOTES.INI file that affects the HTTP server task
v HTTPD.CNF and BROWSER.CNF files
v Changes to Java servlets or the servlets.properties file
This command produces the same results as stopping and restarting the Web
Server. However, this Tell command is faster than stopping and restarting
because when you use the Tell command, the HTTP server task remains in
memory. All outstanding HTTP requests are processed before the HTTP task
restarts, however no HTTP requests are processed during restart.
This command deletes the in-memory page and user-authentication caches.
Displays information about file system protection on the machine, and on
virtual servers, if you set up virtual servers on the machine.
Displays information about SSL and the server key ring file, including
information about whether the server started SSL on the machine. Displays
information about SSL for virtual servers if you set up virtual servers on the
machine.
Displays the names of users, their IP addresses, and the session expiration time
for users authenticated with session-based authentication.
Servers participating in single sign-on, configured for multi-server
session-based authentication may not report sessions accurately using this
command.
If the authentication cookie originates from the current server, displays the
user name, IP address, and session expiration time for that web server. If the
authentication cookie does not originate on the current server, does not display
session information for users.
After a user logs out, this command continues to display the cookie as valid on
the server. The session is still valid even though the user has ended the
session.
Displays a list of virtual servers running on the machine.
Stops the Web Server task.
Appendix A Server Commands 1545
To trace a path to a server, enter:
Trace servername

To trace a specific port, enter:

Trace portname !!! servername

When you attempt to connect to a server, network trace information automatically appears on the status
bar of a Notes workstation or on the server console, depending on where you initiated the connection
attempt. You can use the NOTES.INI Console_LogLevel setting to control the level of detail that messages
on the status bar contain. Trace information is recorded in the log file (LOG.NSF).

For more information on tracing connections, see the chapter ″Setting up Server-to-Server Connections.″
For more information on the Console_LogLevel setting, see the appendix ″NOTES.INI File.″

Domino and DB2 server commands

This list briefly describes the Domino server commands that are available.

Server Command Description

DB2 Access Runs the DB2 Access server tool and initiates the action
indicated by the argument that is used with it.
DB2 Catalog Displays a list of entries in the Domino server’s
CATALOG table. The listed entries reflect the argument
used with the DB2 Catalog command. For example, DB2
Catalog Active lists all entries that have not been marked
for deletion.
DB2 Group Runs the DB2 Group tool and performs the action
associated with the argument.
DB2 Group Info Provides group detail information, such as the class that
a DB2 group is associated with, DB2 group names, group
size, lock/unlock status, path, and size of each DB2
enabled Notes database in the DB2 group.
DB2 Info Provides detail information about the Domino and DB2
configuration.
DB2 Purge Runs at startup, then every 24 hours. This command
forces the purge task to run immediately.
DB2 Reconnect Reconnects the database to DB2.

DB2 Access
Syntax
DB2 Access Remove

DB2 Access Set

DB2 Access Test

Description
Runs the DB2 Access server tool and initiates the action indicated by the argument that is used with it.

1546 Lotus Domino Administrator 7 Help

Arguments
Set -- Sets DB2 access for the Domino server. Sets up the DB2 functions to administer the DB2 Access
server. Run this tool after installing the DB2 Access server or when you change something in your DB2
configuration, particularly the DB2 Access server name or the location of the Domino server.

Test -- Tests the DB2 Access server’s field parameters in the Server document and all DB2 Access server
settings from the NOTES.INI file. If all fields and settings are correct, it tests the connection between the
DB2 Access server and the Domino server, verifies whether the DB2 functions and properties exist,
determines whether the DB2 Access server Connection document is valid, and attempts to open the
Domino Directory on the DB2 Access Server. If the DB2 Access Test tool locates any problems, the
information is returned to the Domino server console or to the Domino Administrator client.

Remove -- Disables the DB2 Access server from a DB2 server. The DB2 Access Remove command
removes the following:
v DB2 Access Views
v DB2 Access server name from the DB2 tab of the Domino server’s Server document
v DB2 Access settings from the Domino server’s NOTES.INI file.

DB2 Catalog
Syntax
DB2 catalog active

DB2 catalog deleted

DB2 catalog filepath

Description
The DB2 Catalog console command displays a list of entries in the Domino server’s CATALOG table. The
entries that are listed reflect the argument used with the DB2 Catalog command. For example, DB2
Catalog Active lists all entries that have not been marked for deletion.

Arguments
Active -- Lists all entities that have not been marked for deletion.

Deleted -- Lists all deleted entities in the Domino server’s CATALOG table.

Filepath (relative to data directory file path) -- Displays DB2 entity information for the specified DB2
enabled Notes database. The DB2 enabled Notes database must be an active database, that is, it cannot be
marked for deletion.

DB2 Group
Syntax
DB2 Group

DB2 group move <source NSF> [Destination group] [-xml]

DB2 group renameclass <Old Class Name> <New Class Name>. [-xml]

DB2 group setclass <Group Name> <Class Name> [-xml]

DB2 group setstate <Group Name> <LOCK/OPEN> [-xml]

DB2 group info

Appendix A Server Commands 1547

Description
The DB2 Group command runs the DB2 Group tool and performs the action associated with the
argument.

Arguments
Move -- The database will be copied to the specified group. Supply the selected DB2 enabled Notes
database name and destination group. To copy a database to a new DB2 group, enter the DB2 enabled
Notes database name only, without a destination group name. The status will be returned as to the status
of the posting of the move.

Renameclass -- Renames the class name to the desired text. All groups associated with an old class name
are associated with the new class name. The maximum class name size is 32 bytes.

Setclass -- Sets the class name to the desired text. The maximum class name size is 32 bytes.

Setstate -- Locks or unlocks a DB2 group that is not yet associated with its maximum number of
DB2-enabled Notes databases. Groups that are associated with the maximum number of DB2-enabled
Notes databases, are locked automatically and cannot be unlocked.

Examples
DB2 group move test.nsf Grp00002

Test.nsf was successfully moved to GRP00002

DB2 GROUP RENAMECLASS

The class was renamed to by User/Westford

DB2 GROUP SETCLASS GRP00002 Mail Files

The class for GRP00002 was set to ’Mail Files’ by User/Westford

DB2 GROUP SETSTATE GRP00002 LOCK

GRP00002 is locked

DB2 Group Info

Syntax

DB2 group inof

Description

The DB2 group information command provides detail, such as the class that a DB2 group is associated
with, DB2 group names, group size, lock/unlock status, path, and size of each DB2 enabled Notes
database in the DB2 group.

Examples

CLASS Marketing Mail

GROUP GROUP SIZE STATUS PATH NSF SIZE TITLE

GRP00001 654321 bytes Locked
mail\mail1.nsf 50832 bytes DBTitle1
mail\mail2.nsf 50832 bytes DBTitle2
mail\mail3.nsf 50832 bytes DBTitle3

1548 Lotus Domino Administrator 7 Help

GROUP GROUP SIZE STATUS PATH NSF SIZE TITLE
mail\mail4.nsf 50832 bytes DBTitle4
mail\mail5.nsf 50832 bytes DBTitle5
mail\mail6.nsf 50832 bytes DBTitle6
mail\mail7.nsf 50832 bytes DBTitle7
mail\mail8.nsf 50832 bytes DBTitle8
mail\mail9.nsf 50832 bytes DBTitle9
mail\mail10.nsf 50832 bytes DBTitle10

GROUP GROUP SIZE STATUS PATH NSF SIZE TITLE

GRP00002 498765 bytes Open
mail\mail11.nsf 50832 bytes DBTitle1
mail\mail12.nsf 50832 bytes DBTitle2
mail\mail13.nsf 50832 bytes DBTitle3
mail\mail14.nsf 50832 bytes DBTitle4

CLASS Support

GROUP GROUP SIZE STATUS PATH NSF SIZE TITLE

GRP00003 394561 bytes Locked
support\spr.nsf 50832 bytes Notes SPR System

DB2 Info
Syntax

DB2 info

Description

Provides detail information about the Domino and DB2 configuration.

Example

For example, if you enter the DB2 INFO command from an AIX configuration, the output from the
command would resemble this sample output:
DB2 Server: Enabled
DB2 Server: Connected
DB2 Server Name: serverone.ibm.com
DB2 Port Number: 50000
DB2 Directory:
DB2 Instance: aixnode
DB2 Database: DOMINO
DB2 Schema: DOMINO
Schema Version: 14
DB2 Access Server: humacc
DB2 Access Path: /local1/domudf

Appendix A Server Commands 1549

Default Datastore: 2
DB2 Purge Interval: 60 Day(s)
Connections: 4

The DB2 INFO command produces a list containing the following information:

Name Description Values Source

DB2 Server Is this server enabled for DB2 storage? Enabled Server document

Not Enabled
DB2 Server The DB2 server’s name or IP address. Local Server document

Host name
DB2 Port Number Number specific to the remote DB2 Port number Server document
server.
Blank
DB2 instance Instance name used by Domino Varies Server document
DB2 Node Name Node name used by Domino to access Varies Server document
DB2 on a remote DB2 server
DB2 Database DB2 database where Domino databases Varies Server document
are stored
DB2 Directory Where DB2 creates data related to DB2 Varies Server document
tables used to store Domino databases
DB2 Schema Version DB2 schema version used when Varies Server document
creating or upgrading Domino system
tables in DB2.
Default Domino Default storage type for Domino DB2 Server document
Database Storage databases.
Type NSF
DB2 Access Server Used to store Domino Access tables for Varies Server document
Name access by DB2 applications.
DB2 Access Server Path used to store Access Server files. Varies Server document
path
DB2 Code Page DB2 database code page. Varies Server document
DB2 Locale Db2 database locale. Varies Server document
Connected to DB2 Whether or not Domino is connected to Yes Domino/DB2 Run-time
a DB2 server.
No
Connect Pool Count Domino’s DB2 (XA) transaction pool Varies Domino Run-time
count.
DB2 Service Status List of DB2 services and whether they Operating System
have been started.
(Local configuration only.)

DB2 Purge
Syntax

DB2 Purge <schemaName>

Description

1550 Lotus Domino Administrator 7 Help

The Domino server’s DB2 purge task runs at startup, then every 24 hours. This command forces the
purge task to run immediately.

schemaName -- The schemaName argument forces all DB2 entities associated with schemaName to be
purged. The purge is immediate.

Note: This will only work if the DB2 enabled Notes database using schemaName had been marked for
deletion (see DB2 CATALOG DELETED).

DB2 Reconnect
Syntax
DB2 reconnect

Description
Reconnects the database to DB2.

Using a console to send commands to a server

Use a server console to see server events as they happen and to send commands to a server. Server
events are also logged to a server’s log file (LOG.NSF). You can view the log file from the Server -
Analysis tab in the Domino Administrator.

For more information on the log file, see the chapter ″Using Log Files.″

There is a server console available directly at a server. There are also remote consoles available through
the Domino Administrator and the Web Administrator. The types of commands you can send to a server
using a remote console depends on the level of administrator access you have in the Server document.

For more information on restricting administrator access to a server, see the chapter ″Controlling Access
to Domino Servers.″ For information on setting console attributes for a remote console, see the chapter
″Monitoring the Domino Server.″

Some tabs in the Domino Administrator and Web Administrator automatically display information you
would normally see as the result of entering a server command at a console. For example, when you click
the Server - Status tab, and click Server Tasks you see the equivalent of the Show Tasks command. In
addition, several tabs have tool bars that let you enter a command via a dialog box. For example, you can
enter Tell commands from the tool bar on the Server - Status tab.

Capturing server command output in a file

Certain server commands display information that you might want to capture in a file. Type the server
command and on the same line, type a space and then the following:
> filename.ext

where filename.ext is the name of the file to which you want to save output. Enter a space after the server
command but not after the redirection symbol (>). For example, this command writes the output of the
Show Tasks command to the file TASKS.OUT in the Notes directory:
Show Tasks > TASKS.OUT

To store output in a file outside the data directory, specify the complete path to the file.

Entering commands at the console at the server

You can enter commands directly at the console at a server. If a server is running under a Controller, you
must use a remote console instead.

Appendix A Server Commands 1551

Note: Most server commands support the arguments ″-?″ and ″/?″ to display online help. For example,
you could enter one of these to obtain help for the server command Tell Amgr:
Tell Amgr -?
Tell Amgr /?
1. Double-click the Domino server icon if the server isn’t running, or switch to the console.

Note: On a UNIX server, log into the server account, change to the server’s Notes directory, and enter
server.
2. Press ENTER to display the console prompt (>).
3. Enter a server command.
If a command parameter contains a space, enclose it in quotation marks -- for example:
Pull "Acme Server"

Tip: To save time and space at the command line, enter the abbreviation for the server command. You
can also press the Up arrow to display a command that you previously entered.
4. (Optional) Use these key combinations, as necessary:
v Press CTRL+Q or PAUSE to stop the screen display and suspend access to the server and events in
process.
v Press CTRL+R to resume display and access to the server.
v Press CTRL+R (or ENTER) to restore a command line. For example, you might restore a command
line if an on-screen event splits it or if it disappears while you’re typing.

Sending Controller and shell commands from a remote console

A server can run under a Java-based Controller -- you start the server by starting the Controller. You can
use remote consoles in the Domino Administrator or Web Administrator to send commands to a server
that runs under a Controller. You can send Controller commands and shell (operating system) commands,
as well as Domino server commands. There is also a Java-based remote console available called the
Domino Console that you can use to connect to a Controller.

For information on the Server Controller and Domino Console, see the chapter ″Setting Up and Using
Domino Administration Tools.″

To send a shell command to a Controller from a remote console, use the prefix $, for example:
$Dir c:\tmp

To send a Controller command, use the prefix #, for example:

#Start Domino

If you are sending several shell or Controller commands, you can change to Shell or Controller command
mode in a remote console by entering the appropriate prefix in the Command box and pressing enter.
Then you do not have to specify the prefix each time you send a command. To exit the specified
command mode, enter the prefix again.

For example, to enter the Controller command mode, enter # in the Command box. When you are done
sending Controller commands, enter # again to exit Controller command mode.

The following table describes the available Controller commands.

Controller command Description

Broadcast message Broadcasts a specified message to all administrators connected
to the Controller

1552 Lotus Domino Administrator 7 Help

Controller command Description
Disable username(s) Disables a specified administrator’s connection to the
Controller. Connection remains disabled until you use the
Enable User command or until you quit and restart the
Controller. To disable more than one administrator’s
connection, specify multiple names, separated by commas, for
example:

#Disable user1,user2
Enable username(s) Enables an administrator’s connection that you previously
disabled using the Disable User command. To enable more
than one administrator’s connection, specify multiple names,
separated by commas, for example:

#Enable user1,user2
Kill Domino Stops the processes on a server that is not responding
Quit Stops the Domino server and the Server Controller
Refresh Admins Refreshes the Controller’s information about administrators
from the Domino Directory
Restart Domino Stops the processes on a server that is not responding and then
restarts the server
Set ControllerLogExpiration=days Specifies the number of days worth of log files to keep on the
server. Default is 7 days. Change takes effect at midnight or
when you restart the Server Controller.
Set ControllerLogFileName=path filename Specifies the name and path of log files created on a server. By
default, log files are stored in the server’s data directory with
filenames that begin with the text dcntrlr, followed by the
creation date, a sequence number and the file extension .log or
.meta. You can specify a different path, and can specify text to
replace the dcntrlr portion of the log file names.

Change takes effect at midnight or when you restart the Server

Set ControllerLogType=value
Controller.
Specifies which type(s) of log file(s) to create on a server or
prevents the creation of log files.
v 0 -- Do not create log files
v 1 -- Create .log files that log only data normally seen at a
console
v 2 -- Create .meta files that log data normally seen at a
console as well as additional details, such as color, font, and
event filter settings
v 3 -- Create both .log files and .meta files simultaneously

Setting takes effect immediately.

Show Users Shows the administrators currently connected to the Controller
Show Processes Shows the tasks running on the Domino server
Start Domino Starts the Domino server if it is down

Sending commands from the Domino Administrator console

A Domino command can contain up to 255 characters. If an argument for a command contains a space,
enclose it in quotation marks. For example: PULL ″Acme Server.″

Appendix A