| Oracle® Fusion Middleware Administrator's Guide for Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) Part Number E28972-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Middleware Administrator's Guide for Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) Part Number E28972-01 |
|
|
PDF · Mobi · ePub |
This chapter describes how to create and manage Oracle Directory Server Enterprise Edition (ODSEE) instances and suffixes. Many other directory administration tasks are configured at the suffix level, but they are covered in other chapters in this book.
This chapter contains detailed information about how to create server instances and suffixes. If you need to quickly create a Directory Server instance and suffix, and import some example data, see Checking Your Directory Server Enterprise Edition Installation in the Installation Guide for Oracle Directory Server Enterprise Edition.
This section shows how to create and delete a Directory Server instance.
Before you can administer data, you must create a Directory Server instance by using command-line tools or the browser interface Directory Service Control Center (DSCC). In DSCC, a Directory Server instance is often referred to simply as a "Directory Server".
When you create a Directory Server instance, the files and directories required for your Directory Server are created in the instance-path that you specify.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
If you use DSCC to create a new server instance, you can choose to copy some or all server configuration settings from an existing server.
The dsadm command enables you to manage a Directory Server instance and the files belonging to that instance on the local host. The command does not let you administer servers over the network, but only directly on the local host. The dsadm command has subcommands for each key management task. For a complete description, see dsadm.
The dsconf command is an LDAP client. The command enables you to configure nearly all server settings on a running Directory Server instance from the command line. You can configure settings whether the server is on the local host or another host that is accessible across the network. The dsconf command has subcommands for each key configuration task. For a complete description, see dsconf.
Create a new Directory Server instance and set the instance path.
$ dsadm create instance-path
You are prompted to set a password for the Directory Manager for this server.
To specify a non-default port number for the server instance, or any other parameter, see the dsadm man page.
For example, to create a new instance in the directory /local/dsInst, use this command:
$ dsadm create /local/dsInst
Choose the Directory Manager password:
Confirm the Directory Manager password:
Use 'dsadm start /local/dsInst' to start the instance
The instance is created in a directory on the local file system and not a network file system.
Check that the server instance has been created correctly.
$ dsadm info instance-path
For example:
$ dsadm info /local/dsInst
Instance Path: /local/dsInst
Owner: user1(group1)
Non-secure port: 1389
Secure port: 1636
Bit format: 64-bit
State: Running
Server PID: 22555
DSCC url: -
SMF application name: -
Instance version: D-A00
If your operating system provides a service management solution, you can enable the server to be managed as a service. Based on your operating system, run one of the commands in Table 4-1.
Start Directory Server.
Important: The Naming Service Cache Daemon (nscd) must be started before you start Directory Server. See the documentation for your operating system for more information.
$ dsadm start instance-path
The server is running but does not contain data or a suffix. Use dsconf to create a suffix.
Register the server instance with Directory Service Control Center by using either of the following methods.
Login to DSCC, and then use the Register Existing Server action on the Servers tab of the Directory Servers tab.
Access DSCC using http://hostname:8080/dscc7 or https://hostname:8181/dscc7 as per your application server configuration.
Use the command dsccreg add-server.
$ dsccreg add-server -h hostname --description "My DS" /local/dsInst Enter DSCC administrator's password: /local/dsInst is an instance of DS Enter password of "cn=Directory Manager" for /local/dsInst: This operation will restart /local/dsInst. Do you want to continue ? (y/n) y Connecting to /local/dsInst Enabling DSCC access to /local/dsInst Restarting /local/dsInst Registering /local/dsInst in DSCC on hostname.
See dsccreg for more information about the command.
If you want to use a password policy and your Directory Server instance is standalone, or if it belongs to a replication topology that has already been migrated to to-DS6-only password policy mode, move the instance to that mode.
$ dsconf pwd-compat -h host -p port to-DS6-migration-mode ## Beginning password policy compatibility changes . ## Password policy compatibility changes finished. Task completed (slapd exit code: 0). $ dsconf pwd-compat -h host -p port to-DS6-mode ## Beginning password policy compatibility changes . ## Password policy compatibility changes finished. Task completed (slapd exit code: 0).
The above action should be performed in the specified sequence.
For more information about password policies compatibilities, see Password Policy in the Upgrade and Migration Guide for Oracle Directory Server Enterprise Edition.
Before you delete the server instance, you must prepare the instance for deletion. Refer to the following procedure to delete a server instance successfully:
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Stop the Directory Server.
$ dsadm stop [--force] instance-path
If the server was previously registered with DSCC, unregister the server using the following command:
$ dsccreg remove-server /local/dsInst Enter DSCC administrator's password: /local/dsInst is an instance of DS Enter password of "cn=Directory Manager" for /local/dsInst: This operation will restart /local/dsInst. Do you want to continue ? (y/n) y Unregistering /local/dsInst from DSCC on localhost. Connecting to /local/dsInst Disabling DSCC access to /local/dsInst Restarting /local/dsInst
For details, see the dsccreg man page.
If you previously enabled the server instance in a service management solution, disable the server from being managed as a service.
| Operating System | Command |
|---|---|
|
Solaris 10 |
|
|
Solaris 9 |
|
|
Windows |
|
Delete the server instance.
$ dsadm delete instance-path
Caution:
This command removes everything, under the instance-path directory.
If the instance has been enabled as a service, or if the instance is started automatically at system startup, dsadm delete requires root access.
You can use the following commands at the command line:
dsadm start
dsadm stop
dsadm restart
These commands must be run by the same UID and GID that created the Directory Server, or run by root. For example, if Directory Server runs as user1, you should run the start, stop, and restart utilities as user1.
Note:
When using these commands, also note the following:
When you stop and restart a Directory Server instance with a large cache in memory configured to hold entries, the cache takes some time to refill. While the cache fills again, the instance responds more slowly.
Directory Server may need some time to start depending upon the cache size or on the need to recover from the database transaction log. In such an event, the dsadm start command may exit on error or timeout. If you anticipate this problem, the timeout may be changed using the dsadm set-flags dsadm-startup-timeout command. In the same way, the shutdown timeout may be changed using the dsadm set-flags dsadm-shutdown-timeout command.
On Solaris, role-based access control allows you to run Directory Server as a user other than root.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
However, this does not apply to the step for enabling and disabling service management. Enabling and disabling service management must be done at the command line when starting and stopping Directory Server.
For more information about dsadm subcommands and options used below, see dsadm.
To start, stop, or restart Directory Server, do one of the following:
To start the server, type:
$ dsadm start instance-path
For example, to start a server with the instance path /local/dsInst, use this command:
$ dsadm start /local/dsInst
If the start operation fails after a configuration change, use the --safe option as shown in the following command:
$ dsadm start --safe /local/dsInst
To stop the server, type:
$ dsadm stop [--force] instance-path
For example:
$ dsadm stop --force /local/dsInst
To restart the server, type:
$ dsadm restart instance-path
For example:
$ dsadm restart /local/dsInst
List the running instances on a host using the following command:
dsadm list-running-instances [--all]
The -all option lists the running instances from any installation path.
After you have created your Directory Server instance, you must create one or more suffixes for the server's Directory Information Tree (DIT). The DIT consists of all of the entries in your server, as identified by their distinguished names (DNs). The hierarchical nature of a DN creates branches and leaves that structure the data in the tree. The DIT is defined and managed administratively in terms of suffixes and sub-suffixes. DSCC provides controls for creating and administering all of these elements. Alternatively, you can use command-line tools.
For conceptual information about structuring directory data and about suffixes in general, refer to the Deployment Planning Guide for Oracle Directory Server Enterprise Edition.
As explained in the following procedure, you can use the dsconf create-suffix command to create a suffix configuration in your directory. Because root suffixes and sub-suffixes are managed internally in the same way, the procedure for creating them from the command line is nearly the same. The procedure shows the dsconf create-suffix command used only with the required options. For more information about other options of this command, see the dsconf man page or run the following command:
$ dsconf create-suffix --help
The configuration entries can be created by any administration user. However, the top entry of the suffix must be created by the Directory Manager or as a Directory Administrator, such as name="DirAdminDN" content="cn=admin,cn=Administrators,cn=config".
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
If you use DSCC to create a new suffix, you can choose to copy some or all suffix configuration settings from an existing suffix.
Create the root suffix.
Ensure that your server is running, then type this command:
$ dsconf create-suffix -h host -p port suffix-DN
where the suffix-DN is the full DN of the new suffix. For a root suffix, the convention is to use the domain-component (dc) naming attribute.
For example, to create a suffix for the DN dc=example,dc=com , use this command:
$ dsconf create-suffix -h host1 -p 1389 dc=example,dc=com
This command creates the new suffix as follows:
The top level (or base) entry of the root suffix is created.
The configuration entries in cn=config for both the suffix and the database are created.
The default database name is based on the suffix DN.
For information about all of the suffixes, including the new suffix that has been created, use this command:
$ dsconf list-suffixes -h host -p port -v
The -v option displays verbose mode, which shows how many entries are on the suffix, and any replication information.
Note:
If you have more than one Directory Server instance, use the -h host name and -p port number options to specify which server instance the suffix should belong to.
If you want to specify a non-default path for the database files, use the -L option. You can change the suffix database path at a later stage. To do this, use the command dsconf set-suffix-prop suffix-DN db-path:new-db-path, then stop the server, move the database files manually, and restart the server.
To see all the options that you can use when creating suffixes, refer to the dsconf man page.
Note:
Database names can contain only ASCII (7-bit) alphanumeric characters, hyphens (-), and underscores (_). Directory Server does not accept multibyte characters (such as in Chinese or Japanese character sets) in strings for database names, file names, and path names.
To work around this issue, when creating a Directory Server suffix having multibyte characters, specify a database name that has no multibyte characters. When creating a suffix on the command line, for example, explicitly set the --db-name option of the dsconf create-suffix command.
$ dsconf create-suffix --db-name asciiDBName UTF-8SuffixDN
Do not use default as database name for the suffix. Do not use multibyte characters for the database name.
If required, create the sub-suffix:
$ dsconf create-suffix -h host -p port subSuffix-DN
then attach the sub-suffix to the root suffix.
$ dsconf set-suffix-prop -h host -p port subSuffix-DN parent-suffix-dn:parentSuffix-DN
where parentSuffix-DN must have the same value as suffix-DN in the previous step. The suffix-DN for the sub-suffix includes the relative distinguished name (RDN) of the sub-suffix and the DN of its parent suffix.
For example, to create the sub-suffix ou=Contractors,dc=example,dc=com, and to attach the sub-suffix to the root suffix, type:
$ dsconf create-suffix -h host1 -p 1389 ou=Contractors,dc=example,dc=com $ dsconf set-suffix-prop -h host1 -p 1389 ou=Contractors,dc=example,dc=com \ parent-suffix-dn:dc=example,dc=com
When this entry is added to the directory, the database module of the server automatically creates the database files in the following directory:
instance-path/db/database-name
where database-name is the name automatically built from a part of the suffix. For example, in the previous example, the database-name would be Contractors
Initialize the suffix with data. See Initializing a Suffix.
Sometimes, you might need to make a suffix unavailable for maintenance, or to make its contents unavailable for security reasons. The action of disabling a suffix prevents the server from reading or writing the contents of the suffix in response to any client operations. When you disable a suffix, you no longer have access to that suffix, and the referral mode is automatically set to disabled.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Disable the suffix.
$ dsconf set-suffix-prop -h host -p port suffix-DN enabled:off
Note:
You cannot disable a suffix on which replication is enabled because most properties of a replicated suffix are determined by the replication mechanism.
Enable the suffix.
$ dsconf set-suffix-prop -h host -p port suffix-DN enabled:on
If you want to limit access to a suffix without disabling the suffix completely, you can modify the access permissions to allow read-only access. In this case you must define a referral to another server for write operations. You can also deny both read and write access, and define a referral for all operations on the suffix.
Referrals can also be used to temporarily point a client application to a different server. For example, while backing up the contents of the suffix, you might add a referral to another suffix.
If your suffix is a consumer in a replicated environment, the replication mechanism determines the value of the referral setting. Although you can manually modify the referral setting, the referral will be overwritten at the next replication update. For information about setting replication referrals, see To Perform Advanced Consumer Configuration.
Referrals are labeled URLs, that is, an LDAP URL optionally followed by a space character and a label. For example:
ldap://phonebook.example.com:389/
Or:
ldap://phonebook.example.com:389/ou=All%20People,dc=example,dc=com
Because space characters are significant, any space characters in the URL part of the referral must be escaped using %20.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Set the referral URL.
$ dsconf set-suffix-prop -h host -p port suffix-DN referral-url:LDAP-URL
where LDAP-URL is a valid URL containing the host name, port number, and DN of the target.
For example:
$ dsconf set-suffix-prop -h host1 -p 1389 dc=example,dc=com \ referral-url:ldap://phonebook.example.com:389/
You can specify any number of LDAP URLs.
Set the referral mode in order to make the suffix read-only.
$ dsconf set-suffix-prop -h host -p port suffix-DN referral-mode:only-on-write
To make the suffix unavailable for both read and write operations, and to return referrals for all requests, set the referral-mode to enabled.
As soon as the command is successful, the suffix is read-only or inaccessible and ready to return referrals.
When the suffix becomes available, disable the referrals to make the suffix read-write again.
$ dsconf set-suffix-prop -h host -p port suffix-DN referral-mode:disabled
When referrals are disabled, the suffix automatically becomes read-write, unless you have disabled the suffix itself by setting the enabled property of the suffix to off.
You can import data to a Directory Server suffix in the following ways:
Initialize a suffix from an LDIF file. This operation deletes the current data in the suffix and replaces it with the contents of the LDIF file.
Use an LDIF file to perform bulk ldapadd, ldapmodify, or ldapdelete operations. This allows you to add, modify, and delete entries in bulk in any suffix of the directory.
Note:
The offline import (dsadm import) does not remove the changelog as the changelog data may still be in the suffix. At server start, replication decides if the changelog needs to be kept or not. Online import (dsconf import) decides straight away if changelog needs to be recreated or not.
The following table shows the differences between initializing a suffix and adding, modifying, and deleting entries in bulk.
Table 4-2 Differences Between Initializing a Suffix and Performing Bulk Modifications
| Domain of Comparison | Initializing Suffixes | Adding, Modifying, and Deleting Entries in Bulk |
|---|---|---|
|
Content |
Overwrites content |
Does not overwrite content |
|
LDAP operations |
N/A |
Add, modify, delete |
|
Performance |
Fast |
Slower |
|
Response to server failure |
Atomic (all changes are lost after a failure) |
Best effort (all changes made up to the point of the failure remain) |
|
LDIF file location |
Accessible from server |
On client machine |
|
Commands |
If server is local and stopped:
If server is remote and running:
|
Note: Bulk import using the |
Initializing a suffix overwrites the existing data in a suffix with the contents of an LDIF file that contains only entries for addition.
You must be authenticated as the Directory Manager or an Administrator to initialize a suffix.
When the server is running, only the Directory Manager and Administrators can import an LDIF file that contains a root entry. For security reasons, only these users have access to the root entry of a suffix, for example, dc=example,dc=com.
Before restoring suffixes involved in replication agreements, read Restoring Replicated Suffixes.
Note:
All LDIF files that you import must use UTF-8 character-set encoding.
When initializing a suffix, the LDIF file must contain the root entry and all directory tree nodes of the corresponding suffix.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Use one of the following commands to initialize the suffix from an LDIF file, that is, import the contents of a database to an LDIF file.
Caution:
These commands overwrite the data in your suffix.
If your server is local and stopped, type:
$ dsadm import instance-path LDIF-file suffix-DN
The following example uses the dsadm import command to import two LDIF files into a single suffix:
$ dsadm import /local/dsInst /local/file/example/demo1.ldif \ /local/file/example/demo2.ldif dc=example,dc=com
If your server is running (local or remote), type:
$ dsconf import -h host -p port LDIF-file suffix-DN
The following example imports an LDIF file using dsconf import. You do not need root privileges to run the command, but you must authenticate as a user with root permissions, such as the Directory Manager.
$ dsconf import -h host1 -p 1389 /local/file/example/demo1.ldif \ ou=People,dc=example,dc=com
You can import gzip compressed files. Examples:
$ dsadm import /local/dsInst /local/file/example/demo2.ldif.gz \ /local/file/example/demo2.ldif dc=example,dc=com $ dsconf import -h host1 -p 1389 /local/file/example/demo2.ldif.gz \ ou=People,dc=example,dc=com
Examples that use command-line tools depend on sample data residing under the dc=example,dc=com suffix of your directory.
You can set up part of the data that is required by creating a dc=example,dc=com suffix. You can then populate the suffix with entries from the install-path/dsee7/resources/ldif/Example.ldif file.
Create a new Directory Server instance and start the instance.
$ dsadm create -p port -P SSL-port instance-path $ dsadm start instance-path
Read the Example.ldif file to find bind passwords needed in the examples.
Create suffix and load the Example.ldif content into the directory by using the following commands:
$ dsconf create-suffix -h localhost -p 1389 dc=example,dc=com $ dsconf import -h localhost -p 1389 \ install-path/dsee7/resources/ldif/Example.ldif dc=example,dc=com
For more information, see To Create a Directory Server Instance.
Generate test data for examples by using the makeldif command, as shown in the next step, and the following template:
define suffix=dc=example,dc=com
define maildomain=example.com
branch: ou=test,[suffix]
subordinateTemplate: person:100
template: person
rdnAttr: uid
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
initials: {givenName:1}{sn:1}
employeeNumber: <sequential>
uid: test{employeeNumber}
mail: {uid}@[maildomain]
userPassword: auth{employeeNumber}{employeeNumber}
telephoneNumber: <random>
description: This is the description for {cn}.
Create a test.template file and copy the template content, as shown above, into it. Use commands such as the following to generate the data in test.ldif and to load the content into the directory.
Note:
The test.template file must be created in the install-path/dsee7/dsrk/bin/example_files directory.
$ cd install-path/dsee7/dsrk/bin/example_files $ ../makeldif -t test.template -o test.ldif Processing complete. 101 total entries written. $ ../ldapmodify -a -c -D uid=hmiller,dc=example,dc=com -w - -f test.ldif Enter bind password: …
If you read Example.ldif, you see that the password for hmiller is hillock.
Note:
This step is specific to the zip installation because the makeldif command is available only in the zip distribution.
When you perform an ldapmodify operation, you are able to add, modify, or delete entries in bulk. Entries are specified in an LDIF file that contains update statements to modify or delete existing entries. This operation does not erase entries that already exist.
The changed entries may target any suffix that is managed by your Directory Server. As with any other operation that adds entries, the server will index all new entries as they are imported.
The ldapmodify command will import an LDIF file through LDAP and perform all operations that the file contains. Using this command you can modify data in all directory suffixes at the same time.
Before restoring suffixes involved in replication agreements, see Restoring Replicated Suffixes.
Note:
All LDIF files that you import must use UTF-8 character-set encoding.
When importing an LDIF file, parent entries must either exist in the directory or be added first from the file.
Add, modify, or delete from an LDIF file in bulk.
$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -B baseDN -f LDIF-file
The following example performs an import using the ldapmodify command. You do not need root privileges to run this command, but you must authenticate as a user with root permissions, such as cn=Directory Manager or name="DirAdminDN" content="cn=admin,cn=Administrators,cn=config". The last parameter specifies the name of the LDIF file to import.
$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - \ -B dc=example,dc=com -f /local/dsInst/ldif/demo.ldif
Deleting a suffix removes its entire branch from the DIT.
Note:
When you delete a suffix, you permanently remove all of its data entries from the directory. You also remove all suffix configuration information, including its replication configuration.
You cannot delete a parent suffix and keep its sub-suffixes in the DIT as new root suffixes. If you want to delete an entire branch that contains sub-suffixes, you must also delete the sub-suffixes of the deleted parent and their possible sub-suffixes.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Remove the suffix configuration entry:
$ dsconf delete-suffix -h host -p port [subSuffix-DN] suffix-DN
This command removes the suffix from the server, starting with the base entry at the suffix-DN. The suffix is no longer visible or accessible in the directory.
Directory Server 11g Release 1 (11.1.1.6) supports the compaction of suffixes offline. Online compaction is not supported in this release. If storage space is available, compacting a suffix reduces the size of the database by reorganizing the database keys, and returns the storage space to the filesystem, if possible. Compacting a suffix also reduces the disk footprint. Since application data is not processed and based on the way the database keys are managed, it is not guaranteed that the storage space can be reclaimed. Nevertheless database size will not grow.
Before You Begin
Be sure you have sufficient disk space.
Compacting a suffix requires free disk space equal to at least twice the size of the largest suffix to be compacted. The free disk space is needed for temporary files. For example, to compact the following three suffixes:
o=suffix1 : 300 Gb o=suffix2 : 170 Gb o=suffix3 : 633 Gb
The server requires at least 633 * 2, or 1266 Gb, of free disk space.
Stop the server and back up your database before performing this task.
Compact the required suffix.
$ dsadm repack instance-path suffix-dn
All .db3 files related to the specified suffix are compacted.
If you run this command with the -b option, you can specify a backend database name, instead of a suffix DN. At least one suffix, or one backend must be specified.
For more information, see the dsadm man page.
ODSEE 11gR1 may store entries with different representations, depending upon the instance being upgraded from DSEE 6 or a later version. When you use an LDAP operation to modify a single entry, ODSEE uses the currently configured format to modify that entry. Entries for which no modifications are done are left untouched. However, the current configuration may differ from what is on disk, and you cannot always modify all entries via LDAP. In these cases, you can rewrite a suffix to convert or upgrade all entries in the Data Base at one time. This is useful, for example, when you want to:
Convert all directory entries in an upgraded instance of ODSEE to the 7.x format
Update all entries in a 7.x ODSEE instance to include new configuration values such as ds-compressed-entries, ds-compression-mode, and ds-entry-crc in the LDIF configuration file
Migrate password policy
Use one of the following commands:
If your server is local and stopped, type:
$ dsadm rewrite instance-path suffix-DN
If your server is running (local or remote), type:
$ dsconf rewrite -h host -p portsuffix-DN
You do not need root privileges to run the command, but you must authenticate as a user with root permissions, such as the Directory Manager.
|
 Copyright © 2001, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|