Managing Oracle Internet Directory Instances

8 Managing Oracle Internet Directory Instances

This chapter describes Oracle Internet Directory server instances and how to create and manage these instances using Oracle Enterprise Manager Fusion Middleware Control and the WLST and OIDCTL utilities.

This chapter includes the following sections:

8.1 Overview of Managing Oracle Internet Directory Instances

Understand the process of managing Oracle Internet Directory Instances.

This section contains the following topics:

8.1.1 About the Instance-Specific Configuration Entry

Understand about the instance-specific configuration entry.

Since 11g Release 1 (11.1.1.0.0), configuration information for an Oracle Internet Directory instance resides in an instance-specific configuration entry, which has a DN of the form:

cn=componentname,cn=osdldapd,cn=subconfigsubentry

where componentname is the name of a Oracle Fusion Middleware system component of Type=OID, such as oid1 or oid2.

You do not manually create an instance-specific configuration entry. Instead, you create a Oracle Fusion Middleware system component of Type=OID, which automatically generates an instance-specific configuration entry named oid1.

Figure 8-1 shows the configuration entries for two Oracle Internet Directory components in the DIT. The DNs for the instance-specific configuration entries are:

cn=oid1,cn=osdldapd,cn=subconfigsubentry
cn=oid2,cn=osdldapd,cn=subconfigsubentry

Figure 8-1 DIT Showing Two Instance-Specific Configuration Entries

This illustration is described in the text.

The attributes in the instance-specific configuration specify information such as hostname, ports, events to be audited, number of child processes, and security configuration. For a complete list, see Attributes of the Instance-Specific Configuration Entry.

8.1.2 About the First Oracle Internet Directory Instance Creation

Understand when and how the first Oracle Internet Directory Instance gets created.

When you install Oracle Internet Directory on a host computer, a default instance-specific configuration entry named oid1 is created for the OID component, as follows:

cn=oid1,cn=osdldapd,cn=subconfigsubentry

The default oid1 configuration entry is created in collocated mode using the following scenarios:

Run the installer to layout the binaries
Run rcu to setup Oracle Internet Directory database
Run config.sh to create the Weblogic domain for Oracle Internet Directory
Start Weblogic admin server and node manager
Run oid_setup() WLST command to create default oid1 component instance

The Oracle Internet Directory component contains an OIDMON process and an Oracle Internet Directory instance (inst=1). The Oracle Internet Directory instance consists of a dispatcher process and one or more OIDLDAPD processes.

Beginning with Oracle Internet Directory 11g Release 1 (11.1.1.7.0), the OIDLDAPD process is separated as the OIDDISPD (dispatcher) process and the OIDLDAPD (server) process. On UNIX and Linux systems, however, the ps -ef command will continue to show both of these processes as OIDLDAPD at runtime.

In addition, the configuration step for Oracle Internet Directory creates some file system directories under Weblogic DOMAIN_HOME directory. Some of the pathnames it creates are specific to the component name. For example, the pathnames under your Oracle instance on UNIX or Linux include:

$DOMAIN_HOME/config/fmwconfig/components/OID/config/componentName
$DOMAIN_HOME/servers/OID/logs/componentName

Note:

Oracle Internet Directory is frequently configured in a cluster where instances on different hosts are all connected to the same Oracle Database.

oid_CreateInstance() WLST command detects that the other OID components are using the same Oracle Database and increments the component name for the new component by 1. That is, successive installations in the cluster will have the component names oid2, oid3, and so forth.

8.1.3 Creating Additional Oracle Internet Directory Instances

The recommended way to add another Oracle Internet Directory instance is to add an additional system component of Type=OID in the Oracle instance.

To do this, use WLST createInstance command, specifying the name of the instance, host and the port on which OID server should be running. This new Oracle Internet Directory instance consists of an OIDMON process, an OIDLDAPD dispatcher process, and one or more OIDLDAPD server processes. For example, see instance_name=oid2 at the bottom of Figure 8-2.

Figure 8-2 Oracle Internet Directory Oracle Internet Directory Process Control Architecture

Use WLST command, oid_createInstance , to create a new instance-specific configuration entry in the DIT. If the new component name is oid2, the new entry looks like this:

cn=oid2,cn=osdldapd,cn=subconfigsubentry

Change the values of attributes in this entry to customize the instance.

The WLST command also creates additional pathnames in the file system under the DOMAIN_HOME directory. If the new instance name is oid2, the path names include:

$DOMAIN_HOME/config/fmwconfig/components/OID/config/oid2
$DOMAIN_HOME/tools/OID/logs

You can use WLST commands to manage the components oid1 and oid2 individually.

Note:

You can use oidctl to create an instance if you are running Oracle Internet Directory as a standalone server, not part of a WebLogic domain. When you create an instance with oidctl, you must use oidctl to stop and start the instance. An Oracle Internet Directory instance created with oidctl cannot be registered with a WebLogic server, so you cannot use Oracle Enterprise Manager Fusion Middleware Control to manage the instance. See Managing Oracle Internet Directory Instances by Using OIDCTL.

See Also:

Understanding Process Control of Oracle Internet Directory Components for information about Oracle Internet Directory processes.

8.1.4 Registering an Oracle Instance or Component with the WebLogic Server

If you want to manage an Oracle Internet Directory component with Oracle Enterprise Manager Fusion Middleware Control, you must register the component and the Oracle instance that contains it with a WebLogic domain. You can register an Oracle instance with a WebLogic domain during installation or Oracle instance creation, but you are not required to do so.

If the Oracle instance is already registered, and you are adding a new Oracle Internet Directory system component to the Oracle instance, the Node Manager automatically registers the component as part of that Oracle instance.

See Also:

Understanding WebLogic Server Domain.

8.2 Overview of Oracle Internet Directory Components Management by Using Fusion Middleware Control

You can view, stop, and start Oracle Internet Directory components by using Oracle Enterprise Manager Fusion Middleware Control.

This section contains the following topics:

8.2.1 Viewing Active Server Information by Using Fusion Middleware Control

You can view information about any Oracle Internet Directory component—including type, debug level, host name, and configuration parameters— using Oracle Enterprise Manager Fusion Middleware Control.

Follow the steps below:

Connect to Oracle Enterprise Manager Fusion Middleware Control as described in Overview of Using Fusion Middleware Control to Manage Oracle Internet Directory.
The Domain Home Page displays the status of components, including Oracle Internet Directory.
Select the Oracle Internet Directory component you want to view.
View the status information on the Oracle Internet Directory Home page.

8.2.2 Starting the Oracle Internet Directory Server by Using Fusion Middleware Control

You can start the Oracle Internet Directory Server using Fusion Middleware Control.

Start the Oracle Internet Directory server as follows:

Go to the Oracle Internet Directory home page in Oracle Enterprise Manager Fusion Middleware Control.
From the Oracle Internet Directory menu, select Control, then Start Up.
When the confirmation dialog appears, click OK.

If Fusion Middleware Control cannot start the server, an error dialog appears.

8.2.3 Stopping the Oracle Internet Directory Server by Using Fusion Middleware Control

You can stop the Oracle Internet Directory Server using Fusion Middleware Control.

Stop the Oracle Internet Directory server as follows:

Go to the Oracle Internet Directory home page in Oracle Enterprise Manager Fusion Middleware Control.
From the Oracle Internet Directory menu, select Control, then Shut Down.
When the confirmation dialog appears, click OK.

If Fusion Middleware Control cannot stop the server, an error dialog appears.

8.2.4 Restarting the Oracle Internet Directory Server by Using Fusion Middleware Control

You can restart the Oracle Internet Directory Server using Fusion Middleware Control.

Restart the Oracle Internet Directory server as follows:

Go to the Oracle Internet Directory home page in Oracle Enterprise Manager Fusion Middleware Control.
From the Oracle Internet Directory menu, select Control, then Restart.
When the confirmation dialog appears, click OK.

If Fusion Middleware Control cannot restart the server, an error dialog appears.

8.3 Managing Oracle Internet Directory Components by Using WLST Commands

You can perform the following Oracle Internet Directory related tasks from the command line by using WLST Commands.

The following list of OID commands available for use can be obtained using help('manageoid') WLST command:

Note:

Arguments to wlst are case sensitive. Be sure to type them exactly as shown. For example, in the command createInstance, only the letterI is in upper case.

For more information about options to an WLST command, type:

wlst.sh

help (command_name)

See Oracle Internet Directory Administration Tools in Reference for Oracle Identity Management for the syntax of the commands used in the examples.

8.3.1 Creating an Oracle Internet Directory Component by Using WLST Command — oid_createInstance

You can create an Oracle Internet Directory system component in an Oracle instance by using WLST Command: oid_createInstance.

Note:

Before executing the oid_createInstance command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic',password='weblogic-password',url='t3://admin-server-host:admin-server-port')

The syntax of oid_createInstance is:

oid_createInstance(instanceName='instance-name', machine='oidhost1', port = nnnn, sslPort = nnnn, host = 'hostname')

Where:

instanceName - This is the name of the managed instance being created.
machine - This is the existing machine entry for the instance. You must specify oidhost1 as the machine name.
orcladminPassword - This is the password for super user 'cn=orcladmin'.
port - Optional. This is the port number of the non-SSL server. If this is not specified, a port will be assigned automatically.
sslPort - Optional. This is the port number of the SSL virtual host. If this is not specified, a port will be assigned automatically.
host - Optional. Name/IP address of the (logical) host, where OID server to be started/stopped If not specified, hostname of the machine will be used.

The oid_createInstance command prompts for the WebLogic administrator's user name if you do not supply it. It also prompts for the passwords if you do not supply password file names on the command line. The oid_createInstance command also uses available ports if you do not specify -port or -sslport, as described in Oracle Internet Directory Ports.

8.3.2 Deleting an Oracle Internet Directory Component by Using WLST Command — oid_deleteInstance()

You can remove an Oracle Internet Directory component by using oid_deleteInstance() WLST Command. This also unregisters the component with the WebLogic server.

Note:

Before executing the oid_createInstance command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic',password='weblogic-password',url='t3://admin-server-host:admin-server-port')

The syntax of oid_deleteInstance() is:

oid_deleteInstance(instanceName = 'oid1')

Where,

instanceName is the name of the managed instance being deleted.

You are prompted for the WebLogic administrator's user name and password if you do not supply them.

8.3.3 Viewing Active Server Instance Information by Using WLST Command — oid_instanceStatus()

You can view the status of components and processes by using the WLST oid_instanceStatus() command.

To view the status, type:

oid_instanceStatus(instanceName = 'instance-name')

Where:

instanceName is the name of the OID instance.

Processes in Instance: asinst_2
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
ias-component                    | process-type       |     pid | status   |        uid |  memused |    uptime | ports---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
oid2                             | oidldapd           |   24760 | Alive    |  988238800 |   102744 |   0:01:12 | N/A
oid2                             | oidldapd           |   24756 | Alive    |  988238799 |    55052 |   0:01:12 | N/A
oid2                             | oidmon             |   24745 | Alive    |  988238796 |    48168 |   0:01:14 | LDAPS:6789,LDAP:6788

oid1                             | oidldapd           |   21590 | Alive    |  988238048 |   103716 |  19:51:48 | N/A
oid1                             | oidldapd           |   21586 | Alive    |  988238047 |    54420 |  19:51:49 | N/A
oid1                             | oidmon             |   21577 | Alive    |  988238046 |    48168 |  19:51:49 | LDAPS:3133,LDAP:3060

8.3.4 Starting the Oracle Internet Directory Server by Using WLST Command — start()

You can start the Oracle Internet Directory Server using WLST start() command.

Note:

Before executing the start() command, ensure that you connect to the weblogic server by using the connect command.
The syntax for connecting to weblogic admin server is:

connect(username='weblogic', password='weblogic-password', url='t3://admin-server-host:admin-server-port')
Ensure that the Node Manager is up and running on the machine where you want to start Oracle Internet Directory instance.
Alternatively, you can start Oracle Internet Directory instance using startComponent.sh command. Before executing startComponent.sh command, ensure that the Node Manager is up and running. You need not connect to WebLogic Server to execute startComponent.sh command. The syntax for startComponent.sh is:
```
$DOMAIN_HOME/bin/startComponent.sh <instance-name>
```
For an Oracle Autonomous Transaction Processing-Shared (ATP-S) database, before executing the startComponent.sh command:
1. Set TNS_ADMIN property to <$DOMAIN_HOME>/config/fmwconfig/components/OID/config/ using the following command:
```
export TNS_ADMIN=<$DOMAIN_HOME>/config/fmwconfig/components/OID/config
```
  To update the contents of the directory pointed to by TNS_ADMIN, see Prerequisites for ATP-S.
2. Start the Oracle Internet Directory instance:
```
<$DOMAIN_HOME>/bin/startComponent.sh <instance-name>
```

The component name of the first Oracle Internet Directory component is oid1.

To start the first Oracle Internet Directory instance, type:

start(name='instance-name')

8.3.5 Stopping the Oracle Internet Directory Server by Using WLST Command — shutdown()

You can stop the Oracle Internet Directory server component using the WLST shutdown() command.

To stop the Oracle Internet Directory server component, type:

shutdown(name='instance-name')

8.3.6 Updating Credential Required by Enterprise Manager to manage OID - oid_setProperties()

Update the credentials for OID connection and ODSSM schema password for Enterprise Manager console to manage and monitor OID instances. This command is only relevant to collocated mode of OID installation where OID is manageable by Enterprise Manager.

Note:

Before executing the oid_setProperties() command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic', password='weblogic-password', url='t3://admin-server-host:admin-server-port')
This command covers the functionality supported by oidcred tool that was used in previous release to update EMD and ODSSM passwords.

The syntax of oid_setProperties() is:

oid_setProperties(context='EM', host='host', port = nnnn, sslmode=nnn, sslwrl = 'file:/wallet-location',
emdPassword = 'emd-login-password', odssmPassword = 'odssm-schema-password')

where,

context - This is the context for which the properties are updated.

Valid values:

'EM' is for Enterprise Manager application context.
host - Optional. Used in 'EM' context. OID host.
port - Optional. Used in 'EM' context. OID port.
sslMode - Optional. Used in 'EM' context. SSL mode.

Valid values:
- -1 : Non SSL mode.
- 0 : SSL no auth mode (anonymous ciphers need to be enabled in OID)
- 1 : SSL one way auth mode. sslwrl needs to be set.
- 2 : SSL two way auth mode. sslwrl needs to be set.
sslwrl - Optional. Wallet location.
emdPassword - Optional. Used in 'EM' context.
- Login password for EMD user (used by EM to connect to OID).
- Password for EM user DN-cn=emd admin,cn=oracle internet directory
odssmPassword - Optional. Used in 'EM' context. ODSSM schema password.

8.3.7 Fetching Enterprise Manager Properties Used to Manage OID - oid_getProperties()

Retrieves the Enterprise Manager properties used to manage OID. This command is only relevant to collocated mode of OID installation where OID is manageable by Enterprise Manager.

Note:

Before executing the oid_getProperties() command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic', password='weblogic-password', url='t3://admin-server-host:admin-server-port')

The syntax of oid_getProperties() is:

oid_getProperties(context='EM')

where,

context - This is the context for which the properties are retrieved.

Valid values: - 'EM' is for Enterprise Manage

This command returns the following values:

Host = OID host
Port = OID port
sslMode = SSL mode
sslwrl = wallet location

8.3.8 Creating a Realm in Oracle Internet Directory - oid_createRealm()

Creates a realm in Oracle Internet Directory.

Note:

Before executing the oid_createRealm() command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic', password='weblogic-password', url='t3://admin-server-host:admin-server-port')

The syntax of oid_createRealm()is:

oid_createRealm(instanceName='instance-name', host='host-name', port = nnnn, orcladminPassword = 'password', realmDN = 'namespace-name')

where,

instanceName - This is the name of the managed OID instance
host - Name/IP address of the OID host
port - This is the port number of the OID
orcladminPassword - This is the password for super user 'cn=orcladmin'
realmDN - This the new realm/namespace to be created

8.3.9 Listing all Oracle Internet Directory Instance Names - oid_listInstances()

Lists all Oracle Internet Directory instance names.

Note:

Before executing the oid_listInstances() command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic', password='weblogic-password', url='t3://admin-server-host:admin-server-port')

The syntax of oid_listInstances() is: oid_listInstances()

8.3.10 Updating Orcladmin Password - oid_setAdminPassword()

This command updates the password for orcladmin super user.

Note:

Before executing the oid_setAdminPassword() command, ensure that you connect to the weblogic server by using the connect command.

The syntax for connecting to weblogic admin server is:

connect(username='weblogic', password='weblogic-password', url='t3://admin-server-host:admin-server-port')

The syntax of oid_setAdminPassword is:

oid_setAdminPassword(orcladminPassword = 'passwd', odsPassword = 'passwd')

where,

orcladminPassword - New password for cn=orcladmin.
odsPassword- DB password needed for verification.

8.4 Starting an Instance of the Replication Server by Using OIDCTL

You can configure an instance of Oracle Internet Directory Replication Server, using the oidctl start command with server=oidrepld. Best practice is to create a separate instance of Oracle Internet Directory to use for replication.

First create a new instance of Oracle Internet Directory as described in Creating Additional Oracle Internet Directory Instances. Then, ensure that the environment variable DOMAIN_HOME is set and type:

oidctl connect=connStr server=oidrepld inst=1 componentname=Component_Name \
   name=Instance_Name start

The componentname value must be the component name of the running oidldapd server. The name value must be the instance name of the running oidldapd server.

Do not start more than one instance of oidrepld on a host. Do not start oidrepld on more than one Oracle Internet Directory instance sharing the same Oracle Database.

Note:

The environment variables DOMAIN_HOME, ORACLE_HOME, and COMPONENT_NAME must be set before you run the oidctl command to start or stop the replication server.

See Also: