Chapter 1   Introduction to iPlanet Directory Server


The iPlanet Directory Server product includes a Directory Server, an administration server to manage multiple directories, and iPlanet Console to manage both servers through a graphical interface. This chapter provides overview information about the Directory Server, and the most basic tasks you need to start administering a directory service using the console.

It includes the following sections:

• Overview of Directory Server Management

• Using the Directory Server Console

• Starting and Stopping the Directory Server

• Configuring LDAP Parameters

• Starting the Server with SSL Enabled

• Starting the Server in Referral Mode

Overview of Directory Server Management

---

iPlanet Directory Server is a robust, scalable server designed to manage an enterprise-wide directory of users and resources. It is based on an open-systems server protocol called the Lightweight Directory Access Protocol (LDAP). The Directory Server runs as the ns-slapd process or service on your machine. The server manages the directory databases and responds to client requests.

You perform most Directory Server administrative tasks through the Administration Server, a second server that iPlanet provides to help you manage Directory Server (and all other iPlanet servers). iPlanet Console is the graphical interface to the Administration Server. Directory Server Console is a part of iPlanet Console designed specifically for use with iPlanet Directory Server.

You can perform most Directory Server administrative tasks from the Directory Server Console. You can also perform administrative tasks manually by editing the configuration files or by using command-line utilities. For more information about the iPlanet Console see Managing Servers with iPlanet Console.

Using the Directory Server Console

---

The Directory Server Console is an interface that you access as a separate window of the iPlanet Console. You start the Directory Server Console from iPlanet Console, as described in the following procedure.

Starting Directory Server Console

1. Check that the directory server daemon, slapd-serverID is running. If it is not, as root user, enter the following command to start it:

   Solaris 9 platform	# /usr/sbin/directoryserver start
   Other platforms	# installDir/slapd-serverID/start-slapd

2. Check that the administration server daemon, admin-serv is running. If it is not, as root user, enter the following command to start it:

   Solaris 9 platform	# /usr/sbin/directoryserver start-admin
   Other platforms	# installDir/start-admin

3. Start iPlanet Console by entering the following command:

   Solaris 9 platform	# /usr/sbin/directoryserver startconsole
   Other platforms	# installDir/startconsole

   The Console login window is displayed. Or, if your configuration directory (the directory that contains the o=NetscapeRoot suffix) is stored in a separate instance of Directory Server, a window is displayed requesting the administrator user DN, password, and the URL of the Admin Server for that directory server.

4. Log in using the bind DN and password of a user with sufficient access permissions for the operations you want to perform. For example, use cn=Directory Manager, and the appropriate password.

   The iPlanet Console is displayed.

5. Navigate through the tree in the left-hand pane to find the machine hosting your Directory Server and click on its name or icon to display its general properties.

   To edit the name and description of your directory server, click the Edit button. Enter the new name and description in the text boxes. The name will appear in the tree on the left, as shown in the following figure.

Figure 1-1    The iPlanet Console

Click OK to set the new name and description.

6. Double-click the name of your Directory Server in the tree or click the Open button to display the Directory Server Console for managing this directory server.

Navigating the Directory Server Console

The Directory Server Console provides the interface for browsing and performing administration operations on your Directory Server instance. It always displays four tabs from which you can access all Directory Server functionality:

• Tasks Tab

• Configuration Tab

• Directory Tab

• Status Tab

Tasks Tab

The Tasks tab is the first interface visible when opening the Directory Server Console. It contains buttons for all of the major administrative tasks such as starting or stopping the Directory Server as shown in the following figure. To view all of the tasks and their buttons, you may need to resize the console window.

Figure 1-2    Tasks Tab of the Directory Server Console

You must be logged in as a user with directory manager rights in order to perform these tasks. If you try to perform a task with insufficient rights, the console will prompt you for the DN and password of a directory manager.

Configration Tab

The Configuration tab of the Directory Server Console provides interfaces and dialogs to view and modify all directory settings such as those for databases, suffixes, replication, schema, logs, and plug-ins. These dialogs are only available or will only take effect if you are logged in as a user with directory manager rights.

The left side of this tab contains a tree of all configuration functions and the right-hand side displays the interface specific to managing each function. These interfaces often contain other tabs, dialogs or pop-up windows. For example, the following figure shows the general settings for the entire directory.

Figure 1-3    Configuration Tab of the Directory Server Console

When you select a configurable item in the left-hand tree, the current settings for that item will appear in one or more tabs in the right-hand pane. Depending on the setting, some changes will take effect immediately when saved, and others not until the server is restarted. For the explanation and behavior of these settings, please refer to the chapter in this guide that describes each functionality.

Unsaved changes in a tab are signalled by a red mark next to the tab name. Unsaved changes will remain on the tab even if you configure another item or change to one of the other major tabs. The Save and Reset buttons apply to all tabs of a given configurable item, but do not affect the unsaved settings of other items.

Most text fields will only allow you to enter values that have the correct syntax for the setting. By default, the label of the setting and the value that you type will be highlighted in red until its syntax is correct. The Save button will be diabled until all settings have valid syntax. You may choose italic font for highlighting incorrect values, or no highlighting at all, from the Misc. tab of the Edit > Preferences dialog.

Directory Tab

The Directory Tab of the console displays the directory entries as a tree for easy navigation. In this tab, all entries and the attributes they contain can be browsed, displayed and edited.

Figure 1-4    Directory Tab of the Directory Server Console

If the bind DN given during the login has sufficient access rights, the configuration entries are viewed as normal entries and may be modified directly. However, you should always use the dialogs available through the Configuration Tab to change the configuration settings safely.

Several options are available through the View menu to change the layout and contents of the Directory Tab. New layout options include viewing all entries in a single tree, including leaf entries, and also displaying attributes in the right-hand pane. The default is to view leaf entries on the right and not in the left-hand tree.

The View>Display options enable ACI counts, role counts, and inactivation state icons for all entries in the directory tree. In the previous figure, ACI counts and leaf entries are displayed in the left-hand tree, and attribute values for the selected entry are displayed in the right-hand pane.

Status Tab

The status tab displays server statistics and log messages. The tree on the left lists all status items, and when selected, the contents of each is displayed in the right-hand pane. For example, the following figure shows a table of log entries.

Figure 1-5    Status Tab of the Directory Server Console

Viewing the Current Bind DN From the Console

You can view the bind DN you used to log in to the Directory Server Console by clicking the login icon in the lower-left corner of the display. The current bind DN appears next to the login icon as shown here:

Changing Login Identity

When you create or manage entries from the Directory Server Console, and when you first access the iPlanet Console, you are given the option to log in by providing a bind DN and a password. This identifies who is accessing the directory tree and determines the access permissions granted to perform operations.

You can log in with the Directory Manager DN when you first start the iPlanet Console. At any time, you can choose to log in as a different user, without having to stop and restart the Console.

To change your login in iPlanet Console:

1. On the Directory Server Console, select the Tasks tab and click the button next to the label "Log on to the Directory Server as a New User." Or, when in another console tab, select the Console>Log in as New User menu item.

   A login dialog box appears.

2. Enter the new DN and password and click OK.

   Enter the full distinguished name of the entry with which you want to bind to the server. For example, if you want to bind as the Directory Manager, then enter the following in the Distinguished Name text box:

   cn=Directory Manager

The Directory Manager DN and password are futhre explained in the following section.

Configuring the Directory Manager

The Directory Manager is the privileged database administrator, comparable to the root user in UNIX. Access control does not apply to the entry you define as Directory Manager. You initially defined this entry during installation. The default is cn=Directory Manager.

The password for this user is defined in the nsslapd-rootdn attribute.

Use the Directory Server Console to change the Directory Manager DN, its password, and the encryption scheme used for this password:

1. Log in to the Directory Console as Directory Manager.

   If you are already logged in to the Console, see "Changing Login Identity" for instructions on how to log in as a different user.

1. On the Directory Server Console, select the Configuration tab and then select the top entry in the navigation tree in the left pane.

2. Select the Manager tab in the right pane.

3. Enter the new distinguished name for the Directory Manager in the Root DN field.

   The default value is cn=Directory Manager.

4. From the Manager Password Encryption pull-down menu, select the storage scheme you want the server to use to store the password for Directory Manager.

5. Enter the new password and confirm it using the text fields provided.

6. Click Save.

Launching the Help System

The help system for iPlanet Directory Server is dependent upon iPlanet Administration Server. If you are running iPlanet Directory Server Console on a machine remote to Administration Server, you will need to confirm the following:

Client IP address authorized on Administration Server. The machine running iPlanet Directory Server Console needs access to Administration Server. To configure Administration Server to accept the client machine's IP address, do the following in Administration Server:

1. Launch iPlanet Administration Server Console. The console should be running on the same machine as Administration Server.

2. Click the Configuration tab, then click the Network tab.

3. In the Connection Restrictions Settings, select "IP Addresses to Allow" from the pull down menu. Click Edit.

4. Edit the IP Addresses field to the following: *.*.*.*

   This allows all clients access to Administration Server.

5. Restart Administration Server. You can now launch the online help by clicking any of the Help buttons in the Directory Server Console.

Proxy authorized on Administration Server. If you use proxies for your HTTP connections on the client machine running Directory Server Console, you need to do one of the following:

• Remove proxies on the machine running Directory Server Console. This allows the client machine to access Administration Server directly.

  To remove the proxies on the machine running Directory Server Console, you need to alter the proxy configuration of the browser you will use to run the help. In Netscape Communicator, select Preferences from the Edit menu. Select Advanced then Proxies to access the proxy configuration. In Internet Explorer, select Internet Options from the Tools menu.

• Add the client machine proxy IP address to Administration Server list of acceptable IP addresses.

  
  

  ---

  Caution

  Adding the client machine proxy IP address to Administration Server creates a potential security hole in your system.

  ---

  
  

The Console Clipboard

The Directory Server Console uses your system clipboard to copy, cut, and paste text. In addition, it contains a useful feature to reduce typing: when navigating within the Directory tab, you can generate the DN or URL of an entry into the clipboard:

1. On the Directory Server Console, select the Directory tab.

2. Browse through the tree and select (left-click) the entry whose DN or URL you want to copy.

3. Then select either Edit>Copy DN or Edit>Copy URL from the menu.

Do this before opening a dialog or another tab so that you can paste the DN or URL text into any text field.

Starting and Stopping the Directory Server

---

If you are not using Secure Sockets Layer (SSL), you can start and stop the Directory Server using the methods listed here. If you are using SSL, see "Starting the Server with SSL Enabled".

---

Note	On UNIX systems, rebooting the system does not automatically start the slapd process. This is because the installation does not automatically create startup or run command (rc) scripts. See your operating system documentation for details on writing these scripts.

---

Starting/Stopping the Server From the Console

1. Start the Directory Server Console.

   For instructions, refer to "Starting Directory Server Console".

2. On the Tasks tab, click "Start the Directory Server" or "Stop the Directory Server" as appropriate.

When you successfully start or stop your Directory Server from the Directory Server Console, the server displays a message box stating either that the server started or has shut down.

Alternatively, if you are using a Windows NT machine, from the Windows NT Services Control Panel:

1. Select Start > Settings > Control Panel from the desktop.

2. Double-click the Services icon.

3. Scroll through the list of services and select the iPlanet Directory Server.

   The service name is iPlanet Directory Server 5.1 (serverID), where serverID is the identifier you specified for the server when you installed it.

4. Start or stop the service:
   • To stop the service, click Stop and then confirm that you want to stop the service.

   • To start the service, select the Directory Server service and click Start.

Starting/Stopping the Server From the Command Line

With root priveleges, run one of the following scripts:

Solaris 9 platform	# /usr/sbin/directoryserver start
Other platforms	# installDir/slapd-serverID/start-slapd

or

Solaris 9 platform	# /usr/sbin/directoryserver stop
Other platforms	# installDir/slapd-serverID/stop-slapd

where serverID is the identifier you specified for the server during installation.

On UNIX, both of these scripts must run with the same UID and GID as the Directory Server. For example, if the Directory Server runs as nobody, you must run the start-slapd and stop-slapd utilities as nobody.

Configuring LDAP Parameters

---

You can view and change the parameters relevant to the server's network and LDAP settings through the Directory Server Console. This section provides information on:

• Changing Directory Server Port Numbers

• Placing the Entire Directory Server in Read-Only Mode

• Tracking Modifications to Directory Entries

For information on schema checking, see Chapter 9, "Extending the Directory Schema."

Changing Directory Server Port Numbers

You can modify the port or secure port number of your user directory server using the Directory Server Console or by changing the value of the nsslapd-port attribute under the cn=config entry.

If you want to modify the port or secure port for a iPlanet Directory Server that contains the iPlanet configuration information (o=NetscapeRoot subtree), you may do so through Directory Server Console.

If you change the configuration directory or user directory port or secure port numbers, you should be aware of the following repercussions:

• You need to change the configuration or user directory port or secure port number configured for the Administration Server. See Managing Servers with iPlanet Console for information.

• If you have other iPlanet Servers installed that point to the configuration or user directory, you need to update those servers to point to the new port number.

To modify the port or secure port on which either a user or a configuration directory listens for incoming requests:

1. On the Directory Server Console, select the Configuration tab and then select the top entry in the navigation tree in the left pane.

2. Select the Settings tab in the right pane.

3. Enter the port number you want the server to use for non-SSL communications in the "Port" text box.

   The default value is 389.

4. Enter the port number you want the server to use for SSL communications in the Encrypted Port text box.

   The encrypted port number that you specify must not be the same port number as you are using for normal LDAP communications. The default value is 636.

5. Click Save and then restart the server.

   See "Starting and Stopping the Directory Server" for information.

Placing the Entire Directory Server in Read-Only Mode

If you maintain more than one database with your directory server and you need to place all your databases in read-only mode, you can do this in a single operation. Note, however, that if your Directory Server contains replicas, you must not use read-only mode because it will disable replication.

To put the Directory Server in read-only mode:

1. On the Directory Server Console, select the Configuration tab and then select the top entry in the navigation tree in the left pane.

2. Select the Settings tab in the right pane.

3. Select the Make Entire Server Read-Only checkbox.

4. Click Save and then restart the server.

   
   

   ---

   Note	This operation also makes the directory server configuration read-only; therefore, you cannot update the server configuration, enable or disable plug-ins, or even restart the directory server while it is in read-only mode.

   ---

   
   

For information on placing a single database in read-only mode, refer to "Enabling Read-Only Mode".

Tracking Modifications to Directory Entries

You can configure the server to maintain special attributes for newly created or modified entries:

• creatorsName—The distinguished name of the person who initially created the entry.

• createTimestamp—The timestamp for when the entry was created in GMT (Greenwich Mean Time) format.

• modifiersName—The distinguished name of the person who last modified the entry.

• modifyTimestamp—The timestamp for when the entry was last modified in GMT format.

  
  

  ---

  Note

  When a database link is used by a client application to create or modify entries, the creatorsName and modifiersName attributes do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrator who is granted proxy authorization rights on the remote server. For information on proxy authorization, refer to "Providing Bind Credentials".

  ---

  
  

To enable the Directory Server to track this information:

1. On the Directory Server Console, select the Configuration tab and then select the top entry in the navigation tree in the left pane.

2. Select the Settings tab in the right pane.

3. Select the Track Entry Modification Times checkbox.

   The server adds the creatorsName, createTimestamp, modifiersName, and modifyTimestamp attributes to every newly created or modified entry.

4. Click Save and then restart the server.

   See "Starting and Stopping the Directory Server" for more information.

Starting the Server with SSL Enabled

---

On Windows NT, if you are using SSL with your server, you must start the server from the server's host machine. This is because a dialog box will prompt you for the certificate PIN before the server will start. For security reasons, this dialog box appears only on the server's host machine.

On UNIX, you must start the server from the command line.

Alternatively, on either platform, you can create a password file to store your certificate password. By placing your certificate database password in a file, you can start your server from the server console, and also allow your server to automatically restart when running unattended.

---

Caution

This password is stored in clear text within the password file, so its usage represents a significant security risk. Do not use a password file if your server is running in an unsecured environment.

---

The password file must be placed in the following location:

Solaris 9 platform	/usr/iplanet/ds5/alias/slapd-serverID-pin.txt
Other platforms	installDir/alias/slapd-serverID-pin.txt

where serverID is the identifier you specified for the server when you installed it.

You need to include the token name and password in the file as follows:

Token:Password

For example:

Internal (Software) Token:mypassword

To create certificate databases, you must use the administration server and the Certificate Setup Wizard. For information on certificate databases, certificate aliases, SSL, and obtaining a server certificate, see Managing Servers with iPlanet Console. For information on using SSL with your Directory Server, see Chapter 11, "Managing SSL."

Starting the Server in Referral Mode

---

Referrals are used to redirect client applications to another server while the current server is unavailable, or when the client requests information that is not held on the current server.

For example, you can start Directory Server in referral mode if you're making configuration changes to the Directory Server and you want all clients to be referred to another master for the duration. To do this, you must start the server with the refer command.

If the server is already running, you can put it in referral mode by using the Directory Server Console. This procedure is explained in "Setting Default Referrals".

Using the refer Command

On a UNIX machine, to start the Directory Server in referral mode follow these steps:

1. Go to the /bin/slapd/server directory under your installation directory:

   Solaris 9 platform	% cd /usr/iplanet/ds5/bin/slapd/server
   Other platforms	% cd /usr/iplanet/servers/bin/slapd/server

2. Run the refer command as follows:

   # ./ns-slapd refer -D instanceDir [-p port] -r LDAPurl

   where instanceDir is the directory instance for which queries will be referred, port is the optional port number of the Directory Server you want to start in referral mode, and LDAPurl is the referral returned to clients. For information on the format of an LDAP URL, refer to Appendix C, "LDAP URLs."

On a Windows NT machine, to start the Directory Server in referral mode follow these steps:

1. Open a DosPromt command-line window.

2. Go to the following directory under your installation directory:

   cd \iplanet\servers\slapd-serverID\bin\slapd\server

3. Run the refer command as follows:

   slapd.exe refer -D instancDir [p port] -r LDAPurl

   where instanceDir is the directory instance for which queries will be referred, port is the optional port number of the Directory Server you want to start in referral mode, and LDAPurl is the referral returned to clients. For information on the format of an LDAP URL, refer to Appendix C, "LDAP URLs."