iPlanet Directory Server 5.0 Installation

1. Introduction to iPlanet Directory Server 5.0

Target Skills:

At the end of this page you will be able to...

Describe the purpose of a Directory Server.

Describe the basic architecture of iPlanet Directory Server.

Describe how indexes are used to optimize the performance of iPlanet Directory Server.

Describe Directory Service design process.

iPlanet Directory Server provides a centralized directory service for an intranet or extranet. Directory Server integrates with existing systems and acts as a centralized repository for the consolidation of employee, customer, supplier, and partner information. It can be extended to manage user profiles and preferences, as well as extranet user authentication.

What is a Directory Service

The following are the key frames from the animation "What is a Directory Service?".

About Global Directory Services

The following are the key frames from the animation "Global Directory Services".

Introduction to iPlanet Directory Server

The following are the key frames from the animation "iPlanet Directory Server ".

Directory Entries and Indexing

The following are the key frames from the animation "Directory Entries and Indexing".

Directory Design

There is more to fielding a directory service than simply installing the software. Directory service design can be a complex process that involves a wide variety of considerations. iPlanet Learning Solutions offers lecture/lab courses that address this task. These courses are:

Consult your iPlanet representative for information and schedules for attending these classes or visit the iPlanet Learning Solutions web site at:

www.iplanet.com/learning/

Design Process Outline

At a high level, the process of designing a directory service involves the following steps:

A directory will contain data such as user names, telephone numbers, and group details. Analyzing the existing data sources of an organization is key to understanding their relationship and identifying what data items should be included in a directory service.

Once you decide what data the directory contains, you need to organize and reference that data. This is the purpose of the directory tree.

Topology design involves determining how you divide your directory tree among multiple physical Directory Servers and how these servers communicate with one another.

Replication is the means by which the same directory data is maintained in multiple Directory Servers in order to increase performance and provide fault tolerance.

You need to plan how to protect the data in the directory and design the other aspects of your service to meet the security requirements of your users and applications.

Summary

In this section, we've looked at directory services, what they are and how they are used, we've discussed global directory services and how iPlanet Directory Service 5.0 provides just such a service. We then looked at the basic architecture of iPlanet Directory Server and saw how the front-end, the backend and the LDBM database work together to provide directory services. Finally, we investigated the basic structure of directory entries and looked at how indexing is used to improve the performance of the Directory Server.

 

 

2. What's New with iDS 5.0

Directory Server 5.0 is the latest release of the highly successful Netscape Directory Server 4.0 and features a new architecture that provides carrier-grade scalability, performance and availability.

New features include multi-master support, roles, class of service, improved access control mechanisms, chaining and multiple backend database support.

Combined, these features will allow the implementation of a highly available directory service which can scale to tens of millions of entries with fast read and write performance.

Target Skills:

At the end of this page you will be able to...

Identify the new features of iPlanet Directory Server.

New and Improved Management Console

Administrative tasks are performed through the Administration Server.

Multiple Databases

The database is the basic unit you use for tasks such as replication, performing backups, and restoring data.

 

Multi-master Replication

iPlanet Directory Server 5.0 supports complex replication scenarios. in which the same subtree can be mastered on two servers.

 

Legacy Consumer Replication

iPlanet Directory Server 5.0 can be involved in replication scenarios with earlier releases of the Directory Server, providing the following conditions are met:

The following restrictions apply:

The main advantage of being able to use a Directory Server 5.0 as a consumer of a legacy Directory Server is to ease the migration of a replicated environment.

Note The Directory Server Console will not prevent you from configuring a database as a read-write replica, and enabling legacy consumer settings. This makes migration easier because you can configure your 5.0 Directory Server as you want it to be after the migration, and activate legacy consumer settings just for the duration of the transition.

Roles

Roles are a new entry grouping mechanism that unify the static and dynamic groups described in the previous sections. Roles are designed to be more efficient and easier to use for applications. For example, an application can locate the role of an entry, rather than select a group and browse the members list.

 

Class of Service

Class of service (CoS) allows you to share attributes between entries in a way that is transparent to applications. CoS simplifies entry management and reduces storage requirements.

Improved Access Control Mechanism

The access control mechanism now supports macros to dramatically reduce the number of access control statements, and proportionally increase the speed of access control evaluation in the server.

In organizations that use repeating DIT structures, it is possible to optimize the number of ACIs used in the directory by using macros. Reducing the number of ACIs in your DIT makes it easier to manage your access control policy, and improves the efficiency of ACI evaluation.

Macros are placeholders that are used to represent a DN, or a portion of a DN in an ACI. You can use a macro to represent a DN in the target portion of the ACI, or in the bind rule portion, or both. In practice, when the Directory Server gets an incoming LDAP operation, the ACI macros are matched against the resource targeted by the LDAP operation. If there is a match, the macro is replaced by the value of the DN of the targeted resource. The Directory Server then evaluates the ACI normally.

Macro ACI Syntax

Macro ACIs include the following types of expressions to replace a DN or part of a DN:

Macro
ACI Keyword
($dn) target, targetfilter, userdn, roledn,groupdn, userattr
[$dn] targetfilter, userdn, roledn, groupdn, userattr
($attr.attrName) userdn, roledn, groupdn, userattr

The following restrictions apply:

In short, you when using any macro, you always need a target definition that contains the ($dn) macro.

You can combine the ($dn) macro and the ($attr.attrName) macro.

Distribution and Chaining

 

Multiple Databases

The database is the basic unit you use for tasks such as replication, performing backups, and restoring data.

 

Summary

In this section we investigated the new features of iPlanet Directory Server 5.0. In the next section we will begin installing the product on a "sandbox" Solaris system.

 

3. Preinstallation Planning

Target Skills:

At the end of this page you will be able to...

Describe the necessary steps for preparing your test system for iDS 5.0 installation.

Overview

Now that we have had an introduction to Directory Server 5.0 we are ready to start working with it. The remainder of this training will focus on developing hands-on skills with iDS 5.0 including installation, configuration, administration, and migration. The installation process can be broken into three parts.

  1. Preinstallation Planning
  2. Getting the Product Software and
  3. Installing the Software

This page will guide you through the first step, Preinstallation Planning.

We suggest that you follow these procedures on a suitable test system running Solaris 2.6 or 8.

Q: How can I deploy iDS 5.0 on a production system for my organization?

A: In this training we will only be showing you how to install, configure, and administer on a test system. If you are interested in developing the knowledge and skills necessary to design an enterprise directory service solution for your organization, we recommend the instructor-led class, Netscape Directory Services: Analysis and Planning 4.x

Before we start installing iDS 5.0 , we will make sure our test system is capable of supporting it.

Step 1 : Login As Root

The Server software needs to be installed by someone with root-level privileges on the target system.

If you're already logged in with a username other than root, it is our strong recommendation that you log out completely and log back in as root or use the su command appropriately.

Q: Why do I need to be logged in as root?

A: We must install as root because we would like to run the server on a port below 1024. We would like to use the default ldap ports 389 and 636 (the iDS SSL port). If you choose port numbers higher than 1024, you can install using any valid UNIX account.

Step 2: Check Solaris Version

Determine your system's version of Solaris by entering uname -r. The command should show either 5.6 or 5.8 as shown below.

# uname -r
5.6

5.8

Step 3: Check Free Disk Space

Determine your system's current disk usage by entering

# df -lk

Look for a directory with at least 200MB of disk space available for downloading and installing the Directory Server. For this exercise, we will use a directory called /train. /train/iplanet/servers will function as our server root.

Q: How should I create my server root for my production installation?

A: Your server root is the directory where you install your iPlanet servers. The default server root for iPlanet Directory Server is /usr/iplanet/servers. To learn more see Creating a New Server Root.

You'll also need a staging area to unpack the distribution software and start the installation. This staging area can be anywhere on your local system. We will be using the /train directory as the staging area as well. Within the /train directory, we will be creating a temporary directory for downloading the Directory Server software called /temp.

Step 4: Find gunzip

The server software (also referred to as product binaries) is distributed in a gunzip format so you'll need a utility program called gunzip before you can start the installation. You can determine if gunzip is in your path by entering

# which gunzip

If the which command was unable to locate gunzip ,try locating it by using

# find / -name gunzip -print
  /user/local/bin/gunzip

In this example, it was found in /user/local/bin. We will need to know this location later when we unpack the server software.

Note: gunzip comes as a component of Solaris 8.

Step 5: Check Available Ports

In the environment we are using for this exercise, we will be installing products on the following ports 389, 636, and 5000.

389    Default port for the Directory Server.
 636    Default port of the Directory Server's SSL.
5000  Port for the Directory Server's Administrator.

If you are running other products on these ports, make sure they are shut down. You can determine if these ports are in use by entering netstat -an | grep <port number>.

# netstat -an | grep 389
# netstat -an | grep 636
# netstat -an | grep 5000

If you don't get any response, you can assume these ports aren't currently being used for anything. If you find that you do have something running, free up that port.

Summary

In this section we prepared to install iPlanet Directory Server 5.0. We checked that we are running either Solaris 2.6 or 8, have enough free disk space and memory, and have the appropriate port numbers available. In addition, we found gunzip and noted its location. Next we will locate and download the iPlanet Directory Server 5.0 software.

4. Getting the Product Software

Target Skills:

At the end of this page you will be able to...

Find the location of the iDS 5.0 software.

  Download the iDS 5.0 software onto your test system.

Before installing iPlanet Directory Server 5.0 on to your Sun test workstation, we will need to find and download the product software. Let's get started.

Step 1: Create a temporary directory

In the train directory, create a directory called temp. We'll use this directory to unpack the installation software, but this will not be the final location of the Directory Server.

# mkdir /train/temp

Step 2: Go to the iPlanet download site

Point your web browser to the iPlanet download page. The link below will take you there in a new window.

http://www.iplanet.com/downloads/download/

The iPlanet download page looks like this:

Step 3: Go to the iPlanet Web Servers page

Scroll down until you see the heading for iPlanet Directory and Security Services. Click on the link iPlanet Directory Server 5.0.



Q: How can I get the latest updates?

A: To benefit from the latest fixes, we recommend installing the latest patches. When you go to install iDS 5.0 on your actual system, you should install the patches before installing the iDS 5.0 software. To see a list of the patches installed on your system type the command "showrev -p."

# showrev -p

Step 4: Locate the Solaris version

When the download page for iPlanet Directory Server 5.0 appears, scroll down the page and look for the table shown here. Click on the Download link for the English, Worldwide (128-bit encryption) iPlanet Directory Server 5.0 for Solaris.

Step 5: Complete the registration form

Enter your name and other relevant information. Be sure to complete all sections of the form or else you'll be returned to it again.

When you've completed the registration form, enter your email address and click the Login button. This should begin the download process.

Step 6: Download the software

Save the compressed file in the /temp directory we created in Step 1.

Your temporary directory should now contain a file named directory-5.0-us.sparc-sun-solaris2.6.tar.gz.The size of this compressed file is about 53 MB.

You can dismiss the second browser window at this point (the one with the iPlanet test-drive site).

Step 7: Unpack the installation software

After the file is downloaded you'll need to unpack and untar it. Use the following command to perform both operations at once:

# gunzip -c *.gz | tar -xvf -

When this operation finishes you should have the files shown below in your temp directory. Use the ls command to list them.

# ls

LICENSE.txt
README.txt
admin
base
directory-5.0-us.sparc-sun-solaris2.6.tar.gz
nsperl
perldap
setup
setup.inf
silent.inf
slapd
svrcore

Summary

In this section we located and downloaded the iPlanet Directory Server 5.0 software. Next, we will use the ./setup command to install the server.

5. Installing the Software

Target Skills:

At the end of this page you will be able to...

Install iDS 5.0 on your test system

Step 1: Run Setup

The Directory Server installation script, setup, should be in your /train/temp directory.

#./setup

The setup script will now ask you a series of questions.

Step 2: Acknowledge the Welcome notice

You should see a message saying "Welcome to the iPlanet Directory Server installation program" along with the following question:

Would you like to continue with installation? [Yes]:

Answer Yes, or simply press the return key.

Q: What is the purpose of answering "no" to this first question?

A: By answering "no" users can easily exit the setup program. One reason you might exit the setup program would be to log in as root or su before running setup.

Step 3: Accept the license agreement

Do you agree to the license terms? [No]: Yes

Agree to the license statement. Note the default is No. Be sure to enter a y or Yes.

Step 4: Select Console and Directory Server Installation

Select the component you want to install [1]:

Agree to the default selection, choice 1 (Install Netscape Servers and the integrated iPlanet Console) by pressing the return key.

Q: What is the iPlanet Console?

A: The iPlanet Console provides the common user interface for all iPlanet server products. From it you can perform common server administration functions such as stopping and starting servers, installing new server instances, and managing user and group information. iPlanet Console can be installed as a stand-alone application on any machine. You can also install it on your network and use it to manage remote iPlanet servers.

 

Step 5: Select Typical Installation

To accept the default shown in brackets, press the Enter key. Choose an installation type [2]:

Accept the default selection, "Typical Installation" by pressing the return key.

Q: What is the difference between typical and express installations?

A: Both the Typical and Express Installation can be used for testing or evaluating iDA 5.0. Because the Express version does not offer you the choice of selecting your server port number or your directory suffix, you should not use it for production installations.

 

Step 6: Select Location for Server Files

Install location [/usr/iplanet/servers]:/train/iplanet/servers

Enter the full path of the location where you want to install your server. The location that you enter must be some directory other than the directory from which you are running setup. If the directory that you specify does not exist, setup creates it for you.

We recommend the following path: /train/iplanet/servers.

 

Step 7: Select All Installation Components

Specify the components you wish to install [All]:

Accept the default selection, All by pressing the return key.

Step 8: Select Core Components

Specify the components you wish to install [1, 2, 3]:

Accept the default selection, 1,2 and 3 by pressing the return key.

Step 9: Select Directory Suite Components

Specify the components you wish to install [1, 2]:

Accept the default selection, 1 and 2 by pressing the return key.

Step 10: Select Administrative Services Components

Specify the components you wish to install [1, 2]:

Accept the default selection, 1 and 2 by pressing the return key.

Step 11: Set Computer Name

Computer name [arius.mcom.com]:

Accept the default selection which should already be set to the name of your target system. In the example above, the hostname is arius.

Step 12: Set System User and Group

System User [nobody]:
System Group [nobody]:

Accept the default selections for System User and System Group: nobody by pressing the return key.

At this point the installation program may appear to freeze- be prepared to wait about 30 seconds for the next question to appear.

Step 13: Use the New Directory Server for Configuration Data

Do you want to register this software with an existing Netscape configuration directory server? [No]:

Accept the default selection, No by pressing the return key.

Q: What do I choose when performing an installation on my production system?

A: For the configuration directory, select the default if this directory will host your o=NetscapeRoot tree. Otherwise, enter Yes. You will then be asked for the contact information for the configuration directory. If the server you are currently installing is not the configuration directory, then the configuration directory must exist before you can continue the installation.

 

Step 14: Use the New Directory Server to Store Data

Do you want to use another directory to store your data? [No]:

This question asks if the iDS 5.0 server you are currently installing will be the one for your user data. In most installations, you can select the default, "no."

Accept the default selection, No by pressing the return key.

Q: In what case would you answer "yes"?

A: If this server instance is intended to be only a configuration directory, then you should enter Yes.

 

Step 15: Set Network Port Number

Directory server network port [389]:

Accept the default selections for main network port number, 389 by pressing the return key. If you have another application using that port, you should choose another port number.

Step 16: Enter Directory Server Identifier

Each instance of a directory server requires a unique identifier. Press Enter to accept the default, or type in another name and press Enter. Directory server identifier [arius]:


Use the default identifier, which is the name of the target system by pressing the return key.

Q: What is the unique identifier used for?

A: This value is used as part of the name of the directory in which the Directory Server instance is installed. For example, if your machine's host name is phonebook, then this name is the default and selecting it will cause the Directory Server instance to be installed into a directory labeled slapd-phonebook.

 

Step 17: Enter Administrator's Name and Password

Netscape configuration directory server administrator ID [admin]:

Password:admin
Password(again):admin

Use the default administrator ID, admin. We suggest you use the same word for the password: admin. You'll have to enter the password twice. Note this is the password you'll use to login to Netscape Console. If you use anything other than the defaults listed here, be sure to write them down! Press the return key after entering each password.

Step 18: Use the New Directory Server to Store Data

The suffix is the root of your directory tree. You may have more than one suffix. Suffix [dc=mcom, dc=com]:

Accept the default selection by pressing return, which should already be set to the domain of your target system.

Q: How should I pick a directory suffix for my organization for a production installation?

A: For a directory suffix, enter a name meaningful to your enterprise. This string is used to form the name of all your organization's directory entries. Therefore, pick some name that is representative of your organization. We recommend that you pick a suffix that corresponds to your internet DNS name. For example, if your organization uses the DNS name siroe.com then enter dc=siroe, dc=com here. These may already appear as your default values.

Step 19: Enter the Directory Server Administrator's Name and Password

Directory Manager DN [cn=Directory Manager]:
Password:dirmanager
Password (again):dirmanager

Here you will enter the distinguished name that you will use when managing the contents of your directory with unlimited privileges. Accept the default selection for Directory Manager DN. We suggest you use the password dirmanager. Note the password must be 8 characters long.

Q: How should I pick the Directory Manager DN for a production installation?

A: In former releases of the Directory Server, the Directory Manager was known as the root DN. This is the entry that you bind to the directory as when you want access control to be ignored. This distinguished name can be short and does not have to conform to any suffix configured for your directory. It also should not correspond to an actual entry stored in your directory.

 

Step 20: Confirm the Administrative Domain

Administration Domain [mcom.com]:

Accept the default selection by pressing the return key.

Step 21: Enter Administrative Port Number

The default in brackets was randomly selected from the available ports on your system. To accept the default, press return. Administration port [18069]:5000

Type in 5000 and press return. We are using the value 5000 to indicate a 5.0 Directory Server, however you may choose any port number that is not in use when you complete your production installion.

Q: What is the Administration Server for?

A: The Administration Server is a common front-end to all iPlanet servers. It receives communications from iPlanet Console and passes those communications on to the appropriate iPlanet server. Your site will have at least one Administration Server for each server root in which you have installed an iPlanet server.

Step 22: Set Administrative User Privileges

Run Administration Server as [root]:

For the user you want to run the Administration Server as root. This is the default. Accept the default selection by pressing the return key.

Step 23: Observe Server Installation Messages

Press Return to continue...

Press the return key.

At this point the server is unpackaged, minimally configured and started. You are told what host and post number the Administration Server is listening on.

Step 24: Check the Server Process

Use the ps command to look for the slapd process

Go to /train/iplanet/servers and type startconsole to begin managing your servers.

# ps -ef | grep slapd
     nobody 669 666 0:16:33:47 pts/4      0:00 ./ns-slapd -f ...

You should see a process owned by nobody listed as ./ns-slapd.

Summary

In this section we used the ./setup command to install the iPlanet Directory Server 5.0. In the next section we will use the iPlanet console to configure the server.

6. Configuring the Server

Target Skills:

At the end of this page you will be able to...

Start the iPlanet Console

Create and delete indexes using iPlanet Console

Edit performance parameters using iPlanet console

Overview

The term "configuration tasks" refers to administrative activities that are usually performed right after installation and only occasionally thereafter. In contrast, "administration tasks" are activities that are performed routinely, such as starting and stopping the server and adding new users. Those activities are covered in the following page, "Basic Administration."


Configuration During Installation

Your Directory Server was configured to some minimum degree during the installation process. All runtime activities are controlled by configuration parameters, and you've already specified the most important ones when you ran the setup program.

Configuration parameters set during installation include the following:

 root DN
 server root
 network service port number
 administrator's login and password
 administrative port number

Your Directory Server was up and running as soon as you completed the installation process, but there are still some parameters that you might want to modify.

Configuration with iPlanet Console

You can change most of the Directory Server's parameter values from the various forms provided in Netscape Console. This is the quickest and easiest way to configure your Directory Server.

Configuration from the Command Line

Many tasks may also be performed from the command line. Because of the introductory nature of this training, we will be covering configuration and administrative tasks mostly through the iPlanet Console. Detailed information about command line configuration and administration is available in the iPlanet Directory Server 5.0 Administrator's Guide.

 

Using iPlanet Console

Step 1: Start the iPlanet Console

To start the iPlanet console, navigate to /train/iplanet/servers/ and use the startconsole command.

# cd /train/iplanet/servers
#./startconsole

Next the Console window will appear.

 

Step 2: Log in as Administrator

Enter the User ID and password you specified when you ran the Setup program. The default ID is admin (that's also what we suggested for the password).

 

Step 3: Expand the Server Group Selection

Click on the icon representing your target system, then expand the Server Group selection to display the two servers you installed earlier: the Admin Server and the Directory Server.

Step 4: Open the Directory Server Administration Window

Click on the icon representing your target system, then expand the Server Group selection to display the two servers you installed earlier: the Admin Server and the Directory Server .

When you've found the icon representing our Directory Server, click on the button labeled . Open in the upper right-hand corner of the window.

Most of the configuration parameters that affect the Directory Server are accessed by controls in this window. We'll step through the process for changing them in the next section.

Creating and Deleting Indexes with iPlanet Console

To make sure you are getting the most out of your indexing, you need to understand the type of searches your client performs. You should set indexes on the attributes that your client is going to request often. For example, if your client is a mail server, it will most likely search only for an exact match on the UID attribute. You would therefore set indexes on the UID attribute. You would not need to index other attributes or use sub-string indexes unless the directory is servicing other types of clients as well.

If possible, reduce the number of indexes being used by the directory server. For example, if the directory server is used solely for mail lookups, only the following attributes need to be indexed (using exact match only): uid, mail, mailHost, and mailAlternativeAddress. These four attributes must be indexed regardless. For the change to take effect after index changes, the database will need to be recreated. Note that if an index is added or modified, then the existing records must be exported to a LDIF file before recreating the database. A command line utility is available if only one index or one member is added.

What is a Directory Service

The following animation illustrates how indexes are created and deleted.

 

Changing Performance Parameters

Now that you've got iPlanet Console running and have found the Administrative window for your Directory Server, there are several parameters you can change which can improve your server's performance.

Click on the Configuration tab to display the window shown here:

The Directory Server's administrative window provided by iPlanet Console lets you set some key configuration parameter values. If you click on the Performance tab in the Configuration window you'll have the opportunity to set 3 of them:



Size limit in entries: This parameter specifies the maximum number of entries the server will return to the client in response to a search operation. If this limit is reached, the server returns any entries it has located that match the search request, as well as an exceeded size limit error. The default value for this parameter is 2,000. Decreasing this value could reduce your average search time but will also limit the number of results returned on very large searches.



Time limit in seconds: This parameter specifies the maximum amount of real time the server spends performing a request. If this limit is reached during a search, the server returns any entries it has located that match the search request, as well as an exceeded time limit error. The default value for this parameter is 3,600. Decreasing this value will produce similar results to decreasing Size Limit.



Idle Timeout: This parameter specifies the amount of time in seconds afterwhich an idle LDAP client connection is closed by the server. A value of 0 indicates that the server will never close idle connections.

Summary

In this section we described what configuration takes place during installation and suggested ways to further configure your Directory Server using the iPlanet Console.

 

 

7. Basic Administration

Target Skills:

At the end of this page you will be able to...

Perform an import from the console.

Create new users.

Start and stop the Directory Server.

In this section we will describe how to perform three of the most common administrative tasks.

1. Populating the Directory Tree
2. Creating new users
3. Stopping and starting the directory server

Populating the Directory Tree

During installation, a simple directory database was created for us. In addition, a simple directory structure was placed in the database for us to use. This directory structure contains both the basic access control and the major branch points for the recommended directory structure. Using this structure as our base directory tree, we are ready to populate it with entries.

In this exercise we will use the iPlanet Console to import data. The following animation will show us how.

 
 
 
   
     

There are also other ways you can create and populate your directory suffixes. These are explained in detail in the iPlanet Directory Server 5.0 Administrator's Guide.

Creating new users

You can use the iPlanet Console to create new users.

 
 
 
 

Stopping and Starting Directory Server with iPlanet Console

The Administration Server automatically starts once it's installed. When you need to restart the server, you can start it from iPlanet Console or from the command line. Below we explain the steps for using the iPlanet Console.

Step 1: Stop the Directory Server

From the console, double click on the Directory Server icon . Once the Directory Server is selected select "Stop Server."



There will be a dialog to confirm that you want to stop the server. Next, you will see a confirmation that the Directory Server has stopped.

Step 2: Start the Directory Server

To start the Directory Server, return to the Directory Console Window. Double click on the Directory Server icon, to open the panel of tasks as shown below. Click on "Start the Directory Server."

You will know that the server has started again when you see a screen like the one shown below.

Q: How can I stop and start my Directory Server just using the command-line?

A: If you prefer to use the command-line for stopping and starting follow this procedure.

Step 1: Navigate to your directory server root.

# cd /train/iplanet/servers/slapd-airus/

Step 2: Use one of the following scripts

To stop the server use...

# ./stop-slapd

To start the server use...

# ./start-slapd

Summary

In this section we described three basic admininstrative tasks. We showed how to import data into the directory tree, create new users, and stop and start the directory server. In our next section we will practice migrating our server.

 

8. Migration

Target Skills:

At the end of this page you will be able to...

Describe how to migrate from a previous version of the Directory Server to iDS 5.0

This page describes how the migration script works and walks you through a test migration from Netscape Directory Server 4.12 to iDS 5.0. It is divided into three sections.

  1. Migration Overview
  2. Prerequisites
  3. Migration Procedure

Migration Overview

The migration process is performed by simply running the migrateInstance5 script on the system where your previous version of the Directory Server is installed. The provided migration script can facilitate upgrading from Netscape Directory Server 4.0, 4.1, 4.11, or 4.12.

Q: What does the migration script [migrateInstance5] do?

A: The migration script performs the following tasks in sequence:

 Backs up your current configuration.

 Checks the schema configuration files, and notifies you of any changes between the standard configuration files and the ones present on your system.

 Creates a database for each suffix stored in the previous version of the Directory Server. (In Directory Server 5.0 you can have multiple databases, but just one suffix per database).

 Migrates the server parameters and database parameters. (In Directory Server 5.0, these are stored in the directory itself).

 Migrates user-defined schema objects.

 Migrates indexes. Migrates standard server plug-ins.

 Migrates the certificate database, and SSL parameters

 Shuts down your previous version of the Directory Server before performing the migration process.

 

Prerequisites

This section lists the prerequisites that your system will need to meet before you can begin the migration process in the form of a checklist.

Migration Prerequisite Checklist


Prerequisites
  1. You must be using Directory Server 4.0, 4.1, 4.11, or 4.12. When you run the migration script, the previous version of the server process ns-slapd should be stopped.
  2. Your previous version of the Directory Server and your new Directory Server 5.0 should be installed on the same host; migration should occur on local drives.
  3. When you install iPlanet Directory Server 5.0, you must choose different ports for secured LDAP connections.
  4. Your iPlanet Directory Server 5.0 must be running when you execute the migration script.


Q:What prerequisites apply when I perform migration on my production system?

A: All of the prerequisites listed above apply. In addition, there are two additional prerequisites:

1. Any custom schema that you created in your previous version of the Directory Server must be stored in the slapd.user_oc.conf and slapd.user_at.conf files. If it is not, refer to the procedure described in Identifying Custom Schema to move it to those files.

2. Set the following environment variables:
 PERL5LIB=server5root$/bin$/slapd$/admin$/bin
 PATH=server5root$/bin$/slapd$/admin$/bin
where server5root represents the directory under which you installed the Directory Server.

 

Migration Procedure

Now we are going to practice migrating a previous version of the server to iDS 5.0. In this exercise, we will assume that you have followed the installation instructions up until now and still have Directory Server 5.0 running on your test system. You will want to follow these procedures as root user.

Step 1: Start with a clean test system

If you still have iDS 5.0 running and installed, now is a time to uninstall. Navigate to your iDS 5.0 root and type in the uninstall command as shown in the example above.

#cd /train/iplanet/servers
# ./uninstall

Following uninstallion you may still have remaining files. Navigate to one level above your root directory and use rm -rf to remove that directory and its subdirectories. You can use ls to confirm that all the files have been removed.

#cd /train
#ls
  iplanet
# rm -rf iplanet
#ls

Step 2: Install Directory Server 4.12

Directory Server 4.12 will act as your previous version of the server. To install Directory Server 4,12, we recommend following the instructions for installing Directory Server 5.0 found in this training with the following modifications.

1. Choose the 4.12 version from the iPlanet Test Drive Site.

2. Save it in a file separate from where the iDS 5.0 will be. We recommend saving the Netscape Directory Server 4.12 in a directory called temp1 outside of the previous directory but still in train.

3. Install your 4.12 Server into the temp1 directory you created.

Install location [/usr/netscape/server4]:/temp1/netscape/server4

4. Choose the default ports.

Q: Why choose the same ports?

A: By continuing to use the same ports for the previous version of the server and for iDS 5.0 (port 389 for the Directory Server and port 4000 for the Administrative Server) you can ensure that the applications pointing to the previous version of the server will now point to your new server.

For the directory server-

Directory server network port [389]:389

For the administrative server-

Administrative server network port [13294]:4000

Step 3: Stop your previous version of the Directory Server.

Navigate to the root folder of your 4.12 Directory Server and stop the slapd process. Note that if you do not stop it, the migration script does it for you.

# cd /train/temp1/netscape/server4/slapd-arius
# ./stop-slapd

Also, stop the admininstrative server by navigating to the server root directory and typing ./stop-admin.

# cd /train//temp1/netscape/server4/
# ./stop-admin

 

Q: How can I confirm that my server stopped?

A: Type the stop command again. This time it should tell you that the server has already stopped as shown below.

For the directory server-

# ./stop-slapd
server not running

For the administrative server-

# ./stop-admin
server not running

Step 4: Install a new 5.0 Directory Server

The installation process is outlined in Installing the Software. You can begin by running the ./setup command on the software you still have in your /train directory.

Step 5: Run the migration script

Navigate to
/train/iplanet/servers/bin/slapd/admin/bin ,
then enter the following command:
migrateInstance5 -D rootDN -w passwd -p port -o server4ID -n server5ID [-h host]

where:

rootDN= "cn=Directory Manager"
DN for Directory Manager in Directory Server 5.0

passwd = dirmanager
password for Directory Manager in Directory Server 5.0

port = 389
LDAP port number in Directory Server 5.0

server4ID= /train/temp1/netscape/server4/slapd-<serverID>
path to the previous version of the Directory Server directory

server5ID = /train/iplanet/servers/slapd-<serverID>
path to the Directory Server 5.0 directory

host=
name of the machine on which the migration is performed (localhost by default)

# cd /usr/iplanet/servers/bin/slapd/admin/bin
# ./migrateInstance5 -D "cn=Directory Manager" -w dirmanager -p 389 -o /train/temp1/netscape/server4/slapd-arius -n /train/iplanet/servers/slapd-arius

Note: ./migrateInstance5...appears all on one line.

Q: What can I do if I forget my Directory manager DN or password?

A: You can find out what the Directory Manager DN is by examining train/iplanet/servers/slapd-<server ID>/config/dse.ldif and looking for the rootdn parameter.

In our example it is located in this path: /train/iplanet/servers/slapd-arius/config/dse.ldif

By design the password is not stored in plain text. You will need to reset a new one. To reset your pathword follow the instructions in Common Installation Problems.

Step 6: Provide a path and filename for your backup directory

Accept the default path and filename for your backup directory.

Connected to 5.0 LDAP server

Backup /train/iplanet/servers/slapd-arius/config on
/train/iplanet/servers/slapd-arius/config_backup ...

Where do you want to back up your configuration directory
[/train/iplanet/servers/slapd-arius/config_backup] ?

The following is an extract of the script's output:

Parse the configuration file:
/train/temp1/netscape/server4/slapd-arius/config
/slapd.conf...
Suffix o=mcom.com doesn't exist
Backend: MigratedDB_0 has been created !!!
Suffix dc=arius,dc=mcom,dc=com doesn't exist
Backend: MigratedDB_1 has been created !!!
For the suffix o=NetscapeRoot, we do nothing
Migrate key/cert databases...
Update general server parameters...
Update successfully nsslapd-reservedescriptors
Update successfully passwordHistory
Update successfully nsslapd-errorlog-maxlogsperdir
Update successfully nsslapd-enquote-sup-oc
Update successfully passwordStorageScheme
Update successfully nsslapd-rootpwstoragescheme
Update global LDBM parameters...
Update successfully nsslapd-mode
Update specific backend parameters...
Migrate DSE entries...
Migrate attributes...
Migrate objectclasses...
Migrate indexes...
Migrate plugin's...
Shutting down server slapd-arius . . .
. . .
data processing... Processing...
.
.
.

Step 7:Your previous version of the Directory Server is migrated

As a result of this migration, a new Directory Server 5.0 instance is installed using the configuration information obtained from your previous version of the Directory Server. In addition, the data from your old server is migrated to the new server and the new server is started.

You should receive a message like the one below.

****** End of migration ******

-> Migration started at Tue Mar 6 23:11:42 2001
-> Migration ended at Tue Mar 6 23:13:00 2001

Summary

In this section we walked through the migration process. First we uninstalled iDS 5.0 for a clean start. Then we installed a previous version of iPlanet Directory Server. Finally we migrated this previous version of Directory Server to the latest 5.0 version.