| 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 configure Directory Server. You can use the dsconf command (see the dsconf man page).
You can also use Directory Service Control Center (DSCC), which is the preferred method. DSCC makes additional checks during the configuration process, which can minimize errors. In addition, DSCC enables you to copy the configuration of one server instance to another server instance. For more information about using DSCC, see the DSCC online help.
To display the configuration of Directory Server instance, run dsconf info.
$ dsconf info -h host -p port Instance path : instance path Global State : read-write Host Name : host Port : port Secure port : secure port Total entries : 20844 Server version : 11.1.1.6 Suffixes : suffix-DN Dest. Servers : host:port On-Going Tasks : import Finished Tasks : backup =================== Suffix suffix-DN Replication role : master Attribute to reindex : mail country telephonenumber Index filter analyzer : Running for suffix-DN (Nov 7, 2008 4:56:33 PM)
The above output assumes that you have created suffixes, and replication agreements with the destination servers. It also displays the ongoing import operation and finished backup operation.
The above output also displays the suffix related information such as Replication role, Attribute to reindex, and Index filter analyzer. If no specific information is available, no such information is displayed in dsconf info output.
The recommended method for modifying the configuration is to use DSCC. This browser interface provides task-based controls to help you set up your configuration quickly and efficiently. Using DSCC, you can modify a configuration setting on one server and then copy that configuration setting to other servers. In addition, the DSCC interface manages the complexity and interdependence of the configuration for you. Detailed procedures for modifying the configuration using DSCC can be found in the DSCC online help.
You can automate configuration tasks by writing scripts that use command-line tools.
Modify the configuration through the command line by using the dsconf command. This command uses LDAP to modify the cn=config subtree. For more information about dsconf, see Directory Server Command-Line Tools.
For any tasks that you cannot perform using dsconf, use the ldapmodify command.
Note:
If you want to modify the server configuration properties by using the command dsconf set-server-prop, you need to know which properties you can modify and their default values. Use this command to display help on all properties:
$ dsconf help-properties -v
Search the property help for the item that you need. For example, on a UNIX platform, type the following to search for memory cache properties:
$ dsconf help-properties -v | grep cache
For more information about configuration entries in cn=config and for a complete description of all configuration entries and attributes, including the range of allowed values, see the Reference for Oracle Directory Server Enterprise Edition.
dse.ldif FileDirectory Server stores all of its configuration information in this file:
instance-path/config/dse.ldif
Caution:
Modifying the configuration by editing the contents of the dse.ldif file directly is prone to error and is not recommended. However, if you choose to edit this file manually, stop the server before you edit the file and restart it after you have finished editing.
The dse.ldif file is in the LDAP Data Interchange Format (LDIF). LDIF is a textual representation of entries, attributes, and their values, and is a standard format described in RFC 2849 (http://www.ietf.org/rfc/rfc2849).
The Directory Server configuration in the dse.ldif file consists of the following:
The attributes and values of the cn=config entry.
All of the entries in the subtree below cn=config and their attributes and values.
The object classes and access control instructions of the root entry ("") and the cn=monitor entry. The other attributes of these entries are generated by the server.
Only the system user who owns the Directory Server instance has the rights to read and write the file.
Directory Server makes most configuration settings readable and writable through LDAP. By default, the cn=config branch of the directory can be read by anyone with authorization and can be written to only by the Directory Manager (cn=Directory Manager) and to the administrative users under cn=Administrators,cn=config. The administration user can view and modify the configuration entries just like any other directory entry.
Do not create non-configuration entries under the cn=config entry because they will be stored in the dse.ldif file, which is not the same highly scalable database as regular entries. As a result, if many entries, and particularly entries that are likely to be updated frequently, are stored under cn=config, performance will likely be degraded. However, it can be useful to store special user entries such as the Replication Manager (supplier bind DN) entry under cn=config, to centralize configuration information.
Note:
If dse.ldif refers to a nonexistent Sun Microsystems plug-in, it can be considered to have a valid signature. The following warning message is displayed:
WARNING<4227> - Plugins - conn=-1 op=-1 msgId=-1 - Detected plugin paths from another install, using current install.
This warning message appears only for plug-ins with a vendor of Sun Microsystems.
Directory Server contains the default administration user the Directory Manager.
This section explains how to create an administration user with root access, and how to configure the Directory Manager.
If you want to create a new administration user with the same rights as name="DirAdminDN" content="cn=admin,cn=Administrators,cn=config", create the new user in the group cn=Administrators,cn=config. All users in this group are subject to a global ACI that allows the same access as the Directory Manager.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create a new administration user.
For example, to create a new user cn=Admin24,cn=Administrators,cn=config, type:
$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=admin,cn=Administrators,cn=config
changetype: add
objectclass: top
objectclass: person
userPassword: password
description: Administration user with the same access rights as Directory Manager.
The -D and -w options give the bind DN and password, respectively, of a user with permissions to create this entry.
The Directory Manager is the privileged server administrator, comparable to the root user on UNIX systems. Access control does not apply to the Directory Manager.
For most administration tasks, you are not required to use the Directory Manager. Instead, you can use the user cn=admin,cn=Administrators,cn=config, or any other user that you create beneath cn=Administrators,cn=config. The only tasks that require the Directory Manager are changing the root ACI, and replication troubleshooting tasks, such as repairing replication and searching tombstones.
You can change the Directory Manager DN and password, as well as create a file from which the password can be automatically read.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Find the existing Directory Manager DN.
$ dsconf get-server-prop -h host -p port root-dn root-dn:cn=Directory Manager
Modify the Directory Manager settings as required.
To modify the Directory Manager DN, type:
$ dsconf set-server-prop -h host -p port root-dn:new-root-dn
Use quotes if there are spaces in the Directory Manager DN. For example:
$ dsconf set-server-prop -h host1 -p 1389 root-dn:"cn=New Directory Manager"
To change the Directory Manager password, type:
Create a temporary file for setting the password. This file is read once, and the password is stored for future use.
$ echo password> /tmp/pwd.txt
Set the server root password file property.
$ dsconf set-server-prop -h host -p port root-pwd-file:/tmp/pwd.txt
This command prompts the server to read the password file. Remove the temporary password file after you have set the password file property.
$ rm /tmp/pwd.txt
The root Directory Server entry (the entry returned for a base object search with a zero-length DN "") and the subtrees below cn=config, cn=monitor, and cn=schema contain access control instructions (ACIs) that are automatically generated by Directory Server. These ACIs are used to determine user permissions to directory entries. These ACIs are sufficient for evaluation purposes. However, for any production deployment, you need to evaluate your access control requirements and design your own access controls.
If you want to hide the existence of one or more additional subtrees and protect your configuration information for security reasons, you must place additional ACIs on the DIT.
Place an ACI attribute in the entry at the base of the subtree you want to hide.
Place an ACI in the root DSE entry on the namingContexts attribute. The root DSE entry attribute called namingContexts contains a list of the base DNs for each of the Directory Server databases.
Place an ACI on the cn=config and cn=monitor subtrees. The subtree DNs are also stored in the mapping tree entries below cn=config and cn=monitor.
For more information about creating ACIs, see Chapter 6, "Directory Server Access Control".
You can modify the LDAP port or the LDAPS secure port number of your user directory server by using DSCC or by using the dsconf set-server-prop command.
If you change a port number, be aware of the following:
If you set a non-privileged port number and Directory Server is installed on a machine to which other users have access, you might expose the port to a hijack risk by another application. In other words, another application can bind to the same address/port pair. This rogue application might then be able to process requests intended for Directory Server. That is, the rogue application could be used to capture passwords used in the authentication process, to alter client requests or server responses, or to produce a denial of service attack. To avoid this security risk, use the listen-address or secure-listen-address properties to specify the interface (address) on which Directory Server listens.
If you change the port number by using the command line, be aware of the following:
If the Directory Server is referenced in replication agreements that are defined on other servers, the replication agreements must be updated to use the new port number.
If you have used DSCC previously to manage the server, the server will be temporarily unable to be viewed after the change in port number. To view the server again, you must unregister the server and then register it again in DSCC using the new port number.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Note:
Once you make your modifications, you must restart the server for the changes to take effect.
Verify the existing settings for your port.
$ dsconf get-server-prop -h host -p port port-type
Where port-type is one of the following:
ldap-portLDAP default port
ldap-secure-portLDAPS secure port
dsml-portDSML default port
dsml-secure-portDSML secure port
For example, to display the LDAPS secure port, type:
$ dsconf get-server-prop -h host1 -p 2501 ldap-secure-port
Enter "cn=Directory Manager" password:
ldap-secure-port : 2511
If the returned result is an integer, the port is enabled. If the returned result is disabled, the port is disabled.
Note:
You can also list the LDAP default port and LDAPS secure port using the dsadm
If required, modify a port number or enable a port.
$ dsconf set-server-prop -h host -p port port-type:new-port
For example, to change the LDAP port number from 1389 to 1390, use this command:
$ dsconf set-server-prop -h host1 -p 1389 ldap-port:1390
To enable the DSML secure port on port number 2250, use this command:
$ dsconf set-server-prop -h host1 -p 1389 dsml-secure-port:2250
If required, disable a port.
$ dsconf set-server-prop -h host -p port port-type:disabled
For example, to disable the DSML secure port, use the command:
$ dsconf set-server-prop -h host1 -p 1389 dsml-secure-port:disabled
In addition to processing requests in the Lightweight Directory Access Protocol (LDAP), Directory Server also responds to requests sent in the Directory Service Markup Language version 2 (DSMLv2). DSML is another way for a client to encode directory operations. The server processes DSML as any other request, with all of the same access control and security features. DSML processing allows many other types of clients to access your directory contents.
Directory Server supports the use of DSMLv2 over the Hypertext Transfer Protocol (HTTP/1.1) and uses the Simple Object Access Protocol (SOAP) version 1.1 as a programming protocol to transport the DSML content. For more information about these protocols and for examples of DSML requests, see Chapter 13, Directory Server DSMLv2, in the Reference for Oracle Directory Server Enterprise Edition.
This section covers the following topics:
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Set the DSML mode to on.
$ dsconf set-server-prop -h host -p port dsml-enabled:on
Set the secure DSML port.
$ dsconf set-server-prop -h host -p port dsml-secure-port:port
Set the non—secure DSML port.
$ dsconf set-server-prop -h host -p port dsml-port:port
By default, this port is set to disabled
Restart the server.
$ dsadm restart instance-path
Next Steps
According to the parameters and attribute values you defined, DSML clients may use the following URLs to send requests to this server:
http://host:DSML-port/relative-URL
https://host:secure-DSML-port/relative-URL
Note:
The relative-URL can be read and set using the dsml-relative-root-url property.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Set the DSML mode to off.
$ dsconf set-server-prop -h host -p port dsml-enabled:off
Set the secure DSML port to disabled.
$ dsconf set-server-prop -h host -p port dsml-secure-port:disabled
Restart the server.
$ dsasm restart instance-path
You can configure the level of security that is required to accept DSML requests. To do this, you must configure DSML client authentication.
Set the DSML client authentication mode.
$ dsconf set-server-prop -h host -p port dsml-client-auth-mode:dsml-mode
By default the dsml-client-auth-mode property is set to client-cert-first.
dsml-mode can be one of:
http-basic-only - This is the default value. The server uses the contents of the HTTP Authorization header to find a user name that can be mapped to an entry in the directory. This process and its configuration are encrypted through SSL but do not use client certification. This is described in DSML Identity Mapping.
client-cert-only - The server uses credentials from the client certificate to identify the client. With this value, all DSML clients must use the secure HTTPS port to send DSML requests and provide a certificate. The server checks that the client certificate matches an entry in the directory. See Chapter 5, "Directory Server Security" for more information.
client-cert-first - The server will attempt to authenticate clients first with a client certificate if one is provided. Otherwise, the server will authenticate clients using the contents of the Authorization header.
If no certificate and no Authorization header is provided in the HTTP request, the server performs the DSML request with anonymous binding. Anonymous binding is also used in the following cases:
The client provides a valid Authorization header but no certificate when client-cert-only is specified.
The client provides a valid certificate but no Authorization header when http-basic-only is specified.
Regardless of the client authentication method, if a certificate is provided but it cannot be matched to an entry, or if the HTTP Authorization header is specified but cannot be mapped to a user entry, the DSML request is rejected with error message 403: "Forbidden".
When performing basic authentication without a certificate, Directory Server uses a mechanism called identity mapping to determine the bind DN to use when accepting DSML requests. This mechanism extracts information from the Authorization header of the HTTP request to determine the identity to use for binding.
The default identity mapping for DSML/HTTP is given by the following entry in your server configuration.
dn: cn=default,cn=HTTP-BASIC,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
cn: default
dsSearchBaseDN: ou=people
dsSearchFilter: (uid=${Authorization})
This configuration indicates that the server should use the HTTP user ID as the uid value for a DN stored in a Directory Server suffix. For example, if the HTTP user is bjensen, the server tries to execute the bind using the DN uid=bjensen,ou=people.
For the mapping to work properly you must therefore complete the value of dsSearchBaseDN. For example, you can change the value of dsSearchBaseDN to ou=people,dc=example,dc=com. Then if the HTTP user is bjensen, the server tries to execute the bind using the DN uid=bjensen,ou=people,dc=example,dc=com.
dn: cn=default,cn=HTTP-BASIC,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
cn: default
dsSearchBaseDN: ou=people,dc=example,dc=com
dsSearchFilter: (uid=${Authorization})
Within the mapping entry attribute dsSearchFilter, you can use placeholders of the format ${header} where header is the name of an HTTP header.
The following are the most common headers used in DSML mappings.
${Authorization}This string is replaced with the user name contained in an HTTP Authorization header. An authorization header contains both a username and its password, but only the user name is substituted in this placeholder.
${From}This string is replaced with the email address that might be contained in an HTTP From header.
${host}This string is replaced with the hostname and port number in the URL of the DSML request, which are those of the server.
To have DSML requests perform a different kind of identity mapping, define a new identity mapping for HTTP headers.
Edit the default DSML-over-HTTP identity mapping or create custom mappings for this protocol.
The mapping entries must be located below the entry cn=HTTP-BASIC,cn=identity mapping,cn=config.
Use the ldapmodify command to add this entry from the command line, as described in Section 3.1.3.1, "Adding Entries Using ldapmodify".
Restart Directory Server for your new mappings to take effect.
Custom mappings are evaluated first. If no custom mapping is successful, the default mapping is evaluated. If all mappings fail to determine the bind DN for the DSML request, the DSML request is forbidden and rejected (error 403).
Each suffix in your directory can be placed in read-only mode independently and can return a specific referral if one is defined. Directory Server also provides a read-only mode for the server that applies to all suffixes and can return a global referral when one is defined.
The server read-only mode is designed to allow administrators to prevent modifications to the directory contents while performing tasks such as reindexing the suffixes. For this reason, server read-only mode does not apply to the following configuration branches:
cn=config
cn=monitor
cn=schema
These branches should be protected at all times by access control instructions (ACIs) against modifications by non-administration users, regardless of the read-only setting (see Chapter 6, "Directory Server Access Control"). Global read-only mode prevents update operations on all other suffixes in the directory, including update operations initiated by the Directory Manager.
Read-only mode also interrupts replication on a suffix if it is enabled. A master replica no longer has any changes to replicate, although it continues to replicate any changes that were made before read-only mode was enabled. A consumer replica does not receive updates until read-only mode is disabled. A master in a multi master replication environment does not have any changes to replicate and is not able to receive updates from the other masters.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Enable the global read-only mode.
$ dsconf set-server-prop -h host -p port read-write-mode:read-only
When you are ready, disable the read-only mode.
$ dsconf set-server-prop -h host -p port read-write-mode:read-write
This section provides information about managing different types of memory. For a description of the different types of cache and for information about cache tuning, see Chapter 8, Directory Server Data Caching, in the Reference for Oracle Directory Server Enterprise Edition.
When you preload the cache, the sever saves the entries in cache at shutdown, and then loads these entries at startup. This allows the server to start up with recently-used entries already in cache. Subsequent Directory Server behavior reflects normal operational performance, rather than ramp-up performance. Preloading caches is useful for arriving at reproducible results when benchmarking, and for measuring and analyzing potential optimizations.
There is no need to actively preload the cache if this feature is enabled. Actively preloading the cache will obliviate the benefits of cache preload while consuming more resources.
If possible, do not actively preload the caches Allow the caches to be preloaded by normal or by typical client interaction with Directory Server before you measure performance.
To enable entry cache preloading, run the following command:
$ dsconf set-suffix-prop -p port suffix-dn entry-cache-preload-enabled:on
Note:
Writing and reading of preloaded data is done only when Directory Server is properly stopped and started. Offline tasks do not take cache contents into account. Crashes will also invalidate preloading the cache.
Also, preloading data information will not be stored under these conditions:
The most recent configuration change to entry cache size was from manual setup to automatic entry cache size.
Fewer than 100 entries exist in the cache.
See the Reference for Oracle Directory Server Enterprise Edition for more information on the entry cache.
Tools for preload database cache can be found at http://www.slamd.com.
Caution:
Modifying cache can severely impact server performance. Use caution when modifying cache.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Obtain the current database cache level.
$ dsconf get-server-prop -h host -p port db-cache-size
Change the database cache level.
$ dsconf set-server-prop -h host -p port db-cache-size:size
where size can be expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.
The default level of cache at installation is suited to a test environment, not a production environment. For tuning purposes, you might want to monitor the database cache for your server.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
To monitor the database cache:
$ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \ -b "cn=monitor,cn=ldbm database,cn=plugins,cn=config" "(objectclass=*)"
If the database cache size is large enough and it has been preloaded, the hit ratio (dbcachehitratio) should be high. In addition, the number of pages that are read in (dbcachepagein) and the clean pages that are written out (dbcacheroevict) should be low. Here, "high" and "low" are relative to the deployment constraints.
For tuning purposes, you might want to check the entry cache for one or more suffixes. Use this procedure to view the entry cache levels.
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
To monitor the entry cache:
$ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \ -b "cn=monitor,cn=db-name,cn=ldbm database,cn=plugins,cn=config" "(objectclass=*)"
If the entry cache for a suffix is large enough to hold most of the entries in the suffix and if the cache is preloaded, the hit ratio (entrycachehitratio) should be high.
If you have preloaded the cache, you will see that as the previously empty entry cache fills, entry cache size (currententrycachesize) approaches the maximum entry cache size (maxentrycachesize). Ideally, the size in entries (currententrycachecount) should be either equal to or very close to the total number of entries in the suffix (ldapentrycachecount).
By default, the entry cache is completely managed by the server, depending upon the load. You may want to evaluate how the server performs with the default values before you modify entry cache settings. See the Reference for Oracle Directory Server Enterprise Edition and the Deployment Planning Guide for Oracle Directory Server Enterprise Edition for tuning recommendations.
Caution:
Modifying cache can severely impact server performance. Use caution when modifying cache.
By default, the entry-cache-mode property is set to automatic. This enables the server cache to be managed automatically based on the server load. You must set this property to manual before you can modify the entry cache.
Set the entry-cache-mode property to manual.
$ dsconf set-suffix-prop -h host -p port suffix-DN entry-cache-mode:manual
Obtain the current entry cache level.
$ dsconf get-suffix-prop -h host -p port suffix-DN entry-cache-count entry-cache-size
Change the entry cache count.
$ dsconf set-suffix-prop -h host -p port suffix-DN entry-cache-count:integer
where integer is the number of entries to be stored in the cache.
Change the entry cache size.
$ dsconf set-suffix-prop -h host -p port suffix-DN entry-cache-size:size
where size is the cache size expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.
The first of entry-cache-size or entry-cache-count that is reached determines that the cache is full.
You can set threshold values for the dynamic memory footprint. You might need to set this threshold when Directory Server is running on a machine where resources are shared or sparse.
For information about memory sizing, see Directory Server and Memory in the Deployment Planning Guide for Oracle Directory Server Enterprise Edition.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Note:
This threshold can only be set on Solaris and Linux platforms.
Note:
By default, the heap-high-threshold-size and heap-low-threshold-size properties are undefined.
Set the maximum heap high memory threshold.
$ dsconf set-server-prop -h host -p port heap-high-threshold-size:value
where value is either undefined or a memory size expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.
For recommendations on the values to use for heap-high-threshold-size , see the server man page.
Optionally, set the maximum heap low memory threshold.
$ dsconf set-server-prop -h host -p port heap-low-threshold-size:value
where value is either undefined or a memory size expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.
For recommendations on the values to use for heap-low-threshold-size , see the server man page.
You can control search operation resource limits on the server for each client account. You set such limits in operational attributes on an account, and Directory Server then enforces them based on the account a client uses to bind to the directory.
The following limits can be set:
The look-through limit specifies the maximum number of entries examined for a search operation.
The size limit specifies the maximum number of entries returned in response to a search operation.
The time limit specifies the maximum time spent processing a search operation.
The idle timeout specifies the maximum time a client connection can remain idle before the connection is dropped.
Note:
The Directory Manager can use unlimited resources by default.
The resource limits that you set on specific user accounts take precedence over the resource limits set in the server-wide configuration. This section provides information about setting resource limits for each account.
The examples given in this section set resource limits directly in the attributes of the entry. You can also set resource limits on account using the Class of Service (CoS) mechanism. The CoS mechanism generates computed attributes as an entry is retrieved for a client application. For more information about defining CoS, see Section 9.1, "About Groups, Roles, and Class of Service".
If you want to define the search limit that is used by the nsslapd process, refer to the following procedure:
You can use the web interface Directory Service Control Center (DSCC) to perform this task.
Use the dsconf get-server-prop command to read the resource limit server properties.
$ dsconf get-server-prop -h host -p port look-through-limit search-size-limit \ search-time-limit idle-timeout look-through-limit : 5000 search-size-limit : 2000 search-time-limit : 3600 idle-timeout : none
The output shows that searches look through a maximum of 5000 entries, return a maximum of 2000 entries, and use a maximum of one hour (3600 seconds) of server time to process the search.
Change the look-through limit.
$ dsconf set-server-prop -h host -p port look-through-limit:integer
where integer is the maximum number of entries examined for a search operation.
Change the search size limit.
$ dsconf set-server-prop -h host -p port search-size-limit:integer
where integer is the maximum number of entries returned by a search operation.
Change the search time limit.
$ dsconf set-server-prop -h host -p port search-time-limit:integer
where integer is the maximum time spent processing a search operation.
Change the idle timeout.
$ dsconf set-server-prop -h host -p port idle-timeout:integer
where integer is the maximum time a client connection can remain idle before the connection is dropped.
|
 Copyright © 2001, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|