This chapter describes how to set up a directory server instance, by using either the graphical user interface (GUI) or the command line interface. The topics in this chapter assume that you have already installed the software, as described in Chapter 2, "Installing the Software".
You can set up the directory server in two ways:
Graphical user interface (GUI). The GUI install uses a Java-based graphical installer that enables you to set up the directory server, load it with data, and get it running in very little time.
The installer asks some basic questions about the server configuration and then gives you the choice of leaving your database empty, loading the server with data from your own LDIF or loading the server with automatically generated sample data. The installer also enables you to configure security and replication, and, optionally, to start the server when the configuration is complete.
Command-line interface (CLI). The command-line install is either interactive, or non-interactive. In a non-interactive installation, you can set up the server without user intervention. In interactive mode, you are prompted for the required information before the configuration begins.
This chapter covers the following topics:
Section 3.1, "Setting up the Directory Server by Using the GUI"
Section 3.2, "Setting Up the Directory Server by Using the CLI"
The following procedure presents a step by step installation using the oud-setup graphical interface.
When you have installed the software, change to the ORACLE_HOME subdirectory.
(UNIX, Linux) $ cd OUD-base-location/ORACLE_HOME (Windows) C:\> cd OUD-base-location\ORACLE_HOME
Ensure that your JAVA_HOME environment variable is set to a supported JVM installation (at least Java 1.6).
Run the oud-setup command to configure the directory server installation.
(UNIX, Linux) $ oud-setup (Windows) C:\OUD-base-location\ORACLE_HOME> oud-setup.bat
The utility launches the graphical installer and creates the Oracle Unified Directory instance in OUD-base-location/instance-dir.
The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:
$ export INSTANCE_NAME=my-oud-instance
The instance is created directly under OUD-base-location by default. To change the instance path, include the path relative to OUD-base-location when you set the INSTANCE_NAME variable. For example:
$ export INSTANCE_NAME=../../local/my-oud-instance
On the Welcome screen, click Next.
The Server Settings screen is displayed.
Enter the following information:
Host Name: Enter the directory server's host name or IP address.
The default is the local host name.
LDAP Listener Port: Enter the LDAP port for the directory server.
The default port that is proposed is the first available port that ends with 389. On UNIX platforms, if you run the installer as a non-root user, the default is 1389, if available.
Administration Connector Port: Enter the port that will be used for administration traffic.
The default administration port is 4444. For more information, see "Managing Administration Traffic to the Server" in Oracle Fusion Middleware Administrator's Guide for Oracle Unified Directory.
LDAP Secure Access: If you want to configure SSL, StartTLS, or both, then click Configure.
Complete the following information:
SSL Access: Select Enable SSL to indicate that the LDAPS (that is, LDAP over SSL) listener should be enabled. Enter the port number on which the directory server listens for connections.
The default secure port that is proposed is the first available port that ends with 636. On UNIX platforms, if you run the installer as a non-root user, the default secure port is 1636, if available.
StartTLS Access: Select Enable StartTLS for LDAP to specify that the LDAP connection handler should allow clients to use the StartTLS extended operation to initiate secure communication over an otherwise insecure connection.
Certificate: Select one of the following radio buttons to obtain the certificate that the server should use for SSL, StartTLS, or both:
Generate Self-Signed Certificate generates a self-signed certificate that can be used to secure the communication. While this is convenient for testing purposes, many clients will not trust the certificate by default, and you might need to configure it manually.
Use an Existing Certificate uses a certificate in an existing JKS keystore, a PKCS #12 file, or a PKCS #11 token. For more information about obtaining certificates, see "Configuring Key Manager Providers" in Oracle Fusion Middleware Administrator's Guide for Oracle Unified Directory.
For production servers, select Use an Existing Certificate, and then select the Keystore Type. Enter the Keystore Path, and Keystore PIN if necessary.
If more than one certificate is defined in the specified key store, you are asked to select one of the certificates from a drop down menu.
Click OK.
Root User DN: Enter the Root User DN, or keep the default, cn=Directory Manager.
Password: Enter the root user bind password.
Password (confirm): Retype the root user bind password.
Click Next.
The Topology Options screen is displayed.
Select one of the following:
This will be a stand-alone server.
This server will be part of a replication topology.
For instructions on setting up a replicated topology, see Section 3.3, "Setting Up Replication During Installation".
Click Next.
The Directory Data screen is displayed.
Specify how to load data into your directory:
Directory Base DN: Enter the base DN for your directory.
The default Base DN is dc=example,dc=com.
Directory Data: Select one of the following data options:
Only Create Base Entry: Creates an entry with the base DN specified previously.
Leave Database Empty: Sets up a database but does not populate any entries.
Import Data from LDIF File: Imports LDIF data from the file specified in the Path field.
Import Automatically-Generated Sample Data: Generates the number of sample entries specified in the Number of User Entries field.
Click Next.
The Oracle Components Integration screen is displayed.
Select one of the following:
No specific integration: Select this option if you want a standard installation. This is the default option.
Enable for EUS (Enterprise User Security): Select this option if you want this server instance to be used as a datastore for Oracle Enterprise User Security.
Note that you can only enable a server instance for EUS if you have enabled SSL access (Described in the Server Settings screen in Step 5 this procedure).
When you enable a server instance for EUS, the following naming contexts are created on the instance:
cn=oraclecontext
cn=oracleschemaversion
cn=subschemasubentry
cn=oraclecontext,<baseDN>
Enable for Oracle Database Net Services: Select this option if you want this server to store the database connect identifiers.
When you enable a server instance for Oracle Database Net Services, the following naming contexts are created on the instance:
cn=oraclecontext
cn=subschemasubentry
cn=oraclecontext,<baseDN>
For more information, see "Configuring the Directory Naming Method" in the Oracle Database Net Services Administrator's Guide.
Click Next.
The Server Tuning screen is displayed.
Select one of the following:
Providing Runtime Options: Click Change to configure any specific JVM setting, or click Next to run the server with the default JVM settings.
For more information, see Section 7.2, "Configuring the Java Runtime Settings During Installation".
Automatic: Select this option, if you want to run a single instance of the server on the system.
The OUD server will be tuned automatically at startup depending on the system resources. Oracle recommends this option to get improved performance when you run a single instance of the server on the system.
Providing Memory Limits: Specify the memory usage of the server, and the server JVM settings are tuned accordingly.
Select Use Same Memory Settings for Offline Tools check box, if you want to specify the same memory limitation to apply to various command-line options, such as import-ldif, export-ldif, verify-index, and rebuild-index.
Providing LDAP Data Information: Select one of the following option:
Tune based on the data to be imported automatically: Select this option, if you want to tune the server based on data the server will contain after the setup is complete.
Note:
This option will not be available, if you have selected the following data option in the Directory Data Screen:Only Create Base Entry
Leave Database Empty
Tune based on the contents of the LDIF file to be imported: This option appears if you have selected Import Data from LDIF File in the Directory Data screen. Select this option, if you want to tune the server based on data the server will contain after the setup is complete.
Use the Contents of an LDIF File to Tune the Server: Click Browse and specify the path of the LDIF file containing the data for tuning the server.
Use the Number of Entries to Tune the Server: Enter the number of entries that the server will contain and their average size for tuning.
If you select the Other option as the size then the Other Size screen is displayed.
Enter an average size for your entries in kilobytes or an example LDAP entry in LDIF format. Click OK.
Click Next.
The Review screen is displayed.
Review your configuration.
Select Start Server when Configuration has Completed to start the server after the directory server has been configured. On Windows systems, select Start Server as a Windows service, if desired.
To display the equivalent command-line installation, select Show Equivalent Command-Line from the drop down menu at the top of the panel. This option displays the non-interactive commands that are run to set up the server with the specified configuration, and can be useful for scripting purposes.
Click Finish.
Click Close.
Test whether the directory server has been set up and started successfully by searching an entry in the directory. For example:
On UNIX systems:
instance-dir/OUD/bin/ldapsearch -h localhost -p 1389 \
-D "cn=directory manager" -w my-password -b "dc=example,dc=com" \
"(objectclass=*)"
On Windows systems:
instance-dir\OUD\bat\ldapsearch.bat -h localhost -p 1389 \
-D "cn=directory manager" -w my-password -b "dc=example,dc=com" \
"(objectclass=*)"
Running oud-setup with the --cli option launches the command-line setup, as described in the following procedure.
When you have installed the software, change to the ORACLE_HOME subdirectory.
(UNIX, Linux) $ cd OUD-base-location/ORACLE_HOME (Windows) C:\> cd OUD-base-location\ORACLE_HOME
Ensure that your JAVA_HOME environment variable is set to a supported JVM installation.
Type oud-setup with the --cli option to launch the install in interactive mode.
(UNIX, Linux) $ ./oud-setup --cli (Windows) C:\> oud-setup.bat -cli
The utility launches the command-line installer and creates the Oracle Unified Directory instance in OUD-base-location/instance-dir.
The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:
$ export INSTANCE_NAME=my-oud-instance
The instance is created directly under OUD-base-location by default. To change the instance path, include the path relative to OUD-base-location when you set the INSTANCE_NAME variable. For example:
$ export INSTANCE_NAME=../../local/my-oud-instance
Enter the root user DN, or press Enter or Return to accept the default (cn=Directory Manager).
Provide a password for the root user and re-enter the password to confirm it.
Enter the LDAP port number for your directory server, or press Enter or Return to accept the default.
If you run the installer as the root user, the default port is 389. If you run the installer as a non-root user, the default port is 1389.
Enter the port number that will be used for administration traffic.
The default administration port is 4444. For more information, see "Managing Administration Traffic to the Server" in Oracle Fusion Middleware Administrator's Guide for Oracle Unified Directory.
Press Enter or Return to create base DNs in the server, or Enter No if you do not want to create base DNs.
Enter the base DN for the directory data, or press Enter or Return to accept the default.
The default Base DN is dc=example,dc=com.
Select one of the following options to set up the directory data:
Only create the base entry creates an entry with the base DN specified previously.
Leave the database empty sets up a database but does not populate any entries.
Import data from an LDIF file imports LDIF data from a file, specified in the following step.
Load automatically-generated sample data generates the number of sample entries specified in the following step.
Type yes if you want to enable SSL and enter the port for LDAPS clients.
If you run the installer as the root user, the default secure port is 636. If you run the installer as a non-root user, the default secure port is 1636.
Type yes if you want to enable StartTLS.
If you enabled SSL or StartTLS in the previous steps, select the certificate type.
Type yes if you want to prepare the server for EUS. This will enable the server instance to be used as a datastore for Oracle Enterprise User Security.
Note that you can only prepare the server for EUS if you have enabled SSL access to the server.
When you enable a server instance for EUS, the following naming contexts are created on the instance:
cn=oraclecontext
cn=oracleschemaversion
cn=subschemasubentry
cn=oraclecontext,<baseDN>
Type yes if you want this server to store the database connect identifiers for Oracle Database Net Services.
When you enable a server instance for Oracle Database Net Services, the following naming contexts are created on the instance:
cn=oraclecontext
cn=subschemasubentry
cn=oraclecontext,<baseDN>
For more information, see "Configuring the Directory Naming Method" in the Oracle Database Net Services Administrator's Guide.
Enter an option depending on how you want to tune the OUD server:
Automatic Tuning
Use the default Java Virtual Machine settings
Use specific Java Virtual Machine arguments
Select Automatic Tuning option, if you want to run a single instance of the server on the system. The OUD server will be tuned automatically at startup depending on the system resources. Oracle recommends this option to get improved performance when you run a single instance of the server on the system.
Enter an option depending on how you want to tune the import-ldif tool:
Automatic Tuning
Use the default Java Virtual Machine settings
Use specific Java Virtual Machine arguments
Type yes or press Enter or Return to accept the default to start the server after the configuration has completed.
Confirm your configuration, and enter 1 or press Enter or Return to accept the default to complete the configuration process.
To display the equivalent non-interactive commands, enter 3. This option displays the commands that are run to set up the server with the specified configuration, and can be useful for scripting purposes.
Test whether the directory server has been set up and started successfully by searching an entry in the directory. For example:
On UNIX:
instance-dir/OUD/bin/ldapsearch -h localhost -p 1389 \
-D "cn=directory manager" -w my-password -b "dc=example,dc=com" \
"(objectclass=*)"
On Windows:
instance-dir\OUD\bat\ldapsearch.bat -h localhost -p 1389 \
-D "cn=directory manager" -w my-password -b "dc=example,dc=com" \
"(objectclass=*)"
If you install the directory server by using the GUI, you can set up replication as part of the installation. If you install the server by using the command-line interface, you must set up replication by using the dsreplication command after the server is installed. For more information, see "Configuring Data Replication With dsreplication" in Oracle Fusion Middleware Administrator's Guide for Oracle Unified Directory.
For the first directory server in your replication topology, follow the instructions in Section 3.1, "Setting up the Directory Server by Using the GUI".
On the Topologies screen, do the following:
Select This server will be part of a replication topology.
Enter the replication port number or accept the default port 8989.
The replication port must be an available port on the server, and must therefore be different for each directory server in a topology if all of them are running on the same host.
Select Configure as Secure if you want to use encrypted communication when connecting to the replication port on the first server.
Note the host name, and administration port, for this first directory server. You will need this information when you configure the second directory server.
Complete the configuration of the first server.
For the second directory server in your replication topology, follow the instructions in Section 3.1, "Setting up the Directory Server by Using the GUI".
On the Topologies screen, do the following:
Select This server will be part of a replication topology.
Enter the replication port number for this directory server.
The replication port must be different from the replication port of the first directory server if both servers are running on the same host.
Select There is already a server in the topology and enter the following:
Host Name: Enter the Host Name for the first directory server.
Port: Enter the administration port for the first directory server.
Admin User: Enter the bind DN for the first directory user, or accept the default.
Admin Password: Enter the bind password for the Admin user.
On the Global Administrator screen, provide the following information:
The UID for the new global administrator.
The password for the new global administrator.
Confirm the password for the new global administrator.
On the Data Replication screen, select one of the following options, and click Next.
Create first instance of base DN to be replicated.
Create local instance of existing base DNs and configure replication. Click the base DN for the first directory server.
Review the configuration settings for the second server, and click Finish.
Repeat the above procedures to set up additional servers in the replication topology.
When you have defined the Global Administrator, the entry with the DN and the password that you provided in step 5c must be defined on all servers in the topology.