Oracle Internet Directory Administrator's Guide Release 2.1.1 Part Number A86101-01 |
Library | Service | Contents | Index

# 3
Preliminary Tasks

This chapter guides you through some tasks you must perform before configuring and using Oracle Internet Directory. It also discusses upgrading from previous releases of Oracle Internet Directory.

Before you can run the administration tools and begin configuring and using the directory, you need to start OID Monitor and start a directory server instance. You also need to reset the default security configuration.

This section contains these topics:

- Task 1: Start the OID Monitor Daemon

- Task 2: Start a Server Instance

- Task 3: Reset the Default Security Configuration

- Upgrading from an Earlier Release of Oracle Internet Directory

## Task 1: Start the OID Monitor Daemon

The OID Monitor daemon must be running to process commands to start and stop the server.

This section contains these topics:

- Starting the OID Monitor

- Stopping the OID Monitor

### Starting the OID Monitor

To start the OID Monitor:

1. Set the following environment variable to the appropriate language setting. The default language set at installation is AMERICAN_AMERICA.

       NLS_LANG=APPROPRIATE_LANGUAGE.UTF8

2. At the system prompt, type:

       oidmon [connect=net_service_name] [sleep=seconds] start

   `

   Argument | Description
   --- | ---
   connect=net_service_name | Specifies the net service name of the database to which you want to connect. This is the network service name set in the `tnsnames.ora` file. This argument is optional.
   sleep=seconds | Specifies number of seconds after which the OID Monitor should check for new requests from OID Control and for requests to restart any servers that may have stopped. The default sleep time is 10 seconds. This argument is optional.
   start | Starts the OID Monitor process

   `

   For example:

       oidmon connect=dbs1 sleep=10 start

### Stopping the OID Monitor

To stop the OID Monitor daemon, at the system prompt, type:

    oidmon [connect=net_service_name] stop

Argument | Description
--- | ---
connect=net_service_name | Specifies net service name of the database to which you want to connect. This is the net service name set in the `tnsnames.ora` file.
stop | Stops the OID Monitor process

For example:

    oidmon connect=dbsl stop

## Task 2: Start a Server Instance

Once the OID Monitor is running, start a server instance by using the OID Control Utility.

Note: The value for the instance flag in the OID Control Utility should always be greater than or equal to one.

This section contains these topics:

- Starting an Oracle Directory Server Instance

- Stopping an Oracle Directory Server Instance

- Starting an Oracle Directory Replication Server Instance

- Stopping an Oracle Directory Replication Server Instance

- Restarting Directory Server Instances

- Troubleshooting Directory Server Instance Startup

### Starting an Oracle Directory Server Instance

The syntax for starting an Oracle directory server instance is:

    oidctl connect=net_service_name server=oidldapd instance=server_instance_number
    [configset=configset_number] [flags=' -p port_number -work maximum_number_of_
    worker_threads_per_server -debug debug_level -l change_logging -server n'] start

Argument | Description
--- | ---
`connect`=net_service_name | If you already have a `tnsnames.ora` file configured, this is the net service name specified in that file, located in `ORACLE_HOME/network/admin`
`server`=oidldapd | Type of server to start (valid values are OIDLDAPD and OIDREPLD). This is not case-sensitive.
`instance`=server_instance_number | Instance number of the server to start. Should be a number between 0 and 1000.
`configset`=configset_number | Configset number used to start the server. This defaults to `configset0` if not set. This should be a number between 0 and 1000.
`-p` port_number | Specifies a port number during server instance startup. Default port if not set is 389.
`-work` maximum_number_of_worker_threads_per_server | Specifies the maximum number of worker threads for this server
`-debug` debug_level | Specifies a debug level during Oracle directory server instance startup
`-l` change_logging | Turns replication change logging on and off. To turn it off, enter -l. To turn it on, omit the flag. The default is true (values = true and false). (directory server only)
`-server` n | Specifies the number of server processes to start on this port
`start` | Starts the server specified in the `server` argument.

For example, to start an Oracle directory server instance whose net service name is dbs1, using configset5`,at` port 12000, with a debug level of 1024, an instance number `3`, and in which change logging is turned off, type at the system prompt:

    oidctl connect=dbs1 server=oidldapd instance=3 configset=5 flags='-p 12000

    -debug 1024 -l ' start

When starting and stopping an Oracle directory server instance, the server name and instance number are mandatory. All other arguments are optional.

All keyword value pairs within the flags arguments must be separated by a single space.

Single quotes are mandatory around the flags.

The configset identifier defaults to zero (`configset0`) if not set.

Note: If you choose to use a port other than the default port (389 for non-secure usage or 636 for secure usage), you must tell the clients which port to use to locate the Oracle Internet Directory. If you use the default ports, clients can connect to the Oracle Internet Directory without referencing a port in their connect requests.

### Stopping an Oracle Directory Server Instance

OID Monitor must be running whenever you start or stop directory server instances.

At the system prompt, type:

    oidctl connect=net_service_name server=OIDLDAPD instance=server_instance_number
    stop

For example:

    oidctl connect=dbs1 server=oidldapd instance=3 stop

### Starting an Oracle Directory Replication Server Instance

The syntax for starting the Oracle directory replication server is:

    oidctl connect=net_service_name server=oidrepld instance=server_instance_number
    [configset=configset_number] flags=' -h hostname -p port_number

    -d debug_level -m [true | false]-z transaction_size ' start

Argument | Description
--- | ---
`connect`=net_service_name | If you already have a `tnsnames.ora` file configured, then this is the name specified in that file, which is located in ORACLE_HOME/network/admin
`server`=oidrepld`` | Type of server to start (valid values are OIDLDAPD and OIDREPLD). This is not case-sensitive.
`instance`=server_instance_number | Instance number of the server to start. Should be a number between 0 and 1000.
`configset`=configset_number | Configset number used to start the server. This defaults to configset0 if not set. This should be a number between 0 and 1000.
`-p` port_number | Specifies a port number during server instance startup. Default port if not set is 389.
`-d` debug_level | Specifies a debug level during replication server instance startup
`-h` | Specifies the host name on which the server runs. (Replication server only)
`-m [`true`|`false`]` | Turns conflict resolution on and off. The default is true (values = true and false). (Replication server only)
`-z` transaction_size | Specifies the number of changes applied in each replication update cycle. If you do not specify this, the number is determined by the Oracle directory server sizelimit parameter, which has a default setting of 1024. You can configure this latter setting.
`start` | Starts the server specified in the server argument.

For example, to start the replication server with an instance=1, at port 12000, with debugging set to 1024, type at the system prompt:

    oidctl connect=dbs1 server=oidrepld instance=1 flags='-p 12000 -h eastsun11 -d
    1024' start

When starting and stopping an Oracle directory replication server, the `-h` flag, which specifies the host name, is mandatory. All other flags are optional.

All keyword value pairs within the flags arguments must be separated by a single space.

Single quotes are mandatory around the flags.

The configset identifier defaults to zero (`configset0`) if not set.

Note: If you choose to use a port other than the default port (389 for non-secure usage or 636 for secure usage), you must tell the clients which port to use to locate the Oracle Internet Directory. If you use the default ports, clients can connect to the Oracle Internet Directory without referencing a port in their connect requests.

### Stopping an Oracle Directory Replication Server Instance

OID Monitor must be running whenever you start or stop directory server instances.

At the system prompt, type:

    oidctl connect=net_service_name server=OIDREPLD instance=server_instance_number
    stop

For example:

    oidctl connect=dbs1 server=oidrepld instance=1 stop

### Restarting Directory Server Instances

To restart a directory server instance, at the system prompt, type:

    oidctl connect=net_service_name server={oidldapd|oidrepld} instance=server_
    instance_number  restart

OID Monitor must be running whenever you start, stop, or restart directory server instances.

If you try to contact a server that is down, you receive from the SDK the error message `81--LDAP_SERVER_DOWN`.

If you change a configuration set entry that is referenced by an active server instance, you must stop that instance and restart it to effect the changed value in the configuration set entry on that server instance. You can either issue the STOP command followed by the START command, or you can use the RESTART command. RESTART both stops and restarts the server instance.

For example, suppose that Oracle directory server instance1 is started, using configset3, and with the net service name dbs1. Further, suppose that, while instance1 is running, you change one of the attributes in configset3. To enable the change in configset3 to take effect on instance1, you enter the following command:

    oidctl connect=dbs1 server=oidldapd instance=1 restart

If there are more than one instance of the Oracle directory server running on that node using configset3, then you can restart all the instances at once by using the following command syntax:

    oidctl connect=dbs1 server=oidldapd restart

Note that this command restarts all the instances running on the node, whether they are using configset3 or not.

Important Note: During the restart process, clients cannot access the Oracle directory server instance. However, the process takes only a few seconds to execute.

### Troubleshooting Directory Server Instance Startup

If the directory server fails to start, you can override all user-specified configuration parameters to start the directory server and then return the configuration sets to a workable state by using the ldapmodify operation.

To start the directory server using its hard-coded default parameters instead of the configuration parameters stored in the directory, type at the system prompt:

    oidctl connect=net_service_name flags='-p port_number -f'

The `-f` option in the flags starts the server with hard-coded configuration values, overriding any defined configuration sets except for the values in `configset0`.

## Task 3: Reset the Default Security Configuration

When you first install Oracle Internet Directory, the default configuration grants to all users read, browse, and search access to all entries in the directory. One of the first things you need to do is establish and implement an access control policy to ensure that each user receives the appropriate authorization. Oracle Corporation specifically recommends that you control access to the subentry `subSchemaSubEntry` and its children because these objects contain information about the directory.

Moreover, when you load directory entries, you are creating a hierarchy of directory entries. You must therefore establish:

- Permissions to load entries into this hierarchy

- Directory access for clients that need read, modify, and write access to the directory entries

  See Also: Chapter 9, "Managing Directory Access Control" for a detailed explanation of access control options and instructions for setting up security Chapter 4, "Using the Administration Tools" for information about the administration tools you use to configure security Appendix E, "Schema Elements" for syntax and usage notes for the command line tools

## Upgrading from an Earlier Release of Oracle Internet Directory

Oracle Internet Directory release 2.1.1 allows you to upgrade from either Oracle Internet Directory release 2.0.4.x or release 2.0.6. You choose to upgrade to a release 2.1.1 when prompted during the installation process.

In a replicated environment, a node running release 2.1.1 can co-exist with nodes running previous releases of Oracle Internet Directory. Moreover, in a replicated environment, upgrade of one node to release 2.1.1 requires no network downtime. The other nodes can remain available while the upgrade progresses.

This section contains these topics:

- Upgrading in a Single Node Environment

- Upgrading in a Multi-Node Environment

### Upgrading in a Single Node Environment

To upgrade on a single node, follow the instructions in the installation documentation for your operating system.

### Upgrading in a Multi-Node Environment

Upgrading a multi-node Oracle Internet Directory system to release 2.1.1 requires special attention. This section discusses the two ways to upgrade a multi-node Oracle Internet Directory system:

- Upgrading one node at a time

- Upgrading all the nodes at the same time

#### Upgrading One Node at a Time

Use this method if you do not want any system downtime. While the upgrade on one node is in progress, it allows all the other nodes to remain available. However, using this method requires that you clearly understand and strictly follow these guidelines:

- When you are upgrading a replication network one node at a time, the upgrade is not complete until all nodes are upgraded. However, during this period, all network nodes, except the one being upgraded, remain available. This is considered a transient state and, to indicate this, the attribute `orclupgradeinprogress` in the DSE root is set to `TRUE`. This attribute is created during the upgrade procedure.

- When all the nodes in a replicated Oracle Internet Directory network have been upgraded to release 2.1.1, the system is no longer in a transient state. At this point, set the attribute `orclupgradeinprogress` to `FALSE` on all the nodes.

- During the transient state, that is, when the `orclupgradeinprogress` attribute in the DSE root is set to `TRUE`, the release 2.1.1 node performs special processing on change log entries it generates for other nodes. This is required for backward compatibility.

- During the transient state, do not use the new password encryption scheme. Doing this creates inconsistencies in password values across various nodes, and nodes running previous releases will disable the authentication. Instead of doing this, continue using the existing password encryption scheme. Once the entire network is upgraded, you can start using the new password encryption scheme.

- While the upgrade is going on, only one node should be Read-Write. The rest should be Read-Only.

- Do not perform binary attribute modification on the upgraded node. Such modifications fail on 2.0.4.x and 2.0.6 nodes.

- Be sure to perform the upgrade on the master definition site (MDS) before you upgrade the master sites.

  See Also: "What's New in Oracle Internet Directory?" for a list of encryption algorithms supported for passwords in Oracle Internet Directory release 2.1.1 "Post Upgrade Procedure for Password Encryption"

Perform the following tasks, first on the MDS, then on the master sites.

##### Task 1: Stop the Oracle Directory Replication Server on the Node to be Upgraded

See Also: "Stopping an Oracle Directory Replication Server Instance"

##### Task 2: Stop the Oracle Directory Server on the Node to be Upgraded

See Also: "Stopping an Oracle Directory Server Instance"

##### Task 3: Stop OID Monitor on the Node to be Upgraded

See Also: "Stopping the OID Monitor"

##### Task 4: Delete Jobs on Other Nodes

Before shutting down the database at the MDS, run the script delasrjobs.sql located in `/oidupgrade/`on the installation CD. This script deletes ASR jobs on other master sites that push changes to the MDS. Deleting these jobs temporarily removes the MDS from the replication environment so that no changes can be applied to it. Other nodes, however, remain operational and continue replicating changes.

##### Task 5: Shutdown Database and Listener on the Node to be Upgraded

If you do not shutdown the database and listener, then Oracle Universal Installer prompts you to do it.

See Also: Net8 Administrator's Guide

for instructions on stopping the listener

- Oracle8i Administrator's Guide for instructions on shutting down the database server

##### Task 6: Upgrade the Node to Oracle Internet Directory Release 2.1.1

Run Oracle Universal Installer to upgrade to Oracle Internet Directory release 2.1.1, which uses Oracle8i release 8.1.7. The installer both migrates the database and upgrades Oracle Internet Directory.

##### Task 7: Start the Database and Listener

After the upgrade is completed, make sure that the database and listener are up and running.

Test the connectivity to other nodes. If connectivity is broken, then use the backup copies of `listener.ora`, `sqlnet.ora` and `tnsnames.ora` and restart the listener. The backup files are named `listener` date`.bak`, `sqlnet` date`.bak` and `tnsnames` date`.bak`.

##### Task 8: Create Push Jobs on Other Nodes

After you have upgraded the node, create jobs on other nodes. You do this by executing `$`ORACLE_HOME`/ldap/admin/creasrjobs.sql` on the upgraded node. This script creates on the other nodes the jobs that were deleted in "Task 4: Delete Jobs on Other Nodes". These jobs now start pushing the existing changes and new changes on other nodes to the node you have just upgraded.

##### Task 9: Perform Post Upgrade Procedure for Password Encryption

Once the node is upgraded, perform the post upgrade procedure for password encryption as described in "Post Upgrade Procedure for Password Encryption".

##### Task 10: Start OID Monitor

See Also: "Starting the OID Monitor"

##### Task 11: Start the Oracle Directory Server

See Also: "Starting an Oracle Directory Server Instance"

##### Task 12: Start the Oracle Directory Replication Server

See Also: "Starting an Oracle Directory Replication Server Instance"

##### Task 13: Upgrade Other Master Sites

After upgrading the MDS, upgrade other master sites one at a time. Perform tasks 1 through 12 on each master site until all the nodes are upgraded.

##### Task 14: Update the orclupgradeinprogress Attribute on All the Nodes

After all the nodes are upgraded to Oracle Internet Directory release 2.1.1, modify the `orclupgradeinprogress` attribute to `FALSE` on all the nodes. To do this:

1. Edit the input file as follows:

       dn:
       modify:replace
       replace:orclupgradeinprogress
       orclupgradeinprogress:FALSE

2. Use ldapmodify to load the file:

       ldapmodify -D "cn=orcladmin" -w welcome -h host_name -p  port_number -f
       input_file.ldif

   See Also: Chapter 10, "Managing Directory Replication" for information about the MDS

#### Upgrading All the Nodes at the Same Time

Use this method to upgrade all the nodes at the same time. If you use this method, then the system is unavailable during the upgrade process.

##### Task 1: Set All the Nodes in the Network to Read-Only Mode

1. Edit the input file as follows:

       dn:
       changetype:modify
       replace:orclservermode
       orclservermode:r

2. Run the following command against all the nodes in the replication network:

       ldapmodify -D "cn=orcladmin" -w welcome -h host_name -p port_number -f
       input_file.ldif

##### Task 2: Wait Until All the Changes in the Change Log Queue Have Been Applied

Before moving to next step, wait for the change log queue to empty. If you skip this step, then changes in the change log queue will be applied once nodes are upgraded.

##### Task 3: Stop the Oracle Directory Replication Server on All Nodes

See Also: "Stopping an Oracle Directory Replication Server Instance"

##### Task 4: Stop the Oracle Directory Server on All Nodes

See Also: "Stopping an Oracle Directory Server Instance"

##### Task 5: Stop OID Monitor on All Nodes

See Also: "Stopping the OID Monitor"

##### Task 6: Shutdown the Database and the Listener on All Nodes

If you do not shutdown the database and listener, then Oracle Universal Installer prompts you to do it.

See Also: Net8 Administrator's Guide

for instructions on stopping the listener

- Oracle8i Administrator's Guide for instructions on shutting down the database server

  ##### Task 7: Upgrade All the Nodes to Oracle Internet Directory Release 2.1.1

  Run Oracle Universal Installer to upgrade to Oracle Internet Directory release 2.1.1, which uses Oracle8i release 8.1.7. The installer both migrates the database and upgrades Oracle Internet Directory.

  ##### Task 8: Start the Database and Listener on All Nodes

  After the upgrade is completed, make sure that the database and listener are up and running.

  Test the connectivity to other nodes. If connectivity is broken, then use the backup copies of `listener.ora`, `sqlnet.ora` and `tnsnames.ora` and restart the listener. The backup files are named `listener` date`.bak`, `sqlnet` date`.bak` and `tnsnames` date`.bak`.

  ##### Task 9: Perform Post Upgrade Procedure for Password Encryption

  ##### Once the node is upgraded, perform the post upgrade procedure for password encryption as described in "Post Upgrade Procedure for Password Encryption".

  ##### Task 10: Start OID Monitor on All Nodes

  See Also: "Starting the OID Monitor"

  ##### Task 11: Start Oracle Directory Server on All Nodes

  See Also: "Starting an Oracle Directory Server Instance"

  ##### Task 12: Start Oracle Directory Replication Server on All Nodes

  See Also: "Starting an Oracle Directory Replication Server Instance"

  ##### Task 13: Update the orclupgradeinprogress Attribute on All the Nodes

  After all the nodes are upgraded to Oracle Internet Directory release 2.1.1, modify the `orclupgradeinprogress` attribute to `FALSE` on all the nodes. To do this:

  1. Edit the input file as follows:

         dn:
         modify:replace
         replace:orclupgradeinprogress
         orclupgradeinprogress:FALSE

  2. Use ldapmodify to load the file:

         ldapmodify -D "cn=orcladmin" -w welcome -h host_name -p  port_number -f
         input_file.ldif

  Perform this modification on all the nodes in the replication environment

  #### LDIF-Based Upgrading

  Oracle Corporation recommends that you use the LDIF-based backup procedure to backup your existing release Oracle Internet Directory. This is explained in this section.

  Normally, you do not need to perform LDIF-based upgrading. Use this method when you cannot successfully run the database-based upgrade process.

  The LDIF-based upgrade process requires the following procedures on a node being upgraded:

  ##### Task 1: Backup the Older Version of Oracle Internet Directory

  Be sure that the Oracle directory server is not running, then run the script backup_oid.sh located in the `/oidupgrade` directory on the CD.

  The syntax to run backup_oid.sh is:

      backup_oid.sh -connect net_service_name -pass password_for_DB_account_`ods'

  The backup_oid.sh script does the following:

  - Exports Oracle Internet Directory schema. As it does this, it generates`.dmp` files--for example, `attr_store.dmp`--in `$``ORACLE_HOME``/ldap/load` directory

  - Backs up the OID subtree using the Ldifwrite utility. As it does this, it generates the file `OID_userdata.ldif` in `$`ORACLE_HOME`/ldap/load`. The subtree under `cn=OracleSchemaVersion` (if it exists) is also backed up as `orcl_schemaver.ldif` in the `$`ORACLE_HOME`/ldap/load` directory.

  If you plan to install Oracle Internet Directory release 2.1.1 in the same ORACLE_HOME, then save these generated files in some other location.

  ##### Task 2: Perform a Fresh Installation of Oracle Internet Directory Release 2.1.1

  See Also: Installation documentation for your operating system

  ##### Task 3: Restore the User-Defined Schema and Data from the Previous Version of Oracle Internet Directory:

  To do this:

  1. Make sure that the Oracle directory server is not running.

  2. Copy the following files to `$`ORACLE_HOME`/1dap/load`:

     - Backed up Oracle Internet Directory schema dump files--that is, files with the extension`.dmp`

     - The file `OID_userdata.ldif`

  3. Run the script restore_oid.sh located in `$`ORACLE_HOME`/ldap/install`.

     The syntax for restore_oid.sh is:

         restore_oid.sh -connect net_service_name -pass password_for_DB_account_`ods'

  The restore_oid.sh script does the following:

  - Imports the Oracle Internet Directory schema from the dump files

  - Inserts the schema differences between the previous release--that is, either 2.0.6 or 2.0.4--and 2.1.1

  - Bulkloads the data from the LDIF file with the `-restore` option

  ##### Task 4: Upgrade Passwords

  Run the cryptupgrd.sh script located in `$`ORACLE_HOME`/ldap/bin/` to upgrade passwords.

  The syntax for cryptupgrd.sh is:

      cryptupgrd.sh -connect  net_service_name -pass password_for_DB_account_`ods'

  #### Post Upgrade Procedure for Password Encryption

  In release 2.0.6 and release 2.0.4, the user password was encrypted by using only one encryption algorithm, namely MD4. A flag in the root DSE, namely, `orcluseencrypt`, merely toggled encryption on and off. By contrast, Oracle Internet Directory release 2.1.1 supports multiple hash schemes.

  Oracle Internet Directory release 2.1.1 stores the hash scheme as a prefix to the password value. A new attribute created in the root DSE during the upgrade procedure indicates the default hashing scheme. If the supplied password is not already encrypted, then the Oracle directory server uses this default value to encrypt passwords.

  The post upgrade procedure for password encryption adds a prefix `MD4` to all the existing password values in the directory. The time taken by this procedure to finish varies depending on the number of entries in the directory.

  To run this procedure, enter the following command:

      cryptupgrd.sh -connect  net_service_name -pass password_for_DB_account_`ods'

  See Also: "What's New in Oracle Internet Directory?" for a list of encryption algorithms supported for passwords in Oracle Internet Directory release 2.1.1

  | Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
  Library | Service | Contents | Index