Installation and Tuning Guide Sun™ ONE Directory Server Version 5.
Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. This distribution may include materials developed by third parties.Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California.
Contents About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Purpose of This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Typographical Conventions . . . .
Chapter 2 Upgrading From Previous Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Upgrading a Single Server Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Upgrading Multiple Replicated Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disk Subsystem Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring I/O and Disk Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sizing for Multiprocessor Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sizing Network Capacity . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimizing for Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Cache Priming and Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Other Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Chapter 7 Tuning Indexing . . . . . . . . . . . . .
Creating a Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Bindings for the Board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring SSL . . . . . . . . . . . . . . . . . . . . .
Sun ONE Directory Server Installation and Tuning Guide • June 2003
About This Guide Sun™ ONE Directory Server 5.2 is a powerful and scalable distributed directory service based on the industry-standard Lightweight Directory Access Protocol (LDAP). Sun ONE Directory Server software is part of the Sun Open Net Environment (Sun ONE), Sun’s standards-based software vision, architecture, platform, and expertise for building and deploying Services On Demand.
Typographical Conventions Typographical Conventions This section explains the typographical conventions used in this book. Monospaced font - This typeface is used for literal text, such as the names of attributes and object classes when they appear in text. It is also used for URLs, filenames, and examples. Italic font - This typeface is used for emphasis, for new terms, and for text that you must substitute for actual values, such as placeholders in path names.
Default Paths and Filenames Table 1 Default ServerRoot Paths ServerRoot Path Product Version Solaris Packages 1 /var/mps/serverroot - After configuration, this directory contains links to the following locations: • /etc/ds/v5.2 (static configuration files) • /usr/admserv/mps/admin (Sun ONE Administration Server binaries) • /usr/admserv/mps/console (Server Console binaries) • /usr/ds/v5.
Downloading Directory Server Tools Downloading Directory Server Tools Some supported platforms provide native tools for accessing Directory Server. More tools for testing and maintaining LDAP directory servers, download the Sun ONE Directory Server Resource Kit (DSRK). This software is available at the following location: http://wwws.sun.com/software/download/ Installation instructions and reference documentation for the DSRK tools is available in the Sun ONE Directory Server Resource Kit Tools Reference.
Suggested Reading • Sun ONE Directory Server Reference Manual - Details the Directory Server configuration parameters, commands, files, error messages, and schema. • Sun ONE Directory Server Plug-In API Programming Guide - Demonstrates how to develop Directory Server plug-ins. • Sun ONE Directory Server Plug-In API Reference - Details the data structures and functions of the Directory Server plug-in API.
Suggested Reading 14 Sun ONE Directory Server Installation and Tuning Guide • June 2003
Part 1 Installation Chapter 1, “Installing Sun ONE Directory Server” Chapter 2, “Upgrading From Previous Versions” Appendix A, “Installed Product Layout” Appendix B, “Using the Sun Crypto Accelerator Board” Appendix C, “Installing Sun Cluster HA for Directory Server” 15
Sun ONE Directory Server Installation and Tuning Guide • June 2003
Chapter 1 Installing Sun ONE Directory Server This chapter is designed to guide you through initial Sun ONE Directory Server software installation and uninstallation. It contains the following sections: • Before You Start • Installation • Uninstallation • Troubleshooting Before You Start Before you install Directory Server for use in a production environment, ensure the system is minimally equipped and configured to run directory services.
Before You Start 1. Plan the deployment of directory services. Refer to the Sun ONE Directory Server Deployment Guide for instructions. 2. If the deployment involves centralized administration of server configuration, users, and groups for multiple directory installations, determine configuration and user directory locations. The configuration directory or Configuration Directory Server (CDS) stores information about how Directory Server itself is configured.
Installation 4. Ensure the host system meets at least minimum disk space and memory requirements, as summarized briefly in Table 4-1 on page 80. 5. Restrict physical access to the host system. 6. Ensure the host system uses a static IP address. 7. If the Directory Server instance is not itself providing a naming service for the network or if the deployment involves remote administration of Directory Server, ensure a naming service and the domain name for the host are properly configured.
Installation Determining What to Install You have a number of alternatives to evaluate before you decide which software to install. Consider these questions: • Do you need large cache capabilities for a high-volume deployment? If so, consider using a platform on which Directory Server can run as a 64-bit process, and install the 64-bit version.
Installation • Do you want to install without first becoming super user? Do you want to install multiple independent sets of Directory Server binaries on the same system? If so, consider installing from a compressed archive, even on Solaris systems. • Do you want to install quickly to evaluate Directory Server? Is this your first time installing this version of Directory Server? If so, consider installing interactively.
Installation Table 1-2 Basic Information Required During Typical Installation (Continued) Description Examples (Optional) User directory host, port, bind DN, password, and suffix if using an existing user directory usergroup.example.
Installation Installing on Solaris Systems How you install Directory Server software depends on which packaging you decide to use, and on whether you want to interact with the install program.
Installation Table 1-3 Prerequisite Solaris Packages Package Description Required for 32-Bit Directory Server Required for 64-Bit Directory Server SUNWj3rt1 J2SDK 1.4 runtime environment Yes Yes SUNWzlib The Zip compression library Yes Yes SUNWzlibx The Zip compression library (64-bit) No Yes 1. It is strongly recommended that you use a Java Runtime Environment version 1.4.1 or later.
Installation Table 1-4 Solaris Packages Provided (SPARC Platforms) (Continued) Package Description SUNWdsvpl Sun ONE Directory Server PerLDAP modules SUNWdsvr Sun ONE Directory Server (Root) SUNWdsvu Sun ONE Directory Server (Usr) SUNWdsvx Sun ONE Directory Server (64-bit) SUNWicu International Components for Unicode User Files SUNWicux International Components for Unicode User Files (64-bit) SUNWjss Network Security Services for Java (JSS) SUNWldk LDAP C SDK SUNWldkx LDAP C SDK (64-bi
Installation Table 1-5 Solaris Packages Provided (x86 Platforms) (Continued) Package Description SUNWldk LDAP C SDK SUNWpr Netscape Portable Runtime Interface SUNWsasl Simple Authentication and Security Layer SUNWtls Network Security Services It is recommended that you use a writable basedir such as /var when installing all packages. Notice when relocating packages that SUNWasvr and SUNWdsvr place startup and shutdown scripts in basedir/etc. 2.
Installation 3. Verify that the packages you want are not yet installed. Do not reinstall packages that have already been installed on the system. 4. Become super user. 5. Use the pkgadd(1M) utility to transfer product packages to the system. Packages SUNWicu, and SUNWicux depend on the version of Solaris running on the system where you install Directory Server.
Installation Table 1-8 Whether to Patch Components On your system... Do this... The packages are already installed, and the patches have been applied. Proceed to Step 4. The packages are already installed, but the patches have not been applied. Apply the appropriate patches for your platform provided with Directory Server. The packages are not yet installed. Install the packages and appropriate patches provided with Directory Server. 4.
Installation Configuring Administration Server 1. Start the configuration program. To use the graphical user interface: root# /usr/sbin/mpsadmserver configure To use the command-line interface: root# /usr/sbin/mpsadmserver configure -nodisplay The first installation screen appears. 2. Follow the instructions on each screen using the work sheet you made when “Preparing Installation Information,” on page 21. Proceed to “Completing the Installation Process,” on page 33.
Installation 1. Perform Directory Server configuration using the -saveState option. root# /usr/sbin/directoryserver configure -saveState dirserv-file to create the specification file, dirserv-file. 2. Perform Administration Server configuration using the -saveState option. root# /usr/sbin/mpsadmserver configure -saveState admserv-file to create the specification file, admserv-file. 3. Adjust the specification files, dirserv-file and admserv-file, before using them to install on other systems.
Installation root# /usr/sbin/mpsadmserver configure -f admserv-file Here admserv-file is the silent installation configuration file. Proceed to “Completing the Installation Process,” on page 33. Preparing For Installation From a Compressed Archive 1. From the directory containing the software you unpacked as described in “Obtaining Directory Server Software,” on page 19, run the idsktune utility.
Installation Performing Interactive Installation From a Compressed Archive 1. Start the installation program in the directory containing the unpacked software. For the graphical user interface: root# ./setup For command-line interface: root# ./setup -nodisplay The first installation screen appears. 2. Follow the instructions on each screen using the work sheet you made when “Preparing Installation Information,” on page 21.
Installation 2. Start the installation program with the -saveState option. root# ./setup -saveState filename to create the specification file, filename. 3. Perform interactive installation. 4. Adjust the specification file, filename, before using it to install on other systems. Some silent installation specification file directives, such as FullMachineName, depend directly on the underlying host system and so cannot be generated generically.
Installation 3. (Optional) Enable core file generation. If you have installed Directory Server as super user, but have set the user and group ID to that of another account, the Directory Server may not be able to generate a core file during a crash. It is strongly recommended that you plan enough space for core files, and allow Directory Server to generate them during a crash.
Installation Instructions For All UNIX Platforms 1. Run the idsktune utility, which you find in the directory containing the unpacked software. idsktune checks for appropriate patches and verifies the system is tuned to support high directory service performance. As super user, enter the following command: root# ./idsktune -q > idsktune.out Perform suggested changes to the system manually. idsktune itself makes no changes to the system. 2. Fix at least all ERROR conditions indicated by idsktune.
Installation 5. Before installing using a locale other than US English, set the LANG environment variable to C. Additional Instructions For AIX Systems • If you plan to use the Console, install the X11.adt package. This package is not part of the standard bundle, but may be obtained from IBM. Additional Instructions For HP-UX Systems 1. Ensure that support for IPv6 is installed, even if you do not intend to use IPv6 interfaces with Directory Server. 2.
Installation Proceed to “Completing the Installation Process,” on page 38. Performing Silent Installation Complete the steps in the following procedures. Creating Specification Files To perform a silent installation, you must first create a file containing installation specifications. For a silent installation specification file template, refer to setup_data/typical.ins under the directory where you unpacked the software. NOTE Specification files may contain passwords in clear text.
Installation root# ./setup -noconsole -nodisplay -state filename Here filename is the silent installation specification file. Completing the Installation Process 1. Ensure that access permissions for files under ServerRoot/alias have been set to prevent access by all users other than servers you install under ServerRoot. 2. (Optional) Add support to start Directory Server on system reboot. Refer to the operating system documentation for details. 3. (Optional) Enable core file generation.
Installation Preparing For Installation 1. When installing Windows 2000, specify that the computer is a stand-alone server, not a member of any existing domain or workgroup, to reduce dependencies on network security services. 2. Apply Service Pack 3. 3. Ensure the display driver supports at least 256 colors. 4. Log on as a user with Administrator privileges. 5. Set the TEMP environment variable to a valid folder for temporary files. Performing Interactive Installation 1. Double click setup.
Installation 1. Log on as a user with Administrator privileges. 2. Start the installation program with the -saveState option. From the folder where you unpacked the product, enter Prompt>setup -saveState filename to create the specification file, filename. 3. Perform interactive installation. 4. Adjust the specification file, filename, before using it to install on other systems.
Uninstallation ❍ ServerRoot\admin-serv\config\obj.conf ❍ ServerRoot\admin-serv\config\secmod.db ❍ ServerRoot\admin-serv\config\server.xml Refer to Windows help for instructions on setting special access permissions for files. This modification prevents unauthorized users from modifying Administration Server configuration data. 3. (Optional) Many command-line scripts written in Perl can now read the bind password interactively (-w - option). To enable this functionality: a.
Uninstallation • Uninstalling on Other UNIX Systems • Uninstalling on Windows Systems Uninstalling on Solaris Systems How you remove Directory Server software depends on which packaging was used during the installation process, and on whether you want to interact with the uninstall program.
Uninstallation Unconfiguring Directory Server • Delete the Directory Server configuration. root# /usr/sbin/directoryserver unconfigure The first uninstallation screen appears. Follow the instructions on each screen. Removing Packages • Using the pkgrm(1M) utility, remove the packages installed in “Performing Interactive Installation Using Solaris Packages,” on page 24. Performing Interactive Uninstallation After Installing From a Compressed Archive 1.
Uninstallation root# /usr/sbin/directoryserver.51bak uninstall -f 51-uninstaller-file 3. Delete the Administration Server configuration using the unconfigure subcommand. root# /usr/sbin/mpsadmserver unconfigure -f ServerRoot/setup/uninstall.ins 4. Delete the Directory Server configuration using the unconfigure subcommand. root# /usr/sbin/directoryserver unconfigure -f ServerRoot/setup/uninstall.ins 5.
Uninstallation Performing Silent Uninstallation 1. Edit uninstall specification file, ServerRoot/setup/uninstall.ins, as shown in Code Example 1-2 on page 43 to include the appropriate administrator identifiers and passwords. 2. Run the uninstallation program in silent mode. root# cd ServerRoot root# ./uninstall_dirserver -noconsole -nodisplay -state setup/uninstall.ins You may remove remaining files manually after uninstallation completes.
Troubleshooting Troubleshooting Table 1-10 Common Installation Problems With Solutions Problem Possible Solutions I get a message about missing libraries. Run idsktune and fix at least all ERROR conditions, installing all recommended patches. Installation did not work, and now I cannot uninstall.
Troubleshooting Table 1-10 Common Installation Problems With Solutions (Continued) Problem Possible Solutions An LDAP authentication error causes installation to fail. You may have provided the incorrect fully qualified domain name during installation, such as dirserv.nisDomain.Example.COM instead of dirserv.example.com. I have forgotten the Directory Manager DN and password. The Directory Manager DN is recorded as the value of nsslapd-rootdn in ServerRoot/slapd-serverID/config/dse.ldif.
Troubleshooting Table 1-10 Common Installation Problems With Solutions (Continued) Problem Possible Solutions I installed the 32-bit version of the Directory Server by mistake. 1. Export all suffixes to LDIF as described in the Sun ONE Directory Server Administration Guide. How do I run the 64-bit version instead? 2. Remove all database files. Database files are found under the path indicated by the value of nsslapd-directory on cn=config,cn=ldbm database,cn=plugins,cn=config for the instance. 3.
Troubleshooting Table 1-10 Common Installation Problems With Solutions (Continued) Problem Possible Solutions I wrote a script to handle installation. When I tried installing using my script, the installer returned 73, rather than 0.
Troubleshooting 50 Sun ONE Directory Server Installation and Tuning Guide • June 2003
Chapter 2 Upgrading From Previous Versions This chapter covers upgrading to Sun ONE Directory Server 5.2 from Netscape Directory Server 4.x, and from iPlanet Directory Server 5.x. NOTE This chapter does not explain how to upgrade from Innosoft Distributed Directory Server 4.5.1. This chapter focuses primarily on how to migrate directory data from old servers to new servers.
Before You Upgrade NOTE Ensure you have sufficient disk space on the host where you run the existing server. The upgrade process requires at least enough local disk space to house binaries and databases for both the old and new servers, and also enough extra space to hold LDIF files containing the entries in all existing suffixes.
Before You Upgrade 5. Migrates user-defined schema objects. 6. Migrates indexes. 7. Migrates standard server plug-ins. You must migrate custom plug-ins manually. At minimum, you must recompile all custom plug-ins. Refer to the Sun ONE Directory Server Plug-In API Programming Guide for a detailed list of plug-in API changes. 8. (5.x to 5.2 only) Migrates replication agreements. NOTE Before replicating from a 5.2 Directory Server to a 5.1 server, set nsslapd-schema-repl-useronly on cn=config to on.
Upgrading a Single Server If the existing environment involves multiple, replicated servers, read all relevant sections of this chapter carefully before proceeding with the upgrade. You must plan your approach fully to avoid unnecessary downtime. For Help With Upgrades Sun Professional Services can help you upgrade critical directory services. Refer to http://www.sun.com/service/sunps/sunone/ for contact information.
Upgrading a Single Server Although you may choose to reuse most of the configuration information supplied for the original installation, do not reuse the existing port number. Instead, you may change the port number of the new server after migrating existing data. (4.x to 5.2) Handling Custom Schema The script provided for migrating data recognizes only those custom schema either placed in the standard slapd.user_oc.conf and slapd.user_at.conf files, or placed in other files and included in slapd.
Upgrading a Single Server 1. If you intend to initialize replication on the new Directory Server offline from files, obtain the files before proceeding. Refer to the Sun ONE Directory Server Administration Guide for instructions on exporting Directory Server data. 2. Ensure the new Directory Server is running. 3. Work as a user having the right to start, stop, and run database export and import on both the old and new servers. For example, become super user or log on as Administrator. 4.
(4.x to 5.2) Upgrading Replicated Servers Refer to the Sun ONE Directory Server Administration Guide for instructions on configuring replication for 5.2 servers. (Optional) Reusing the Existing Port Number After migrating data from the old server to the new, you may choose to retire the old server and have the new server listen on the same port as the old. Using the same port may allow client applications to continue operating without changing their configurations.
(4.x to 5.2) Upgrading Replicated Servers 4. Make the new server as a legacy consumer of the 4.x master (for the 4.x topology). Again, refer to the Sun ONE Directory Server Administration Guide for instructions. 5. Initialize replication from the 4.x master to the new server. The process is described in Chapter 13, “Managing Replication,” of the Netscape Directory Server Administration Guide. Refer to the section entitled, “Manual Consumer Initialization.” You may now upgrade the consumers.
(4.x to 5.2) Upgrading Replicated Servers 1. Proceed according to the instructions under “Upgrading a Single Server,” on page 54 to upgrade the top server in the branch. This cuts replication flow to the branch, temporarily bringing replication updates on downstream servers in the branch to a halt. 2. Configure the replication agreement on the new server in the 5.2 branch to receive updates from a 5.2 server closer in the replication topology to the new master.
(4.x to 5.2) Upgrading Replicated Servers Example 4.x Upgrade Scenario Consider an upgrade for a 4.x master replicating to two branches, one with single consumer, one with hub supplying two consumers. This section shows the steps performed to upgrade to a new multi-master topology. Figure 2-1 shows the 4.x topology before the upgrade. Figure 2-1 Existing 4.x Topology Example 4.x Master 4.x Hub 4.x Consumer 4.x Consumer 4.x Consumer Figure 2-2 shows the addition of a 5.
(4.x to 5.2) Upgrading Replicated Servers Figure 2-2 Example 4.x Topology with Additional New Server 4.x Master 5.2 Master, Legacy Consumer 4.x Hub 4.x Consumer 4.x Consumer 4.x Consumer Figure 2-3 shows the first step in replacing a 4.x branch. Notice the entire branch stops receiving replication updates during the upgrade. This interruption starts when the upstream 4.x consumer is stopped for upgrade, and ends when you restart the 4.x consumer.
(4.x to 5.2) Upgrading Replicated Servers Figure 2-4 shows the next step in replacing a 4.x branch. Figure 2-4 Example 4.x Branch During Upgrade - Step 2 4.x Master 5.2 Master, Legacy Consumer 4.x Hub 4.x Consumer 5.2 Hub 4.x Consumer 4.x Consumer 5.2 Consumer Figure 2-5 shows the next step in replacing a 4.x branch. Figure 2-5 Example 4.x Branch During Upgrade - Step 3 4.x Master 5.2 Master, Legacy Consumer 4.x Hub 4.x Consumer 5.2 Hub 4.x Consumer 4.x Consumer 5.
(4.x to 5.2) Upgrading Replicated Servers Figure 2-6 Example 4.x Branch During Upgrade - Next Branch 4.x Master 5.2 Master, Legacy Consumer 4.x Hub 4.x Consumer 5.2 Hub 4.x Consumer 5.2 Consumer 4.x Consumer 5.2 Consumer 5.2 Consumer Figure 2-7 shows the two topologies side by side. Figure 2-7 Example of 4.x and 5.2 Topologies During Upgrade 4.x Master 5.2 Master, Legacy Consumer 4.x Hub 4.x Consumer 5.2 Hub 4.x Consumer 5.2 Consumer 4.x Consumer 5.2 Consumer Chapter 5.
(4.x to 5.2) Upgrading Replicated Servers Figure 2-8 shows the addition of a master, a hub and additional replication agreements to the new topology. Figure 2-8 Adding Servers to the 5.2 Topology 4.x Master 4.x Hub 4.x Consumer 5.2 Master Additional 5.2 Master 5.2 Hub Additional 5.2 Hub 5.2 Consumer 5.2 Consumer 4.x Consumer 4.x Consumer You may also add additional servers after completing the upgrade process. Figure 2-9 shows removal of the replication agreement from the old 4.
(4.x to 5.2) Upgrading Replicated Servers Figure 2-9 Removing the Replication Agreement 4.x Master 4.x Hub 4.x Consumer Rem o ve 5.2 Master Additional 5.2 Master 5.2 Hub Additional 5.2 Hub 5.2 Consumer 5.2 Consumer 4.x Consumer 4.x Consumer After redirecting client requests and removing the replication agreement, you may disable the 4.x servers. Figure 2-10 shows the resulting 5.2 topology.
(5.x to 5.2) Upgrading Replicated Servers Figure 2-10 Resulting 5.2 Topology 5.2 Master Additional 5.2 Master 5.2 Hub Additional 5.2 Hub 5.2 Consumer 5.2 Consumer Client requests are now directed to the 5.2 topology. (5.x to 5.2) Upgrading Replicated Servers When upgrading replicated 5.x servers, you typically start with the consumers, continue with the hubs, and finish with the masters.
(5.x to 5.2) Upgrading Replicated Servers Upgrading 5.x Servers 1. For each consumer in the existing topology, proceed according to the instructions under “Upgrading a Single Server,” on page 54 to upgrade the consumer. 2. For each hub in the existing topology, proceed according to the same instructions to update the hub. 3. For each master in the existing topology, proceed according to the same instructions to update the master. Adding Additional Servers After completing the upgrade from the 5.
(5.x to 5.2) Upgrading Replicated Servers Figure 2-11 Existing 5.x Topology Example 5.x Master 5.x Master 5.x Hub 5.x Hub 5.x Consumer 5.x Consumer The first step involves upgrading consumers. Figure 2-12 shows the resulting topology. Figure 2-12 Example 5.x Consumer Upgrade Step 5.x Master 5.x Master 5.x Hub 5.x Hub 5.x Consumer 5.x Consumer 5.2 Consumer 68 Sun ONE Directory Server Installation and Tuning Guide • June 2003 5.
(5.x to 5.2) Upgrading Replicated Servers The next step involves upgrading hubs. Figure 2-13 shows the results. Figure 2-13 Example 5.x Hub Upgrade Step 5.x Master 5.x Master 5.x Hub 5.x Hub 5.x Consumer 5.2 Hub 5.2 Hub 5.2 Consumer 5.2 Consumer 5.x Consumer The next step involves upgrading masters. Figure 2-14 shows the results. Figure 2-14 5.x Master 5.x Hub 5.x Consumer Example 5.x Master Upgrade - Step 3 5.x Master 5.2 Master 5.2 Master 5.2 Hub 5.2 Hub 5.2 Consumer 5.
(5.x to 5.2) Upgrading Replicated Servers Figure 2-15 shows the 5.2 topology following the upgrade. At this point, servers in the old topology may be retired, and new servers added to the 5.2 topology. Figure 2-15 Example 5.2 Topology after Upgrading 5.2 Master 5.2 Master 5.2 Hub 5.2 Hub 5.2 Consumer 5.2 Consumer Client requests are now directed to the 5.2 topology.
Part 2 Tuning Chapter 3, “Top Tuning Tips” Chapter 4, “Hardware Sizing” Chapter 5, “Tuning the Operating System” Chapter 6, “Tuning Cache Sizes” Chapter 7, “Tuning Indexing” Chapter 8, “Tuning Logging” Chapter 9, “Managing Use of Other Resources” 71
Sun ONE Directory Server Installation and Tuning Guide • June 2003
Chapter 3 Top Tuning Tips Tuning performance implies modifying the default configuration to reflect specific deployment requirements. This guide describes how to tune a single Directory Server instance. It is assumed here that your overall directory service design including the replication topology is complete, and that you use the information here to tune the Directory Server instances to meet the design requirements.
Table 3-1 Tuning Process Phase Description Define goals Define specific, measurable objectives for tuning, based on deployment requirements.
Table 3-1 Tuning Process (Continued) Phase Description Profile and monitor Profile and monitor the behavior of Directory Server after applying the potential modifications. Collect measurements of all relative behavior. Plot and analyze Plot and analyze the behavior observed while profiling and monitoring. Attempt to find evidence and patterns that suggest further tests. You may need to go back to the profiling and monitoring phase to collect more data.
a. Remove unnecessary indexes and add additional indexes to support expected requests. From time to time, it may become necessary to add additional indexes that support requests from new applications. It is possible to add, remove, and modify indexes while Directory Server is running, with the limitation that existing data are only indexed progressively from that point forward.
6. Distribute disk activity. Especially for deployments supporting large numbers of updates, Directory Server can be extremely disk I/O intensive. If possible, consider spreading the load across multiple disks using separate controllers. Refer to “Sizing Disk Subsystems,” on page 85 for more information.
Sun ONE Directory Server Installation and Tuning Guide • June 2003
Chapter 4 Hardware Sizing Appropriate hardware sizing is a critical component of directory service planning and deployment. When sizing hardware, the amount of memory available and the amount of local disk space available are of key importance. NOTE For best results, install and configure a test system with a subset of entries representing those used in production. You can then use the test system to approximate the behavior of the production server.
Suggested Minimum Requirements Table 4-1 Minimum Disk Space and Memory Requirements Required for... Free Local Disk Space Free RAM Unpacking product At least 125 MB - Product installation At least 200 MB At least 256 MB 10,000-250,000 entries Add at least 3 GB Add at least 256 MB 250,000-1,000,000 entries Add at least 5 GB Add at least 512 MB Over 1,000,000 entries Add 8 GB or more Add 1 GB or more Minimum disk space requirements include 1 GB devoted to access logs.
Sizing Physical Memory On Windows systems, format drives as NTFS rather than FAT. FAT is not supported for use with Directory Server. NTFS allows access controls to be set on files and directories. Minimum Processing Power High volume systems typically employ multiple, high-speed processors to provide appropriate processing power for multiple simultaneous searches, extensive indexing, replication, and other features. Refer to “Sizing for Multiprocessor Systems,” on page 94 for details.
Sizing Physical Memory NOTE When deploying Directory Server in a production environment, configure cache sizes well below theoretical process limits, leaving appropriate resources available for general system operation. Estimating memory size required to run Directory Server involves estimating the memory needed both for a specific Directory Server configuration, and for the underlying system on which Directory Server runs.
Sizing Physical Memory To estimate approximate memory size, perform the following steps. 1. slapdBase Estimate the base size of the server process, slapdBase. = 75 MB +(nsslapd-threadnumber x 0.5 MB) +(nsslapd-maxconnections x 0.5 KB) 2. Determine the sum of entry cache sizes, entryCacheSum. entryCacheSum = Sumall 3. cacheSum Determine the total size for all caches, cacheSum. = entryCacheSum + nsslapd-dbcachesize + nsslapd-import-cachesize 4.
Sizing Physical Memory NOTE For top performance, dedicate the system running Directory Server to this service only. If you must run other applications or services, monitor the memory they use as well when sizing total memory required. Additionally, allocate memory for general system overhead and normal administrative use. A first estimate for this amount, systemOverhead, should be at least several hundred megabytes, or 10 percent of the total physical memory, whichever is greater.
Sizing Disk Subsystems If the system cannot accommodate additional memory, yet you continue to observe constant page swapping, reduce the size of the database and entry caches. Running out of swap space can cause the Directory Server to crash. Refer to Chapter 6, “Tuning Cache Sizes”, for a discussion of the alternatives available when providing adequate physical memory to cache all directory data is not an option. Sizing Disk Subsystems Disk use and I/O capabilities can strongly impact performance.
Sizing Disk Subsystems 5. Add extra disk space to compensate for error and variation. Disk space for suffixes is only part of the picture; you must also consider how Directory Server uses disks. How the Directory Server Uses Disks Directory suffixes are part of what Directory Server stores on disk. A number of other factors affecting disk use may vary widely depending even on how Directory Server is used after deployment and so are covered here in general terms.
Sizing Disk Subsystems Transaction Log Transaction log volume depends upon peak write loads. If writes occur in bursts, transaction logs use more space than if the write load is constant. Directory Server trims transaction logs periodically. Transaction logs therefore should not continue to grow unchecked. Transaction logs are not, however, flushed during online backup. Directory Server is generally run with durable transactions enabled.
Sizing Disk Subsystems If the deployment involves replication, plan additional space to hold initialization LDIF files, as these differ from backup LDIF files. Memory Based Rather Than Disk Based File Systems Some systems support memory based tmpfs file systems. On Solaris for example /tmp is often mounted as a memory based file system to increase performance.
Sizing Disk Subsystems Transaction Logs When durable transaction capabilities are enabled, Directory Server performs a synchronous write to the transaction log for each modification operation. An operation is thus blocked when the disk is busy. Placing transaction logs on a dedicated disk can improve write performance, and increase the modification rate Directory Server can handle. Refer to “Transaction Logging,” on page 147 for more information.
Sizing Disk Subsystems Cache Files on Memory Based File Systems In a tmpfs file system, for example, files are swapped to disk only when physical memory is exhausted.
Sizing Disk Subsystems RAID Alternatives RAID stands for Redundant Array of Inexpensive Disks. As the name suggests, the primary purpose of RAID is to provide resiliency. If one disk in the array fails, data on that disk is not lost but remains available on one or more other disks in the array. To implement resiliency, RAID provides an abstraction allowing multiple disk drives to be configured as a larger virtual disk, usually referred to as a volume.
Sizing Disk Subsystems RAID 0, Striped Volume Striping spreads data across multiple physical disks. The logical disk, or volume, is divided into chunks or stripes and then distributed in a round-robin fashion on physical disks. A stripe is always one or more disk blocks in size, with all stripes having the same size. The name RAID 0 is a contradiction in that it provides no redundancy. Any disk failure in a RAID 0 stripe causes the entire logical volume to be lost.
Sizing Disk Subsystems During normal operation, RAID 5 usually offers lower performance than RAID 0, 1+0 and 0+1, as a RAID 5 volume must do four physical I/O operations for every logical write. The old data and parity are read, two exclusive or operations are performed, and the new data and parity are written. Read operations do not suffer the same penalty and thus provide only slightly lower performance than a standard stripe using an equivalent number of disks.
Sizing for Multiprocessor Systems Monitoring I/O and Disk Use Disks should not be saturated under normal operating circumstances. You may use utilities such as iostat(1M) on Solaris and other systems to isolate potential I/O bottlenecks. Refer to Windows help for details on handling I/O bottlenecks on Windows systems. Sizing for Multiprocessor Systems Directory Server software is optimized to scale across multiple processors.
Sizing for SSL Although hardware accelerator cards cannot eliminate the impact of using SSL, they can improve performance significantly compared with software-based implementation. Sun ONE Directory Server 5.2 supports the use of SSL hardware accelerators such as supported Sun Crypto Accelerator hardware. Using a Sun Crypto Accelerator board can be useful when SSL key calculation is a bottleneck.
Sizing for SSL 96 Sun ONE Directory Server Installation and Tuning Guide • June 2003
Chapter 5 Tuning the Operating System Default system and network settings are not suitable for high performance directory services. Tuning the system for optimum Directory Server performance involves at minimum checking that the latest recommended patches are installed on the system, enforcing basic security measures, and changing some system and network settings. This chapter addresses those tuning issues.
Patching the System Patching the System In order to maintain overall system security, and to ensure proper installation and operation of Sun ONE Directory Server 5.2, install the latest recommended system patches, service packs, or fixes. Table 5-1 suggests where to look for required patches. Table 5-1 Where to Obtain Patches, By Platform Platform Browse... Sun Solaris™ Operating Environment http://sunsolve.sun.com/ Hewlett Packard HP-UX http://www.hp.com/support/ IBM AIX http://www.ibm.
Enforcing Basic Security Strong Passwords Use a super user or Administrator password at least 8 characters long that includes punctuation or other non-alphabetic characters. Using a strong password is particularly important when running Directory Server on Windows platforms. If you choose to use longer operating system passwords, it may be necessary to configure the way passwords are handled by the system. Refer to the operating system documentation for instructions.
Keeping Accurate Time Disabling Unnecessary Services For top performance and less risk, dedicate the system to Directory Server alone. Running additional services, especially network services, negatively affects server performance and scalability, and may increase security risks. Disable as many network services as possible. Directory Server uses only TCP/IP and does not require file sharing and other services.
Generating Basic Tuning Recommendations (Solaris Packages) As part of the installation and configuration process, appropriate scripts enable restart at boot time. (Windows) Configure Windows to restart automatically after system failure. Refer to Windows help for details. For other platforms, refer to the operating system documentation for details on starting services at boot time.
Tuning System Settings Tuning System Settings You may use the idsktune tool that reads current system settings and recommends changes. In general, implementing the recommendations optimizes performance both on systems dedicated to running Directory Server and on systems running additional applications. Consider local network conditions and other applications before implementing specific recommendations. Refer to the operating system documentation for additional network tuning tips.
Tuning System Settings File Descriptors Directory Server uses file descriptors when handling concurrent client connections. Having a low maximum number of file descriptors available in the system or available to a process can thus limit the number of concurrent connections. Recommendations concerning the number of file descriptors therefore relate to the number of concurrent connections Directory Server may be able to handle on the system.
Tuning System Settings Transmission Control Protocol (TCP) Settings Specific network settings depend on the platform. On some systems, it is possible to enhance Directory Server performance by modifying TCP settings. This section discusses the reasoning behind idsktune recommendations concerning TCP settings. Closed Connections in the TIME-WAIT State Some systems allow you to configure how long a TCP connection is held in the kernel table after closure.
Tuning System Settings Inactive Connections Some systems allow you to configure the interval between transmission of keepalive packets. This setting can determine how long a TCP connection is maintained while inactive and potentially disconnected. When set too high, the keepalive interval may cause the system to use unnecessary resources keeping connections alive for clients that have become disconnected.
Tuning System Settings Retransmission Timeout Some systems allow you to configure the initial time interval between retransmission of packets. This setting affects the wait before retransmission of an unacknowledged packet. When set too high, clients may be kept waiting on lost packets. For intranet deployments on fast and reliable networks, setting this parameter to a value of 500 milliseconds may improve performance.
Chapter 6 Tuning Cache Sizes Directory Server caches directory information in memory and on disk in order to be able to respond more quickly to client requests. Properly tuned caching minimizes the need to access disk subsystems when handling client requests. NOTE Unless caches are tuned and working properly, other tuning may have only limited impact on performance. Types of Cache Directory Server handles three types of cache as described in Table 6-1.
Types of Cache Figure 6-1 shows caches for an instance of Directory Server handling three suffixes, each with its own entry cache. The instance is configured to handle significant disk activity, placing the transaction log, database, and other files and logs on separate disk subsystems as suggested in Chapter 8, “Tuning Logging.
Types of Cache Directory Server moves pages between the database files and the database cache to maintain maximum database cache size. The actual amount of memory used by Directory Server for database cache may be up to 25 percent larger than the size you specify, due to additional memory needed to manage the database cache itself.
Types of Cache Actual memory used by the Directory Server process depends primarily on the memory allocation library used, and on the entries cached. Entries with many small attribute values usually require more overhead than entries with a few large attribute values. For 32-bit servers, entry cache size must in practice be limited to 2 GB or less. NOTE On AIX platforms, Directory Server is created with maxdata = 0x50000000, allowing you to allocate 1 GB each to both database cache and entry cache.
Types of Cache File System Cache The operating system allocates available memory not used by Directory Server caches and other applications to the file system cache. This cache holds data recently read from the disk, making it possible for subsequent requests to obtain data copied from cache rather than to read it again from the disk. As memory access is many times faster than disk access, leaving some physical memory available to the file system cache can boost performance.
How Searches Use Cache If all suffix initialization takes place offline with Directory Server stopped, you may be able to work around this limitation. In this case import cache does not coexist with database cache, so you may allocate the same memory to import cache for offline suffix initialization and to database cache for online use. If you opt to implement this special case, however, ensure that no one performs online bulk loads on the production system.
How Searches Use Cache Figure 6-2 Searches and Cache Sub-tree or one-level search Base search (DN specified) 1 Entry Cache for o=suffix1 (formatted entries) Entry Cache for o=suffix2 (formatted entries) Entry Cache for o=suffix3 (formatted entries) 1 2 2 Indexes from database Database Cache for the instance Entry pages from database Candidate list for filter Directory Server Instance 3 Memory (RAM), Including File System Cache Disk Subsystems Operating System Base Search Process As shown, bas
How Searches Use Cache 1. Attempts to retrieve the entry having the specified base DN from the entry cache. If the entry is found there, Directory Server checks whether the candidate entry matches the filter provided for the search. If the entry matches, Directory Server then quickly returns the formatted, cached entry to the client application. 2. Attempts to retrieve the entry from the database cache.
How Updates Use Cache How Updates Use Cache Figure 6-3 illustrates how Directory Server handles updates. Individual lines represent threads accessing different levels of memory, with broken lines representing steps to minimize through effective tuning.
How Suffix Initialization Uses Cache Updates involve more processing than searches. To process updates, Directory Server: 1. Performs a base DN search to retrieve the entry to update or verify in the case of an add operation that it does not already exist. 2. Changes the database cache, updating in particular any indexes affected by the update.
How Suffix Initialization Uses Cache Figure 6-4 Suffix Initialization (Bulk Loading) and Cache LDIF to import into o=suffix2 1 Entry Cache for o=suffix1 (formatted entries) Entry Cache for o=suffix2 (formatted entries) Entry Cache for o=suffix3 (formatted entries) 2 Database Cache for the instance Import Cache for the instance Indexes from database 3 Entry pages from database Directory Server Instance Memory (RAM), Including File System Cache Disk Subsystems Operating System To initialize a
Optimizing For Searches 3. Reads from and writes to the database files when import cache runs out. Directory Server may also write log messages during suffix initialization, but does not write to the transaction log. Tools for suffix initialization such as ldif2db (/usr/sbin/directoryserver ldif2db) delivered with Directory Server provide feedback concerning cache hit rate and import throughput. Having both cache hit rate and import throughput drop together suggests that import cache may be too small.
Optimizing For Searches Figure 6-5 Monitoring Cache Hit Rate Using Directory Server Console Alternatively, paging and cache activity can be monitored by searching from the command line: $ ldapsearch -D admin -w password \ -b cn=monitor,cn=database_name,cn=ldbm database,cn=plugins,cn=config As a rough estimate of the amount of memory needed for all the database indexes held in .db3 files to fit in the database cache, use the following formula.
Optimizing For Searches As a rough estimate of the number of entry cache slots and the amount of memory needed for all entries to fit in the entry cache, use the following formulas. Again these formulas are approximately accurate for default index configuration used with typical entries having no large binary attributes such as photos. nsslapd-cachesize = 4.5 x (number of entries in LDIF) nsslapd-cachememsize = 3.8 x (id2entry.db3 file size) Verify and correct estimates through empirical testing.
Optimizing for Updates Alternatively, if search patterns are less random, you may choose to set entry and database caches higher on the assumption that most of the searches in the particular deployment access the same small subset of all entries in the directory, and that the gains from having entries and indexes cached for such searches offset the cost of handling occasional unusual search requests. Verify and correct assumptions through empirical testing.
Cache Priming and Monitoring Cache Priming and Monitoring Priming caches means filling them with data such that subsequent Directory Server behavior reflects normal operational performance, rather than ramp up. Prime caches before measuring and analyzing potential optimizations. Prime the entry cache for the suffix using the ldapsearch utility.
Other Optimizations $ ldapsearch -D admin -w password \ -b cn=monitor,cn=database_name,cn=ldbm\ database,cn=plugins,cn=config If database cache size is large enough and the cache is primed, then the hit ratio (dbcachehitratio) should be high, and number of pages read in (dbcachepagein) and clean pages written out (dbcacheroevict) should be low. Here, “high” and “low” must be understood relative to the deployment constraints.
Other Optimizations 124 Sun ONE Directory Server Installation and Tuning Guide • June 2003
Chapter 7 Tuning Indexing As Directory Server handles more and more entries, searches potentially consume more and more time and system resources. Indexes are one tool to improve search performance. This chapter covers how Directory Server indexes work so that you understand the costs and benefits of using a specific index in the context of a particular deployment. About Indexes Indexes associate lookup information with Directory Server entries.
Benefits: How Searches Use Indexes Table 7-1 Standard Index Types (Continued) Index Type Answers the question... International Which entries match for this international locale? Presence Which entries have this attribute? Substring Which entries have a value matching *foo* for this attribute? An index file for a particular attribute such as CN may contain multiple types of indexes. For instance, if CN is indexed in the example database for equality and for substring matching, then example_cn.
Costs: How Updates Affect Indexes 2. Directory Server examines the request to ensure the search base corresponds to a suffix it can handle. If not, it returns an error to the client, and may return a referral to another Directory Server instance. 3. Directory Server determines whether it manages an index or indexes appropriate to the search.
Costs: How Updates Affect Indexes In general, tuning indexing for an instance of Directory Server means maintaining only those indexes for which the benefits from faster search processing offset the costs of more update processing and of more space needed. Maintaining useful indexes is good practice; maintaining unused indexes for attributes on which clients rarely search is a waste.
Costs: How Updates Affect Indexes Equality Indexes Figure 7-2 depicts an equality index for the SN (surname) attribute. It shows how this index maintains a list per attribute value of entries having that attribute value for the SN attribute.
Costs: How Updates Affect Indexes The cost of equality indexes is generally lower than for substring indexes, for example, but higher in terms of space than for presence. Some client applications such as messaging servers may, however, rely on equality indexes for top search performance. Avoid equality indexes for large binary attributes such as photos and encrypted passwords. Substring Indexes Figure 7-3 depicts a substring index for the SN (surname) attribute.
Costs: How Updates Affect Indexes Directory Server offers a further optimization allowing initial substring searches of only one character before the wildcard. Thus a search for (sn=a*), but not (sn=*a*) or (sn=*a), can also be accelerated when a substring index is available, for example. Notice that Directory Server builds an index of substrings according to its own built-in rules. These substrings are not configurable by the system administrator.
Costs: How Updates Affect Indexes When Directory Server receives an update request for an entry matching a vlvFilter value, it must determine whether the entry must be removed from the index or not, determine the correct position of the entry in the list, and must then carry out any necessary modifications before returning acknowledgement of the update to the client application. Approximate Indexes Directory Server maintains approximate indexes using a variation of the metaphone phonetic algorithm.
Costs: How Updates Affect Indexes Code Example 7-1 Sample User Entry dn: uid=yyorgens,ou=People,dc=example,dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson uid: yyorgens givenName: Yolanda sn: Yorgenson cn: Yolanda Yorgenson mail: yolanda.yorgenson@example.
Tuning Indexing for Performance Tuning Indexing for Performance In many cases, tuning indexing for performance implies activating indexes to speed up frequent searches, and disactivating indexes that are expensive to maintain and not frequently used. NOTE Database backups include indexes, and so should match the Directory Server configuration. After changing how indexes are configured, back up both the configuration and the data.
Tuning Indexing for Performance $ ldapmodify -h host -p port -D "cn=directory manager" -w password dn: cn=example,cn=ldbm database, cn=plugins, cn=config changetype: modify replace: nsslapd-require-index nsslapd-require-index: on ^D (^Z on Windows systems) The change takes effect immediately. No need to restart Directory Server. Limiting Index List Length In large and fast growing directory deployments, indexing may reach the point of diminishing returns for a particular index key.
Tuning Indexing for Performance Figure 7-5 Reaching the All IDs Threshold for an Index Key Entry IDs blinn entryid entryid entryid entryid entryid entryid cubbins entryid entryid entryid entryid entryid entryid cooper entryid entryid entryid entryid entryid entryid entryid entryid entryid entryid entryid entryid entryid entryid entryid ... Many entries for people with surname Smith -- more than nsslapd-allidsthreshold. Handled by Directory Server as an unindexed search.
Tuning Indexing for Performance The notes=U flag at the end of an access log RESULT message indicates Directory Server performed an unindexed search. A previous SRCH message for the same connection and operation specifies the search filter used. The following two-line example traces an unindexed search for (cn=Smith) returning 10000 entries. Time stamps have been removed from the messages. conn=2 op=1 SRCH base="o=example.
Tuning Indexing for Performance 5. If database cache size was tuned for the old all IDs threshold value and the server has adequate physical memory, consider increasing database cache size by 25 percent of the magnitude of the increase to the threshold. In other words, if you increase the all IDs threshold from 4000 to 6000, you may choose to increase database cache size by about 12.5 percent to account for increased index list size.
Chapter 8 Tuning Logging Directory Server provides several log types, summarized in Table 8-1. This chapter discusses how to handle the different types of logs. Table 8-1 Types of Logs Used by Directory Server Log Type Use Access Flat file Evaluating directory use patterns, verifying configuration settings, diagnosing access problems. Audit Flat file Providing audit trails for security and data integrity. Changelog Database Enables synchronization between replicas.
Access Logging Access Logging The access log contains detailed information about client connections and operations performed. The access log can be indispensable when diagnosing access problems, verifying server configuration settings, and evaluating server usage patterns. The default logging level results, however, in significant disk activity for most deployments, and the volume of disk activity can negatively affect server performance.
Access Logging Table 8-2 Tuning Recommendations for Access Logging (Continued) Configuration Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-accesslog-logging-enabled Enables and disables access logging. Turn off (default is on) for maximum performance. If the deployment requires that access logging be enabled, set nsslapd-accesslog-level to the lowest acceptable setting, and put the access log on its own disk or disk subsystem.
Audit Logging Audit Logging The audit log contains detailed information about all changes made to each database as well as to server configuration. Audit logging is disabled by default. When enabled in deployments having high modify volume, enabling audit logging causes a very noticeable overall drop in performance. Unless the deployment requires it, leave audit logging disabled.
Error Logging Table 8-3 Tuning Recommendations for Audit Logging (Continued) Configuration Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-auditlog-logminfreediskspace Specifies minimum free disk space allowed before old logs are purged. When the amount of free disk space falls below the value specified on this attribute, the oldest audit logs are deleted until enough disk space is freed to correspond to the setting for this attribute.
Error Logging Table 8-4 Tuning Recommendations for Error Logging Configuration Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-errorlog Specifies the path and filename of the error log file. For low volume deployments, the error log may share a disk with the access and audit logs. For high volume deployments, consider putting the error log on its own disk, with its own controller. Choose a disk with a large I/O buffer.
Multi-Master Replication Change Logging Table 8-4 Tuning Recommendations for Error Logging (Continued) Configuration Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-infolog-level Specifies the level of informational logging used. Leave at 0 (default) unless debugging a component for which setting nsslapd-infolog-area alone fails to generate sufficient detail.
Retro Change Logging Table 8-5 Tuning Recommendations for Multi-Master Change Logging (Continued) Configuration Entry DN and Configuration Attribute Short Description and Tuning Recommendations dn: cn=changelog5,cn=config Specifies the maximum number of entries in the changelog. nsslapd-changemaxentries Change this from 0 (default, indicating no maximum) to a number sufficient to allow replicated servers to become fully synchronized before the changelog is trimmed.
Transaction Logging Table 8-6 Tuning Recommendations for Retro Change Logging (Continued) Configuration Entry DN and Configuration Attribute Short Description and Tuning Recommendations dn: cn=Retro Changelog Plugin,cn=plugins,cn=config Specifies the maximum age for entries in the retro changelog. nsslapd-changelogmaxage Change this from 0 (default, indicating no maximum) to an interval after which clients using the retro changelog have processed the log entries generated.
Transaction Logging Table 8-7 Tuning Recommendations for Transaction Logging Configuration Entry DN and Configuration Attribute Short Description and Tuning Recommendations dn: cn=config,cn=ldbm database,cn=plugins,cn=config Specifies how often Directory Server checkpoints the transaction log, ensures the entire database system is synchronized to disk, and cleans up transaction logs.
Chapter 9 Managing Use of Other Resources After optimizing cache size, attribute value indexing, and log management, it may prove useful to tune how Directory Server limits resources made available to client applications, and how Directory Server makes use of system resources. It may also prove useful to reconfigure and even disable some features offered as Directory Server plug-ins.
Limiting Resources Available to Clients Table 9-1 Tuning Recommendations for Limiting Resources Available to Clients Configuration Entry DN and Attribute Short Description and Tuning Recommendations dn: cn=config Sets the time in seconds after which Directory Server closes an idle client connection. Here idle means that the connection remains open, yet no operations are requested. By default, no time limit is set.
Limiting Resources Available to Clients Table 9-1 Tuning Recommendations for Limiting Resources Available to Clients (Continued) Configuration Entry DN and Attribute Short Description and Tuning Recommendations dn: cn=config Sets the maximum size in bytes for an incoming message. Directory Server rejects requests to add entries larger than this limit.
Using Available System Resources Table 9-1 Tuning Recommendations for Limiting Resources Available to Clients (Continued) Configuration Entry DN and Attribute Short Description and Tuning Recommendations dn: cn=config Sets the maximum number of seconds Directory Server allows for handling a search request. nsslapd-timelimit Some applications, such as messaging servers, may need to perform very large searches. Ideally, you might dedicate a replica to support the application in this case.
Using Available System Resources Table 9-2 Tuning Recommendations for Configuring Use of System Resources (Continued) Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-maxdescriptors Sets the maximum number of file descriptors Directory Server attempts to use. Directory Server uses file descriptors to handle client connections, and to maintain files internally.
Using Available System Resources Table 9-2 Tuning Recommendations for Configuring Use of System Resources (Continued) Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-reservedescriptors Sets the number of file descriptors Directory Server maintains to manage indexing, replication and other internal processing. Directory Server does not use such file descriptors to handle client connections.
Using Available System Resources Table 9-2 Tuning Recommendations for Configuring Use of System Resources (Continued) Attribute (on dn: cn=config) Short Description and Tuning Recommendations nsslapd-threadnumber Sets the number of threads Directory Server uses. Consider adjusting the value of this attribute if any of the following are true: • Client applications perform many time-consuming operations such as updates or complex searches simultaneously.
Using Available System Resources resource targeted for the resulting operation. If a macro matches, Directory Server replaces it with the value of the actual DN. Directory Server then evaluates the ACI normally. For more information on ACIs, refer to the Sun ONE Directory Server Administration Guide. Testing has demonstrated that Directory Server can support more than 50,000 ACIs. The impact on performance for various deployment scenarios is currently under analysis.
Using Available System Resources Table 9-3 Tuning Recommendations for Some Standard Plug-Ins (Continued) Name and DN Short Description and Tuning Recommendations Referential Integrity Plug-In Allows Directory Server to ensure relationships between related entries are maintained. For example, when a user entry is removed from the directory or renamed, the groups to which the user belonged are updated as needed without manual intervention.
Using Available System Resources 158 Sun ONE Directory Server Installation and Tuning Guide • June 2003
Appendix A Installed Product Layout This appendix summarizes product software layout after a typical installation. Of the files installed, only those listed here and discussed in the product documentation belong to the supported public product interface. NOTE Examples shown here reflect a product installation for the Solaris Operating Environment. File names and extensions may differ for installations on other platforms.
The ServerRoot Directory Table A-1 Utilities Under ServerRoot (Continued) Utility Remarks ServerRoot/startconsole Start Sun ONE Server Console ServerRoot/stop-admin Stop administration server ServerRoot/uninstall Uninstall product software The ServerRoot /bin directory contains product binaries and configuration templates used internally when creating a server instance.
The ServerRoot Directory The ServerRoot/plugins directory contains sample server plug-ins, header files for plug-in development, and plug-ins for SNMP support.
The Server Instance Directory Table A-7 Certificate Mapping Configuration File Under ServerRoot/shared/config Directory or File Remarks ServerRoot/shared/config Internal use, except for the following ServerRoot/shared/config/certmap.conf Map certificates to entries The ServerRoot /setup5 directory contains sample templates for silent installation and uninstallation.
The Server Instance Directory Table A-9 Server Instance Scripts (Continued) Scripts Remarks ServerRoot/slapd-ServerID/db2ldif.pl Dump database to LDIF (online) ServerRoot/slapd-ServerID/getpwenc Print encrypted password ServerRoot/slapd-ServerID/ldif2db Import LDIF (offline) ServerRoot/slapd-ServerID/ldif2db.
Internal Use Only Table A-10 Server Instance Subdirectories (Continued) Directory Remarks ServerRoot/slapd-ServerID/conf_bk/ Directory server configuration backup ServerRoot/slapd-ServerID/config/ Directory server configuration ServerRoot/slapd-ServerID/config/schema/ Directory schema configuration ServerRoot/slapd-ServerID/db/ Directory databases ServerRoot/slapd-ServerID/ldif/ Sample LDIF files ServerRoot/slapd-ServerID/locks/ Run time process locks ServerRoot/slapd-ServerID/logs/ Server l
Appendix B Using the Sun Crypto Accelerator Board This appendix provides instructions on using a Sun Crypto Accelerator board with Directory Server to enhance performance for connections using the Secure Sockets Layer (SSL) protocol with certificate-based authentication. Before You Start Table B-1 covers items that must be completed before attempting to use the Sun Crypto Accelerator board to enhance SSL connection performance.
Creating a Token Refer to Sun ONE Server Console Server Management Guide both for a discussion of the SSL protocol itself and of SSL certificates, and for instructions on how to use the protocol with Sun ONE servers supporting Sun ONE Server Console administration. Creating a Token Directory Server uses a token and password to access the appropriate cryptographic key material on the accelerator board.
Generating Bindings for the Board secadm> set realm=dsrealm secadm{dsrealm}> su System Administrator Login Required Login: super-user Password: secadm{root@dsrealm}# 4. Create the user nobody to use the default slot, supplying the password used when restarting Directory Server with SSL configured. secadm{root@dsrealm}# create user=nobody Initial password: password Confirm password: password User nobody created successfully.
Importing Certificates 5. Make the external security module the default for RSA, DSA, RC4, and DES. $ ./modutil -default "Crypto Mod" -dbdir ../../alias \ -mechanisms "RSA:DSA:RC4:DES" -dbprefix "slapd-serverID" This should successfully change the default security module. At this point you have generated bindings for the accelerator board and may import certificates.
Configuring SSL 1. Create a file, ssl.ldif, of modifications to change SSL related Directory Server configuration entries. Code Example B-1 Modifications to Activate SSL Using the Board (ssl.
Configuring SSL $ ldapmodify -p currPort -D "cn=directory manager" -w password -f ssl.ldif where currPort is the number of the port on which the Directory Server currently listens for client requests. 3. Restart the Directory Server in secure mode. $ ServerRoot/slapd-serverID/restart-slapd Enter PIN for nobody@dsrealm: password Here password is the user password for nobody provided when the token nobody@dsrealm was created.
Appendix C Installing Sun Cluster HA for Directory Server This appendix describes how to install and configure both the Sun Cluster HA for Directory Server data service and the associated Administration Server data service. Refer to the Sun Cluster 3.0 product documentation for Sun Cluster installation instructions and key concepts. You must configure the data services as a failover services. Before You Start Use this section in conjunction with the worksheets in the Sun Cluster 3.
Before You Start Table C-1 Installation and Configuration Process Task What you should know “Setting Up Network Resources,” on page 173 The names of the cluster nodes that can master the data services. The logical host names to be used by clients accessing Directory Server such as ds1.example.com, ds2.example.com. Refer to the Sun Cluster 3.0 product documentation for instructions on setting up logical host names.
Setting Up Network Resources Setting Up Network Resources Sun Cluster software manages logical host names that differ both from node names and from host names for individual network interfaces. Figure C-1 shows how logical host names, managed by a two-node cluster, are not permanently associated with either of the nodes. Figure C-1 Cluster with Two Nodes Client requests ds-1.example.com Client requests ds-2.example.
Setting Up Network Resources 2. Verify that all network addresses you use have been added to the name service database. To avoid failures during name service lookup, ensure as well that all fully qualified domain names, fully qualified logical host names and shared IP addresses are present in the /etc/hosts file on each cluster node. Also configure name service mapping in /etc/nsswitch.conf on each cluster node to check local files first before trying to access other name services. 3.
Installing the Servers Installing the Servers In Sun Cluster HA for Directory Server, both Directory Server and Administration Server run under the control of Sun Cluster. This means that instead of supplying the servers with a fully qualified domain name for the physical node during installation, you provide a fully qualified logical host name that can fail over to a different node.
Installing the Data Service Packages 1. Install the Solaris packages for both Directory Server and Administration Server, referring to “Installing Solaris Packages,” on page 24 for instructions. 2. Configure Directory Server using settings identical to those provided when “Installing on the Active Node,” on page 175. 3. Configure Administration Server using settings identical to those provided when “Installing on the Active Node,” on page 175. 4. Copy ServerRoot/alias/slapd-serverID-pin.
Configuring the Servers 4. Add the servers to the failover resource group created in “Setting Up Network Resources,” on page 173. # scrgadm -a -j resource-name-ds -g resource-group -t SUNW.dsldap \ -y Network_resources_used=logical-host-name \ -y Port_list=port-number/tcp \ -x Confdir_list=ServerRoot/slapd-serverID # scrgadm -a -j resource-name-as -g resource-group -t SUNW.
Example Registration and Configuration Example Registration and Configuration Code Example C-1 shows how you might register and configure the data service for the cluster illustrated in Figure C-1 on page 173. Code Example C-1 Registering and Configuring the Data Service (Create a failover resource group on the node that is online.) # scrgadm -a -g ds-resource-group-1 -h foo,bar (Add a logical hostname resource to the resource group.) # scrgadm -a -L -g ds-resource-group-1 -l ds-1.example.
Configuring Extension Properties What You Can Configure You typically configure resource extension properties using the Cluster Module of the Sun Management Center, or using the scrgadm utility. You can change the extension properties listed in Table C-2 using the scrgadm utility with the -x parameter=value option. Table C-2 SUNW.
Configuring Extension Properties Table C-3 How the Fault Monitor Interprets Probes Directory Server running in... Probe Used Algorithm Normal mode ldapsearch 1. Attempt a search. 2. If the search operation results in: • LDAP_SUCCESS, then the service is considered healthy. • An LDAP error, then the service must be restarted. • A problem other than timeout, then the fault monitor probes again depending on Monitor_retry_count and Monitor_retry_interval.
Synchronizing HA Storage and Data Services Synchronizing HA Storage and Data Services The SUNW.HAStorage resource type synchronizes actions between HA storage and data services, permitting higher performance when a disk-intensive data service such as Directory Server undergoes fail over. To synchronize a Directory Server data service with HA storage, complete the following steps on the node that is online for the logical host name in use by the data service: 1. Register the HA storage resource type.
Uninstalling 3. Add the Directory Server to the failover resource group created in “Setting Up Network Resources,” on page 173. # scrgadm -a -j resource-name-ds -g resource-group -t SUNW.dsldap \ -y Network_resources_used=logical-host-name \ -y Port_list=port-number/tcp \ -x Confdir_list=ServerRoot/slapd-serverID Here you provide a new resource-name-ds to identify the Directory Server instance. The resource-group parameter is the name of the group specified in “Setting Up Network Resources,” on page 173.
Uninstalling # scrgadm -r -t SUNW.dsldap # scrgadm -r -t SUNW.mps 4. Delete the server configurations. # /usr/sbin/mpsadmserver unconfigure # /usr/sbin/directoryserver unconfigure 5. Remove the packages installed, including SUNWdsha and SUNWasha, from each node using the pkgrm(1M) utility.
Uninstalling 184 Sun ONE Directory Server Installation and Tuning Guide • June 2003
Index A access control 155–156 access log 140 approximate indexes 132 audit log 142 B network resources 173 prerequisites 171–172 resource extensions 178 configuration directory 18 core files enabling generation of 34, 38 sizing for 88 coreadm 34, 99 currententrycachecount 123 currententrycachesize 123 browsing indexes 131 D C cache database 108 entry 109 file system 111 import 110 monitoring 119, 123 optimizing 118–123 priming 122 total size 111 use in searches 112–114 use in suffix initialization 116
H hardware sizing. See sizing I idsktune 28, 31, 35, 97, 98, 101, 102 indexes 32-bit vs.
nsslapd-db-logdirectory 148 nsslapd-directory 89, 125 nsslapd-errorlog 88, 144 nsslapd-errorlog-logging-enabled 144 nsslapd-errorlog-logmaxdiskspace 144 nsslapd-errorlog-logminfreediskspace 144 nsslapd-idletimeout 150 nsslapd-import-cachesize 82, 110 nsslapd-infolog-area 144 nsslapd-infolog-level 145 nsslapd-ioblocktimeout 150 nsslapd-listenhost 152, 154 nsslapd-lookthroughlimit 127, 135 tuning search sizes 150 nsslapd-maxbersize 151 nsslapd-maxconnections 82 nsslapd-maxdescriptors 153, 154 nsslapd-maxthrea
troubleshooting 46–49 tuning access control 155–156 blocked connections 150 cache 75, 107–123 entry sizes 151 file descriptors 103, 153, 154 generating recommendations 101 idle connections 150 indexes 134–138 IP interfaces 152, 154 large files 103 logs 76, 140–148 plug-ins 156–157 resource limits 76, 149–152 search sizes 151 SSL 165–170 system resources 152–155 system settings 102–106 TCP 104–106, 153 threads 103, 151, 155 time limits 152 tips 73–77 U uninstallation 41–45 cluster 182 upgrading custom 4.