Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition

Part II Directory Proxy Server Administration

Chapter 16 Directory Proxy Server Tools

Directory Proxy Server provides a browser interface and command-line tools to register and manage instances of Directory Proxy Server. The browser interface is called Directory Service Control Center (DSCC). This chapter describes basic tasks that are required to administer Directory Proxy Server by using DSCC or the command line.

To decide whether to use DSCC or the command line to perform a specific task, see Deciding When to Use DSCC and When to Use the Command Line.

For more information about the administration framework, see Directory Server Enterprise Edition Administration Model in Oracle Fusion Middleware Deployment Planning Guide for Oracle Directory Server Enterprise Edition.

This chapter covers the following topics:

Using DSCC for Directory Proxy Server

This section describes how to access DSCC for Directory Proxy Server.

ProcedureTo Access DSCC for Directory Proxy Server

  1. Access DSCC in the same way as you would for Directory Server.

    See To Access DSCC.

  2. Click on the Proxy Server tab to view and manage Directory Proxy Server.

    The following figure shows the initial window for Directory Proxy Server.

    Figure 16–1 Initial DSCC Window for Directory Proxy Server

    Screen capture shows a list of registered Directory Proxy Servers
in DSCC.

  3. Click a Directory Proxy Server instance to view or to manage that server.


    Note –

    For more information about using DSCC, see the online help.


Command-Line Tools for Directory Proxy Server

The commands-line tools that you use to work with Directory Proxy Server are called dpadm and dpconf. For information about how to use these commands, see the dpadm(1M) and dpconf(1M) man pages.

The dpconf is an LDAP based command so you must specify the user bind DN and password for the command to authenticate. While the dpadm command operates on the instance files.

This section describes the location of the dpadm and dpconf commands. It also provides information on environment variables, comparisons between the commands, and where to find help for using the commands.

Location of Directory Proxy Server Commands

The Directory Proxy Server command-line tools are located in the following directory by default:


install-path/bin

Your installation path depends on your operating system. Installation paths for all operating systems are listed in Default Paths and Command Locations.

Setting Environment Variables for dpconf

The dpconf command requires some options that you can preset by using environment variables. If you do not specify an option when using the command, or do not set the environment variable, the default setting will be used. You can configure environment variables for the following options:

-D userDN

User bind DN. Environment variable: LDAP_ADMIN_USER. Default: cn=Proxy Manager.

-w password-file

Password file for the user bind DN. Environment variable: LDAP_ADMIN_PWF. Default: Prompt for password.

-h host

Host name or IP address. Environment variable: DIR_PROXY_HOST. Default: localhost.

-p LDAP-port

LDAP port number. Environment variable: DIR_PROXY_PORT. Default: 389 if the server instance is running as root, and 1389 if the server instance is running as a regular user.

-e, --unsecured

Specifies that dpconf should open a clear connection by default. Environment variable: DIR_PROXY_UNSECURED. If this variable is not set, dpconf opens a secure connection by default.

For more details, see the dpconf(1M) man page.

Comparison of dpadm and dpconf

The following table shows a comparison of the dpadm and dpconf commands.

Table 16–1 Comparison of the dpadm and dpconf Commands

 

dpadm Command

dpconf Command

Purpose 

To manage the process or the files on a local instance of Directory Proxy Server 

To configure a local or remote instance of Directory Proxy Server 

User 

Operating system user 

LDAP user 

Local or remote 

The command must be local to the instance, that is, the command must be run on the host on which the server is running.

The command can be local to the instance but can also be run from anywhere on the network.

Example uses of the command 

Create an instance of Directory Proxy Server. 

Start and stop an instance of Directory Proxy Server. 

Manage the certificate database. 

Modify the configuration of an instance of Directory Proxy Server. 

Create a data view. 

Configure load balancing in a data source pool. 

Server state 

The server can be running or stopped. 

The server must be running.

How the command identifies the server instance 

By specifying the instance path. The instance path can be relative or absolute. 

By specifying the host name or IP address and the port number. 

The command uses the LDAP port (-p) or the LDAPS secure port (-P). If a port number is not specified on the command line, the environment variable PROXY_PORT is used. If the environment variable is not set, the default ports are used.

Setting Multi-Valued Properties With dpconf

Certain Directory Proxy Server properties can take multiple values. Use the following syntax to specify the following values:


$ dpconf set-container-prop -h host -p port \
 property:value [property:value]

For example, to set multiple writable attributes for an LDAP data view named my-view, type the following command:


$ dpconf set-ldap-data-view-prop -h host1 -p 1389 view-name\
 writable-attr:uid writable-attr:cn writable-attr:userPassword

To add a value to a multi-valued property that already contains values, type the following command:


$ dpconf set-container-prop -h host -p port \
 property+:value

To remove a value from a multi-valued property that already contains values, type the following command:


$ dpconf set-container-prop -h host -p port\
 property-:value

For example, in the scenario described previously, to add sn to the list of writable attributes, type the following command:


$ dpconf set-ldap-data-view-prop -h host1 -p 1389 view-name\
writable-attr+:sn

To remove cn from the list of writable attributes, type the following command:


$ dpconf set-ldap-data-view-prop -h host1 -p 1389 view-name\
writable-attr-:cn

Obtaining Help for Using dpadm and dpconf

For information about how to use the dpadm and dpconf commands, see the dpadm(1M) and dpconf(1M) man pages.

Chapter 17 Directory Proxy Server Instances

This chapter describes how to administer an instance of Directory Proxy Server. This chapter covers the following topics:

Working With Directory Proxy Server Instances

When you create an instance of Directory Proxy Server, the files and directories required for the instance are created in the path that you specify.

In this procedure, you create a server instance on the local host using the dpadm command. You then configure the instance using the dpconf command.

Non-root users can create server instances.

A Directory Proxy Server instance must be configured to proxy directory client application requests to data sources through data views. When you start or stop an instance, you start or stop the server process that proxies directory client application requests.

The dpadm command enables you to manage a Directory Proxy Server instance and the files belonging to that instance on the local host. The command does not allow you to administer servers over the network, but only directly on the local host. The dpadm command has subcommands for each key management task. For a complete description, see dpadm(1M).

The dpconf command is an LDAP client. The command enables you to configure nearly all server settings on a running Directory Proxy 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 dpconf command has subcommands for each key configuration task. For a complete description, see dpconf(1M).

ProcedureTo Create a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

If you use DSCC to create a new server instance, you can choose to copy some or all of the server configuration settings from an existing server.

  1. Create the instance of Directory Proxy Server.


    $ dpadm create -p port instance-path
    

    For example, to create a new instance in the directory /local/dps, use this command:


    $ dpadm create -p 2389 /local/dps

    To specify any other parameter of the instance, see the dpadm(1M) man page.

  2. Type a password if required.

  3. Confirm that the instance has been created by verifying the status of the instance.


    $ dpadm info instance-path
    
  4. (Optional) If you installed Directory Proxy Server using the native packages, and your operating provides a service management solution, you can enable the server to be managed as a service, as shown in this table.

    Operating System 

    Command 

    Solaris 10 

    dpadm enable-service --type SMF instance-path

    Solaris 9 

    dpadm autostart instance-path

    Windows 

    dpadm enable-service --type WIN_SERVICE instance-path

  5. (Optional) 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 Proxy 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 Proxy" /local/dps
      Enter DSCC administrator's password:
      /local/dps is an instance of DPS
      Enter password of "cn=Proxy Manager" for /local/dps:
      Connecting to /local/dps
      Enabling DSCC access to /local/dps
      Registering /local/dps in DSCC on hostname.

      See dsccreg(1M) for more information about the command.

ProcedureTo Find the Status of a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Find the status of an instance of Directory Proxy Server.


    $ dpadm info instance-path
    

ProcedureTo Start and Stop Directory Proxy Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To start or stop Directory Proxy Server, do one of the following.

    • To start Directory Proxy Server, type:


      $ dpadm start instance-path
      

      For example, to start an instance at /local/dps, use this command:


      $ dpadm start /local/dps
    • To stop Directory Proxy Server, type:


      $ dpadm stop instance-path
      

      For example:


      $ dpadm stop /local/dps

ProcedureTo List All the Running Instances

  1. List the running instances on a host using the following command:


    dpadm list-running-instances [--all]

    The -–all option lists the running instances from any installation path.

ProcedureTo Stop the Running Instances

  1. Stop the running instances on a host using the following command:


    dpadm stop-running-instances [-i] [--force]

    For more information, see dpadm(1M).

ProcedureTo View Whether It Is Necessary to Restart a Directory Proxy Server Instance

Sometimes, a configuration change requires the server to be restarted before the change takes effect. Use this procedure to check whether it is necessary to restart a Directory Proxy Server instance after a configuration change.

  1. View whether it is necessary to restart the server.


    $ dpconf get-server-prop -h host -p port is-restart-required
    • If the command returns true, you must restart the instance of Directory Proxy Server.

    • If the command returns false, it is not necessary to restart the instance of Directory Proxy Server.

ProcedureTo Restart Directory Proxy Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Restart Directory Proxy Server.


    $ dpadm restart instance-path
    

    For example, to restart an instance at /local/dps, use this command:


    $ dpadm restart /local/dps

ProcedureTo Delete a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. (Optional) Stop the Directory Proxy Server instance.


    $ dpadm stop instance-path
    

    If you do not stop the instance, the delete command will stop it automatically. However, if you have enabled the instance in a service management solution, you must stop it manually.

  2. (Optional) If you have previously used DSCC to manage the server, use the command line to unregister the server.


    $ dsccreg remove-server /local/dps
    Enter DSCC administrator's password:
    /local/dps is an instance of DPS
    Enter password of "cn=Proxy Manager" for /local/dps:
    Unregistering /local/dps from DSCC on localhost.
    Connecting to /local/dps
    Disabling DSCC access to /local/dps

    For details, see the dsccreg(1M) man page.

  3. (Optional) If you previously enabled the server instance in a service management solution, then disable the server from being managed as a service.

    Operating System 

    Command 

    Solaris 10 

    dpadm disable-service --type SMF instance-path

    Solaris 9 

    dpadm autostart --off instance-path

    Windows 

    dpadm disable-service --type WIN_SERVICE instance-path

  4. Delete the instance.


    $ dpadm delete instance-path
    

Configuring Directory Proxy Server Instances

This section describes how to configure an instance of Directory Proxy Server. The procedures in this section use the dpadm and dpconf commands. For information about these commands, see the dpadm(1M) and dpconf(1M) man pages.

ProcedureTo Display the Configuration of Directory Proxy Server Instance

  1. Type dpconf info


    $ dpconf info -p port
    Instance Path           :  instance path
    Host Name               :  host
    Secure listen address   :  IP address
    Port                    :  port
    Secure port             :  secure port
    SSL server certificate  :  defaultServerCert
    
    Directory Proxy Server needs to be restarted.

    dpconf info displays Secure listen address and Non-secure listen address only if these properties are set to non-default values. The above output does not display Non-secure listen address, as this property is not set to a non-default value.

    dpconf info also reminds the user to restart the instance if it needs to be restarted.

    You can also use dpadm info INSTANCE_PATH to display Directory Proxy Server instance configuration information.

ProcedureTo Modify the Configuration of Directory Proxy Server

This section describes how to modify the configuration of Directory Proxy Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Find the current configuration of Directory Proxy Server.


    $ dpconf get-server-prop -h host -p port
    

    allow-cert-based-auth                      : allow
    allow-ldapv2-clients                       : true
    allow-persistent-searches                  : false
    allow-sasl-external-authentication         : true
    allow-unauthenticated-operations           : true
    allow-unauthenticated-operations-mode      : anonymous-and-dn-identified
    allowed-ldap-controls                      : -
    cert-data-view-routing-custom-list         : none
    cert-data-view-routing-policy              : all-routable
    cert-search-attr-mappings                  : none
    cert-search-base-dn                        : none
    cert-search-bind-dn                        : none
    cert-search-bind-pwd                       : none
    cert-search-user-attr                      : userCertificate
    compat-flag                                : none
    configuration-manager-bind-dn              : cn=proxy manager
    configuration-manager-bind-pwd             : {3DES}RPdIFbvoWdvhLR8lU43zCMZyKFGPxfFg
    connection-pool-wait-timeout               : 3s
    data-source-read-timeout                   : 20s
    data-view-automatic-routing-mode           : automatic
    email-alerts-enabled                       : false
    email-alerts-message-from-address          : local
    email-alerts-message-subject               : Proxy Server Administrative Alert
    email-alerts-message-subject-includes      : false
    -alert-code
    email-alerts-message-to-address            : root@localhost
    email-alerts-smtp-host                     : localhost
    email-alerts-smtp-port                     : smtp
    enable-remote-user-mapping                 : false
    enable-user-mapping                        : false
    enabled-admin-alerts                       : all
    enabled-ssl-cipher-suites                  : JRE
    enabled-ssl-protocols                      : SSLv3
    enabled-ssl-protocols                      : TLSv1
    encrypt-configuration                      : true
    extension-jar-file-url                     : none
    is-restart-required                        : false
    number-of-search-threads                   : 20
    number-of-worker-threads                   : 50
    proxied-auth-check-timeout                 : 30m
    remote-user-mapping-bind-dn-attr           : none
    revert-add-on-failure                      : true
    scriptable-alerts-command                  : echo
    scriptable-alerts-enabled                  : false
    search-mode                                : sequential
    search-wait-timeout                        : 10s
    ssl-client-cert-alias                      : none
    ssl-server-cert-alias                      : defaultServerCert
    supported-ssl-cipher-suites                : SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DHE_DSS_WITH_DES_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DHE_RSA_WITH_DES_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
    supported-ssl-cipher-suites                : SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DH_anon_WITH_DES_CBC_SHA
    supported-ssl-cipher-suites                : SSL_DH_anon_WITH_RC4_128_MD5
    supported-ssl-cipher-suites                : SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
    supported-ssl-cipher-suites                : SSL_RSA_EXPORT_WITH_RC4_40_MD5
    supported-ssl-cipher-suites                : SSL_RSA_WITH_3DES_EDE_CBC_SHA
    supported-ssl-cipher-suites                : SSL_RSA_WITH_DES_CBC_SHA
    supported-ssl-cipher-suites                : SSL_RSA_WITH_NULL_MD5
    supported-ssl-cipher-suites                : SSL_RSA_WITH_NULL_SHA
    supported-ssl-cipher-suites                : SSL_RSA_WITH_RC4_128_MD5
    supported-ssl-cipher-suites                : SSL_RSA_WITH_RC4_128_SHA
    supported-ssl-cipher-suites                : TLS_DHE_DSS_WITH_AES_128_CBC_SHA
    supported-ssl-cipher-suites                : TLS_DHE_RSA_WITH_AES_128_CBC_SHA
    supported-ssl-cipher-suites                : TLS_DH_anon_WITH_AES_128_CBC_SHA
    supported-ssl-cipher-suites                : TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
    supported-ssl-cipher-suites                : TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
    supported-ssl-cipher-suites                : TLS_KRB5_EXPORT_WITH_RC4_40_MD5
    supported-ssl-cipher-suites                : TLS_KRB5_EXPORT_WITH_RC4_40_SHA
    supported-ssl-cipher-suites                : TLS_KRB5_WITH_3DES_EDE_CBC_MD5
    supported-ssl-cipher-suites                : TLS_KRB5_WITH_3DES_EDE_CBC_SHA
    supported-ssl-cipher-suites                : TLS_KRB5_WITH_DES_CBC_MD5
    supported-ssl-cipher-suites                : TLS_KRB5_WITH_DES_CBC_SHA
    supported-ssl-cipher-suites                : TLS_KRB5_WITH_RC4_128_MD5
    supported-ssl-cipher-suites                : TLS_KRB5_WITH_RC4_128_SHA
    supported-ssl-cipher-suites                : TLS_RSA_WITH_AES_128_CBC_SHA
    supported-ssl-protocols                    : SSLv2Hello
    supported-ssl-protocols                    : SSLv3
    supported-ssl-protocols                    : TLSv1
    syslog-alerts-enabled                      : false
    syslog-alerts-facility                     : USER
    syslog-alerts-host                         : localhost
    time-resolution                            : 250ms
    time-resolution-mode                       : custome-resolution
    use-cert-subject-as-bind-dn                : true
    use-external-schema                        : false
    user-mapping-anonymous-bind-dn             : none
    user-mapping-anonymous-bind-pwd            : none
    user-mapping-default-bind-dn               : none
    user-mapping-default-bind-pwd              : none
    verify-certs                               : false

    Alternatively, view the current setting of one or more configuration properties.


    $ dpconf get-server-prop -h host -p port property-name ...

    For example, find whether unauthenticated operations are allowed by running this command:


    $ dpconf get-server-prop -h host -p port allow-unauthenticated-operations
    allow-unauthenticated-operations  :  true
  2. Change one or more of the configuration parameters.


    $ dpconf set-server-prop -h host -p port property:value ...

    For example, disallow unauthenticated operations by running this command:


    $ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:false

    If you attempt to perform an illegal change, the change is not made. For example, if you set the allow-unauthenticated-operations parameter to f instead of false, the following error is produced:


    $ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:f
    The value "f" is not a valid value for the property "allow-unauthenticated-operations".
    Allowed property values: BOOLEAN
    The "set-server-prop" operation failed.
  3. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Configuring the Proxy Manager

The Proxy Manager is the privileged administrator, comparable to the root user on UNIX systems. The Proxy Manager entry is defined when an instance of Directory Proxy Server is created. The default DN of the Proxy Manager is cn=Proxy Manager.

You can view and change the Proxy Manager DN and password, as shown in the following procedure.

ProcedureTo Configure the Proxy Manager

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Find the configuration of the Proxy Manager.


    $ dpconf get-server-prop -h host -p port configuration-manager-bind-dn\
     configuration-manager-bind-pwd
    
    
    configuration-manager-bind-dn   :  cn=proxy manager
    configuration-manager-bind-pwd  :  {3DES}U77v39WX8MDpcWVrueetB0lfJlBc6/5n

    The default value for the Proxy Manager is cn=proxy manager. A hashed value is returned for the configuration manager password.

  2. Change the DN of the Proxy Manager.


    $ dpconf set-server-prop -h host -p port configuration-manager-bind-dn:bindDN
    
  3. Create a file that contains the password for the Proxy Manager and set the property that points to that file.


    $ dpconf set-server-prop -h host -p port configuration-manager-bind-pwd-file:filename
    

Configuration Changes Requiring Server Restart

Most configuration changes to Directory Proxy Server and its entities can be made online. Certain changes require that the server be restarted before the changes take effect. If you make configuration changes to any properties in the following list, the server must be restarted:


custom-distribution-algorithm
distribution-algorithm
db-name
db-url
db-user
custom-distribution-algorithm
distribution-algorithm
custom-distribution-algorithm
distribution-algorithm
bind-dn
client-cred-mode
ldap-address
ldap-port
ldaps-port
num-bind-init
num-read-init
num-write-init
ssl-policy
load-balancing-algorithm
custom-distribution-algorithm
distribution-algorithm
listen-address
listen-port
number-of-threads
listen-address
listen-port
number-of-threads
custom-distribution-algorithm
distribution-algorithm
compat-flag
number-of-search-threads
number-of-worker-threads
syslog-alerts-enabled
syslog-alerts-host
time-resolution
use-external-schema
aci-data-view

The rws and rwd keywords of a property indicate whether changes to the property require the server to be restarted.

To determine whether a change to a property requires the server to be restarted, run the following command:


$ dpconf help-properties | grep property-name

For example, to determine whether changing the bind DN of an LDAP data source requires the server to be restarted, run the following command:


$ dpconf help-properties | grep bind-dn
connection-handler   	bind-dn-filters        rwd  STRING | any
This property specifies a set of regular expressions. The bind DN 
of a client must match at least one regular expression in order for 
the connection to be accepted by the connection handler. (Default: any)
ldap-data-source      bind-dn               rws  DN | ""
This property specifies the DN to use when binding to the LDAP data 
source. (Default: undefined)

To determine whether the server must be restarted following a configuration change, run the following command:


$ dpconf get-server-prop -h host -p port is-restart-required

Backing Up and Restoring Directory Proxy Server Instances

When you use dpadm to back up Directory Proxy Server, the configuration files and server certificates are backed up. If you have implemented Directory Proxy Server virtual ACIs, the ACIs are also backed up.

Directory Proxy Server automatically backs up the conf.ldif file whenever the server starts successfully.

ProcedureTo Back Up a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the instance of Directory Proxy Server.


    $ dpadm stop instance-path
    
  2. Back up the instance of Directory Proxy Server.


    $ dpadm backup instance-path archive-dir
    

    The archive-dir directory is created by the backup command and must not exist before you run the command. This directory contains a backup of each of the configuration files and the certificates.

ProcedureTo Restore a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

You must create a Directory Proxy Server instance before starting the restore operation.

  1. Stop the instance of Directory Proxy Server.


    $ dpadm stop instance-path
    
  2. Restore the instance of Directory Proxy Server.


    $ dpadm restore instance-path archive-dir
    
    • If the instance path exists, the restore operation is performed silently. The configuration files and the certificates in the archive-dir directory replace those in the instance-path directory.

    • If the instance path does not exist, the restore operation fails.

Chapter 18 LDAP Data Views

An LDAP data view exposes data in an LDAP server to a client request and specifies the data source pool that responds to the request. By defining LDAP data views, you can perform the following tasks:

Creating LDAP Data Views

Creating an LDAP data view includes the following steps:

  1. To Create an LDAP Data Source.

  2. To Create an LDAP Data Source Pool.

  3. To Attach an LDAP Data Source to a Data Source Pool.

  4. To Create an LDAP Data View.

Creating and Configuring LDAP Data Sources

This section describes how to use the dpconf command to create and configure LDAP data sources. For reference information about these topics, see LDAP Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure LDAP data sources, see the following procedures.

ProcedureTo Create an LDAP Data Source

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create the data source.


    $ dpconf create-ldap-data-source -h host -p port [-s] source-name host:port
    

    In this command, source-name is a name that you assign to the new data source. host and port refer to the host and port on which the LDAP server is running. Note that the data source does not use SSL by default. Use -s to enable to specify a secure port.

    If the host is specified by an IP V6 address, you need to use the IP V6 reference when you create the data source. For example, if Directory Proxy Server will bind to a host with the IP V6 address fe80::209:3dff:fe00:8c93 on port 2389, use the following command to create the data source:


    $ dpconf create-ldap-data-source -h host1 -p 1389 ipv6-host \
     [fe80::209:3dff:fe00:8c93]:2389

    If you use the console to create the data source, you must specify the actual IP V6 address (without the square brackets).

    For information about how to modify the properties of an LDAP data source, see To Configure an LDAP Data Source.

  2. (Optional) View the list of data sources.


    $ dpconf list-ldap-data-sources -h host -p port
    

ProcedureTo Configure an LDAP Data Source

The following procedure shows how to display the properties of an LDAP data source and how to set the properties that you require to change. The procedure shows the commands using which any of the properties of the LDAP data source can be changed. It also shows how to get the detailed information of a property, which helps you to set that property.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the properties of the data source by using this command syntax:


    $ dpconf get-ldap-data-source-prop -h host -p port \
    [-M unit] [-Z unit] source-name [property...]

    In this command, -M and -Z refer to the units in which you want data to be displayed. The M option specifies the unit of time. The value for -M can be M, w, d, h, m, s, or ms, to represent months, weeks, days, hours, minutes, seconds, or milliseconds. The -Z option specifies the data size unit. The value for -Z can be T, G, M, k, or b, to represent Terabytes, Gigabytes, Megabytes, kilobytes, or bytes.

    If you do not specify a property, all properties are displayed. The default properties of an LDAP data source are as follows:


    bind-dn                         :  -
    bind-pwd                        :  -
    client-cred-mode                :  use-client-identity
    connect-timeout                 :  10s
    description                     :  -
    down-monitoring-interval        :  inherited
    is-enabled                      :  false
    is-read-only                    :  true
    ldap-address                    :  host
    ldap-port                       :  port
    ldaps-port                      :  ldaps
    monitoring-bind-timeout         :  5s
    monitoring-entry-dn             :  ""
    monitoring-entry-timeout        :  5s
    monitoring-inactivity-timeout   :  2m
    monitoring-interval             :  30s
    monitoring-mode                 :  reactive
    monitoring-retry-count          :  3
    monitoring-search-filter        :  (|(objectClass=*)(objectClass=ldapSubEntry))
    num-bind-incr                   :  10
    num-bind-init                   :  10
    num-bind-limit                  :  1024
    num-read-incr                   :  10
    num-read-init                   :  10
    num-read-limit                  :  1024
    num-write-incr                  :  10
    num-write-init                  :  10
    num-write-limit                 :  1024
    proxied-auth-check-timeout      :  1.8s
    proxied-auth-use-v1             :  false
    ssl-policy                      :  never
    use-read-connections-for-writes :  false
    use-tcp-keep-alive              :  true
    use-tcp-no-delay                :  true
  2. Enable the data source.


    $ dpconf set-ldap-data-source-prop -h host -p port source-name is-enabled:true
  3. Configure all the properties that are listed in Step 1, if you want to change the default settings.


    $ dpconf set-ldap-data-source-prop -h host -p port source-name property:value
    

    For example, if you want to modify entries on a data source, configure the data source to allow write operations.


    $ dpconf set-ldap-data-source-prop -h host -p port source-name is-read-only:false

    To use a read connection to process write operation when all the write connections are busy, run the following command. The vice-versa is also true.


    dpconf set-ldap-data-source-prop -h host -p port source-name \
    use-read-connections-for-writes:true 

    To find information about a property used in a subcommand, run this command:


    $ dpconf help-properties ldap-data-source property
    

    For example, to find information about the is-read-only property, run this command:


    dpconf help-properties ldap-data-source is-read-only

    To list the key properties for data sources, use the verbose option -v with the list-ldap-data-sources subcommand.


    $ dpconf list-ldap-data-sources -v
    Name         is-enabled  ldap-address  ldap-port  ldaps-port  description
    -----------  ----------  ------------  ---------  ----------  -----------
    datasource0  true        myHost        myPort     ldaps       -
    datasource1  true        myHost        myPort     ldaps       -
  4. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server. For a list of configuration changes that require a server restart, see Configuration Changes Requiring Server Restart.

Creating and Configuring LDAP Data Source Pools

This section describes how to use the dpconf command to create and configure LDAP data source pools. For reference information about these topics, see LDAP Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure data source pools, see the following procedures:

ProcedureTo Create an LDAP Data Source Pool

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create one or more data source pools.


    $ dpconf create-ldap-data-source-pool -h host -p port pool-name
    

    Additional data source pools can be specified after the first pool-name. For information about how to modify the properties of a data source pool, see To Configure an LDAP Data Source Pool.

  2. (Optional) View the list of data source pools.


    $ dpconf list-ldap-data-source-pools -h host -p port
    

ProcedureTo Configure an LDAP Data Source Pool

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the properties of the data source pool by using this command syntax:


    $ dpconf get-ldap-data-source-pool-prop -h host -p port \
    [-M unit] [-Z unit] pool-name [property...]

    In this command, -M and -Z refer to the units in which you want data to be displayed. The M option specifies the unit of time. The value for -M can be M, w, d, h, m, s, or ms, to represent months, weeks, days, hours, minutes, seconds, or milliseconds. The -Z option specifies the data size unit. The value for -Z can be T, G, M, k, or b, to represent Terabytes, Gigabytes, Megabytes, kilobytes, or bytes.

    If you do not specify a property, all properties are displayed. The default properties of an LDAP data source pool are as follows:


    client-affinity-bind-dn-filters     :  any
    client-affinity-criteria            :  connection
    client-affinity-ip-address-filters  :  any
    client-affinity-policy              :  write-affinity-after-write
    client-affinity-timeout             :  20s
    description                         :  -
    enable-client-affinity              :  false
    load-balancing-algorithm            :  proportional
  2. Configure the properties that are listed in Step 1.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     property:value
    

    For information about how to configure the properties of a data source pool for load balancing and client affinity, see Chapter 20, Directory Proxy Server Load Balancing and Client Affinity.

Attaching LDAP Data Sources to a Data Source Pool

A data source that is attached to a data source pool is called an attached data source. The properties of an attached data source determine the load balancing configuration of the data source pool. When you configure the weights of an attached data source, consider the weights of all of the attached data sources in a data source pool. Ensure that the weights work together as required. For information about how to configure weights for load balancing, see To Configure Weights for Load Balancing.

ProcedureTo Attach an LDAP Data Source to a Data Source Pool

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Attach one or more data sources to a data source pool.


    $ dpconf attach-ldap-data-source -h host -p port pool-name \
     source-name [source-name ...]
  2. (Optional) View the list of attached data sources for a given data source pool.


    $ dpconf list-attached-ldap-data-sources -h host -p port -E pool-name
    

    In this command, -E is optional, and modifies the display output to show one property value per line.

  3. (Optional) View the key properties of the attached data sources for a given data source pool.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    

    In this command, -v specifies verbose output. For example, view the properties of an example data source pool.


    $ dpconf list-attached-ldap-data-sources -h host1 -p 1389 -v My-pool
    SRC_NAME     add-weight  bind-weight  compare-weight  
    -----------  ----------  -----------  --------------  
    datasource0  disabled    disabled     disabled        
    datasource1  disabled    disabled     disabled        
    
    delete-weight  modify-dn-weight  modify-weight  search-weight
    -------------  ----------------  -------------  -------------
    disabled       disabled          disabled       disabled
    disabled       disabled          disabled       disabled
  4. (Optional) View the properties of an attached data source by using the following command syntax:


    $ dpconf get-attached-ldap-data-source-prop -h host -p port [-M unit] [-Z unit] \
     pool-name source-name [property...]

    In this command, -M and -Z refer to the units in which you want data to be displayed. The M option specifies the unit of time. The value for -M can be M, w, d, h, m, s, or ms, to represent months, weeks, days, hours, minutes, seconds, or milliseconds. The -Z option specifies the data size unit. The value for -Z can be T, G, M, k, or b, to represent Terabytes, Gigabytes, Megabytes, kilobytes, or bytes.

    If you do not specify a property, all properties are displayed.

    The properties of an attached data source define the weight for each type of operation in load balancing. The default weights of an attached data source are as follows:


    add-weight        :  disabled  
    bind-weight       :  disabled  
    compare-weight    :  disabled  
    delete-weight     :  disabled  
    modify-dn-weight  :  disabled  
    modify-weight     :  disabled  
    search-weight     :  disabled 
  5. The default weights of an attached data source are 0 and disabled. You must set the weights of an attached data source for Directory Proxy Server to work as intended.

    In the following example, all the properties are set to one. You can change the values of these properties as per your requirements. For information about how to configure weights of an attached data source for load balancing, see To Configure Weights for Load Balancing.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name add-weight:1
    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name bind-weight:1
    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name compare-weight:1
    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name delete-weight:1
    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name modify-dn-weight:1
    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name modify-weight:1
    $ dpconf set-attached-ldap-data-source-prop -h host -p port \
    pool-name source-name search-weight:1

Working with LDAP Data Views

For information about how to create and configure LDAP data views, see the following procedures:

ProcedureTo Create an LDAP Data View

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create an LDAP data view.


    $ dpconf create-ldap-data-view -h host -p port view-name pool-name suffix-DN
    

    For information about how to modify the properties of an LDAP data view, see To Configure an LDAP Data View.

  2. View the list of LDAP data views.


    $ dpconf list-ldap-data-views -h host -p port
    

ProcedureTo Configure an LDAP Data View

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the properties of an LDAP data view.


    $ dpconf get-ldap-data-view-prop -h host -p port view-name
    

    If you create a data view without configuring any of the properties, your data view has the following configuration:


    alternate-search-base-dn                    :  ""
    attr-name-mappings                          :  none
    base-dn                                     :  suffix-DN
    contains-shared-entries                     :  false
    custom-distribution-algorithm-class         :  none
    description                                 :  -
    distribution-algorithm                      :  none
    dn-join-rule                                :  none
    dn-mapping-attrs                            :  none
    dn-mapping-source-base-dn                   :  none
    excluded-subtrees                           :  -
    filter-join-rule                            :  none
    is-enabled                                  :  true
    is-read-only                                :  false
    is-routable                                 :  true
    ldap-data-source-pool                       :  pool-name
    lexicographic-attrs                         :  all
    lexicographic-lower-bound                   :  none
    lexicographic-upper-bound                   :  none
    non-viewable-attr                           :  none
    non-writable-attr                           :  none
    numeric-attrs                               :  all
    numeric-default-data-view                   :  false
    numeric-lower-bound                         :  none
    numeric-upper-bound                         :  none
    pattern-matching-base-object-search-filter  :  all
    pattern-matching-base-dn-regular-expression :  all
    pattern-matching-dn-regular-expression      :  all
    pattern-matching-one-level-search-filter    :  all
    pattern-matching-subtree-search-filter      :  all
    process-bind                                :  -
    replication-role                            :  master
    viewable-attr                               :  all except non-viewable-attr
    writable-attr                               :  all except non-writable-attr

    Note –

    All users except the Proxy Manager see the cn=config and cn=monitor suffixes from the back-end server. By default, data from the back-end servers is not available to the Proxy Manager. The cn=config and cn=monitor subtrees that are available to the Proxy Manager are those of the proxy itself.

    When you create a Directory Proxy Server instance, a connection handler for the Proxy Manager is created with an empty data view policy. If the Proxy Manager requires access to back-end data, you must add a data view to the data view policy of the Proxy Manager connection handler. On such a data view, the cn=config and cn=monitor subtrees are excluded by default.


  2. Change one or more of the properties that are listed in Step 1.


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
     property:value [property:value ... ]

    For example, to access the dc=example,dc=com subtree on a data source, specify dn-mapping-source-base-dn in the data view.


    $ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView \
    dn-mapping-source-base-dn:dc=example,dc=com

    To add a value to a multi-valued property, use this command:


    $ dpconf set-ldap-data-view-prop -h host -p port view-name property+:value
    

    To remove a value from a multi-valued property, use this command:


    $ dpconf set-ldap-data-view-prop -h host -p port view-name property-:value
    
  3. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Accessing Configuration Entries for a Directory Server by Using Directory Proxy Server

The configuration entries for Directory Proxy Server are in cn=config. When you use Directory Proxy Server to access configuration entries, by default, you access the configuration entries of Directory Proxy Server.

To access the configuration entries of a directory server, it is better to connect directly to Directory Server, not to Directory Proxy Server. For information about how to configure Directory Server, see Chapter 3, Directory Server Configuration.


Caution – Caution –

If you reconfigure Directory Proxy Server to access the configuration entries of a directory server, you are likely to break the administration framework of Directory Proxy Server.


If you really need to access the configuration entries of a directory server through Directory Proxy Server, take special steps to ensure that you do not break the administration framework of Directory Proxy Server. This section describes how to access the configuration entries of a directory server by using Directory Proxy Server.

ProcedureTo Access the Configuration Entries of a Directory Server by Using Directory Proxy Server

  1. Create a data source as described in Creating and Configuring LDAP Data Sources.

  2. Create an LDAP data source pool as described in Creating and Configuring LDAP Data Source Pools.

  3. To expose the configuration entries of one specific data source, attach only one LDAP data source to the LDAP data source pool as described in Attaching LDAP Data Sources to a Data Source Pool.


    $ dpconf attach-ldap-data-source -h host -p port pool-name data-source-name
    

    After performing this step, a client can access the configuration entries of the data source that is connected to Directory Proxy Server.

    If you attach more than one LDAP data source to the LDAP data source pool, you can access the configuration entries of one of the data sources connected to Directory Proxy Server. However, you cannot know which data source the configuration entries belong to.

    You must set the weights of an attached data source for Directory Proxy Server to work as intended. For more information, see Attaching LDAP Data Sources to a Data Source Pool.

  4. Create an LDAP data view to expose cn=config.


    $ dpconf create-ldap-data-view -h host -p port view-name pool-name cn=config

Renaming Attributes and DNs

Each entry in a directory is identified by a DN and a set of attributes and their values. Often, the DNs and the attributes defined on the client side do not map to the DNs and the attributes defined on the server side. Data views can be defined to rename DNs and attributes. When a client makes a request, the DNs and attributes are renamed to match the server side. When the result is returned to a client, the DNs and attributes are changed back to match the client side.

For information about attribute renaming and DN renaming, see Attribute Renaming and DN Renaming in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. For information about how to rename attributes and DNs, see the following procedures:

ProcedureTo Configure Attribute Renaming

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set one or more attr-name-mappings properties on the data view for which you want to configure attribute mapping.


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
      attr-name-mappings:client-side-attribute-name#server-side-attribute-name[#qualifier]\
      [attr-name-mappings:client-side-attribute-name#server-side-attribute-name#qualifier...]

    For example, rename surname on the client side to sn on the server side.


    $ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView \
     attr-name-mappings:surname#sn

    To add an attribute mapping to an existing list of mappings, use this command:


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
     attr-name-mappings+:client-side-attribute-name#server-side-attribute-name[#qualifier]
    

    To remove an attribute mapping from an existing list of mappings, use this command:


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
     attr-name-mappings-:client-side-attribute-name#server-side-attribute-name[#qualifier]
    

ProcedureTo Configure DN Renaming

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the base-dn property and the DN mapping properties of the data view for which you want to rename DNs.


    $ dpconf get-ldap-data-view-prop -h host -p port view-name base-dn \
     dn-mapping-source-base-dn dn-mapping-attrs

    The properties have the following meanings:

    • base-dn is the DN of the subtree on the client side, which is equivalent to the base DN of the data view.

    • dn-mapping-source-base-dn is the DN of the subtree on the server side.

    • dn-mapping-attrs defines a list of attributes that contain DNs of entries.

    For example, the data view for the dc=example,dc=com database on the client side has the following values when DN renaming is not defined:


    $ dpconf get-ldap-data-view-prop myDataView base-dn \
     dn-mapping-source-base-dn dn-mapping-attrs
     base-dn                    :  dc=example,dc=com
     dn-mapping-attrs           :  none
     dn-mapping-source-base-dn  :  none
  2. Map a DN on the client side to a DN on the server side.


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
      dn-mapping-source-base-dn:server-side-dn
    

    For example, map the dc=example,dc=com database on the client side to dc=example,dc=org on the server side.


    $ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView \
     dn-mapping-source-base-dn:dc=example,dc=org
  3. Rename attributes in the portion of the DIT that is affected by Step 2, if those attributes contain DNs.


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
      dn-mapping-attrs:attribute-name [dn-mapping-attrs:attribute-name ...]

    For example, if the group attribute contains DNs in the namespace affected by the rename operation in Step 2, rename the attribute as follows:


    $ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView dn-mapping-attrs:group

    To add a DN mapping to an existing list of mappings, use this command:


    $ dpconf set-ldap-data-view-prop -h host -p port \
    view-name dn-mapping-attrs+:attribute-name
    

    To remove a DN mapping from an existing list of mappings, use this command:


    $ dpconf set-ldap-data-view-prop -h host -p port \
    view-name dn-mapping-attrs-:attribute-name
    
  4. View the base-dn property and the DN mapping properties of the data view for which you have renamed DNs.


    $ dpconf get-ldap-data-view-prop -h host -p port view-name base-dn \
     dn-mapping-source-base-dn dn-mapping-attrs

    For example, the data view for the dc=example,dc=com database on the client side has the following values after DN renaming:


    $ dpconf get-ldap-data-view-prop -h host1 -p 1389 myDataView base-dn \
     dn-mapping-source-base-dn dn-mapping-attrs
     base-dn                    :  dc=example,dc=com
     dn-mapping-attrs           :  group
     dn-mapping-source-base-dn  :  dc=example,dc=org

Configuring View Exclusion Base and Alternate Search Base

When a subordinate data view is created, Directory Proxy Server automatically excludes the subordinate data view from the superior data view. When a request targets the subordinate data view, the request is sent to the subordinate data view, not to the superior data view.

When an alternate search base is specified in a subordinate data view, search operations targeted at the superior data view are also performed in the subordinate data view.

By default, Directory Proxy Server automatically configures the excluded-subtrees and alternate-search-base-dn properties. The following procedure describes how to configure these properties manually.

ProcedureTo Manually Configure the excluded-subtrees and alternate-search-base-dn Properties

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure Directory Proxy Server to manually route requests.


    $ dpconf set-server-prop -h host -p port data-view-automatic-routing-mode:manual

    When data-view-automatic-routing-mode is manual, Directory Proxy Server does not generate the excluded-subtrees and alternate-search-base-dn properties. You must set the values of these properties manually. The values that you set here are not checked by Directory Proxy Server. Be aware that setting these values incorrectly can break the administration path.

    Alternatively, configure Directory Proxy Server to partially route requests manually.


    $ dpconf set-server-prop -h host -p port data-view-automatic-routing-mode:limited

    When data-view-automatic-routing-mode is limited, Directory Proxy Server does not generate the excluded-subtrees and alternate-search-base-dn properties. However, Directory Proxy Server does check that the values set here do not conflict with the administration path.

  2. Configure the view exclusion base.


    $ dpconf set-ldap-data-view-prop -h host -p port view-name excluded-subtrees:suffix-DN
    

    The view exclusion base determines branches of the DIT whose entries are not exposed by the data view.

  3. Configure the alternate search base.


    $ dpconf set-ldap-data-view-prop -h host -p port view-name \
     alternate-search-base-dn:search-base-DN
    

    The alternate search base determines other branches of the DIT in which entries belonging to this data view may be located. The base DN is defined by default as an alternate search base in all data views.

Creating and Configuring Data Views for Example Use Cases

This section contains the following information about data views and how to create and configure them:

The examples in this section assume that the connection handler allows all client connections to be processed by Directory Proxy Server.

Default Data View

If you create a data view without configuring any of the properties, your data view has the following configuration:


alternate-search-base-dn                    :  ""
alternate-search-base-dn                    :  base-DN
attr-name-mappings                          :  none
base-dn                                     :  suffix-DN
contains-shared-entries                     :  -
description                                 :  -
distribution-algorithm                      :  -
dn-join-rule                                :  -
dn-mapping-attrs                            :  none
dn-mapping-source-base-dn                   :  none
excluded-subtrees                           :  -
filter-join-rule                            :  -
is-enabled                                  :  true
is-read-only                                :  false
is-routable                                 :  true
ldap-data-source-pool                       :  pool-name
lexicographic-attrs                         :  all
lexicographic-lower-bound                   :  none
lexicographic-upper-bound                   :  none
non-viewable-attr                           :  -
non-writable-attr                           :  -
numeric-attrs                               :  all
numeric-default-data-view                   :  false
numeric-lower-bound                         :  none
numeric-upper-bound                         :  none
pattern-matching-base-object-search-filter  :  all
pattern-matching-dn-regular-expression      :  all
pattern-matching-one-level-search-filter    :  all
pattern-matching-subtree-search-filter      :  all
process-bind                                :  -
replication-role                            :  master
viewable-attr                               :  all except non-viewable-attr
writable-attr                               :  all except non-writable-attr

Data Views That Route All Requests, Irrespective of the Target DN of the Request

This section shows the configuration of a data view that routes all the requests that do not match their targets mentioned in their target DNs, to a data source pool. This data view is called the root data view. The root data view is created by default when an instance of Directory Proxy Server is created. For information about the root data view, see Data Views to Route All Requests, Irrespective of the Target DN of the Request in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The root data view has the following configuration:


alternate-search-base-dn                    :  -
attr-name-mappings                         :  none
base-dn                                    :  ""
contains-shared-entries                    :  -
description                                :  Automatically-generated data view 
                                              able to route client operations 
                                              independently of the operation base dn
distribution-algorithm                     :  -
dn-join-rule                               :  -
dn-mapping-attrs                           :  none
dn-mapping-source-base-dn                  :  none
excluded-subtrees                          :  ""
excluded-subtrees                          :  cn=config
excluded-subtrees                          :  cn=monitor
excluded-subtrees                          :  cn=proxy manager
excluded-subtrees                          :  cn=virtual access controls
excluded-subtrees                          :  dc=example,dc=com
filter-join-rule                           :  -
is-enabled                                 :  true
is-read-only                               :  false
is-routable                                :  true
ldap-data-source-pool                      :  defaultDataSourcePool
lexicographic-attrs                        :  all
lexicographic-lower-bound                  :  none
lexicographic-upper-bound                  :  none
non-viewable-attr                          :  -
non-writable-attr                          :  -
numeric-attrs                              :  all
numeric-default-data-view                  :  false
numeric-lower-bound                        :  none
numeric-upper-bound                        :  none
pattern-matching-base-object-search-filter :  all
pattern-matching-dn-regular-expression     :  all
pattern-matching-one-level-search-filter   :  all
pattern-matching-subtree-search-filter     :  all
process-bind                               :  -
replication-role                           :  master
viewable-attr                              :  all except non-viewable-attr
writable-attr                              :  all except non-writable-attr

Data Views That Route Requests When a List of Subtrees Is Stored on Multiple, Data-Equivalent Data Sources

This section describes how to configure a data view that routes requests targeted at a list of subtrees to a set of data-equivalent data sources. For information about this type of deployment, see Data Views to Route Requests When a List of Subtrees Are Stored on Multiple, Data-Equivalent Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The example in this section has multiple data sources that contain the same set of subtrees. The data sources are data-equivalent and are pooled into one data source pool for load balancing. A data view is configured for each subtree to expose that subtree to client requests. The following figure shows the sample deployment.

Figure 18–1 Sample Deployment That Routes Requests When a List of Subtrees Is Stored on Multiple, Data-Equivalent Data Sources

Figure shows an example deployment that routes requests
targeted at a list of subtrees to a set of data-equivalent data sources.

ProcedureTo Configure Data Views That Route Requests When a List of Subtrees Is Stored on Multiple, Data-Equivalent Data Sources

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.

  2. Create a data source pool as described in Creating and Configuring LDAP Data Source Pools.

  3. Attach the data sources to the data source pool as described in Attaching LDAP Data Sources to a Data Source Pool.

  4. (Optional) Configure load balancing.

    For information, see Configuring Load Balancing.

  5. Create a data view with a base DN at dc=example1,dc=com that refers to the data source pool.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-1 \
    data-source-pool-1 dc=example1,dc=com
  6. Create another data view with a base DN at dc=example2,dc=com that refers to the data source pool.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-2 \
    data-source-pool-1 dc=example2,dc=com

    The other properties of the data views are the same as the default data view in Default Data View.

  7. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Data Views That Provide a Single Point of Access When Different Subtrees Are Stored in Different Data Sources

This section describes how to configure a data view that provides a single point of access to different subtrees stored in multiple data sources. For information about this type of deployment, see Data Views to Provide a Single Point of Access When Different Subtrees Are Stored on Different Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The example in this section contains a data view for each subtree. A data source pool is configured for each set of data-equivalent data sources. The following figure shows the example deployment.

Figure 18–2 Sample Deployment That Provides a Single Point of Access When Different Subtrees Are Stored on Different Data Sources

Figure shows an sample deployment that provides a single
point of access to different subtrees stored in multiple data sources.

ProcedureTo Configure Data Views That Provide a Single Point of Access When Different Subtrees Are Stored on Different Data Sources

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.

  2. Create two data source pools as described in Creating and Configuring LDAP Data Source Pools.

  3. Attach the data sources that contain dc=example1,dc=com to data-source-pool-1, and the data sources that contain dc=example2,dc=com to data-source-pool-2, as described in Attaching LDAP Data Sources to a Data Source Pool.

  4. (Optional) Configure load balancing.

    For information, see Configuring Load Balancing.

  5. Create a data view with a base DN at dc=example1,dc=com that refers to data-source-pool-1.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-1 \
    data-source-pool-1 dc=example1,dc=com
  6. Create another data view with a base DN at dc=example2,dc=com that refers to data-source-pool-2.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-2 \
    data-source-pool-1 dc=example2,dc=com

    The other properties of the data views are the same as the default data view in Default Data View.

  7. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Data Views That Provide a Single Point of Access When Superior and Subordinate Subtrees Are Stored in Different Data Sources

This section describes how to configure a data view for a single point of access when a superior branch of a subtree is stored in a different data source to a subordinate branch. For information about this type of deployment, see Data Views to Route Requests When Superior and Subordinate Subtrees Are Stored in Different Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The example in this section contains three data views. The base DN of data view 1 is superior to the base DN of data view 2 and the base DN of data view 3. Or, in other words, data source 2 and data source 3 contain subtrees that are subordinate to the subtree on data source 1. The following figure shows the example deployment.

Figure 18–3 Sample Deployment to Routes Requests When Superior and Subordinate Subtrees Are Stored in Different Data Sources

Figure shows a sample deployment that routes requests
when superior and subordinate subtrees are stored in different data sources.

Directory Proxy Server automatically excludes a subordinate branch of a subtree from a data view when the subordinate branch is configured as the base DN of a separate data view.

ProcedureTo Configure Data Views That Provide a Single Point of Access When Superior and Subordinate Subtrees Are Stored in Different Data Sources

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.

  2. Create three data source pools as described in Creating and Configuring LDAP Data Source Pools.

  3. Attach the data sources to the data source pools by following the instructions in Attaching LDAP Data Sources to a Data Source Pool.

    • Attach the data sources that contain dc=example,dc=com to data-source-pool-1.

    • Attach the data sources that contain ou=computer,dc=example,dc=com to data-source-pool-2.

    • Attach the data sources that contain ou=people,dc=example,dc=com to data-source-pool-3.

  4. (Optional) Configure load balancing.

    For information, see Configuring Load Balancing.

  5. Create a data view with a base DN at dc=example,dc=com and a data source pool data-source-pool-1.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-1 \
     data-source-pool-1 dc=example,dc=com
  6. Create a data view with a base DN at ou=computer,dc=example,dc=com and a data source pool data-source-pool-2.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-2 \
     data-source-pool-2 ou=computer,dc=example,dc=com
  7. Create a data view with a base DN at ou=people,dc=example,dc=com and a data source pool data-source-pool-3.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-3 \
     data-source-pool-3 ou=people,dc=example,dc=com
  8. Verify that the subtrees ou=computer,dc=example, dc=com and ou=people,dc=example, dc=com have been excluded from dataview-1 by looking at the excluded-subtrees parameter.


    $ dpconf get-ldap-data-view-prop -h host1 -p 1389 dataview-1 excluded-subtrees

    The list of excluded subtrees is returned.

  9. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Chapter 19 Directory Proxy Server Certificates

This chapter describes how to configure certificates on Directory Proxy Server. For information about configuring certificates on Directory Server, see Managing Certificates.

The procedures in this chapter use the dpadm and dpconf commands. For information about these commands, see the dpadm(1M) and dpconf(1M) man pages.

This chapter covers the following topics:

Default Self-Signed Certificate

When you create a Directory Proxy Server instance, it has a default self-signed certificate. A self-signed certificate is a public and private key pair, where the public key is self-signed by Directory Proxy Server.

ProcedureViewing the Default Self-Signed Certificate

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the default self-signed certificate.


    $ dpadm show-cert instance-path defaultservercert

Creating, Requesting and Installing Certificates for Directory Proxy Server

To run the Secure Sockets Layer (SSL) on Directory Proxy Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution.

The PKI solution involves an external Certificate Authority (CA). For a PKI solution you need a CA-signed server certificate, which contains both a public key and a private key. This certificate is specific to one Directory Proxy Server instance. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes called a CA root key or root certificate.

For information about how to create a non-default self-signed certificate and to request and install a CA-signed certificate, see the following procedures.

ProcedureTo Create a Non-default Self-Signed Certificate for Directory Proxy Server

When you create a Directory Proxy Server instance, a default self-signed certificate is automatically provided. If you want to create a self-signed certificate with non-default settings, use this procedure.

The procedure creates the public and private key pair for a server certificate, where the public key is signed by Directory Proxy Server. A self-signed certificate is valid for three months.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To create a non-default self-signed certificate for Directory Proxy Server, type:


    $ dpadm add-selfsign-cert instance-path cert-alias
    

    where cert-alias is the name of the self-signed certificate.

    For example, you could create a certificate called my-self-signed-cert as follows:


    $ dpadm add-selfsign-cert /local/dps my-self-signed-cert

    For a description of all command options, see the dpadm(1M) man page or type dpadm add-selfsign-cert --help at the command line.

ProcedureTo Request a CA-Signed Certificate for Directory Proxy Server

Self-signed certificates are useful for test purposes. However, in a production environment, using trusted Certificate Authority (CA) certificates is more secure.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Request a CA-signed server certificate.


    $ dpadm request-cert instance-path cert-alias
    

    where cert-alias is the name of the certificate that you are requesting. Certificate Authorities might require all of the options of the command to identify the server. For a description of all command options, see the dpadm(1M) man page.

    The process for obtaining a CA certificate depends on the CA that you use. Some commercial CAs provide a web site that allows you to download the certificate. Other CAs will send the certificate to you in email.

    For example, you could request a certificate called my-CA-signed-cert as follows:


    $ dpadm request-cert -S cn=my-request,o=test /local/dps my-CA-signed-cert
    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBYDCBygIBADAhMQ0wCwYDVQQDEwRnZXJpMRAwDgYDVQQDEwdteWNlcnQ0MIGfMA0GCSqGSIb3
    DQEBAQUAA4GNADCBiQKBgQC3v9ubG468wnjBDAMbRrEkmFDTQzT+LO30D/ALLXOiElVsHrtRyWhJ
    PG9cURI9uwqs15crxCpJvho1kt3SB9+yMB8Ql+CKnCQDHlNAfnn30MjFHShv/sAuEygFsN+Ekci5
    W1jySYE2rzE0qKVxWLSILFo1UFRVRsUnORTX/Nas7QIDAQABoAAwDQYJKoZIhvcNAQEEBQADgYEA
    fcQMnZNLpPobiX1xy1ROefPOhksVz8didY8Q2fjjaHG5lajMsqOROzubsuQ9Xh4ohT8kIA6xcBNZ
    g8FRNIRAHCtDXKOdOm3CpJ8da+YGI/ttSawIeNAKU1DApF9zMb7c2lS4yEfWmreoQdXIC9YeKtF6
    zwbn2EmIpjHzETtS5Nk=
    -----END NEW CERTIFICATE REQUEST-----

    When you request a certificate by using the dpadm request-cert command, the certificate request is a PKCS #10 certificate request in Privacy Enhanced Mail (PEM) format. PEM is the format specified by RFCs 1421 through 1424. For more information, see http://www.ietf.org/rfc/rfc1421.txt. The PEM format represents a base64-encoded certificate request in ASCII format.

    When you request a CA-signed certificate, a temporary self-signed certificate is created. When you receive and install the CA-signed certificate from the CA, the new certificate replaces the temporary self-signed certificate.

    Save the certificate request for future reference. You may need it while renewing the certificate.

  2. Send the certificate request to the CA, according to its procedures.

    After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the response time can be short. However, if the CA is external to your company, the CA can take several weeks to respond to your request.

  3. Save the certificate that you receive from the CA.

    Save your certificate in a text file, and back up the certificate in a safe location.

ProcedureTo Install a CA-Signed Server Certificate for Directory Proxy Server

To trust the CA-signed server certificate, you must install the certificate on a Directory Proxy Server instance. This procedure installs the public key of a CA certificate to the certificate database on Directory Proxy Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. See if the trusted CA certificate for this CA is already installed.

    To do this, list all installed CA certificates, as described in To List CA Certificates.

  2. If the trusted CA certificate is not installed, add it to the certificate database on the Directory Proxy Server instance.


    $ dpadm add-cert instance-path cert-alias cert-file
    

    where cert-alias is the name of the trusted CA certificate and cert-file is the name of the file containing the trusted CA certificate.

  3. Install the CA-signed server certificate to the certificate database.


    $ dpadm add-cert instance-path cert-alias cert-file
    

    Where cert-alias is the name of the CA-signed server certificate and cert-file is the name of the file containing the CA-signed server certificate.


    Note –

    The cert-alias name must be the same as the cert-alias used in the certificate request.


    For example, you can add a CA-signed server certificate named CA-cert to the certificate database on/local/dps as follows:


    $ dpadm add-cert /local/dps CA-cert /local/safeplace/ca-cert-file.ascii

Renewing an Expired CA-Signed Certificate for Directory Proxy Server

This section describes how to renew an expired CA-signed server certificate.

ProcedureTo Renew an Expired CA-Signed Server Certificate for Directory Proxy Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain an updated certificate from your CA.

  2. Install the certificate on your instance of Directory Proxy Server.


    $ dpadm renew-cert instance-path cert-alias cert-file
    

    where cert-alias is the name of the new certificate and cert-file is the name of the file containing the certificate. For a description of all command options, see the dpadm(1M) man page.

Listing Certificates

For information about how to list server and CA certificates, see the following procedures.

ProcedureTo List Server Certificates

This procedure lists all certificates that are installed on an instance of Directory Proxy Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. List the server certificates in the certificate database on the Directory Proxy Server instance.


    $ dpadm list-certs instance-path
    

    By default, an instance of Directory Proxy Server contains a server certificate named defaultservercert. The text Same as issuer indicates that the default certificate is a self-signed server certificate.

    For example:


    $ dpadm list-certs /local/dps
    Alias             Valid from       Expires on       Self-signed? Issued by          Issued to
    ----------------- ---------------- ---------------- ------------ ------------------ --------------
    defaultservercert 2006/06/01 04:15 2008/05/31 04:15 y            CN=myserver:myport Same as issuer
    1 certificate found.

ProcedureTo List CA Certificates

This procedure lists CA certificates that are installed on an instance of Directory Proxy Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. List the CA certificates in the certificate database on the Directory Proxy Server instance.


    $ dpadm list-certs -C instance-path
    

    For example:


    $ dpadm list-certs -C /local/dps
    Alias   Valid from       Expires on        Built-in  Issued by    Issued to
    ------  ----------       ----------------  --------- ---------    ---------
    CAcert1 1999/06/21 06:00 2020/06/21 06:00  y         CN=company1, O=company2
    ...

Adding a Certificate From a Back-End LDAP Server to the Certificate Database on Directory Proxy Server

This section describes how to add a certificate from a back-end LDAP server to the certificate database on Directory Proxy Server.

ProcedureTo Add a Certificate From a Back-End Directory Server to the Certificate Database on Directory Proxy Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Display the certificate from the back-end Directory Server in PEM format by using this command syntax:


    dsadm show-cert -F ascii instance-path [cert-alias]

    If you do not specify a cert-alias, the default server certificate is displayed. For a description of all command options, see the dsadm(1M) man page.

    For example, show the default self-signed server certificate as follows:


    $ dsadm show-cert -F ascii /local/dsInst defaultCert
    -----BEGIN CERTIFICATE-----
    MIICJjCCAY+gAwIBAgIFAIKL36kwDQYJKoZIhvcNAQEEBQAwVzEZMBcGA1UEChMQ
    U3VuIE1pY3Jvc3lzdGVtczEZMBcGA1UEAxMQRGlyZWN0b3J5IFNlcnZlcjENMAsG
    A1UEAxMEMjAxMTEQMA4GA1UEAxMHY29uZHlsZTAeFw0wNjA1MjIxMTQxNTVaFw0w
    NjA4MjIxMTQxNTVaMFcxGTAXBgNVBAoTEFN1biBNaWNyb3N5c3RlbXMxGTAXBgNV
    BAMTEERpcmVjdG9yeSBTZXJ2ZXIxDTALBgNVBAMTBDIwMTExEDAOBgNVBAMTB2Nv
    bmR5bGUwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAK9U3ry3sJmEzwQY8CGd
    7S2MTZuBedo03Vea1lfDtD08WIsdDMzhHplTdeHAkWWNc8g2PDcEFXeWp9UXFMuD
    Pcia7t8HtFkm73VmlriWhMd8nn3l2vkxhsPK2LHFEeOIUDR9LBBiMiEeLkjdoEhE
    VLMSoYKqKI+Aa5grINdmtFzBAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAF4eDbSd7
    qy2l10dIogT+rnXZ362gLTlQFCblhbGpmmptbegUdL1ITGv/62q1isPV2rW7CkjM
    Cqb0fo3k5UkKKvW+JbMowpQeAPnlgpX612HuDr1tldnKV4eyU7gpG31t/cpACALQ
    7OPi1A7oVb2Z8OJKfEJHkp3txBSsiI2gTkk=
    -----END CERTIFICATE-----
  2. Save the certificate.

    Save your certificate in a text file, and back up the certificate in a safe location.

  3. Add the certificate from the back-end LDAP server to the certificate database on an instance of Directory Proxy Server.


    $ dpadm add-cert instance-path cert-alias cert-file
    

    where cert-alias is the name of the certificate and cert-file is the name of the file containing the certificate.

    For example, you could add the certificate defaultCert as follows:


    $ dpadm add-cert /local/dps defaultCert /local/safeplace/defaultCert.ascii

Exporting a Certificate to a Back-End LDAP Server

Back-end LDAP servers might require a certificate from Directory Proxy Server. This section describes how to configure Directory Proxy Server to export a certificate to a back-end LDAP server.

ProcedureTo Configure Directory Proxy Server to Export a Client Certificate to a Back-End LDAP Server

  1. Specify the certificate to be sent to the back-end LDAP server.


    $ dpconf set-server-prop -h host -p port ssl-client-cert-alias:cert-alias
    

    Where cert-alias is the name of the certificate. For a description of all command options, see the dpconf(1M) man page.

  2. Copy the contents of the certificate to a file.


    $ dpadm show-cert -F ascii -o filename instance-path cert-alias
    
  3. Add the certificate to the certificate database for the back-end LDAP server as described in To Add the CA-Signed Server Certificate and the Trusted CA Certificate.

Next Steps

Configure the back-end LDAP server for client authentication. For information about how to do this for Directory Server, see Configuring Credential Levels and Authentication Methods.

See Also

For information about configuring certificate-based authentication between clients and Directory Proxy Server, see To Configure Certificate-based Authentication.

Backing Up and Restoring a Certificate Database for Directory Proxy Server

Server certificates are backed up when you use dpadm to back up Directory Proxy Server. The backed up certificates are stored in the archive-path/alias directory.

For information about how to back up and restore Directory Proxy Server, see Backing Up and Restoring Directory Proxy Server Instances.

Prompting for a Password to Access the Certificate Database

By default, the password for the certificate database is managed internally. Therefore, you do not need to type a certificate password or specify the password file. When the certificate database is managed internally through a stored password, the password is stored in a secure environment.

For more security and more control over certificates, configure Directory Proxy Server to prompt for a password on the command line. You are then prompted to enter the password for all dpadm subcommands except autostart, backup, disable-service, enable-service, info, restore, and stop.

For information about configuring Directory Proxy Server to prompt or not to prompt for passwords, see the following procedures.

ProcedureTo Prompt for a Password to Access the Certificate Database

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the server.


    $ dpadm stop instance-path
    Directory Proxy Server instance 'instance-path' stopped
  2. Set the password prompt flag to on, then type and confirm the certificate database password.


    $ dpadm set-flags instance-path cert-pwd-prompt=on
    Choose the certificate database password:
    Confirm the certificate database password:
  3. Start the server, then type the certificate database password.


    $ dpadm start instance-path
    Enter the certificate database password:

ProcedureTo Disable the Password Prompt to Access the Certificate Database

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the server.


    $ dpadm stop instance-path
    Directory Proxy Server instance 'instance-path' stopped
  2. Set the password prompt flag to off, then type the existing password.


    $ dpadm set-flags instance-path cert-pwd-prompt=off
    Enter the old password:
  3. Start the server.


    $ dpadm start instance-path
    

Chapter 20 Directory Proxy Server Load Balancing and Client Affinity

For a description of load balancing and client affinity, see Chapter 16, Directory Proxy Server Load Balancing and Client Affinity, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This chapter covers the following topics:

Configuring Load Balancing

For information about load balancing, see Load Balancing in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This section explains how to configure load balancing and provides sample configurations.

ProcedureTo Select a Load Balancing Algorithm

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain the current load balancing algorithm by viewing the properties of the LDAP data source pool.


    $ dpconf get-ldap-data-source-pool-prop -h host -p port pool-name
    

    The default properties of an LDAP data source pool are as follows:


    client-affinity-bind-dn-filters     :  any
    client-affinity-criteria            :  connection
    client-affinity-ip-address-filters  :  any
    client-affinity-policy              :  write-affinity-after-write
    client-affinity-timeout             :  20s
    description                         :  -
    enable-client-affinity              :  false
    load-balancing-algorithm            :  proportional

    By default, the load balancing algorithm is proportional.

  2. Configure the LDAP data source pool to use an algorithm.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
      load-balancing-algorithm:selected-algorithm
    

    where selected-algorithm is one of the following:

    • failover

    • operational-affinity

    • proportional

    • saturation

    For more information about the algorithms, see Introduction to Load Balancing in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

  3. Restart the instance of Directory Proxy Server.


    $ dpadm restart instance-path
    

ProcedureTo Configure Weights for Load Balancing

You need to configure the weights of an attached data source in relation to the weights of any other attached data sources in the data source pool. Consider the weights of all of your attached data sources. If a data source has a weight of disabled for a type of operation, requests of that type are never sent to that data source. If a data source has a weight of 0 (zero), no requests are distributed to that data source.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the list of data sources that are attached to the data source pool.


    $ dpconf list-attached-ldap-data-sources -h host -p port pool-name
    
  2. View the properties of one of the attached data sources.


    $ dpconf get-attached-ldap-data-source-prop pool-name \
     attached-data-source-name
    

    The properties of an attached data source define the weight for each type of operation. The default weights of an attached data source are as follows:


    add-weight        :  disabled  
    bind-weight       :  disabled  
    compare-weight    :  disabled  
    delete-weight     :  disabled  
    modify-dn-weight  :  disabled  
    modify-weight     :  disabled  
    search-weight     :  disabled 
  3. Configure the weights of one of the attached data sources.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name \
     attached-data-source-name add-weight:value \
     bind-weight:value compare-weight:value delete-weight:value \
     modify-dn-weight:value modify-weight:value search-weight:value
    
  4. Repeat Step 2 and Step 3 for the other attached data sources.

  5. Compare the key parameters of the attached data sources.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    

    For example, a data source pool can contain data sources with the following weights:


    $ dpconf list-attached-ldap-data-sources -h host1 -p 1389 -v myPool
    SRC_NAME add-weight bind-weight compare-weight delete-weight 
    -------- ---------- ----------- -------------- ------------- 
    DS-1     disabled   3		       disabled       disabled      
    DS-2     2          2           2              2             
    DS-3     1          1           1              1             
    
    modify-dn-weight modify-weight search-weight
    ---------------- ------------- -------------
    disabled         disabled      disabled
    2                2             2
    1                1             1

Example Configurations for Load Balancing

This section contains sample procedures for configuring each of the load balancing algorithms.

ProcedureTo Configure the Proportional Algorithm for Load Balancing

For a description of the proportional algorithm, see Proportional Algorithm for Load Balancing in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

In this example, the data source ds–1 is configured with twice the weight of the other two data sources.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Creating LDAP Data Views.

  1. Configure the data source pool to use the proportional algorithm for load balancing.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
      load-balancing-algorithm:proportional
  2. Configure the properties of the first data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \
     add-weight:2 bind-weight:2 compare-weight:2 delete-weight:2 modify-dn-weight:2 \
     modify-weight:2 search-weight:2
  3. Configure the properties of the second data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  4. Configure the properties of the third data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  5. Compare the key parameters of the attached data sources.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    SRC_NAME add-weight bind-weight compare-weight delete-weight 
    -------- ---------- ----------- -------------- ------------- 
    ds-1     2          2           2              2             
    ds-2     1          1           1              1             
    ds-3     1          1           1              1             
    
    modify-dn-weight modify-weight search-weight
    ---------------- ------------- -------------
    2                2             2
    1                1             1
    1                1             1
  6. Restart the instance of Directory Proxy Server.


    $ dpadm restart instance-path
    

ProcedureTo Configure the Saturation Algorithm for Load Balancing

For a description of the saturation algorithm, see Saturation Algorithm for Load Balancing in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

In this example, the data source ds-1 performs the majority of bind operations but does not perform any other types of operations. The three data sources are configured with the following weights :

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Creating LDAP Data Views.

  1. Configure the data source pool to use the saturation algorithm for load balancing.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     load-balancing-algorithm:saturation
  2. Configure the properties of the first data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \
     add-weight:disabled bind-weight:3 compare-weight:disabled delete-weight:disabled \
     modify-dn-weight:disabled modify-weight:disabled search-weight:disabled
  3. Configure the properties of the second data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \
     add-weight:2 bind-weight:2 compare-weight:2 delete-weight:2 modify-dn-weight:2 \
     modify-weight:2 search-weight:2
  4. Configure the properties of the third data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  5. Compare the key parameters of the attached data sources.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    SRC_NAME add-weight bind-weight compare-weight delete-weight 
    -------- ---------- ----------- -------------- ------------- 
    ds-1     disabled   3		       disabled       disabled      
    ds-2     2          2           2              2             
    ds-3     1          1           1              1             
    
    modify-dn-weight modify-weight search-weight
    ---------------- ------------- -------------
    disabled         disabled      disabled
    2                2             2
    1                1             1
  6. Restart the instance of Directory Proxy Server.


    $ dpadm restart instance-path
    

ProcedureTo Configure the Operational Affinity Algorithm for Global Account Lockout

For a description of this algorithm, Operational Affinity Algorithm for Global Account Lockout in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This example has three data sources. The data source ds-1 is configured to receive all bind requests.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Creating LDAP Data Views.

  1. Configure the data source pool to use the operational affinity algorithm.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     load-balancing-algorithm:operational-affinity
  2. Configure the properties of the first data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \
     add-weight:1 bind-weight:100 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  3. Configure the properties of the second data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  4. Configure the properties of the third data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  5. Compare the key parameters of the attached data sources.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    SRC_NAME add-weight bind-weight compare-weight delete-weight 
    -------- ---------- ----------- -------------- ------------- 
    ds-1     1          100         1              1             
    ds-2     1          1           1              1             
    ds-3     1          1           1              1             
    
    modify-dn-weight modify-weight search-weight
    ---------------- ------------- -------------
    1                1             1
    1                1             1
    1                1             1
  6. Restart the instance of Directory Proxy Server.


    $ dpadm restart instance-path
    

ProcedureTo Configure Operational Affinity Algorithm for Cache Optimization

For a description of this algorithm, see Operational Affinity Algorithm for Cache Optimization in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This example has three data sources. All search and compare operations are treated by the data source ds-1. When ds-1 responds to a request, the targeted entry is stored in the cache. If ds-1 responds repeatedly to the same request, the data source can use cached data.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Creating LDAP Data Views.

  1. Configure the data source pool to use the operational affinity algorithm.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     load-balancing-algorithm:operational-affinity
  2. Configure the properties of the first data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \
     add-weight:1 bind-weight:1 compare-weight:100 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:100
  3. Configure the properties of the second data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  4. Configure the properties of the third data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  5. Compare the key parameters of the attached data sources.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    SRC_NAME add-weight bind-weight compare-weight delete-weight 
    -------- ---------- ----------- -------------- ------------- 
    ds-1     1          1           100            1             
    ds-2     1          1           1              1             
    ds-3     1          1           1              1             
    
    modify-dn-weight modify-weight search-weight
    ---------------- ------------- -------------
    1                1             100
    1                1             1
    1                1             1
  6. Restart the instance of Directory Proxy Server.


    $ dpadm restart instance-path
    

ProcedureTo Configure the Failover Algorithm for Load Balancing

For a description of the failover algorithm, see Failover Algorithm for Load Balancing in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This example has three data sources. The data source ds-1 receives all requests. If ds-1 fails, ds-2 receives all requests until ds-1 recovers. If ds-2 fails before ds-1 recovers, ds-3 receives all requests.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Creating LDAP Data Views.

  1. Configure the data source pool to use the failover algorithm for load balancing.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     load-balancing-algorithm:failover
  2. Configure the properties of the first data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \
     add-weight:3 bind-weight:3 compare-weight:3 delete-weight:3 modify-dn-weight:3 \
     modify-weight:3 search-weight:3
  3. Configure the properties of the second data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \
     add-weight:2 bind-weight:2 compare-weight:2 delete-weight:2 modify-dn-weight:2 \
     modify-weight:2 search-weight:2
  4. Configure the properties of the third data source.


    $ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \
     add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \
     modify-weight:1 search-weight:1
  5. Compare the key parameters of the attached data sources.


    $ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name
    SRC_NAME add-weight bind-weight compare-weight delete-weight 
    -------- ---------- ----------- -------------- ------------- 
    ds-1     3          3           3              3             
    ds-2     2          2           2              2             
    ds-3     1          1           1              1             
    
    modify-dn-weight modify-weight search-weight
    ---------------- ------------- -------------
    3                3             3
    2                2             2
    1                1             1
  6. Restart the instance of Directory Proxy Server.


    $ dpadm restart instance-path
    

Configuring Directory Proxy Server To Perform Load Balancing

A simple case of load balancing consists of sending search and compare operations to one set of directories, and sending other operations to another set. Directory Proxy Server receives all client operations. The server must determine which set gets the reads, and which set gets the other operations.

    The key stages in configuring Directory Proxy Server to handle this load balancing scenario are as follows.

  1. Add directories as data sources for Directory Proxy Server.

  2. Add the data sources to a data source pool.

  3. Configure some of the data sources to accept search and compare, other data sources to accept add, bind, delete, modify, and modify DN operations.

  4. Add the data source pool to a data view.

The following example involves Directory Proxy Server, listening on port 9389. The proxy is configured here to balance the load as described across one Directory Server instance, ds1:1389, handling search and compare operations, and another Directory Server instance, ds2:2389, handling other operations.

The first step creates the data sources, and enables the data sources. This step requires a proxy server restart.


$ dpconf create-ldap-data-source -p 9389 ds1 localhost:1389
$ dpconf create-ldap-data-source -p 9389 ds2 localhost:2389
$ dpconf set-ldap-data-source-prop -p 9389 ds1 is-enabled:true
$ dpconf set-ldap-data-source-prop -p 9389 ds2 is-enabled:true
$ dpadm restart /local/dps

The second step adds the data sources to a data source pool.


$ dpconf create-ldap-data-source-pool -p 9389 "Directory Pool"
$ dpconf attach-ldap-data-source -p 9389 "Directory Pool" ds1 ds2

The third step configures ds1 to accept search and compare operations, ds2 to accept other operations.


$ dpconf set-attached-ldap-data-source-prop -p 9389 "Directory Pool" ds1 \
add-weight:disabled bind-weight:disabled compare-weight:1 delete-weight:disabled \
modify-dn-weight:disabled modify-weight:disabled search-weight:1
$ dpconf set-attached-ldap-data-source-prop -p 9389 "Directory Pool" ds2 \
add-weight:1 bind-weight:1 compare-weight:disabled delete-weight:1 \
modify-dn-weight:1 modify-weight:1 search-weight:disabled

The fourth step adds the data source pool to a data view, so that client application requests are routed to the pool.


$ dpconf create-ldap-data-view -p 9389 "Balanced View" "Directory Pool" \
dc=example,dc=com

Configuring Client Affinity

Client affinity reduces the risk of propagation delay in load-balanced deployments. For information about client affinity, see Client Affinity in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This section explains how to configure affinity between a client connection and a data source, and provides sample configurations.

ProcedureTo Configure Client Affinity

This procedure describes how to configure affinity between a client connection and a data source.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the current load balancing algorithm by viewing the properties of the data source pool.


    $ dpconf get-ldap-data-source-pool-prop -h host -p port pool-name
    

    The default properties of a data source pool are as follows:


    client-affinity-bind-dn-filters     :  any
    client-affinity-criteria            :  connection
    client-affinity-ip-address-filters  :  any
    client-affinity-policy              :  write-affinity-after-write
    client-affinity-timeout             :  20s
    description                         :  -
    enable-client-affinity              :  false
    load-balancing-algorithm            :  proportional

    These parameters configure client affinity: client-affinity-bind-dn-filters, client-affinity-criteria, client-affinity-ip-address-filters, client-affinity-policy, client-affinity-timeout, and enable-client-affinity. For a description of the properties and a list of their valid values, type:


    dpconf help-properties ldap-data-source-pool client-affinity-bind-dn-filters \
    client-affinity-criteria client-affinity-policy client-affinity-ip-address-filters\
     client-affinity-timeout enable-client-affinity

    For more information about the properties, see these man pages: client-affinity-bind-dn-filters(5dpconf), client-affinity-criteria(5dpconf), client-affinity-ip-address-filters(5dpconf)client-affinity-policy(5dpconf), client-affinity-timeout(5dpconf), and enable-client-affinity(5dpconf).

  2. Enable client affinity.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     enable-client-affinity:true
  3. Select a policy for client affinity.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     client-affinity-policy:selected-policy
    

    where selected-policy is one of the following:

    write-affinity-after-write

    Affinity for write requests after the first write request

    read-write-affinity-after-write

    Affinity for all requests after the first write request

    read-write-affinity-after-any

    Affinity for all requests after the first read request or write request

    read-affinity-after-write

    Affinity for the first read request after a write request

  4. Configure the duration of the client affinity.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     client-affinity-timeout:time-out[unit]

    The default unit for timeout is milliseconds.

    The above setting is applicable to the only connection under consideration. It is not applicable to all the connections from a particular client.

Example Configurations for Client Affinity

This section contains example configurations related to client affinity, and includes examples for replication delay, verifying write operations, and connection-based routing.

ProcedureTo Configure Client Affinity for Replication Delay When a Data Source Pool Contains Masters and Consumers

This procedure configures client affinity for all read and write operations that occur up to three seconds after the first write operation.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the affinity parameters for the data source pool.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     client-affinity-policy:read-write-affinity-after-write client-affinity-timeout:3000 \
     enable-client-affinity:true

ProcedureTo Configure Client Affinity to Verify Each Write Operation With a Read Operation

This procedure configures client affinity for the first read operation after each write operation. The example could be for an application where a specified bind DN validates each write operation by performing a read operation.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the affinity parameters for the data source pool.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     client-affinity-policy:read-affinity-after-write enable-client-affinity:true

ProcedureTo Configure Client Affinity for Client—Based Routing

If an application makes an update using one connection from the pool but then uses a different connection to do the search for that entry, the affinity setting on the connection used to do the update is not used because the search is done from a different connection. The search operation could also be routed to a different server than where the update was performed. In this case, the affinity feature works only within the same client connection.

To resolve this, affinity should be defined at the client level such as an IP address or bind DN. When an update is made by a client, all the connections from that client follow the same affinity rule.

  1. Specify the criteria to determine if the requests are coming from the same client.


    dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
    client-affinity-criteria:ip-address-and-bind-dn 

    For all the options, see client-affinity-criteria(5dpconf).

    The server matches the bind DN as well as the IP address of the client requests, if the entries meet the criteria then they are from the same client.

  2. Specify the regular expressions that the bind DN of the connection must match to consider that requests come from the same client.


    dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
    client-affinity-bind-dn-filters:"uid=boss*"
  3. Specify the IPv4 or IPv6 address that the IP address of the connection must match to consider that requests come from the same client.


    dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
    client-affinity-ip-address-filters:129.157.192.108

ProcedureTo Configure Client Affinity for Connection-Based Routing

In versions prior to Directory Proxy Server 6.0, one connection was opened between a client and an LDAP server. The same connection was used for all requests from the client until the connection was closed. This type of routing is called connection-based routing. This procedure describes how to configure client affinity for connection-based routing.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Ensure that all data sources are attached to the data source pool and that client-cred-mode is set to use-client-identity.

  1. Configure the affinity parameters for the data source pool.


    $ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \
     client-affinity-policy:read-write-affinity-after-any enable-client-affinity:true

Chapter 21 Directory Proxy Server Distribution

Directory Proxy Server enables distribution through the definition of data views. Data views are defined with a view base, which determines the base DN of the entries in that data view. Based on the distribution algorithms provided in Directory Proxy Server, you can specify how entries are divided among the different data views.

For an overview of Directory Proxy Server distribution and a description of example use cases, see Chapter 17, Directory Proxy Server Distribution, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This chapter covers the following topics:

Configuring Directory Proxy Server Distribution Algorithms

Directory Proxy Server provides the following distribution algorithms:

Configuring Pattern Matching Distribution Algorithm

Directory Proxy Server distributes the requests to data views based on the match between the parameters of the requests and one or more patterns. Set the following parameters to configure the Pattern matching distribution algorithm:

All the pattern matching distribution algorithm properties are multivalued. Use PROP+:VAL to add a value, and PROP-:VAL to remove a value. For example:


$ dpconf set-ldap-data-view-prop -p port-number ldap-data-view \
pattern-matching-dn-regular-expression:value
$ dpconf set-ldap-data-view-prop -p port-number ldap-data-view \
pattern-matching-dn-regular-expression+:value2

The order in which values are set, the priority is decided.


$ ldapsearch -D "cn=proxy manager" -w - -p port-number -b "cn=ldap-data-view,cn=data views,cn=config" \
"objectclass=*" dnMatchingRegex

version: 1
dn: cn=ldap-data-view,cn=data views,cn=config
dnMatchingRegex: 1:value
dnMatchingRegex: 2:value2

In the above example, the value prefixed by 1 is of highest priority.

To switch back to version 6 behavior for pattern matching distribution algorithm, set the compat-flag Directory Proxy Server configuration property to pattern-matching-algo-6.

The configuration attributes that end with filter are LDAP filters, not regular expressions. These LDAP filters are evaluated against LDAP filters contained in the incoming search requests.

For example, use the following settings to configure the Pattern Matching distribution algorithm to send the requests for the users with even uid to even data view and the users with odd uid to odd data view.


$ dpconf set-ldap-data-view-prop even
pattern-matching-base-object-search-filter:'|(uid=\2a)(uid=*0)(uid=*2)\
(uid=*4)(uid=*6)(uid=*8))'\
pattern-matching-one-level-search-filter:'|(uid=\2a)(uid=*0)(uid=*2)\
(uid=*4)(uid=*6)(uid=*8))'\
pattern-matching-subtree-search-filter:'|(uid=\2a)(uid=*0)(uid=*2)\
(uid=*4)(uid=*6)(uid=*8))'\
pattern-matching-dn-regular-expression:'uid=[0-9]+[02468]'
distribution-algorithm: pattern-matching 

$ dpconf set-ldap-data-view-prop odd
pattern-matching-base-object-search-filter:'|(uid=\2a)(uid=*1)(uid=*3)\
(uid=*5)(uid=*7)(uid=*9))'\
pattern-matching-one-level-search-filter:'|(uid=\2a)(uid=*1)(uid=*3)\
(uid=*5)(uid=*7)(uid=*9))'\
pattern-matching-subtree-search-filter:'|(uid=\2a)(uid=*1)(uid=*3)\
(uid=*5)(uid=*7)(uid=*9))'\
pattern-matching-dn-regular-expression:'uid=[0-9]+[13579]'
distribution-algorithm: pattern-matching 

In the (uid=\2a) expression, the \2a is an ASCII representation of * where 2 and a are two hexadecimal digits. The (uid=\2a) expression makes sure that the data view accepts the requests for all uids.

The syntax supported by the pattern matching algorithm is specified by the Java Pattern class (documented at ). This syntax is not the same as the usual regex syntax.

Configuring Numeric Distribution Algorithm

Directory Proxy Server distributes the requests to data views according to the numeric value of the RDN in the request. The numeric value is taken from the value of the first RDN beneath the base DN of the data view. Set the following parameters define the Numeric bounds:

For example, to configure the numeric distribution algorithm to send the requests for uid between 0 to 99 to a specific data view. Use the same syntax for the rest of the users but with a different data view.


$ dpconf set-ldap-data-view-prop dataview distribution-algorithm:numeric \
 numeric-attrs:uid numeric-lower-bound:0 numeric-upper-bound:99

Configuring Lexicographic Distribution Algorithm

Directory Proxy Server distributes the requests to data views according to the lexicographic value of the RDN in the request. Lexicographic bounds are taken from the value of the first RDN beneath the base DN of the data view. Set the following parameters to define the Lexicographic bounds:

For example, to configure the Lexicographic distribution algorithm to send the requests of the users whose name starts between A to M to one data view and the requests for the rest of the users to another data view.


$ dpconf set-ldap-data-view-prop dataview distribution-algorithm:lexicographic \
 lexicographic-attrs:cn lexicographic-lower-bound:A lexicographic-upper-bound:M

Configuring Replication Distribution Algorithm

Directory Proxy Server distributes the requests to data views according to the role of the data view in replication. The algorithm distributes write operations to all data sources in the data source pool and read operations to a single data source. The replication role is defined by the replication-role parameter. A data view can have a master role or a consumer role.


$ dpconf set-ldap-data-view-prop dataview distribution-algorithm:replication

Configuring Custom Distribution Algorithm

Custom distribution algorithm can be configured for all types of data views, that is, ldap-data-view, jdbc-data-view, ldif-data-view, and join-data-view. In the following procedure the algorithm is set only for ldap-data-view.

ProcedureTo Configure Custom Distribution Algorithm

  1. Set the extension-jar-file-url property to contain the path of the Java Archive (JAR) file containing your distribution algorithm class.


    $ dpconf set-server-prop -h host -p port extension-jar-file-url:jar file path
    

    The jar file path can be replaced with a valid JAR file path such as file:/expt/dps/custom_plugin/myjar.jar.

  2. Before you configure custom-distribution-algorithm, set distribution-algorithm to none.


    $ dpconf set-ldap-data-view-prop view name distribution-algorithm:none
  3. Set the custom-distribution-algorithm property to your custom distribution algorithm class.


    $ dpconf set-ldap-data-view-prop view name \
    custom-distribution-algorithm:PackageName.AlgoClassName
    

Configuring Directory Proxy Server for Distribution of Suffix Data

A simple case of data distribution consists of storing entries having UIDs beginning with A through M in one set of directories, and storing entries having UIDs beginning with N through Z in another set of directories. Directory Proxy Server receives all client operations. The server must determine which set of directories handles A through M, and which set handles N through Z.

    The key stages in configuring Directory Proxy Server to handle this data distributions scenario are as follows.

  1. Add directories as data sources for Directory Proxy Server.

  2. Add the data sources to data source pools to handle the different data distributions.

  3. Create data views designed to distribute client requests to the appropriate data pools.

  4. Split the LDIF to be loaded into the appropriate data sources.

  5. Import the split LDIF into the appropriate data sources.

  6. Adjust the operation based weights for the data sources attached to the appropriate data pools.

The following example involves Directory Proxy Server, listening on port 9389. To keep the example simple, the proxy is configured here to distribute as described across only three Directory Server instances. For availability and read scalability, use replicated directory topologies to store LDAP data. One Directory Server instance, dsA-M:1389 handles the user entries having UIDs beginning with A through M. Another Directory Server instance, dsN-Z:2389, handles the user entries having UIDs beginning with N through Z. A final directory instance handles the base entries of the suffix, dsBase:3389.

The first step creates and enables the data sources. The base data source holds entries near the root of the suffix that do not have UIDs. In a typical deployment, these entries would be much fewer in number than distributed entries.


$ dpconf create-ldap-data-source -p 9389 dsA-M localhost:1389
$ dpconf set-ldap-data-source-prop -p 9389 dsA-M is-enabled:true

$ dpconf create-ldap-data-source -p 9389 dsN-Z localhost:2389
$ dpconf set-ldap-data-source-prop -p 9389 dsN-Z is-enabled:true

$ dpconf create-ldap-data-source -p 9389 dsBase localhost:3389
$ dpconf set-ldap-data-source-prop -p 9389 dsBase is-enabled:true

The second step adds the data sources to a data source pool.


$ dpconf create-ldap-data-source-pool -p 9389 "Base Pool"
$ dpconf attach-ldap-data-source -p 9389 "Base Pool" dsBase

$ dpconf create-ldap-data-source-pool -p 9389 "A-M Pool"
$ dpconf attach-ldap-data-source -p 9389 "A-M Pool" dsA-M

$ dpconf create-ldap-data-source-pool -p 9389 "N-Z Pool"
$ dpconf attach-ldap-data-source -p 9389 "N-Z Pool" dsN-Z

The third step creates data views designed to distribute client requests to the appropriate data pools. Notice how the base pool handles dc=example,dc=com, whereas the pools holding data distributed according to UID values handle ou=people,dc=example,dc=com. This step requires a server restart.


$ dpconf create-ldap-data-view -p 9389 "Base View" "Base Pool" \
dc=example,dc=com

$ dpconf create-ldap-data-view -p 9389 "A-M View" "A-M Pool" \
ou=people,dc=example,dc=com
$ dpconf set-ldap-data-view-prop -p 9389 "A-M View" \
distribution-algorithm:lexicographic lexicographic-attrs:uid \
lexicographic-lower-bound:a lexicographic-upper-bound:m
The proxy server will need to be restarted in order for the changes to take effect

$ dpconf create-ldap-data-view -p 9389 "N-Z View" "N-Z Pool" \
ou=people,dc=example,dc=com
$ dpconf set-ldap-data-view-prop -p 9389 "N-Z View" \
distribution-algorithm:lexicographic lexicographic-attrs:uid \
lexicographic-lower-bound:n lexicographic-upper-bound:z
The proxy server will need to be restarted in order for the changes to take effect
$ dpadm restart /local/dps

The fourth step splits the LDIF to be loaded into the appropriate data sources. This example uses both the dpadm split-ldif command to perform the initial split, and also some file editing to retain the top entry in all the data sources. This makes it possible both to retain the top entry that specifies access control instructions, and to use a single import command for each data source.


$ dpadm split-ldif /local/dps /opt/SUNWdsee7/resources/ldif/Example.ldif /tmp

This step also requires a top entry that is added to the LDIF before import.


$ cp /opt/SUNWdsee7/resources/ldif/Example.ldif /tmp/top.ldif
$ vi /tmp/top.ldif 
dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc: example
aci: (target ="ldap:///dc=example,dc=com")(targetattr !=
 "userPassword")(version 3.0;acl "Anonymous read-search access";
 allow (read, search, compare)(userdn = "ldap:///anyone");)
aci: (target="ldap:///dc=example,dc=com") (targetattr =
  "*")(version 3.0; acl "allow all Admin group"; allow(all) groupdn =
  "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

$ cat /tmp/top.ldif /tmp/base\ view.ldif > /tmp/top\ and\ base\ view.ldif
$ cat /tmp/top.ldif /tmp/a-m\ view.ldif > /tmp/top\ and\ a-m\ view.ldif
$ cat /tmp/top.ldif /tmp/n-z\ view.ldif > /tmp/top\ and\ n-z\ view.ldif

The fifth step imports the split LDIF into the appropriate data sources. Here, the directory handling the base entries is on port 3389. The directory handling A-M is listening on port 1389. The directory handling N-Z is listening on port 2389.


$ dsconf import -p 1389 /tmp/top\ and\ a-m\ view.ldif dc=example,dc=com
...
Task completed (slapd exit code: 0).

$ dsconf import -p 2389 /tmp/top\ and\ n-z\ view.ldif dc=example,dc=com
...
Task completed (slapd exit code: 0).
$ dsconf import -p 3389 /tmp/top\ and\ base\ view.ldif dc=example,dc=com
...
Task completed (slapd exit code: 0).

The sixth step adjusts the operation based weights for the data sources attached to the appropriate data pools. If client applications perform operations other than searches, then weights must be set for those operations as well.


$ dpconf set-attached-ldap-data-source-prop -p 9389 "Base Pool" dsBase search-weight:1
$ dpconf set-attached-ldap-data-source-prop -p 9389 "A-M Pool" dsA-M search-weight:1
$ dpconf set-attached-ldap-data-source-prop -p 9389 "N-Z Pool" dsN-Z search-weight:1

After the operations based weights are set, client applications can search through Directory Proxy Server as if the data were not physically distributed.

The following search looks for a user whose UID begins with R.


$ ldapsearch -p 9389 -b dc=example,dc=com uid=rfisher
version: 1
dn: uid=rfisher, ou=People, dc=example,dc=com
cn: Randy Fisher
sn: Fisher
givenName: Randy
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
ou: Human Resources
ou: People
l: Cupertino
uid: rfisher
mail: rfisher@example.com
telephoneNumber: +1 408 555 1506
facsimileTelephoneNumber: +1 408 555 1992
roomNumber: 1579

The next search looks for one of the base entries.


$ ldapsearch -p 9389 -b ou=groups,dc=example,dc=com cn=hr\ managers
version: 1
dn: cn=HR Managers,ou=groups,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: HR Managers
ou: groups
uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com
uniqueMember: uid=cschmith, ou=People, dc=example,dc=com
description: People who can manage HR entries

Creating and Configuring Data Views for Example Use Cases

This section contains the following information about data views and how to create and configure them:

The examples in this section assume that the connection handler allows all client connections to be processed by Directory Proxy Server.

Data Views That Provide a Single Point of Access When Different Parts of a Subtree Are Stored in Different Data Sources

This section describes how to configure a data view that provides a single point of access to different parts of a subtree. This example contains two data views with the same base DN. A numeric distribution algorithm is used to separate entries into different data views. A data source pool is configured for each set of data-equivalent data sources. The following figure shows the example deployment.

For information about this type of deployment, see Data Views to Route Requests When Different Parts of a Subtree Are Stored in Different Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

Figure 21–1 Sample Deployment That Provides a Single Point of Access When Different Parts of a Subtree Are Stored in Different Data Sources

Figure shows a sample deployment that provides a single
point of access to different parts of subtree stored in multiple data sources.

ProcedureTo Configure Data Views That Provide a Single Point of Access When Different Parts of a Subtree Are Stored in Different Data Sources

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.

  2. Create two data source pools as described in Creating and Configuring LDAP Data Source Pools.

  3. Attach the data sources that contain one part of the subtree to data-source-pool-1, and the data sources that contain the other part of the subtree to data-source-pool-2, as described in Attaching LDAP Data Sources to a Data Source Pool.

  4. (Optional) Configure load balancing.

    For information, see Configuring Load Balancing.

  5. Create a data view with a distribution algorithm to select entries in ou=people,dc=example,dc=com with uid between 0 and 99, and configure the data view to direct requests to data-source-pool-1.


    $ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-1 \
     ldap-data-source-pool:data-source-pool-1 base-dn:ou=people,dc=example,dc=com \
     distribution-algorithm	:numeric numeric-attrs:uid numeric-lower-bound	:0 \
     numeric-upper-bound	:99
  6. Create another data view with a distribution algorithm to select entries in ou=people,dc=example,dc=com with uid between 100 and 199, and configure the data view to direct requests to data-source-pool-2.


    $ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-2 \
     ldap-data-source-pool:data-source-pool-2 base-dn:ou=people,dc=example,dc=com \
     distribution-algorithm:numeric numeric-attrs:uid numeric-lower-bound:100
     numeric-upper-bound	:199

    The other properties of the data views are the same as the default data view in Default Data View.

  7. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Data Views With Hierarchy and a Distribution Algorithm

This section describes how to configure a data view to combine hierarchy with distribution algorithms. For information about this type of deployment, see Data Views With Hierarchy and a Distribution Algorithm in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The example in this section contains four data views. The base DN of data view 1 is superior to the base DNs of the other data views. Data view 3 and data view 4 have the same base DN, but a numeric distribution algorithm separates the entries into different data views.

Directory Proxy Server automatically excludes a subordinate branch of a subtree from a data view when the subordinate branch is configured as the base DN of a separate data view. A numeric distribution algorithm separates entries from the same subtree into different data views. A data source pool is configured for each set of data-equivalent data sources.

The following figure shows the example deployment.

Figure 21–2 Sample Data View With Hierarchy and a Distribution Algorithm

Figure shows a sample with data views that combine hierarchy
and distribution algorithms.

ProcedureTo Configure Data Views With Hierarchy and a Distribution Algorithm

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.

  2. Create four data source pools as described in Creating and Configuring LDAP Data Source Pools.

  3. Attach the data sources to the data source pools by following the instructions in Attaching LDAP Data Sources to a Data Source Pool.

    • Attach the data sources that contain dc=example,dc=com to data-source-pool-1.

    • Attach the data sources that contain ou=computer,dc=example,dc=com to data-source-pool-2.

    • Attach the data sources that contain entries in ou=people,dc=example,dc=com with uid between 0 and 99 to data-source-pool-3.

    • Attach the data sources that contain entries in ou=people,dc=example,dc=com with uid between 100 and 199 to data-source-pool-4.

  4. (Optional) Configure load balancing.

    For information, see Configuring Load Balancing.

  5. Create a data view with a base DN at dc=example,dc=com, that refers to data-source-pool-1.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-1 \
     data-source-pool-1 dc=example,dc=com
  6. Create a data view with a base DN at ou=computer,dc=example,dc=com that refers to data-source-pool-2.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-2 \
     data-source-pool-2 ou=computer,dc=example,dc=com
  7. Create a data view with a base DN at ou=people,dc=example,dc=com that refers to data-source-pool-3. Configure a distribution algorithm on the data view to select entries with uid between 0 and 99.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-3 \
     data-source-pool-3 ou=people,dc=example,dc=com
    $ dpconf set-ldap-data-view-prop dataview-3 distribution-algorithm:numeric \
     numeric-attrs:uid numeric-lower-bound:0 numeric-upper-bound:99
  8. Create a data view with a base DN at ou=people,dc=example,dc=com that refers to data-source-pool-4, and configure a distribution algorithm on the data view to select entries with uid between 100 and 199.


    $ dpconf create-ldap-data-view -h host1 -p 1389 dataview-4 \
     data-source-pool-4 ou=people,dc=example,dc=com
    $ dpconf set-ldap-data-view-prop dataview-4 distribution-algorithm:numeric \
     numeric-attrs:uid numeric-lower-bound:100 numeric-upper-bound:199
  9. Verify that the subtrees ou=computer,dc=example, dc=com and ou=people,dc=example, dc=com have been excluded from dataview-1 by looking at the excluded-subtrees parameter.


    $ dpconf get-ldap-data-view-prop -h host1 -p 1389 dataview-1 excluded-subtrees

    The list of excluded subtrees is returned.

  10. Restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Chapter 22 Directory Proxy Server Virtualization

This chapter describes how to create virtual data views. Virtual data views transform the source data and present a different view of that data to client applications. Virtual data views include transformed LDAP data views, LDIF data views, join data views, and JDBC data views. For an overview of the features of virtual data views and a description of example use cases, see Chapter 18, Directory Proxy Server Virtualization, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

You cannot use Directory Service Control Center (DSCC) to perform the procedures in this chapter. You must use the command line.

This chapter covers the following topics:

Creating and Configuring LDIF Data Views

An LDIF data view is a simple virtual data view in which an LDIF file is made to look like an LDAP data source. Unlike for LDAP data views, you do not create data sources or data source pools when you set up LDIF data views. Instead, you specify an LDIF file when you create the data view. By default, you cannot write to an LDIF data view. For more information, see Defining Access Control on Virtual Data Views.

For information about creating and configuring LDIF data views, see the following procedures.

ProcedureTo Create an LDIF Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create an LDIF data view.


    $ dpconf create-ldif-data-view -h host -p port view-name path-to-ldif-file suffix-dn
    
  2. (Optional) View the list of LDIF data views.


    $ dpconf list-ldif-data-views -h host -p port
    

    The virtual access controls data view is the only default LDIF data view. This data view is generated by the server and enables requests to be routed to virtual access control instructions (ACIs).

ProcedureTo Configure an LDIF Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. View the properties of an LDIF data view.


    $ dpconf get-ldif-data-view-prop -h host -p port view-name
    

    An LDIF data view has the following default properties:


    alternate-search-base-dn                    :  -  
    attr-name-mappings                          :  none  
    base-dn                                     :  suffixDN
    bind-pwd-attr                               :  userPassword  
    contains-shared-entries                     :  false  
    custom-distribution-algorithm               :  none  
    db-pwd-encryption                           :  clear-text  
    description                                 :  -  
    distribution-algorithm                      :  none  
    dn-join-rule                                :  none  
    dn-mapping-attrs                            :  none  
    dn-mapping-source-base-dn                   :  none  
    excluded-subtrees                           :  -  
    filter-join-rule                            :  none  
    is-enabled                                  :  true  
    is-read-only                                :  false  
    is-routable                                 :  true  
    ldif-data-source                            :  /path/to/filename.ldif
    lexicographic-attrs                         :  all  
    lexicographic-lower-bound                   :  none  
    lexicographic-upper-bound                   :  none  
    non-viewable-attr                           :  none  
    non-writable-attr                           :  none  
    numeric-attrs                               :  all  
    numeric-default-data-view                   :  false  
    numeric-lower-bound                         :  none  
    numeric-upper-bound                         :  none  
    pattern-matching-base-object-search-filter  :  all  
    pattern-matching-dn-regular-expression      :  all  
    pattern-matching-one-level-search-filter    :  all  
    pattern-matching-subtree-search-filter      :  all  
    process-bind                                :  -  
    replication-role                            :  master  
    viewable-attr                               :  all except non-viewable-attr  
    writable-attr                               :  all except non-writable-attr
  2. Change one or more of the properties that are listed in Step 1.


    $ dpconf set-ldif-data-view-prop -h host -p port view-name property:value \
     [property:value ... ]

    For example, to change the source LDIF file for the data view, set the ldif-data-source property.


    $ dpconf set-ldif-data-view-prop -h host1 -p 1389 -D cn="Proxy Manager" \
    myLDIFDataView ldif-data-source:/local/files/example.ldif

Defining Access Control on Virtual Data Views

ACIs on virtual data views can be stored in an LDAP directory or in an LDIF file. For information about how virtual ACIs work, see Access Control On Virtual Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

When you create a Directory Proxy Server instance, the following default configuration for virtual access controls is defined:

ProcedureTo Define a New ACI Storage Repository

If you do not want to use the default ACI configuration described previously, you can define a different storage repository.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a data view for the repository in which the virtual ACIs will be stored.

  2. Specify the name of the data view created in the previous step as the ACI data view.


    $ dpconf set-virtual-aci-prop -h host -p port aci-data-view:data-view-name
    
  3. If the ACI repository is an LDAP directory, define the credentials required to access the ACI data view.


    $ dpconf set-virtual-aci-prop -h host -p port aci-manager-bind-dn:bind-dn
    $ dpconf set-virtual-aci-prop -h host -p port aci-manager-bind-pwd-file:filename
    

ProcedureTo Configure Virtual Access Controls

Regardless of the ACI repository that you use, you must configure the virtual access controls.


Note –

Only the Proxy Manager can create a pool of ACIs and manage ACIs directly through the ACI data view. If the ACI repository is an LDAP directory, you must modify the schema of that directory to include the aciSource object class and the dpsaci attribute. For more information about customizing the schema, see Extending Directory Server Schema.


You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a pool of ACIs in the ACI repository, and set up global ACIs.

    For information about global ACIs, see Global ACIs in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. To set up global ACIs, add an aciSource entry under the view base of the ACI data view. For example:


    % ldapmodify -p port -D "cn=proxy manager" -w -
    dn: cn=aci-source-name,cn=virtual access controls
    changetype: add
    objectclass: aciSource
    dpsaci: (targetattr="*") (target="ldap:///ou=people,o=virtual") (version 3.0; 
     acl "perm1"; allow(all) groupdn="ldap:///cn=virtualGroup1,o=groups,o=virtual";)
    cn: aci-source-name
    
  2. Configure one or more connection handlers to use this pool of ACIs.


    % dpconf set-connection-handler-prop -h host -p port connection-handler \
    aci-source:aci-source-name
    
  3. Add the required ACIs to the data.

    To do this, create a virtual entry that contains the ACIs. For example:


    % ldapmodify -p port -D "cn=virtual application,ou=application users,dc=com" -w -
    dn: ou=people,o=virtual
    changetype: modify
    add: dpsaci
    dpsaci: (targetattr="*")(version 3.0; acl "perm1"; allow(all) userdn="ldap:///self";)
    dpsaci: (targetattr="*")(version 3.0; acl "perm1"; allow(search, read, compare) 
     userdn ="ldap:///anyone";)

    Note –

    Any user with the appropriate access rights can add and retrieve virtual ACIs through the data view.


Defining Schema Checking on Virtual Data Views

Generally, for LDAP data views, schema checking is performed by the back-end directory, using the back-end directory's schema. Use the following procedure if you want schema checking to be performed by Directory Proxy Server.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

To normalize requests, particularly the DN, set the use-external-schema property of the server, as follows:

ProcedureTo Define Schema Checking

  1. Indicate that the server instance should use an external schema.


    $ dpconf set-server-prop -h host -p port use-external-schema:true
  2. Enable schema checking on the connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler \
     schema-check-enabled:true
  3. Create a data view that exposes cn=schema.

    If the external schema is defined in an LDAP directory, create an LDAP data view, as described in Chapter 18, LDAP Data Views, with a view base of cn=schema.

    If the external schema is defined in an LDIF file, create an LDIF data view, as described in Creating and Configuring LDIF Data Views with a view base of cn=schema.

  4. Add this data view to the list of data views exposed by the connection handler.

    By default, all data views are exposed by the connection handler. If you have defined a custom list of data views that are exposed by the connection handler, add this data view to the list.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler \
     data-view-routing-custom-list+:data-view-name
    

Creating and Configuring Join Data Views

A join data view is an aggregation of multiple data views. For information about how a join data view works, see Join Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure join data views, see the following procedures.

ProcedureTo Create a Join Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Identify the primary and secondary data views that will be aggregated to form the join view.

    The primary and secondary data views must exist before the join view can be created. The primary and secondary views can be any type of data view, including an LDAP data view, LDIF data view, JDBC data view, or another join data view. Specific properties must be configured on the secondary view to allow it to function as the source for a join view. For more information, see To Configure the Secondary View of a Join View.

  2. Create the join data view.


    $ dpconf create-join-data-view -h host -p port view-name primary-view secondary-view \
     suffix-dn
    
  3. (Optional) View the list of join views to check that your data view has been created successfully.


    $ dpconf list-join-data-views -h host -p port
    

ProcedureTo Configure a Join Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. View the properties of a join data view.


    $ dpconf get-join-data-view-prop -h host -p port view-name
    

    The default properties of a join data view are as follows:


    allow-heuristic-search                      :  true  
    allow-partial-search                        :  false  
    alternate-search-base-dn                    :  -  
    attr-name-mappings                          :  none  
    base-dn                                     :  suffixDN  
    contains-shared-entries                     :  false  
    custom-distribution-algorithm               :  none  
    description                                 :  -  
    distribution-algorithm                      :  none  
    dn-join-rule                                :  none  
    dn-mapping-attrs                            :  none  
    dn-mapping-source-base-dn                   :  none  
    excluded-subtrees                           :  -  
    filter-join-rule                            :  none  
    is-enabled                                  :  true  
    is-read-only                                :  false  
    is-routable                                 :  true  
    join-rule-control-enabled                   :  false  
    lexicographic-attrs                         :  all  
    lexicographic-lower-bound                   :  none  
    lexicographic-upper-bound                   :  none  
    non-viewable-attr                           :  none  
    non-writable-attr                           :  none  
    numeric-attrs                               :  all  
    numeric-default-data-view                   :  false  
    numeric-lower-bound                         :  none  
    numeric-upper-bound                         :  none  
    pattern-matching-base-dn-regular-expression :  all  
    pattern-matching-base-object-search-filter  :  all  
    pattern-matching-dn-regular-expression      :  all  
    pattern-matching-one-level-search-filter    :  all  
    pattern-matching-subtree-search-filter      :  all  
    primary-view                                :  primary-view  
    process-bind                                :  -  
    replication-role                            :  master  
    request-grouping-size                       :  5
    secondary-view                              :  secondary-view  
    viewable-attr                               :  all except non-viewable-attr  
    vlv-control-enabled                         :  false  
    vlv-control-page-size                       :  1k  
    vlv-control-sorting-attr                    :  objectclass  
    writable-attr                               :  all except non-writable-attr  
  2. Change one or more of the properties that are listed in Step 1.


    $ dpconf set-join-data-view-prop -h host -p port view-name property:value \
     [property:value ... ]

    For example, to change the primary data view of a data source to myLDAPDataView, use the following command:


    $ dpconf set-join-data-view-prop -h host1 -p 1389 -D cn="Proxy Manager" \
     myJoinDataView primary-view:myLDAPDataView

    If vlv-control-enabled is set to true, Directory Proxy Server uses VLV control in search requests when it contacts the primary data view.

  3. When a join data view is configured, set viewable-attr and writable-attr properties on primary data view and secondary data view.

    Setting of these properties helps in splitting the search filters appropriately on primary and secondary data views. Otherwise, there might be discrepancies in search results when search filter contains attributes from secondary data view.

  4. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

ProcedureTo Configure a Join Data View to Enable Referencing of a Data View by Multiple Join Data Views

Setting join rule configuration information in the join data view makes the data view to be referenced by multiple join data views. To do so, perform the following:

  1. Set join-rule-control-enabled to true on the join data view.


    $ dpconf set-join-data-view-prop view-name join-rule-control-enabled:true

    After setting join-rule-control-enabled to true, join rule configuration information stored in the join data view is used by the server. If you have a join data view with the join rule configuration information stored in the secondary data view then this information is not used by the server. To have this information used by the server, you will have to manually add the configuration information at the join data view level.

  2. Define a join rule that determines how the secondary view is related to the primary view.

    The join rule can be one of the following:

    • DN join rule


      $ dpconf set-join-data-view-prop view-name \
      dn-join-rule:uid=\${primary-view-name.uid},ou=People,dc=example
    • Filter join rule


      $ dpconf set-join-data-view-prop view-name \
      filter-join-rule:uid=\${primary-view-name.uid}

    In the above commands, the attribute name is enclosed in ${} when treated as a variable. If you do not use attribute names enclosed in ${}, the attribute names are treated as constants.

    If you use bash or ksh in UNIX, the $ character should be escaped by \ in the \${primary-view-name.uid} like constructions whereas no escaping is required on Windows.

ProcedureTo Configure the Secondary View of a Join View

Specific properties must be configured on the secondary data view to allow it to function as the source for a join view. Because the secondary view can be any type of data view, the command you use will depend on the data view type. The following sample commands assume that the secondary view is an LDAP data view. For more information about the properties described here, see Additional Secondary Data View Properties in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Define a join rule that determines how the secondary view is related to the primary view.

    Never set the filter-join-rule and dn-join-rule on the primary data view of a join view.

    The join rule can be one of the following:

    • DN join rule


      $ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \
      dn-join-rule:uid=\${primary-view-name.uid},ou=People,dc=example
    • Filter join rule


      $ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \
      filter-join-rule:uid=\${primary-view-name.uid}

    The configuration for the dn-join-rule and filter-join-rule properties is used by the server only if the join-rule-control-enabled property on the join data view is set to false. Otherwise, if the join-rule-control-enabled property is set to true on the join data view, then the information set on the secondary view will be ignored.

  2. If the filter join rule is set on the join data view, you need to set a virtual transformation rule on the secondary data view to be able to add an entry on the join data view.


    dpconf add-virtual-transformation secondary-view-name \
    write add-attr-value dn uid=\${uid}

    Note –

    Without setting this rule, addition of entries to join data view would not be possible.


  3. (Optional) Specify whether binds are allowed on the secondary view.

    By default, binds are permitted on all data views. If you want to prohibit binds to the secondary data view, run the following command:


    $ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name process-bind:false

    For more information about this property, see Handling of Binds in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

  4. (Optional) Specify whether the secondary view contains shared entries.


    $ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \
    contains-shared-entries:true

    For more information about this property, see Handling of Shared Entries in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

Creating and Configuring Coordinator Data Views

The Coordinator data view has an ordered list of data views to coordinate. When the Coordinator data view receives a request, it sends the request to its coordinated data views in the right order, which is defined by the order used in the CLI to specify the coordinated data view. The Coordinator data view sends the request to coordinated data view as defined by the routing policy and in the end returns the result(s) to the client. For more information, see Coordinator Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The Coordinator data view supports the following routing policies:


Note –

All the data views coordinated by a coordinator data view must have the same view base identical with the view base of the coordinator data view.


ProcedureTo Create a Coordinator Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Identify the data views that will be aggregated to form the Coordinator data view.

    The data views must exist before the Coordinator data view can be created. The data views can be any type of data view, including an LDAP data view, LDIF data view, JDBC data view, or another join data view.

  2. Create the Coordinator data view.


    $ dpconf create-coordinator-data-view -h host -p port VIEW_NAME \
    COORDINATED_VIEW [COORDINATED_VIEW...] SUFFIX_DN
    

    The following command creates a Coordinator data view, view_com, using two data views.


    $ dpconf create-coordinator-data-view -h host -p port view_com \
    first_view second_view dc=com
  3. (Optional) View the list of Coordinator data views to check that your data view has been created successfully.


    $ dpconf list-coordinator-data-views -h host -p port
    

    In this case, the above command displays view_com.

ProcedureTo Configure a Coordinator Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. View the properties of a Coordinator data view.


    $ dpconf get-coordinator-data-view-prop -h host -p port VIEW_NAME
    

    The default properties of a join data view are as follows:


    alternate-search-base-dn                       :  ""
    attr-name-mappings                             :  none
    base-dn                                        :  ""
    contains-shared-entries                        :  -
    coordinated-data-view                          :  first_view 
    coordinated-data-view                          :  second_view
    custom-distribution-algorithm                  :  none
    description                                    :  -
    distribution-algorithm                         :  none
    dn-join-rule                                   :  none
    dn-mapping-attrs                               :  none
    dn-mapping-source-base-dn                      :  none
    excluded-subtrees                              :  ""
    filter-join-rule                               :  none
    is-enabled                                     :  true
    is-read-only                                   :  false
    is-routable                                    :  true
    lexicographic-attrs                            :  all
    lexicographic-lower-bound                      :  none
    lexicographic-upper-bound                      :  none
    non-viewable-attr                              :  none
    non-writable-attr                              :  none
    numeric-attrs                                  :  all
    numeric-default-data-view                      :  false
    numeric-lower-bound                            :  none
    numeric-upper-bound                            :  none
    pattern-matching-base-object-search-filter     :  all
    pattern-matching-dn-regular-expression         :  all
    pattern-matching-one-level-search-filter       :  all
    pattern-matching-subtree-search-filter         :  all
    process-bind                                   :  -
    replication-role                               :  master
    routing-policy                                 :  all-candidates
    viewable-attr                                  :  all except non-viewable-attr 
    writable-attr                                  :  all except non-writable-attr 

    For example, the following commands lists the coordinated-data-views property of the specified Coordinator data view.


    $ dpconf get-coordinator-data-view-prop VIEW_NAME coordinated-data-view 
    
    coordinated-data-view  :  first_view
    coordinated-data-view  :  second_view 
  2. Change one or more of the properties that are listed in Step 1.


    $ dpconf set-coordinator-data-view-prop -h host -p port VIEW_NAME PROP:VAL \
    [PROP:VAL...] 

    For example, add more coordinated data views to the Coordinator data view using the following command:


    $ dpconf set-coordinator-data-view-prop -h host -p port view_com \
    coordinated-data-view+:third_view coordinated-data-view+:fouth_view 

    As per the order of the coordinated data views specified in the above command, the coordinated data views are send in the following order:


    $ dpconf get-coordinator-data-view-prop VIEW_NAME coordinated-data-view 
    
    coordinated-data-view  :  first_view
    coordinated-data-view  :  second_view 
    coordinated-data-view  :  third_view
    coordinated-data-view  :  fourth_view 
  3. (Optional) Change the routing-policy mode that describe how Coordinator data view sends the requests to coordinated data views.


    $ dpconf set-coordinator-data-view-prop -h host -p port view_com \
    routing-policy:first-match

    For more information, see routing-policy(5dpconf).

  4. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Creating and Configuring JDBC Data Views

A JDBC data view enables you to make a relational database accessible to LDAP client applications. For information about how JDBC data views work, see JDBC Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure JDBC data views, see the following procedures.

ProcedureTo Create a JDBC Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a JDBC data source for the relational database.


    $ dpconf create-jdbc-data-source -h host -p port -b db-name -B db-url -J driver-url \
    [-J driver-url]... -S driver-class  source-name
    

    Currently, only one JDBC data source is supported for each JDBC data view. In other words, you cannot load balance across JDBC data sources. To access multiple JDBC data sources, you can create a data view for each data source, and join them together with a join data view.

    The following properties must be set when you create a JDBC data source:

    db-name

    The name of the relational database, for example, payrolldb.

    db-url

    The URL to the database, in the form jdbc:vendor:driver://dbhost:dbport.

    The db-url is not a complete JDBC database URL, because it does not contain the database name. (The database name is specified by the db-name property.)

    You must finish db-url with a / for MySQL, DB2, and Derby databases and with a : for Oracle database.

    driver-class

    The JDBC driver class, for example org.hsqldb.jdbcDriver.

    driver-url

    The path to the JDBC driver, for example file:///path/to/hsqldb/lib/hsqldb.jar.

    The driver-url property is multivalued. Hence, driver-url can support multiple JAR files for the JDBC driver to ensure connectivity to the JDBC source on different platforms.

    If a 3rd party JDBC driver, which is other than the JDBC driver provided by the DB Vendor, is used to connect to the RDBMS back-end, set the db-vendor property. For more information about the db-vendor property, see db-vendor(5dpconf)

  2. Create a JDBC data source pool.


    $ dpconf create-jdbc-data-source-pool -h host -p port pool-name
    
  3. Attach the JDBC data source to the JDBC data source pool.


    $ dpconf attach-jdbc-data-source -h host -p port pool-name source-name
    
  4. Create a JDBC data view.


    $ dpconf create-jdbc-data-view -h host -p port view-name pool-name suffix-DN
    
  5. (Optional) View the list of JDBC data views to check that your data view has been created successfully.


    $ dpconf list-jdbc-data-views -h host -p port
    

ProcedureTo Configure a JDBC Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. View the properties of a JDBC data view.


    $ dpconf get-jdbc-data-view-prop -h host -p port view-name
    

    The default properties of a JDBC data view are as follows:


    alternate-search-base-dn                    :  -
    attr-name-mappings                          :  none
    base-dn                                     :  o=sql1
    contains-shared-entries                     :  -
    description                                 :  -
    distribution-algorithm                      :  -
    dn-join-rule                                :  -
    dn-mapping-attrs                            :  none
    dn-mapping-source-base-dn                   :  none
    excluded-subtrees                           :  -
    filter-join-rule                            :  -
    is-enabled                                  :  true
    is-read-only                                :  false
    is-routable                                 :  true
    jdbc-attr-date-format                       :  yyyy-MM-dd
    jdbc-attr-time-format                       :  hh:mm:ss
    jdbc-attr-timestamp-format                  :  yyyy-MM-dd hh:mm:ss
    jdbc-data-source-pool                       :  pool-name
    lexicographic-attrs                         :  all
    lexicographic-lower-bound                   :  none
    lexicographic-upper-bound                   :  none
    non-viewable-attr                           :  -
    non-writable-attr                           :  -
    numeric-attrs                               :  all
    numeric-default-data-view                   :  false
    numeric-lower-bound                         :  none
    numeric-upper-bound                         :  none
    pattern-matching-base-object-search-filter  :  all
    pattern-matching-dn-regular-expression      :  all
    pattern-matching-one-level-search-filter    :  all
    pattern-matching-subtree-search-filter      :  all
    process-bind                                :  -
    replication-role                            :  master
    viewable-attr                               :  all except non-viewable-attr
    writable-attr                               :  all except non-writable-attr
  2. Change one or more of the properties that are listed in Step 1.


    $ dpconf set-jdbc-data-view-prop -h host -p port view-name property:value \
     [property:value ... ]
  3. (Optional) In addition to the ISO format, you can set JDBC attributes of type date, time, and timestamp attributes in all of the following formats as well.

    Following lists the components that constitutes date and time:


    Letter      Date or Time Component   Examples
    G           Era designator           AD
    y           Year                     1996; 96
    M           Month in year            July; Jul; 07
    w           Week in year             27
    W           Week in month            2
    D           Day in year              189
    d           Day in month             10
    F           Day of week in month     2
    E           Day in week              Tuesday; Tue
    a           Am/pm marker             PM
    H           Hour in day (0-23)       0
    k           Hour in day (1-24)       24
    K           Hour in am/pm (0-11)     0
    h           Hour in am/pm (1-12)     12
    m           Minute in hour           30
    s           Second in minute         55
    S           Millisecond              978
    z           Time zone                Pacific Standard Time; PST; GMT-08:00
    Z           Time zone                -0800

    The following examples show how date and time patterns are interpreted in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone.


    Date and Time Pattern                Result
    "yyyy.MM.dd G 'at' HH:mm:ss z"       2001.07.04 AD at 12:08:56 PDT
    "EEE, MMM d, ''yy"                   Wed, Jul 4, '01
    "h:mm a"                             12:08 PM
    "hh 'o''clock' a, zzzz"              12 o'clock PM, Pacific Daylight Time
    "K:mm a, z"                          0:08 PM, PDT
    "yyyyy.MMMMM.dd GGG hh:mm aaa"       02001.July.04 AD 12:08 PM
    "EEE, d MMM yyyy HH:mm:ss Z"         Wed, 4 Jul 2001 12:08:56 -0700
    "yyMMddHHmmssZ"                      010704120856-0700
    "yyyy-MM-dd'T'HH:mm:ss.SSSZ"         2001-07-04T12:08:56.235-0700

ProcedureTo Configure JDBC Tables, Attributes, and Object Classes

When you configure a JDBC data view, you must also configure the following objects:

  1. Create a JDBC table for each table in the relational database.


    % dpconf create-jdbc-table jdbc-table-name db-table
    

    The name of the db-table is case sensitive. Make sure that you use the identical case that is used in the relational database, otherwise operations that target that table might fail.

  2. Create a JDBC attribute for each column in each relational database table.


    % dpconf add-jdbc-attr table-name attr-name sql-column
    

    Creating a JDBC attribute maps the table column to an LDAP attribute.

  3. (Optional) If the column in the relational database is case sensitive, change the LDAP syntax of the JDBC attribute.


    % dpconf set-jdbc-attr-prop table-name attr-name ldap-syntax:ces

    The value of ldap-syntax is cis by default. This implies that the jdbc-attr is case insensitive. Change the value to ces if your relational database is case sensitive.

    Certain relational databases, such as Oracle and DB2, are case sensitive by default. LDAP is case insensitive by default. When Directory Proxy Server detects that a column of the relational database table is case sensitive, an ldapsearch query with the corresponding attribute in the filter is translated into a SQL query using the function UPPER.

    For example, the query ldapsearch -b "dc=mysuffix" "(attr=abc)" is translated into the following SQL query:


    SELECT * FROM mytable WHERE (UPPER(attr)='ABC')

    By default, this type of query is not indexed. Queries of this nature can therefore have a substantial performance impact.

    You can alleviate the performance impact in two ways:

    • By setting the ldap-syntax property of the jdbc-attr to ces.

    • By creating an index with the function UPPER for each jdbc-attr that might be used in an LDAP filter.


    Note –

    If your relational database is not case sensitive, use ldap-syntax with the default value, that is, cis. ldap-syntax:ces is not supported with the case insensitive databases.


  4. Create a JDBC object class for the LDAP relational database table.


    % dpconf create-jdbc-object-class view-name objectclass primary-table \
      [secondary-table... ] DN-pattern
    

    Creating a JDBC object class essentially specifies an LDAP object class with which these tables will be associated. The JDBC object class also specifies the primary table and the secondary tables, if they exist.

    When you create a JDBC object class, you specify a DN pattern. DN pattern describes which attributes are to be used to construct DN of the entry. For example, when you specify DN pattern as uid then the DN of the entry is constructed using attribute uid and view base of the data view. For example, uid=bjensen,ou=people,dc=example,dc=com. The DN pattern can constitute multiple attributes. In that case, attributes should be separated by , (comma). For example, if DN pattern is specified as uid,country, DN of the entry returned by the data view is uid=bjensen,country=America,ou=people,dc=example,dc=com.

    When data source contains duplicate entries and the duplicate entries are not required, set perform-distinct-select to true using the following command:


    % dpconf set-jdbc-object-class-prop view-name objectclass perform-distinct-select:true

    All the subtree components defined in the DN pattern of JDBC object class should have a JDBC object class defined for them. For example, if there is a DN pattern uid,ou in a JDBC object class, there should be a JDBC object class definition with a DN pattern ou. This is necessary for Directory Proxy Server to construct a properly structured DIT. Otherwise, the subtree with values like ou=xxx,base-DN would not be returned in the search results.

  5. If a secondary table exists, define the join rule between the primary table and the secondary table.


    % dpconf set-jdbc-table-prop secondary-table-name filter-join-rule:join-rule
    

    A join rule is defined on the secondary table and determines how data from that table is linked to data from the primary table. How you define the relationships between the primary and secondary tables of an object class is important. For more information, see Defining Relationships Between JDBC Tables.

  6. Specify the super class for the JDBC object class.


    % dpconf set-jdbc-object-class-prop view-name objectclass super-class:value
    

    The super class indicates the LDAP object class from which the JDBC object class inherits.

Defining Relationships Between JDBC Tables

In the simplest case, a JDBC object class contains only a single (primary) table. There is no secondary table, and thus no need to define relationships between tables.

If the object class contains more than one table, the relationships between these tables must be clearly defined. The relationships between tables are always defined on the secondary table. The following properties of a secondary table enable you to define these relationships:

The following examples illustrate how the filter join rule is defined, based on the values of the first two properties. These examples assume that the object class has one primary table and one secondary table.


Example 22–1 is-single-row-table:true and contains-shared-entries:true

These are the default values of these properties. In this case, the relationship between the primary and secondary tables is n->1, that is, n rows in the primary table reference one shared row in the secondary table.

In the relational database, a foreign key (FK) is defined in the primary table, and points to a column in the secondary table.

Take, for example, an organization in which several employees can share the same manager. Two relational database tables are defined, with the following structure:


primary table : EMPLOYEE [ID, NAME, FK_MANAGER_ID]
secondary table : MANAGER  [ID, NAME]

The following object class and attributes are defined:


object-class : employee
attr : name (from primary EMPLOYEE.NAME)
attr : manager (from secondary MANAGER.NAME)

The following filter join rule is defined in the secondary table:


ID=\${EMPLOYEE.FK_MANAGER_ID}"

In case of multiple secondary tables, you must configure filter-join-rule on each secondary table. For more information on how to configure filter-join-rule for multiple secondary tables, see the Step 12.

With this configuration, the following behavior occurs for LDAP operations:



Example 22–2 is-single-row-table:true and contains-shared-entries:false

In this case, the relationship between the primary and secondary tables is 1->1 or 1<-1, that is, one row in the primary table is referenced by one row in the secondary table.

In the relational database, the foreign key (FK) might be defined in the primary table, or in the secondary table.

Take, for example, an organization in which the UID of employees is stored in one table, and the surname of employees is stored in a second table. Two relational database tables are defined, with the following structure:


primary table : UID [ID, VALUE, FK_SN_ID]
secondary table : SN [ID, VALUE]

The following object class and attributes are defined:


object-class : employee
attr : uid (from primary UID.VALUE)
attr : sn (from secondary ID.VALUE)

The following filter join rule is defined in the secondary table:


ID=\${UID.FK_SN_ID}

You can use it in the following manner using the dpconf command:


dpconf set-jdbc-table-prop SN filter-join-rule:ID=\${UID.FK_SN_ID}

This configuration could be the other way around, with the foreign key FK_UID_ID stored in the secondary table, and pointing to UID.ID.



Example 22–3 is-single-row-table:false and contains-shared-entries:false

In this case, the relationship between the primary and secondary tables is 1->n, that is, one row in the primary table is referenced by n rows in the secondary table. This example illustrates the case of multi-valued attributes. A multi-valued attribute is represented as a set of rows in the secondary table, with one row per attribute value.

In the relational database, the foreign key is defined in the secondary table, and points to a column in the primary table.

Take, for example, an organization in which an employee can have several telephone numbers. Two relational database tables are defined, with the following structure:


primary table : EMPLOYEE [ID, NAME]
secondary table : PHONE [ID, VALUE, USER_ID]

The following object class and attributes are defined:


object-class : employee
attr : cn (from primary EMPLOYEE.NAME)
attr : telephoneNumber (from secondary PHONE.VALUE)

The following filter join rule is defined in the secondary table:


USER_ID=\${EMPLOYEE.ID}


Example 22–4 is-single-row-table:false and contains-shared-entries:true

This case is currently unsupported in Directory Proxy Server.


Sample Virtual Configurations

The following section provides two sample configurations. These configurations illustrate the main features of a virtual directory, and indicate how these features are configured.

Joining an LDAP Directory and a MySQL Database

The procedures in this section describe a sample virtual configuration that joins an LDAP directory and a MySQL database. The LDAP directory is the primary data source, that contains most of the user information. The MySQL database contains additional information about the users. The resulting configuration is illustrated in the following figure.

Figure 22–1 Sample Virtual Configuration

Figure shows join data view comprising LDAP data view
and JDBC data view

You can use the sample data provided in install-path/resources/ldif/Example.ldif to duplicate this example, or you can substitute the sample data with your own data.

This configuration can be broken into three sections:

For simplicity, all the commands in this section assume that the Directory Proxy Server is running on the local host in /local/dps. The commands also assume that the following environment variables have been set:

DIR_PROXY_PORT

1389

LDAP_ADMIN_PWF

pwd.txt, a file containing the administrator password.

DIRSERV_PORT

4389

LDAP_ADMIN_USER

cn=Directory Manager

Configuring and Testing the LDAP Data View

ProcedureTo Configure the LDAP Data View

Before You Begin

The tasks in this section assume the following information:

  1. Create an LDAP data source named myds1 for the Directory Server instance.


    % dpconf create-ldap-data-source myds1 host1:4389
  2. Enable the data source, and allow write operations to the data source.


    % dpconf set-ldap-data-source-prop myds1 is-enabled:true is-read-only:false
  3. Create an LDAP data source pool named myds1-pool.


    % dpconf create-ldap-data-source-pool myds1-pool
  4. Attach the LDAP data source to the LDAP data source pool.


    % dpconf attach-ldap-data-source myds1-pool myds1
  5. Specify that the data source should receive 100% of the bind, add, search, and modify operations from that data source pool.


    % dpconf set-attached-ldap-data-source-prop myds1-pool myds1 add-weight:100 \
     bind-weight:100 modify-weight:100 search-weight:100
  6. Create an LDAP data view for the data source pool, named myds1–view, with a base DN of dc=example,dc=com.


    % dpconf create-ldap-data-view myds1-view myds1-pool dc=example,dc=com

ProcedureTo Test the LDAP Data View

  1. As a user under dc=example,dc=com, search all entries in the LDAP data source to verify that you can read from the data view.


    % ldapsearch -p 1389 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery \
     -b dc=example,dc=com "objectclass=*"

    Note –

    You must use the credentials of a user under dc=example,dc=com. If you want to use cn=Directory Manager, you must define a data view to handle that DN.


  2. As a user under dc=example,dc=com, modify the userPassword attribute to verify that you can write to the data view.


    % ldapmodify -p 1389 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery
    dn: uid=kvaughan,ou=people,dc=example,dc=com
    changetype: modify
    replace: userPassword
    userPassword: myNewPassword

    Note –

    A default ACI in Directory Server allows users to modify their own passwords.


Configuring and Testing the JDBC Data View

The following tasks assume that a MySQL database is installed, running and populated with data, and that the MySQL database has the following characteristics:

The following table describes the tables in the database, and their composite fields. You need this information to set up the JDBC data view.

MySQL Table 

Fields 

EMPLOYEE

ID, SURNAME,PASSWORD, ROOM, COUNTRY_ID

COUNTRY

ID, NAME

PHONE

USER_ID, NUMBER

ProcedureTo Configure the JDBC Data View

  1. Create a JDBC data source named mysql1 for the SQL database.


    % dpconf create-jdbc-data-source -b sample_sql \
     -B jdbc:mysql://host2.example.com:3306/ \
     -J file:/net/host2.example/local/mysql/lib/jdbc.jar \
     -S com.mysql.jdbc.Driver mysql1

    Note –

    You can set the number of connections for JDBC data source using the num-connection-incr(5dpconf), num-connection-init(5dpconf), and num-connection-limit(5dpconf) JDBC data source properties.


  2. Specify the user name and password file for the SQL database.


    % dpconf set-jdbc-data-source-prop mysql1 db-pwd:sqlpwd db-user:rootUser
    

    The sqlpwd and rootUser are the password and username of the authenticating user and these credentials are stored in the database. You must configure the proxy server with username and password when configuring a JDBC data source.

    The db-vendor property of the JDBC data source should be set using set-jdbc-data-source-prop if a third party JDBC driver, which is other than the one provided by DB Vendor, is used to connect to the RDBMS back-end. This data is used to construct vendor specific SQL statements, whenever possible, to improve performance. For more information, see db-vendor(5dpconf).

  3. Restart the proxy server.


    % dpadm restart /local/dps
  4. Enable the data source, and allow write operations to the data source.


    % dpconf set-jdbc-data-source-prop mysql1 is-enabled:true is-read-only:false
  5. (Optional) Set monitoring-inactivity-timeout, monitoring-interval, and monitoring-mode for better monitoring of the open connections and data sources. .

    For more information, see monitoring-inactivity-timeout(5dpconf), monitoring-interval(5dpconf), and monitoring-mode(5dpconf)

  6. Create a JDBC data source pool named mysql1–pool.


    % dpconf create-jdbc-data-source-pool mysql1-pool
  7. Attach the JDBC data source to the data source pool.


    % dpconf attach-jdbc-data-source mysql1-pool mysql1
  8. Create a JDBC data view for the data source pool, named myjdbc1–view, with a base DN of o=sql.


    % dpconf create-jdbc-data-view mysql1-view mysql1-pool o=sql
  9. Create a JDBC table for each table in the MySQL database.


    % dpconf create-jdbc-table employee1 EMPLOYEE
    % dpconf create-jdbc-table country1 COUNTRY
    % dpconf create-jdbc-table phone1 PHONE

    The name of the table in the SQL database is case sensitive. Make sure that you use the same case that is used in the SQL database.

  10. Create a JDBC attribute for each column in each table.

    Creating a JDBC attribute maps the MySQL column to an LDAP attribute.


    % dpconf add-jdbc-attr employee1 uid ID
    % dpconf add-jdbc-attr employee1 sn SURNAME
    % dpconf add-jdbc-attr employee1 userPassword PASSWORD
    % dpconf add-jdbc-attr employee1 roomNumber ROOM
    % dpconf add-jdbc-attr phone1 telephoneNumber NUMBER
    % dpconf add-jdbc-attr country1 countryName NAME

    It is not necessary to create JDBC attributes for the phone1 user_id and country1 id columns, because these columns only contain the values that are present in EMPLOYEE.ID for which an LDAP attribute uid is already created.

  11. Create a JDBC object class for the LDAP person object class.

    In this step, the employee1 table is identified as the primary table, and the country1 and phone1 tables are identified as secondary tables. The creation of a JDBC object class also requires a DN. In this example, the DN is constructed from the uid attribute and the base DN of the data view.


    % dpconf create-jdbc-object-class mysql1-view person employee1 country1 phone1 uid
  12. Define the join rules between the primary table and the secondary tables.

    A join rule is defined on the secondary table and determines how data from that table is linked to data from the primary table.


    % dpconf set-jdbc-table-prop country1 filter-join-rule:ID=\${EMPLOYEE.COUNTRY_ID}
    % dpconf set-jdbc-table-prop phone1 filter-join-rule:USER_ID=\${EMPLOYEE.ID}
  13. Specify the super class for the JDBC object class.

    The super class indicates the LDAP object class from which the JDBC object class inherits attributes.


    % dpconf set-jdbc-object-class-prop mysql1-view person super-class:top

ProcedureTo Create the Required ACIs

Before you can test the JDBC data view, you must enable write access to the data view by configuring ACIs. By default, write access to non-LDAP data views is denied. For the purposes of this example, it is sufficient to add one global ACI that allows users to modify their own passwords.

  1. As the Proxy Manager, add a pool of ACIs to the JDBC data source and add a global ACI that allows users to modify their own entries.


    % ldapmodify -p 1389 -D "cn=proxy manager" -w password
    dn: cn=mysql1,cn=virtual access controls
    changetype: add
    objectclass: acisource
    dpsaci: (targetattr="*") (target = "ldap:///o=sql") 
    (version 3.0; acl "enable all access for all users "; allow(all) 
    userdn="ldap:///uid=kvaughan,o=sql";)
    cn: mysql1
  2. Create a connection handler to handle connections to the o=sql domain.


    % dpconf create-connection-handler mysql1-handler
  3. Enable the connection handler and configure it to handle all binds from users in the o=sql domain.


    % dpconf set-connection-handler-prop mysql1-handler is-enabled:true \
     bind-dn-filters:"uid=.*,o=sql"
  4. Configure the connection handler to use the pool of ACIs added previously.


    % dpconf set-connection-handler-prop mysql1-handler aci-source:mysql1

ProcedureTo Test the JDBC Data View

  1. As a user under o=sql, search the JDBC data source to verify that you can read from the data view.


    % ldapsearch -p 1389 -D "uid=kvaughan,o=sql" -w mypwd -b o=sql "objectclass=*"

    Note –

    You must use the credentials of a user under o=sql.


  2. As a user under o=sql, modify the userPassword attribute to verify that you can write to the data view.


    % ldapmodify -p 1389 -D "uid=kvaughan,o=sql" -w mypwd
    dn: uid=kvaughan,o=sql
    changetype: modify
    replace: userPassword
    userPassword: myNewpwd

Creating and Testing the Join Data View

ProcedureTo Create the Join Data View

  1. Create a join data view named myjoin1–view.

    Specifying the LDAP data view as the primary data view, and the JDBC data view as the secondary data view.


    % dpconf create-join-data-view myjoin1-view myds1-view mysql1-view o=join
  2. Define a join rule on the secondary data view.

    The following join rule specifies that the uid attribute of entries from the secondary data view should match the uid attribute of entries from the primary data view.


    % dpconf set-jdbc-data-view-prop mysql1-view filter-join-rule:uid=\${myds1-view.uid}
  3. If the filter join rule is set on the join data view, you need to set a virtual transformation rule on the secondary data view to be able to add an entry on the join data view.


    dpconf add-virtual-transformation secondary-view-name \
    write add-attr-value dn uid=\${uid}

    Note –

    Without setting this rule, addition of entries to join data view would not be possible.


  4. Define the set of attributes that can be read from and written to the primary data view through a join data view.


    % dpconf set-ldap-data-view-prop myds1-view viewable-attr:dn \
    viewable-attr:cn viewable-attr:sn viewable-attr:givenName \
    viewable-attr:objectClass viewable-attr:ou viewable-attr:l \
    viewable-attr:uid viewable-attr:mail viewable-attr:telephoneNumber \
    viewable-attr:facsimileTelephoneNumber viewable-attr:roomNumber \
    viewable-attr:userPassword
    % dpconf set-ldap-data-view-prop myds1-view writable-attr:dn \
    writable-attr:cn writable-attr:sn writable-attr:givenName \
    writable-attr:objectClass writable-attr:ou writable-attr:l \
    writable-attr:uid writable-attr:mail writable-attr:telephoneNumber \
     writable-attr:facsimileTelephoneNumber writable-attr:roomNumber \
    writable-attr:userPassword

    These definitions apply only in the context of the join view. By default all attributes can be read and written if you access the LDAP data view directly.

  5. Define the set of attributes that can be read from and written to the secondary data view through a join data view.


    % dpconf set-jdbc-data-view-prop mysql1-view viewable-attr:dn \
     viewable-attr:objectclass viewable-attr:sn viewable-attr:roomNumber \
     viewable-attr:userpassword viewable-attr:jobtitle viewable-attr:countryName \
     viewable-attr:telephoneNumber
    % dpconf set-jdbc-data-view-prop mysql1-view writable-attr:dn \
    writable-attr:objectclass writable-attr:sn writable-attr:roomNumber \
    writable-attr:userpassword writable-attr:jobtitle \
    writable-attr:countryName writable-attr:telephoneNumber

    These definitions apply only in the context of the join view. By default all attributes can be read and written if you access the JDBC data view directly.

ProcedureTo Create the Required ACIs

  1. As the proxy manager, add a global ACI that allows anonymous access to the join data view.


    % ldapmodify -p 1389 -D "cn=proxy manager" -w password
    dn: cn=myjoin1,cn=virtual access controls
    changetype: add
    objectclass: acisource
    dpsaci: (targetattr="*") (target = "ldap:///o=join") 
    (version 3.0; acl "anonymous_access"; allow(all) userdn="ldap:///anyone";)
    cn: myjoin1
  2. Configure the connection handler to use the pool of ACIs added previously.


    % dpconf set-connection-handler-prop default-connection-handler aci-source:myjoin1

ProcedureTo Test the Join Data View

  1. As an anonymous user, search the join data view.

    In this step, we search Kirsten Vaughan's entry to see whether data from both join views is retrieved.


    % ldapsearch -p 1389 -b o=join "uid=kvaughan"

    Note that the returned entry includes the attributes from both the LDAP data view and the JDBC data view.

  2. As a user under o=join, modify the userPassword attribute to verify that you can write to the join data view.


    % ldapmodify -p 1389
    dn: uid=kvaughan,ou=people,o=join
    changetype: modify
    replace: userPassword
    userPassword: myPassword

Joining Multiple Disparate Data Sources

This configuration describes an organization, Example.com, whose specific directory service requirements are met by some of the features of a virtual directory.

Data Storage Scenario

Example.com stores organizational data in multiple disparate data sources. For legacy reasons, user data is spread across an LDAP directory, a flat LDIF file, and an SQL database. The HR department stores user data in an LDAP directory, with a base DN of o=example.com. The Payroll department stores data in an SQL database. Administrative data such as departments and building numbers is stored by the administration department in an LDIF file, with a base DN of dc=example,dc=com.

In addition, Example.com has acquired a company named Company22. Company 22 also stores its user data in an LDAP directory, with a base DN of dc=company22,dc=com.

The following diagram provides a high level view of how Example.com's user data is stored.

Figure 22–2 Data Storage In Disparate Sources

Figure shows how Example.com's user data is stored in
disparate data sources

Client Application Requirements

Example.com has several LDAP client applications that require access to the data stored in the disparate data sources. The requirements of the client applications are not all the same. Different views of the data are required. In some cases, the clients require the data to be aggregated. In addition, some client applications require access to Company22's user data so that these new employees of Example.com can be administered along with the old employees.

The following diagram provides a high level view of Example.com's client application requirements.

Figure 22–3 Client Application Requirements

Figure shows the requirements of Example.com's LDAP applications

The following sections walk you through sufficient configuration Directory Proxy Server data views to meet the client application requirements described in this sample scenario. For information about how data views work, see Chapter 17, Directory Proxy Server Distribution, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition and Chapter 18, Directory Proxy Server Virtualization, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The configuration of the sample scenario is divided into the following sections:

Aggregate Data From the HR LDAP Directory and the Administration LDIF File

The HR department stores information such as employee names, job start data, and job level. The administration department stores additional data such as building codes and office numbers. The client application that handles the HR data requires access to the combined data from both sources. Both data sources have a common attribute, the employeeNumber that exists in each entry.

The following diagram illustrates the requirements of the client application.

Figure 22–4 Aggregation of Data From LDAP Directory and LDIF File

Figure shows a join view of an LDAP directory and an
LDIF file

To fulfill this application requirement, a data view is created for the payroll directory and for the administration LDIF file. These two data views are then joined to provide access to the aggregated data. This common attribute enables Directory Proxy Server to aggregate the data for each user.

For simplicity, the commands used in this section assume the following information:

To obtain the complete syntax of each command, run the command without any options. For example:


$ dpconf create-ldap-data-view
Operands are missing
Usage: dpconf create-ldap-data-view VIEW_NAME POOL_NAME SUFFIX_DN

ProcedureCreate and Enable an LDAP Data View for the Payroll Directory

  1. Create an LDAP data source for the payroll directory.


    $ dpconf create-ldap-data-source payroll-directory payrollHost:2389
  2. Create an LDAP data source pool for the payroll directory.


    $ dpconf create-ldap-data-source-pool payroll-pool
  3. Attach the payroll data source to the data source pool.


    $ dpconf attach-ldap-data-source payroll-pool payroll-directory
  4. Configure the weights of the attached data source.


    $ dpconf set-attached-ldap-data-source-prop -h payrollHost -p 2389 \
    payroll-pool payroll-directory add-weight:2 \
    bind-weight:2 compare-weight:2 delete-weight:2 \
    modify-dn-weight:2 modify-weight:2 search-weight:2
  5. Create an LDAP data view for the payroll directory.


    $ dpconf create-ldap-data-view payroll-view payroll-pool o=example.com
  6. Enable the LDAP data view so that client requests can be routed to this data view.


    $ dpconf set-ldap-data-view-prop payroll-view is-enabled:true
  7. Restart Directory Proxy Server for the changes to take effect.


    $ dpadm restart /local/myDPS

ProcedureCreate and Enable an LDIF Data View for the Administration Data

  1. Create an LDIF data view for the administration data.


    $ dpconf create-ldif-data-view admin-view example.ldif dc=example,dc=com
  2. Enable the LDIF data view for the administration data.


    $ dpconf set-ldif-data-view-prop admin-view is-enabled:true
  3. Specify that the administrator view contains entries that are used by more than one entry in the payroll view.


    $ dpconf set-ldif-data-view-prop admin-view contains-shared-entries:true

    When this property is set to TRUE, deleting an entry in the payroll data view will not result in the deletion of the shared entry in the administrator data view. Adding an entry to the payroll data view will only add the entry to the secondary data view if it does not already exist.

  4. Restart Directory Proxy Server for the changes to take effect.


    $ dpadm restart /local/myDPS

ProcedureJoin the Payroll Data View and the Administrator Data View

  1. Create a filter join rule on the administrator data view that specifies how the data should be aggregated.

    The following join rule specifies that data should be joined based on the employeeNumber attribute of the user entry.


    $ dpconf set-ldif-data-view-prop admin-view \
    filter-join-rule:employeeNumber=\${payroll-view.employeeNumber}
  2. Create a join data view that aggregates the two data views.

    For the join data view, the organization uses the suffix DN dc=example,dc=com.


    $ dpconf create-join-data-view example-join-view payroll-view admin-view \
    dc=example,dc=com

Add Data From Company 22 to Example.Com's DIT by Renaming the DN

The user data for Company 22 is stored under the DN dc=company22,dc=com. While Example.com wants to keep this user data separate in most cases, one client application needs to administer Company 22 employees along with the rest of the Example.com employees. This client application requires Company 22's user data to look like Example.com data.

The following diagram illustrates the requirements of the client application.

Figure 22–5 DN Renaming

Figure shows rename a DN to add data to a DIT

To fulfill this application requirement, a data view with a virtual DN of dc=example,dc=com is created for the Company 22's directory.

For simplicity, the commands used in this section assume the following information:

ProcedureCreate a Data View For Company 22's Directory With a Virtual DN

  1. Create an LDAP data source for Company 22's directory.


    $ dpconf create-ldap-data-source company22-directory company22Host:2389
  2. Create an LDAP data source pool for Company 22's directory.


    $ dpconf create-ldap-data-source-pool company22-pool
  3. Attach Company 22's data source to the data source pool.


    $ dpconf attach-ldap-data-source company22-pool company22-directory
  4. Configure the weights of the attached data source.


    $ dpconf set-attached-ldap-data-source-prop -p 2389 \
    company22-pool company22-directory add-weight:2 \
    bind-weight:2 compare-weight:2 delete-weight:2 \
    modify-dn-weight:2 modify-weight:2 search-weight:2
  5. Create an LDAP data view for Company 22's directory with a virtual DN of dc=example,dc=com.


    $ dpconf create-ldap-data-view company22-view company22-pool dc=example,dc=com
  6. Instruct Directory Proxy Server to map this virtual DN to the real DN that is in Company 22's directory.


    $ dpconf set-ldap-data-view-prop company22-view \
    dn-mapping-source-base-dn:dc=company22,dc=com
  7. Enable the LDAP data view for Company 22's directory so that client requests can be routed to this data view.


    $ dpconf set-ldap-data-view-prop company22-view is-enabled:true
  8. Restart Directory Proxy Server for the changes to take effect.


    $ dpadm restart /local/myDPS

Add Company 22's Data to the HR Data

The HR department requires an aggregated view of the HR data for Example.com and the newly acquired Company 22. The following diagram illustrates the requirements of the global HR application.

Figure 22–6 Aggregation of Data From Join Data View and LDAP Data View

Figure shows a complex join view of an LDAP directory
and another join view

ProcedureJoin the Example Join Data View and the Company 22 Data View

  1. Create a filter join rule on the Company 22 data view that specifies how the data should be aggregated.

    The following join rule specifies that data should be joined based on the employeeNumber attribute of the user entry.


    $ dpconf set-ldif-data-view-prop company22-view \
    filter-join-rule:employeeNumber=\${example-join-view.employeeNumber}
  2. Create a join data view that aggregates Company 22's data view and Example.com's join data view.


    $ dpconf create-join-data-view global-join-view example-join-view \
    company22-view dc=example,dc=com

Enable LDAP Clients to Access the Payroll Data in an SQL Database

Example.com's payroll department stores salary data in an SQL database. The database has two tables, and employee table and a salary table. Example.com has an LDAP client application that requires access to that data. The client application requires the SQL data to look like LDAP data.

The following diagram illustrates the requirements of the client application.

Figure 22–7 JDBC Dataview Providing Access to an SQL Database

Figure shows JDBC data view providing access to an SQL
database

To fulfill this application requirement, a JDBC data view is created that maps columns in the SQL tables to LDAP attributes.

For simplicity, the commands used in this section assume the following information:

ProcedureCreate a JDBC Data View For Example.com's Payroll Database

  1. Create a JDBC data source for the payroll database.


    $ dpconf create-jdbc-data-source -b payrollsqldb \
      -B jdbc:payrollsqldb:payrollsql://localhost/ \
      -J file://payrollsqldb.jar \
      -S org.payrollsqldb.jdbcDriver payroll-src 
  2. Configure the JDBC data source with the properties of the SQL database.


    $ dpconf set-jdbc-data-source-prop payroll-src \
      db-user:proxy db-pwd-file:password-file-location/myPasswordFile
  3. Enable the JDBC data source.


    $ dpconf set-jdbc-data-source-prop payroll-src is-enabled:true
  4. Create a JDBC data source pool for the payroll database.


    $ dpconf create-jdbc-data-source-pool payroll-pool
  5. Attach the payroll data source to the data source pool.


    $ dpconf attach-jdbc-data-source payroll-pool payroll-src
  6. Create a JDBC data view for the payroll database, with a virtual DN of o=payroll.


    $ dpconf create-jdbc-data-view payroll-view payroll-pool o=payroll
  7. Create a JDBC table for each table in the SQL database.


    $ dpconf create-jdbc-table jdbc-employee employee
    $ dpconf create-jdbc-table jdbc-salary salary
  8. Add a JDBC attribute for each column in the SQL tables.


    $ dpconf add-jdbc-attr jdbc-employee eid employee_id
    $ dpconf add-jdbc-attr jdbc-employee first firstname
    $ dpconf add-jdbc-attr jdbc-employee last lastname
    $ dpconf add-jdbc-attr jdbc-employee description description
    $ dpconf add-jdbc-attr jdbc-employee spouse spousename
    $ dpconf add-jdbc-attr jdbc-salary salary salary
    $ dpconf add-jdbc-attr jdbc-salary social ssn
  9. Specify which attributes can be viewed and which can be written, through the JDBC data view.


    $ dpconf set-jdbc-data-view-prop payroll-view \
     viewable-attr:eid \
     viewable-attr:first \
     viewable-attr:last \
     viewable-attr:desc \
     viewable-attr:spouse \
     viewable-attr:salary \
     viewable-attr:social 
     $ dpconf set-jdbc-data-view-prop payroll-view \
     writable-attr:eid \
     writable-attr:first \
     writable-attr:last \
     writable-attr:description \
     writable-attr:spouse \
     writable-attr:salary \
    writable-attr:social
  10. Create a JDBC object class that maps to an LDAP object class.

    The following command creates an object class that maps to the LDAP person object class. The object class specifies that the employee table should be used as the primary table, and that the salary table should be used as the secondary table. The eid attribute should be used to construct the DN.


    $ dpconf create-jdbc-object-class payroll-view \
     person jdbc-employee jdbc-salary eid
  11. Create a filter join rule on the secondary table that specifies how data from the secondary table should be linked to data from the primary table.

    The following join rule specifies that data should be joined based on the employee_id attribute.


    $ dpconf set-jdbc-table-prop jdbc-salary \
    filter-join-rule:employee_id=\${employee.employee_id}
  12. Create a super class on the JDBC object class.


    $ dpconf set-jdbc-object-class-prop payroll-view person super-class:extensibleObject

Add Virtual Access Control

Access control on LDAP directories is handled by defining ACIs in the directories themselves. When data sources are accessed through virtual data views, ACIs must be defined that apply only to the data viewed through these data views.

Any access that goes through Directory Proxy Server is controlled by a connection handler. For information about connection handlers, see Chapter 25, Connections Between Clients and Directory Proxy Server .

ProcedureAdd an ACI That Allows Anonymous Access

  1. Add the ACI.


    $ ldapadd -v -D "cn=proxy manager" -w password -p 389
    dn: cn=ldifonly-acis,cn=virtual access controls
    objectclass: top
    objectclass: aciSource
    cn: ldifonly-acis
    dpsaci: (targetattr="*")(version 3.0; acl "anonymous_access"; allow(all) \
    (userdn="ldap:///anyone");)
  2. Point the connection handler to the virtual ACI.


    $ dpconf set-connection-handler-prop anonymous aci-source:ldifonly-acis
  3. Enable the connection handler.


    $ dpconf set-connection-handler-prop anonymous is-enabled:true

Chapter 23 Virtual Data Transformations

Virtual data transformations are defined on existing data views, and enables you to create virtual data using the virtual data views. For information about how they work, see Virtual Data Transformations in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This chapter covers the following topics:

Configuring Virtual Data Transformations

You can add a virtual data transformation to any type of data view: an LDAP data view, an LDIF data view, a join data view, or a JDBC data view.

ProcedureTo Add a Virtual Transformation

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Add the transformation to a data view.


    $ dpconf add-virtual-transformation -h host -p port view-name \
     transformation-model transformation-action attribute-name [parameters...]

    The transformation-model can be one of the mapping, write, and read transformations.

    The transformation-action can be one of the add-attr, remove-attr, add-attr-value, remove-attr-value, def-value, and attr-value-mapping actions.

    Note that parameters might be mandatory, depending on the transformation-model and the transformation-action.

    For information about transformation models, transformation actions, and transformation parameters, see Virtual Data Transformations in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

  2. (Optional) View the list of virtual transformations that are defined on a data view.


    $ dpconf list-virtual-transformations -h host -p port view-name
    

ProcedureTo Remove a Virtual Transformation

  1. Remove the virtual transformation using the following command.


    dpconf remove-virtual-transformation view_name transformation_name
    

Virtual Transformation Examples

The following sections provide use cases in which virtual data views are required, and the combination of transformation models and actions required to implement the use cases.

Deriving an Attribute From the Existing Attributes of an Entry

Use the following transformation rule to derive an attribute from the existing attributes of an entry. For example, when the following transformation rule is applied, it displays the mail attribute derived from the givenName and sn attributes.


$ dpconf add-virtual-transformation dataview1 read add-attr \
mail \${givenName}.\${sn}@example.com 

The following diagram indicates the transformation that occurs on user entries when they are returned in a search.

Deriving an Attribute From the Existing Attributes of
an Entry

Mapping a Virtual Attribute to a Physical Attribute

Use the following mapping transformation rule to add an attribute that is delivered as a part of a pure virtual attribute. For example, when the following transformation rule is applied, the givenName is stored in the server even when it is not specified in the entry. The value is taken from the pure virtual attribute which is defined as mail \${givenName}@example.com.


$ dpconf add-virtual-transformation dataview1 mapping add-attr \
mail \${givenName}@example.com 

First add an entry that contains a virtual attribute, mail, but no givenName attribute. The virtual transformation generates the value for the givenName attribute and the entry is stored with givenName but without the mail attribute. Then, doing a search on using the uid attribute, retrieve the value for givenName, and the same virtual transformation generates the value of the virtual attribute mail.

The following diagram indicates the transformation that occurs on user entries.

Adding an Attribute to the Entry From the Virtual Attribute

Displaying a Second Virtual Value of an Attribute, Specified by Another Physical Attribute

Use the following transformation to display the value of an attribute that is specified by another attribute. For example, displaying uid as cn along with the value of cn that is already stored in the entry. The following does not store the additional value to cn but before the result is returned to the client, the transformation is applied.


$ dpconf add-virtual-transformation dataview1 read add-attr-value cn \${uid}

The following diagram indicates the transformation that occurs on user entries when they are returned in a search.

Displaying the Value of an Attribute Specified by Another
Attribute

Storing a Second Value to an Attribute Specified by Another Physical Attribute

Use the following transformation rule to store the value of an attribute along with the value that you provide while adding a new entry. In this scenario, when you add an entry, an additional value for the mail attribute is stored. This transformation is applied only at the time of creating new entries.


$ dpconf add-virtual-transformation dataview1 write add-attr-value \
mail \${uid}@example.com

The following diagram indicates the transformation that occurs on an add request.

Adding a Value to an Attribute From Another Attribute

Removing an Attribute From the Output

Use the following transformation rule if you do not want to display an attribute in the output. For example, when the following transformation rule is applied, the givenName is not returned in the output.


dpconf add-virtual-transformation dataview1 read remove-attr givenName

The following diagram indicates the transformation that occurs on user entries when they are returned in a search.

Removing an Attribute From the Output

Masking an Attribute While Saving an Entry

Use the following transformation rule if you do not want to store a specific attribute. For example, when the following transformation rule is applied, the givenName attribute is not stored in the physical database. This transformation is applied only at the time of creating new entries.


$ dpconf add-virtual-transformation dataview1 write remove-attr givenName

The following diagram indicates the transformation that occurs on an add request.

Masking an Attribute While Saving an Entry

Displaying a Default Value of an Attribute

Use the following transformation if you want to display a default value assigned to an attribute. For example, when the following transformation is applied, a default telephone number in the entries that do not contain their own telephone number is displayed.


$ dpconf add-virtual-transformation data-view read 11111 telephoneNumber default-number

The following diagram indicates the transformation that occurs on user entries when they are returned in a search.

Displaying a Default Value of an Attribute

Storing a Default Value to an Attribute

The default value is stored only if the value for an attribute is not specified during the creation of an entry. Use the following transformation rule if you want to store an attribute with the default value. For example, when the following transformation is applied, a default telephone number with each entry you create is added. This transformation is applied only at the time of adding an entry.


$ dpconf add-virtual-transformation dataview1 write 11111 \
telephoneNumber telephone-number

The following diagram indicates the transformation that occurs on an add request.

Adding a Default Value to an Attribute

Chapter 24 Connections Between Directory Proxy Server and Back-End LDAP Servers

This chapter describes how to configure connections between Directory Proxy Server and back-end LDAP servers. The chapter covers the following topics:

Configuring Connections Between Directory Proxy Server and Back-End LDAP Servers

When an LDAP data source is created, the number of default connections opened for the LDAP data source are six, that is, two for each read, bind, and write operations respectively. To verify the default connections, type the following command:


$ dpconf get-ldap-data-source-prop src-name num-read-init num-write-init num-bind-init
num-bind-init   :  2
num-read-init   :  2
num-write-init  :  2

The number of connections increases automatically when the traffic increases.

For information about how to configure connections between Directory Proxy Server and back-end LDAP servers, see the following procedures:

ProcedureTo Configure the Number of Connections Between Directory Proxy Server and Back-End LDAP Servers


Note –

This procedure configures the number of connections for bind operations. To configure the number of connections for read or write operations, perform the same procedure but replace bind with read or write.


You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the initial number of connections between Directory Proxy Server and a back-end LDAP server for bind operations.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     num-bind-init:new-value
    
  2. Configure the increment of connections for bind operations.

    The increment is the number of connections that are added each time more than the current number of connections are requested.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     num-bind-incr:new-value
    
  3. Configure the maximum number of connections for bind operations.

    When this maximum number of connections is reached, no more connections can be added.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     num-bind-limit:new-value
    

ProcedureTo Configure Connection Timeout

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the maximum length of time that Directory Proxy Server can attempt to connect to a data source.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     connect-timeout:new-value
    

    For example, configure the connection timeout to 10 milliseconds.


    $ dpconf set-ldap-data-source-prop -h host1 -p 1389 data-source-name connect-timeout:10

ProcedureTo Configure Connection Pool Wait Timeout

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the maximum length of time that Directory Proxy Server can wait for an established connection in a connection pool to become available.


    $ dpconf set-server-prop -h host -p port data-source-name \
     connection-pool-wait-timeout:value
    

    For example, configure the timeout to 20 seconds.


    $ dpconf set-ldap-data-source-prop -h host1 -p 1389 data-source-name \
     connection-pool-wait-timeout:20000

Configuring SSL Between Directory Proxy Server and Back-End LDAP Servers

The following procedure describes how to configure SSL between Directory Proxy Server and back-end LDAP servers.

ProcedureTo Configure SSL Between Directory Proxy Server and a Back-End LDAP Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure a secure port between Directory Proxy Server and the back-end LDAP server.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     ldaps-port:port-number
    
  2. Configure when SSL is used for connections between Directory Proxy Server and the back-end LDAP server.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name ssl-policy:value
    
    • If value is always, SSL is always used for connections.

    • If value is client, SSL is used if the client is using SSL.

    If the connection is not using SSL, you can promote the connection to SSL by using the startTLS command.

    Transport Layer Security (TLS) is the standard version of SSL. TLS over LDAP is the IETF approved standard way of securing LDAP. LDAPS is a de facto standard but leads to some complexity such as having two ports instead of only one port for the service.

  3. Choose the protocols and ciphers for SSL as described in Choosing SSL Ciphers and SSL Protocols for Directory Proxy Server.

  4. Configure Directory Proxy Server to validate an SSL server certificate from the back-end LDAP server.

    For information, see To Add a Certificate From a Back-End Directory Server to the Certificate Database on Directory Proxy Server.

  5. If the back-end LDAP server requests a certificate from Directory Proxy Server, configure Directory Proxy Server to send an SSL client certificate.

    For information, see Exporting a Certificate to a Back-End LDAP Server.

  6. Restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Choosing SSL Ciphers and SSL Protocols for Directory Proxy Server

The ciphers and protocols that can be used by Directory Proxy Server depend on the Java Virtual Machine (JVM) that is being used. By default, Directory Proxy Server uses the default ciphers and protocols that are enabled for the JVM machine.

ProcedureTo Choose the List of Ciphers and Protocols

Use this procedure to retrieve the supported ciphers and protocols, and the enabled ciphers and protocols. If a cipher or protocol is supported, you can enable or disable it.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the list of supported ciphers and protocols.


    $ dpconf get-server-prop -h host -p port supported-ssl-cipher-suites \
     supported-ssl-protocols
  2. View the list of enabled ciphers and protocols.


    $ dpconf get-server-prop -h host -p port enabled-ssl-cipher-suites \
     enabled-ssl-protocols
  3. Enable one or more supported ciphers or protocols.

    1. Enable one or more supported ciphers.


      $ dpconf set-server-prop -h host -p port \
       enabled-ssl-cipher-suites:supported-ssl-cipher-suite \
       [enabled-ssl-cipher-suites:supported-ssl-cipher-suite ...]

      To add a cipher to an existing list of supported ciphers, use this command:


      $ dpconf set-server-prop -h host -p port \
       enabled-ssl-cipher-suites+:supported-ssl-cipher-suite
      
    2. Enable one or more supported protocols.


      $ dpconf set-server-prop -h host -p port \
       enabled-ssl-cipher-protocols:supported-ssl-cipher-protocol \
       [enabled-ssl-cipher-protocols:supported-ssl-cipher-protocol ...]

      To add a protocol to an existing list of supported protocols, use this command:


      $ dpconf set-server-prop -h host -p port \
       enabled-ssl-cipher-protocols+:supported-ssl-cipher-protocol
      
  4. (Optional) Disable a supported cipher or protocol.


    $ dpconf set-server-prop -h host -p port \
     enabled-ssl-cipher-protocols-:supported-ssl-cipher-protocol
    

Forwarding Requests to Back-End LDAP Servers

This section contains information about the various methods you can use to forward requests from Directory Proxy Server to back-end LDAP servers.

Forwarding Requests With Bind Replay

For information about bind replay for client credentials in Directory Proxy Server, see Directory Proxy Server Configured for BIND Replay in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. The following procedure describes how to forward requests from Directory Proxy Server to a back-end LDAP server by using bind replay.

ProcedureTo Forward Requests With Bind Replay

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the data source client credentials to authenticate to a back-end LDAP server by using the credentials provided by a client.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     client-cred-mode:use-client-identity

Forwarding Requests With Proxy Authorization

For information about proxy authorization in Directory Proxy Server, see Directory Proxy Server Configured for Proxy Authorization in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This section contains procedures for forwarding requests by using proxy authorization and by using a proxy authorization control.

ProcedureTo Forward Requests by Using Proxy Authorization

  1. Configure the data source to expect proxy authorization controls of either version 1 or version 2.

    For example, configure the data source to expect proxy authorization controls of version 1.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     proxied-auth-use-v1:true

    Alternatively, configure the data source to expect proxy authorization controls of version 2.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     proxied-auth-use-v1:false
  2. Configure the data source to authenticate to a back-end LDAP server by using proxy authorization.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     client-cred-mode:use-proxy-auth

    To configure a data source to authenticate to a back-end LDAP server by using proxy authorization for write operations only, run this command:


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     client-cred-mode:use-proxy-auth-for-write

    When write operations only are performed with a proxy authorization control, the client identity is not forwarded to the LDAP server for read requests. For more information about forwarding requests without the client identity, see Forwarding Requests Without the Client Identity.

  3. Configure the data source with the bind credentials of Directory Proxy Server.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     bind-dn:DPS-bind-dn bind-pwd-file:filename
    
  4. Configure the data source with the timeout.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     proxied-auth-check-timeout:value
    

    Directory Proxy Server verifies that the client DN has the relevant ACIs for proxy authorization by using the getEffectiveRights command. The result is cached in Directory Proxy Server and renewed when the proxied-auth-check-timeout expires.

  5. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

ProcedureTo Forward Requests by Using Proxy Authorization When the Request Contains a Proxy Authorization Control

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure Directory Proxy Server to accept proxy authorization controls of version 1, version 2, or both.


    $ dpconf set-server-prop -h host -p port allowed-ldap-controls:proxy-auth-v1 \
     allowed-ldap-controls:proxy-auth-v2

Forwarding Requests Without the Client Identity

The following procedure describes how to forward requests from Directory Proxy Server to a back-end LDAP server without forwarding the client identity.

ProcedureTo Forward Requests Without the Client Identity

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the data source to authenticate to a back-end LDAP server by using the credentials of Directory Proxy Server.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     client-cred-mode:use-specific-identity
  2. Configure the data source with the bind credentials of Directory Proxy Server.


    $ dpconf set-ldap-data-source-prop -h host -p port data-source-name \
     bind-dn:bind-dn-of-DPS bind-pwd-file:filename
    
  3. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Forwarding Requests as an Alternate User

This section contains information about how to forward requests as an alternate user.

ProcedureTo Configure Remote User Mapping

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable operations to be forwarded with an alternate user.


    $ dpconf set-server-prop -h host -p port enable-user-mapping:true
  2. Specify the name of the attribute that contains the ID for remote mapping.


    $ dpconf set-server-prop -h host -p port \
     remote-user-mapping-bind-dn-attr:attribute-name
    
  3. Enable Directory Proxy Server to map the client ID remotely.


    $ dpconf set-server-prop -h host -p port enable-remote-user-mapping:true
  4. Configure the default mapping.


    $ dpconf set-server-prop -h host -p port \
     user-mapping-default-bind-dn:default-mapping-bind-dn \
     user-mapping-default-bind-pwd-file:filename
    

    If the mapped identity is not found on the remote LDAP server, the client identity is mapped to the default identity.

  5. Configure the user mapping in the entry for the client on the remote LDAP server.

    For information about configuring user mapping in Directory Server, see Proxy Authorization.

ProcedureTo Configure Local User Mapping

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable operations to be forwarded with an alternate user.


    $ dpconf set-server-prop -h host -p port enable-user-mapping:true
  2. Ensure that Directory Proxy Server is not configured to map the client ID remotely.


    $ dpconf set-server-prop -h host -p port enable-remote-user-mapping:false
  3. Configure the default mapping.


    $ dpconf set-server-prop -h host -p port \
     user-mapping-default-bind-dn:default-mapping-bind-dn \
     user-mapping-default-bind-pwd-file:filename
    

    The client ID is mapped to this DN if the mapping on the remote LDAP server fails.

  4. If you permit unauthenticated users to perform operations, configure the mapping for unauthenticated clients.


    $ dpconf set-server-prop -h host -p port \
     user-mapping-anonymous-bind-dn:anonymous-mapping-bind-dn \
     user-mapping-anonymous-bind-pwd-file:filename
    

    For information about how to permit unauthenticated users to perform operations, see To Configure Anonymous Access.

  5. Configure the ID of the client.


    $ dpconf set-user-mapping-prop -h host -p port \
     user-bind-dn:client-bind-dn user-bind-pwd-file:filename
    
  6. Configure the ID of the alternate user.


    $ dpconf set-user-mapping-prop -h host -p port \
     mapped-bind-dn:alt-user-bind-dn mapped-bind-pwd-file:filename
    

ProcedureTo Configure User Mapping for Anonymous Clients

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure the mapping for unauthenticated clients.


    $ dpconf set-server-prop -h host -p port \
     user-mapping-anonymous-bind-dn:anonymous-mapping-bind-dn \
     user-mapping-anonymous-bind-pwd-file:filename
    

    The mapping for anonymous clients is configured in Directory Proxy Server because the remote LDAP server does not contain an entry for an anonymous client.

    For information about permitting unauthenticated users to perform operations, see To Configure Anonymous Access.

Chapter 25 Connections Between Clients and Directory Proxy Server

For an overview of the connections between clients and Directory Proxy Server, connection handlers, and a description of the criteria and policies used in connection handlers, see Chapter 20, Connections Between Clients and Directory Proxy Server, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This chapter covers the following topics:

Creating, Configuring, and Deleting Connection Handlers

For information about how to create, configure, and delete connection handlers, and to configure affinity for data views, see the following procedures.

ProcedureTo Create a Connection Handler

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a connection handler.


    $ dpconf create-connection-handler -h host -p port connection-handler-name
    
  2. (Optional) View the list of connection handlers.


    $ dpconf list-connection-handlers -h host -p port
    

ProcedureTo Configure a Connection Handler

Before You Begin

The properties of a connection handler must be defined in relation to the properties of the other connection handlers that are defined for the Directory Proxy Server instance. Consider the properties of all of your connection handlers to ensure that they specify different sets of criteria and are prioritized correctly.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View a verbose list of connection handlers to see their key properties and relative priorities.


    $ dpconf list-connection-handlers -h host -p port -v
    Name                               is-enabled  priority  description
    ---------------------------------  ----------  --------  ---------------------------
    anonymous                          false       99        unauthenticated connections
    default connection handler         true        100       default connection handler
    directory services administrators  true        1         Administrators connection handler

    The connection handlers anonymous and default connection handler are created when you create an instance of Directory Proxy Server.

  2. View all of the properties of one connection handler.


    $ dpconf get-connection-handler-prop -h host -p port connection-handler-name
    

    The default properties of a new connection handler are as follows:


    aci-source                              :  none
    allowed-auth-methods                    :  anonymous
    allowed-auth-methods                    :  sasl
    allowed-auth-methods                    :  simple
    allowed-ldap-ports                      :  ldap
    allowed-ldap-ports                      :  ldaps
    bind-dn-filters                         :  any
    close-client-connection                 :  false
    data-view-routing-custom-list           :  none
    data-view-routing-policy                :  all-routable
    data-view-use-internal-client-identity  :  false
    description                             :  -
    domain-name-filters                     :  any
    enable-data-view-affinity               :  false
    group-dn-filters                        :  any
    group-search-bind-dn                    :  any
    group-search-bind-pwd                   :  none
    ip-address-filters                      :  any
    is-enabled                              :  false
    is-ssl-mandatory                        :  false
    priority                                :  99
    request-filtering-policy                :  no-filtering
    require-data-view-availability          :  true
    resource-limits-policy                  :  no-limits
    schema-check-enabled                    :  false
    user-filter                             :  any
  3. Configure the priority of the connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name\
     priority:value
    

    The priority can be any number from 1 to 100, where 1 is the highest priority. For an instance of Directory Proxy Server, the connection handlers are evaluated in order of priority.


    Note –

    You cannot set the priority of a connection handler to 100 because 100 is already set as the priority of the default connection handler.


  4. (Optional) Specify the DN filtering property of the connection handler.

    This property enables you to control access based on part or all of the bind DN. The value of the property is a regular expression.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     bind-dn-filters:regular-expression
    

    The bind DN filter takes the form of a Java regular expression. For information about creating Java regular expressions, see http://download.oracle.com/docs/cd/E17476_01/javase/1.4.2/docs/api/java/util/regex/Pattern.html.

    For example, to send all binds from users under ou=people,dc=example,dc=com to a connection handler named secure-handler, set the bind-dn-filters property as follows:


    $ dpconf set-connection-handler-prop -h host1 -p 1389 secure-handler \
     bind-dn-filters:"uid=.*,ou=people,dc=example,dc=com"
  5. (Optional) Specify the name of a request filtering policy to use with this connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     request-filtering-policy:policy-name
    

    where policy-name is the name of an existing request filtering policy. For information about how to create and configure a request filtering policy, see Creating and Configuring Request Filtering Policies and Search Data Hiding Rules.

  6. (Optional) Specify the name of a resource limits policy to use with this connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     resource-limits-policy:policy-name
    

    where policy-name is the name of an existing resource limits policy. For information about how to create and configure a resource limits policy, see Creating and Configuring a Resource Limits Policy.

  7. Configure any other properties that are listed in Step 2.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     property:value [property:value ...]

    For example, configure the connection handler to accept SSL connections only.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     is-ssl-mandatory:true

    For a description of a property and a list of its valid values, run this command:


    $ dpconf help-properties connection-handler

    Configure group-dn-filters, group-search-bind-dn, group-search-bind-pwd, and group-search-bind-pwd-file to specify the criteria to select connection handlers. For more information, see the respective man pages.

  8. Enable the connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name\
     is-enabled:true
  9. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

ProcedureTo Delete a Connection Handler

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. (Optional) View the list of connection handlers.


    $ dpconf list-connection-handlers -h host -p port
    
  2. Delete one or more connection handlers.


    $ dpconf delete-connection-handler -h host -p port connection-handler-name\
     [connection-handler-name ... ]

ProcedureTo Configure Affinity for Data Views

When a connection is allocated to a connection handler, you can use affinity to expose the requests on that connection to the list of data views that are configured for that connection handler, or to all of the configured data views. Therefore, successive requests on that connection are exposed exclusively to the data view that is used for the first request.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable affinity for data views.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     enable-data-view-affinity:true
  2. (Optional) Configure the connection handler to route requests to a custom list of data views.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name\
     data-view-routing-policy:custom
  3. (Optional) Configure the list of data views.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     data-view-routing-custom-list:view-name [data-view-routing-custom-list:view-name ...]

    To add a data view to an existing list of data views, use this command:


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     data-view-routing-custom-list+:view-name
    

    To remove a data view from an existing list of data views, use this command:


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     data-view-routing-custom-list-:view-name
    

Creating and Configuring Request Filtering Policies and Search Data Hiding Rules

For an overview of request filtering policies, see Request Filtering Policies for Connection Handlers in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. For an overview of search data hiding rules, see Search Data Hiding Rules in the Request Filtering Policy in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure request filtering policies and search data hiding rules, see the following procedures.

ProcedureTo Create a Request Filtering Policy

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a request filtering policy.


    $ dpconf create-request-filtering-policy policy-name
    
  2. Associate the request filtering policy with a connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     request-filtering-policy:policy-name
    

ProcedureTo Configure a Request Filtering Policy

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the properties of a request filtering policy.


    $ dpconf get-request-filtering-policy-prop -h host -p port policy-name
    

    The default properties of a request filtering policy are as follows:


    allow-add-operations                :  true
    allow-bind-operations               :  true
    allow-compare-operations            :  true
    allow-delete-operations             :  true
    allow-extended-operations           :  true
    allow-inequality-search-operations  :  true
    allow-modify-operations             :  true
    allow-rename-operations             :  true
    allow-search-operations             :  true
    allowed-comparable-attrs            :  all
    allowed-search-scopes               :  base
    allowed-search-scopes               :  one-level
    allowed-search-scopes               :  subtree
    allowed-subtrees                    :  ""
    description                         :  -
    prohibited-comparable-attrs         :  none
    prohibited-subtrees                 :  none
  2. Configure the request filtering policy by setting one ore more of the properties listed in Step 1.


    $ dpconf set-request-filtering-policy-prop -h host -p port policy-name \
      property:value [property:value ...]

    By setting the properties listed in Step 1, you configure the following features of the request filtering policy:

    • The types of operations that clients are allowed to perform

    • The subtrees that are exposed to a client or hidden from a client

    • The scope for search operations

    • The types of search filters

    • The attribute types that can or cannot be compared in search and compare operations

ProcedureTo Create Search Data Hiding Rules

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create one or more search data hiding rules for a request filtering policy.


    $ dpconf create-search-data-hiding-rule -h host -p port policy-name rule-name \
     [rule-name ...]
  2. View the properties of a search data hiding rule.


    $ dpconf get-search-data-hiding-rule-prop policy-name rule-name
    

    The default properties of a search data hiding rule are as follows:


    attrs                              :  none
    rule-action                        :  hide-entry
    target-attr-value-assertions       :  none
    target-dn-regular-expressions      :  none
    target-dns                         :  none
  3. Configure a search data hiding rule by setting one or more of the properties listed in Step 2.


    $ dpconf set-search-data-hiding-rule-prop -h host -p port policy-name rule-name \
      property:value [property:value ...]

    One of the following rule actions can be used:

    hide-entry

    The target entry is not returned.

    hide-attributes

    The target entry is returned but the specified attributes are filtered out.

    show-attributes

    The target entry is returned but the unspecified attributes are filtered out.

    The rule can be applied to the following entries:

    target-dns

    Entries with the specified DN

    target-dn-regular-expressions

    Entries with the specified DN pattern

    target-attr-value-assertions

    Entries with a specified attribute name and attribute value pair (attrName#attrValue)

    The following configuration defines a search data hiding rule that hides entries of type inetorgperson.


    $ dpconf set-search-data-hiding-rule-prop -h host1 -p port my-policy my-rule \
      target-attr-value-assertions:objectclass#inetorgperson

Example Request Filtering Policy and Search Data Hiding Rule

The following examples contain a request filtering policy and a search data hiding rule. When the request filtering policy is combined with the search data hiding rule, access to data is limited as follows:


Example 25–1 Sample Request Filtering Policy


allow-add-operations                :  false
allow-bind-operations               :  true
allow-compare-operations            :  true
allow-delete-operations             :  false
allow-extended-operations           :  false
allow-inequality-search-operations  :  true
allow-modify-operations             :  false
allow-rename-operations             :  false
allow-search-operations             :  true
allowed-comparable-attrs            :  all
allowed-search-scopes               :  base
allowed-search-scopes               :  one-level
allowed-search-scopes               :  subtree
allowed-subtrees                    :  ou=people,dc=example,dc=com
description                         :  myRequestFilteringPolicy
prohibited-comparable-attrs         :  none
prohibited-subtrees                 :  none


Example 25–2 Sample Search Data Hiding Rule


attrs                              :  -
rule-action                        :  hide-entry
target-attr-value-assertions       :  objectclass:inetorgperson
target-dn-regular-expressions      :  -
target-dns                         :  -

Creating and Configuring a Resource Limits Policy

For an overview of resource limits policies, see Resource Limits Policies for Connection Handlers in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. For information about how to create and configure resource limits policies and to customize search limits, see the following procedures.

ProcedureTo Create a Resource Limits Policy

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create a resource limits policy.


    $ dpconf create-resource-limits-policy -h host -p port policy-name
    

    For information about how to modify the properties of a resource limits policy, see To Configure a Resource Limits Policy.

  2. Associate the resource limits policy to a connection handler.


    $ dpconf set-connection-handler-prop -h host -p port connection-handler-name \
     resource-limits-policy:policy-name
    

ProcedureTo Configure a Resource Limits Policy

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the properties of a resource limits policy.


    $ dpconf get-resource-limits-policy-prop -h host -p port policy-name
    

    The default properties of a resource limits policy are as follows:


    denied-presence-filter-attr                 :  all
    denied-presence-filter-attr-enabled         :  false
    description                                 :  -
    max-client-connections                      :  unlimited
    max-connections                             :  unlimited
    max-op-count-per-interval                   :  inlimited
    max-simultaneous-operations-per-connection  :  unlimited
    max-total-operations-per-connection         :  unlimited
    minimum-search-filter-substring-length      :  unlimited
    op-count-per-interval-timeout               :  1s
    referral-bind-policy                        :  default
    referral-hop-limit                          :  default
    referral-policy                             :  default
    search-size-limit                           :  unlimited
    search-time-limit                           :  unlimited
    warning-op-count-per-interval               :  unlimited
  2. Configure the resource limits policy by setting one or more of the properties that are listed in Step 1:


    $ dpconf set-resource-limits-policy-prop -h host -p port policy-name \
      property:value [property:value ...]

    To specify the threshold number of operations per time interval at which a warning is raised, run the following command:


    $ dpconf  set-resource-limits-policy-prop -h host -p port policy-name \
    warning-op-count-per-interval:1500 

    When the specified number of operations exceed in a specified time interval, the warning-resource-limit-exceeded alert is raised. For more information on warning-resource-limit-exceeded, see Configuring Administrative Alerts for Directory Proxy Server.

ProcedureTo Block Presence Filters in the Search Operation

  1. Configure denied-presence-filter-attr to deny access when search operation contains at least one of the attributes in the list of denied filter attributes.


    $ dpconf set-resource-limits-policy-prop  -h host -p port policy-name \
    denied-presence-filter-attr:attribute-name
    
  2. Turn on denied-presence-filter-enabled to indicate whether to deny access when the search filter contains specified attributes.


    $ dpconf set-resource-limits-policy-prop -h host -p port policy-name\
    denied-presence-filter-enabled:on 

ProcedureTo Customize Search Limits

Customized limits can be defined for search operations according to the search base and search scope. If the target DN and scope of a search operation matches the specified criteria, the maximum size of the search result is limited.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create one or more custom search limits.


    $ dpconf create-custom-search-size-limit -h host -p port policy-name \
      custom-search-limit-name [custom-search-limit-name ...]
  2. Set the criteria for the custom search limit.


    $ dpconf set-custom-search-size-limit-prop -h host -p port policy-name \
      custom-search-limit-name one-level-search-base-dn:value subtree-search-base-dn:value
    
  3. Set the limit for the number of results that are returned when a search meets one of the criteria in Step 2.


    $ dpconf set-custom-search-size-limit-prop -h host -p port policy-name \
     custom-search-limit-name search-size-limit:value
    
  4. View the properties of a custom search limit.


    $ dpconf get-custom-search-size-limit-prop -h host -p port policy-name \
      custom-search-limit-name
    

    The default properties of a custom search limit are as follows:


    one-level-search-base-dn  :  none
    search-size-limit         :  unlimited
    subtree-search-base-dn    :  none

ProcedureTo Limit LDAP Operations Rates

Directory Proxy Server lets you set a threshold for the maximum number of LDAP operations allowed in a given time period. You set the operations rate limit per connection handler using a resource limits policy. The settings effectively allow you to limit the LDAP operation rate for an LDAP client application. For example you can use this capability to ensure that one LDAP client application can perform a maximum of 2500 LDAP operations per second, whereas another LDAP client operation is limited to a maximum of 1200 operations per second.

First set up a connection handler to describe connections from the client application whose LDAP operation rate you want to limit. Then create a resource limits policy for the connection handler. Finally follow the steps here to limit the operation rate using the resource limits policy on the connection handler.

  1. Enable the operations rate limit counters.


    $ dpconf set-resource-limits-policy-prop -h host -p port policy-name \
    max-op-count-per-interval:2500
    $ dpconf set-resource-limits-policy-prop -h host -p port policy-name \
    op-count-per-interval-timeout:1s
  2. When an LDAP client exceeds the operation rate limit you set, Directory Proxy Server can raise an alert provided you set up Directory Proxy Server as described in the Configuring Administrative Alerts for Directory Proxy Server section.

    To add an alert about operation rate limits being reached, run this command:


    $ dpconf set-server-prop -h host -p port\
     enabled-admin-alerts+:error-resource-limit-exceeded

    Directory Proxy Server raises an alert when the operations rate limit is exceeded. Directory Proxy Server also writes a message in the access log each time an operation is refused because the application exceeds its limit.

Configuring Directory Proxy Server as a Connection Based Router

Directory Proxy Server 5.2 is a connection based router. In Directory Proxy Server 5.2, a client connection is routed to a specific directory server. All requests on that client connection are sent to the same directory server until the connection is broken or until the client unbinds.

Directory Proxy Server 11g Release 1 (11.1.1) is an operation based router. However, for compatibility, this version of Directory Proxy Server can be configured as a connection based router, as described in the following procedure.

ProcedureTo Configure Directory Proxy Server as a Connection Based Router

  1. Create and configure one or more connection handlers as described in Creating, Configuring, and Deleting Connection Handlers.

    You can also use the default connection handler.

  2. Configure all connection handlers to route requests to the root data view only.

    For example:


    $ dpconf set-connection-handler-prop -h host1 -p 1389 myConnectionHandler \
     data-view-routing-policy:custom data-view-routing-custom-list:"root data view"
  3. Create and configure a data source for each back-end LDAP server as described in Creating and Configuring LDAP Data Sources.

    For example:


    $ dpconf create-ldap-data-source -h host1 -p 1389 myDataSource host2:2389
  4. Create and configure a data source pool as described in Creating and Configuring LDAP Data Source Pools.

    For example:


    $ dpconf create-ldap-data-source-pool -h host1 -p 1389 myDataSourcePool
  5. Attach all of the data sources to the data source pool as described in Attaching LDAP Data Sources to a Data Source Pool.

    For example,


    $ dpconf attach-ldap-data-source -h host1 -p 1389 myDataSourcePool myDataSource
  6. Configure each data source to authenticate clients by using BIND replay as described in Forwarding Requests With Bind Replay.

    For example:


    $ dpconf set-ldap-data-source-prop -h host1 -p 1389 myDataSource \
     client-cred-mode:use-client-identity
  7. Configure affinity between the client connection and the data source pool as described in Configuring Client Affinity.

    For example:


    $ dpconf set-ldap-data-source-pool-prop -h host1 -p 1389 myDataSourcePool \
     enable-client-affinity:true client-affinity-policy:read-write-affinity-after-write

Chapter 26 Directory Proxy Server Client Authentication

For an overview of client authentication in Directory Proxy Server, see Chapter 21, Directory Proxy Server Client Authentication, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This chapter covers the following topics:

Configuring Listeners Between Clients and Directory Proxy Server

Directory Proxy Server provides a secure listener and a non-secure listener for communication with clients. For information about listeners for Directory Proxy Server, see Directory Proxy Server Client Listeners in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This section describes how to configure the listeners.

ProcedureTo Configure the Listeners Between a Client and Directory Proxy Server


Note –

This procedure configures the non-secure listener between a client and Directory Proxy Server. To configure the secure listener, perform the same procedure but replace ldap with ldaps.


You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. In DSCC, you can configure this property on the Performance tab.

  1. View the properties of the non-secure listener.


    $ dpconf get-ldap-listener-prop -h host -p port
    

    The default properties of the non-secure listener are as follows:


    connection-idle-timeout          :  1h
    connection-read-data-timeout     :  2s
    connection-write-data-timeout    :  1h
    is-enabled                       :  true
    listen-address                   :  0.0.0.0
    listen-port                      :  port-number
    max-connection-queue-size        :  128
    max-ldap-message-size            :  unlimited
    number-of-threads                :  2
    use-tcp-keep-alive               :  true
    use-tcp-no-delay                 :  true
  2. Change one or more of properties that are listed in Step 1 according to your requirements.


    $ dpconf set-ldap-listener-prop -h host -p port property:new-value
    

    For example, to disable the non-secure port for an instance of Directory Proxy Server running on host1, run the following command:


    $ dpconf set-ldap-listener-prop -h host1 -p 1389 is-enabled:false

    Caution – Caution –

    If you plan to use a privileged port number, you must run Directory Proxy Server as root.


    To change the non-secure port number, run the following command:


    $ dpconf set-ldap-listener-prop -h host -p port listen-port:new-port-number
    
  3. If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

    Changes to certain listener properties require a server restart. dpconf alerts you if the server must be restarted. For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Authenticating Clients to Directory Proxy Server

By default, Directory Proxy Server is configured for simple bind authentication. No additional configuration is required for simple bind authentication.

For information about authentication between clients and Directory Proxy Server, see Client Authentication Overview in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. For information about how to configure authentication, see the following procedures.

ProcedureTo Configure Certificate-based Authentication

For information about certificate-based authentication of clients, see Configuring Certificates in Directory Proxy Server in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This section describes how to configure certificate-based authentication.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.


Note –

Certificate-based authentication can only be performed over an SSL connection.


  1. Configure Directory Proxy Server to require a client to present a certificate when the client establishes an SSL connection.


    $ dpconf set-server-prop -h host -p port allow-cert-based-auth:require

ProcedureTo Configure Anonymous Access

For information about anonymous access, see Anonymous Access in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. For information about how to map the identity of an anonymous client to another identity, see Forwarding Requests as an Alternate User.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Permit unauthenticated users to perform operations.


    $ dpconf set-server-prop -h host -p port \
    allow-unauthenticated-operations:true
  2. (Optional) Specify the access mode for unauthenticated users.


    $ dpconf set-server-prop -h host -p port allow-unauthenticated-operations-mode:mode
    

    For more information, see allow-unauthenticated-operations-mode(5dpconf).

ProcedureTo Configure Directory Proxy Server for SASL External Bind

For information about SASL external bind, see Using SASL External Bind in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Disallow unauthenticated operations.


    $ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:false
  2. Require clients to present a certificate when establishing a connection.


    $ dpconf set-server-prop -h host -p port allow-cert-based-auth:require

    The client provides a certificate that contains a DN.

  3. Enable the authentication of clients by SASL external bind.


    $ dpconf set-server-prop -h host -p port -e allow-sasl-external-authentication:true
  4. Configure the identity used by Directory Proxy Server to map a client certificate on a back-end LDAP server.


    $ dpconf set-server-prop -h host -p port -e \
    cert-search-bind-dn:bind-DN cert-search-bind-pwd-file:filename
    
  5. Configure the base DN of the subtree that Directory Proxy Server searches.

    Directory Proxy Server searches the subtree to find a user entry that is mapped to a client certificate.


    $ dpconf set-server-prop -h host -p port -e  \
    cert-search-base-dn:base-DN
    
  6. Map information in the client certificate to certificates on the LDAP server.

    1. Name the attribute on the LDAP server that contains certificates.


      $ dpconf set-server-prop -e cert-search-user-attribute:attribute
      
    2. Map an attribute on the client certificate to the DN of the entry on the LDAP server that contains certificates.


      $ dpconf set-server-prop -h host -p port -e \
       cert-search-attr-mappings:client-side-attribute-name:server-side-attribute-name
      

      For example, to map a client certificate with the DN cn=user1,o=example,c=us to an LDAP entry with the DN uid=user1,o=example, run the following command:


      $ dpconf set-server-prop -h host1 -p 1389 -e cert-search-attr-mappings:cn:uid \
       cert-search-attr-mappings:o:o
      
  7. (Optional) Route requests for SASL external bind operations to all data views or to a custom list of data views.

    • To route requests to all data views, run this command:


      $ dpconf set-server-prop -h host -p port -e \
      cert-data-view-routing-policy:all-routable
    • To route requests to a list of data views, run this command:


    $ dpconf set-server-prop -h host -p port -e cert-data-view-routing-policy:custom \
    cert-data-view-routing-custom-list:view-name [view-name...]
       
Troubleshooting

Use the -e option wherever it is mentioned in the above procedure to successfully configure Directory Proxy Server for SASL External Bind.

Chapter 27 Directory Proxy Server Logging

Directory Proxy Server logs information in access logs and error logs. Unlike Directory Server, Directory Proxy Server does not have an audit log. For a description of the logs in Directory Proxy Server, see Chapter 23, Directory Proxy Server Logging, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

This chapter covers the following topics:

Viewing Directory Proxy Server Logs

You can view Directory Proxy Server logs directly through the log files or by using Directory Service Control Center (DSCC).

By default, the logs are stored in this directory:


instance-path/logs

The following figure shows a screen capture of the error log for Directory Proxy Server on DSCC.

Figure 27–1 Error Log Window for Directory Proxy Server

Figure shows error logs for a proxy server instance

Configuring Directory Proxy Server Logs

Directory Proxy Server error logs and access logs can be configured by using the dpconf command or DSCC. For information about how to configure the logs by using DSCC, see the Directory Proxy Server online help. This section describes how to configure Directory Proxy Server logs by using the dpconf command.

You can retrieve a complete list of the configuration options along with the allowed values and default values by running these commands:


$ dpconf help-properties error-log
$ dpconf help-properties access-log

ProcedureTo Configure Directory Proxy Server Access and Error Logs

This procedure configures the Directory Proxy Server access log. To configure the Directory Proxy Server error log, perform the same procedure but replace access with error.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the properties of the access log.


    $ dpconf get-access-log-prop -h host -p port
    

    The default properties of an access log are as follows:


    default-log-level                :  info
    enable-log-rotation              :  true
    log-buffer-size                  :  1M
    log-file-name                    :  logs/access
    log-file-perm                    :  600
    log-level-client-connections     :  inherited
    log-level-client-disconnections  :  inherited
    log-level-client-operations      :  inherited
    log-level-connection-handlers    :  inherited
    log-level-data-sources           :  inherited
    log-level-data-sources-detailed  :  none
    log-min-size                     :  100M
    log-rotation-frequency           :  1h
    log-rotation-policy              :  size
    log-rotation-size                :  100M
    log-rotation-start-day           :  -
    log-rotation-start-time          :  -
    log-search-filters               :  false
    max-age                          :  unlimited
    max-log-files                    :  10
    max-size                         :  unlimited
    min-free-disk-space-size         :  1M
  2. Change one or more of the properties that are listed in Step 1.


    $ dpconf set-access-log-prop -h host -p port property:value \
     [property:value ...]

    For example, to set the default log level for all message categories to all, set the value of the default-log-level property to all.


    $ dpconf set-access-log-prop -h host1 -p 1389 default-log-level:all

    To disable all logs, irrespective of the log level for each message category, set the value of the default-log-level property to none.


    $ dpconf set-access-log-prop -h host1 -p 1389 default-log-level:none

    To reset a specific log level to the default log level, set that log level property to inherited. For example, to reset the log level for client connections, run the following command:


    $ dpconf set-access-log-prop -h host1 -p 1389 log-level-client-connections:inherited

    For information about properties that can be set by the set-access-log-prop subcommand, type:


    $ dpconf help-properties access-log

Configuring Directory Proxy Server Log Rotation

By default, log files are rotated when the log file size reaches 100 Mbytes. Ten log files are retained by default, after which the rotation procedure begins to overwrite the oldest log file. This section describes how to configure Directory Proxy Server logs for scheduled rotation, how to rotate logs manually, and how to disable log rotation. For example configurations, see Example Configurations for Log Rotation.

ProcedureTo Configure Periodic Rotation of Access and Error Logs

This procedure configures the Directory Proxy Server access log. To configure the Directory Proxy Server error log, perform the same procedure but replace access with error.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. (Optional) View the properties of the access log.


    $ dpconf get-access-log-prop -h host -p port
    
  2. (Optional) View valid values for the properties of the access log.


    $ dpconf help-properties access-log
  3. To rotate logs when they reach a certain size, set the following properties:


    $ dpconf set-access-log-prop -h host -p port \
     log-rotation-policy:size log-rotation-size:maximum file size
    

    Caution – Caution –

    In case of high activity levels, because of the asynchronous nature of Directory Proxy Server, the log file might not be rotated at the exact configured size but at a size close to the configured size. This means that the rotated file might end up being slightly smaller or slightly larger than the configured size.


    If the unit of the maximum file size is not specified, the default unit of bytes is used. When the log file reaches the defined size, the log is rotated. The file size must be at least 1 Mbyte and no more than 2 Gbytes.

    For an example of how to rotate logs by size, see Rotating the Log Based on Log Size.

  4. To rotate logs periodically, irrespective of the log size, set the following properties:


    $ dpconf set-access-log-prop -h host -p port \
     log-rotation-frequency:interval in months, weeks, hours, or minutes \
     log-rotation-policy:periodic \
     log-rotation-start-day:day in week (1-7) or day in the month (1-31) \
     log-rotation-start-time:time of day (hhmm)
    

    If the log is configured for rotation on the 31st of the month but the month has fewer than 31 days, the log is rotated on the first day of the following month.

    By default, the log-rotation-start-day and log-rotation-start-time properties have no default value. If you configure to rotate logs without setting these properties, the log will be rotated as per the specified frequency but the time of the day or day of the week might be changed.

    For examples of how to rotate logs periodically, see Rotating the Log Based on Time.

  5. To rotate logs periodically if the log file is big enough, set the log-rotation-frequency and log-min-size properties.


    $ dpconf set-access-log-prop -h host -p port \
     log-rotation-frequency:interval in months, weeks, hours, or minutes \
     log-rotation-policy:periodic log-min-size:minimum file size
     log-rotation-start-day:day in week (1-7) or day in the month (1-31) \
     log-rotation-start-time:time of day (hhmm)
    

    The log-min-size property represents the minimum size of the log. The rotation takes place at the scheduled time only if the log file is bigger than the specified size.

    If the log is configured for rotation on the 31st of the month but the month has fewer than 31 days, the log is rotated on the first day of the following month.

    By default, the log-rotation-start-day and log-rotation-start-time properties have no default value. If you configure to rotate logs without setting these properties, the log will be rotated as per the specified frequency but the time of the day or day of the week might be changed.

    For an example of how to rotate logs periodically if the file size is big enough, see Rotating the Log Based on Time and Log Size.

ProcedureTo Rotate Access and Error Logs Files Manually

This procedure rotates the Directory Proxy Server access log. To rotate the Directory Proxy Server error log, perform the same procedure but replace access with error.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Rotate the access log.


    $ dpconf rotate-log-now -h host -p port access

ProcedureTo Disable Access and Error Log Rotation

This procedure disables rotation of the Directory Proxy Server access log. To disable rotation of the Directory Proxy Server error log, perform the same procedure but replace access with error.

  1. Disable log file rotation.


    $ dpconf set-access-log-prop -h host -p port enable-log-rotation:false

Example Configurations for Log Rotation

Examples of how to configure log rotation by log size, time, or both follow.

Rotating the Log Based on Log Size

This section example shows how to configure a log rotation according to log size only. This configuration rotates the log when it reaches 10 Mbytes, irrespective of the time since the log was last rotated.


$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-policy:size \
  log-rotation-size:10M

Rotating the Log Based on Time

The examples in this section show how to configure log rotation according to the time since the last rotation, irrespective of log size.

If the log-rotation-start-day is set to 31 and the month has only 30 days, the log is rotated on the first day of the following month. If the log-rotation-start-day is set to 31 and the month has only 28 days (February), the log is rotated on the 3rd.

Rotating the Log Based on Time and Log Size

This example shows how to configure a log rotation for a specified interval if the file size is big enough.

This configuration rotates the log at 3:00, 11:00, and 19:00 every day, if the size of the log file exceeds 1 Mbyte. If the size of the log file does not exceed 1 Mbyte, the log file is not rotated.


$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:8h \
 log-rotation-policy:periodic log-min-size:1M log-rotation-start-time:0300

Deleting Directory Proxy Server Logs

Directory Proxy Server enables you to configure log deletion based on time, size, or free disk space (the default). For more information about these deletion policies, see Log File Deletion in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The following procedures configure log deletion for the access log. To configure log deletion for the error log, use the same commands, but replace access with error.

ProcedureTo Configure Access and Error Log Deletion Based on Time

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Specify the maximum age for log files.


    $ dpconf set-access-log-prop -h host -p port max-age:duration
    

    where duration includes a unit of days (d), weeks (w), or months (M). For example, to delete backup log files older than five days, use this command:


    $ dpconf set-access-log-prop -h host1 -p 1389 max-age:5d

ProcedureTo Configure Access and Error Log Deletion Based on File Size

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Specify the maximum size for log files.


    $ dpconf set-access-log-prop -h host -p port max-size:memory-size
    

    For example, to keep only the most recent log files with their aggregate size not more than 5 Mbytes, use this command:


    $ dpconf set-access-log-prop -h host1 -p 1389 max-size:5M

ProcedureTo Configure Access and Error Log Deletion Based on Free Disk Space

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Specify the minimum available disk space.


    $ dpconf set-access-log-prop -h host -p port min-free-disk-space-size:memory-size
    

    For example, to delete backup log files when the available disk space is less than 2 Mbytes, use this command:


    $ dpconf set-access-log-prop -h host1 -p 1389 min-free-disk-space-size:2M

Logging Alerts to the syslogd Daemon

This section describes how to configure the logging of alert messages to the syslogd daemon and how to configure the operating system to accept syslog alerts.

ProcedureTo Configure Directory Proxy Server to Log Alerts to the syslogd Daemon

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. (Optional) View the current values of the properties for the system log alerts.


    $ dpconf get-server-prop -h host -p port syslog-alerts-enabled \
     syslog-alerts-facility syslog-alerts-host

    The default properties for the system log alerts are as follows:


    syslog-alerts-enabled   :  false
    syslog-alerts-facility  :  USER
    syslog-alerts-host      :  localhost

    The syslog-alerts-host property defines the host name of the syslogd daemon to which the messages are sent. The syslog-alerts-facility property is read-only and causes messages to be sent to the user category in the system log.

  2. Enable alert messages to be logged to the syslogd daemon.


    $ dpconf set-server-prop -h host -p port syslog-alerts-enabled:true
  3. (Optional) Send alert messages to the syslogd daemon on a different host.


    $ dpconf set-server-prop -h host -p port syslog-alerts-host:hostname
    

Configuring the Operating System to Accept syslog Alerts

This section provides instructions on configuring the Solaris, Linux, and HP-UX operating systems to accept syslog alerts.

ProcedureTo Configure the Solaris OS to Accept syslog alerts

  1. Add the appropriate facility to the syslog configuration file.

    For example, to store all alerts using the USER facility, add the following line to /etc/syslog.conf:


    user.info       /var/adm/info

    Here /var/adm/info is an example local directory in which messages will be stored. Ensure that /var/adm/info exists before continuing.

  2. Restart the syslogd daemon.

    1. On Solaris 8 and 9, restart syslogd by typing this:


      $ /etc/init.d/syslog stop | start
    2. On Solaris 10, restart syslogd by typing this:


      $ svcadm restart system/system-log
  3. Verify that messages are logged in syslog.


    $ logger -p user.info "Test message"
    $ cat /var/adm/info
     Jun 19 17:18:38 host user: [ID 12345 user.info] Test message

ProcedureTo Configure Linux to Accept syslog Alerts

  1. Add the appropriate facility to the syslog configuration file.

    For example, to store all alerts using the USER facility, add the following line to /etc/syslog.conf:


    user.info       /var/adm/info

    Here /var/adm/info is an example local directory in which messages will be stored. Ensure that /var/adm/info exists before continuing.

  2. Configure the syslogd daemon to run with the -r option.

    This option allows syslogd to accept connections from the network. By default, the -r option is not set.

    To set the -r option, add the following line to /etc/sysconfig/syslog:


    SYSLOGD_OPTIONS="-m 0 -r"

    If /etc/sysconfig/syslog does not exist, add the same line to /etc/init.d/syslog.

  3. Restart the syslogd daemon.


    $ /etc/init.d/syslog stop | start
  4. Verify that messages are logged in syslog.


    $ logger -p user.info "Test message"
    $ cat /var/adm/info
     Jun 19 17:18:38 host user: [ID 12345 user.info] Test message

ProcedureTo Configure HP-UX to Accept syslog alerts

  1. Add the appropriate facility to the syslog configuration file.

    For example, to store all alerts using the USER facility, add the following line to /etc/syslog.conf:


    user.info       /var/adm/info

    Here /var/adm/info is an example local directory in which messages will be stored. Ensure that /var/adm/info exists before continuing.

  2. Restart the syslogd daemon.


    $ /sbin/init.d/syslogd stop | start
  3. Verify that messages are logged in syslog.


    $ logger -p user.info "Test message"
    $ cat /var/adm/info
     Jun 19 17:18:38 host user: [ID 12345 user.info] Test message

Tracking Client Requests Through Directory Proxy Server and Directory Server Access Logs

To track the path of a client request, you must understand how requests are logged in the Directory Proxy Server access log and in the Directory Server access log. To understand this section, first read Tracking Client Requests Through Directory Proxy Server and Directory Server Access Logs in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

ProcedureTo Track Operations From Directory Server Through Directory Proxy Server to the Client Application

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Locate the connection number for the operation that you want to track in the Directory Server access log.

    For example, the following line in the access log shows an operation, op=2 with connection number conn=12839.


    [20/Jul/2006:18:01:49 -0500] conn=12839 op=2 msgId=4 - SRCH base="dc=example,dc=com" 
     scope=2 filter="(objectClass=organizationalunit)" attrs=ALL
  2. Obtain the Directory Proxy Server connection information for that connection.

    To obtain this information, search the Directory Server access log to locate all operations with the corresponding connection number. For example, on UNIX systems, run the following grep command to locate all lines in the Directory Server access log that correspond to connection conn=12839:


    $ grep conn=12839 access

    The line showing the initial LDAP connection is what you are looking for and will be similar to this:


    [19/Jul/2006:16:32:51 -0500] conn=12839 op=-1 msgId=-1 - fd=27 slot=27 
     LDAP connection from 129.153.160.175:57153 to 129.153.160.175

    The previous line shows that there is an LDAP connection from 129.153.160.175:57153 to Directory Server. The port number (57153) is the information that is required to link the connection back to the Directory Proxy Server access log. The port number enables you to find the corresponding connection in the Directory Proxy Server log, and to locate the client information from this connection.

    If the log files have been rotated since the connection was first established, you need to search the archived log files as well as the current access log file.

  3. Locate the corresponding connection in the Directory Proxy Server access log.

    To obtain this information, search the Directory Proxy Server access log to locate all operations with the corresponding port number.

    You might find multiple entries in the log file with the same port number. To ensure that you locate the correct entry, include the timestamp from the Directory Server log entry in your search.

    For example, on UNIX systems, run the following grep command to locate the connection entry that corresponds to the timestamp and port number found in the Directory Server log:


    $ grep 19/Jul/2006:16:32 access | grep 57153

    Note that the seconds value is excluded from the timestamp to take into account slight differences in server times.

    The corresponding line in the Directory Proxy Server log will be similar to this:


    [19/Jul/2006:16:32:51 -0500] - SERVER_OP  - INFO  - Created BIND  LDAP connection 
     s_conn=ds-d1m1-9389:34 client=0.0.0.0:57153 
     server=idm160.central.example.com:9389 main

    This line shows that Directory Proxy Server created a BIND connection to s_conn=ds-d1m1-9389:34. Directory Proxy Server identifies itself as the client client=0.0.0.0 on TCP port 57153.

    The important information to extract from this line of the log is the server ID and port number (s_conn=ds-d1m1-9389:34).

  4. Locate all operations that correspond to the server ID and port number identified in the previous step.

    To obtain this information, search the Directory Proxy Server access log for all operations with the corresponding server ID and port number.

    For example, on UNIX systems, run the following grep command to locate the operation that corresponds to the server ID found in the previous step:


    $ grep s_conn=ds-d1m1-9389:34 access

    In this case, it is not useful to search for the timestamp because these operations might span several days. However, you must determine that the operations returned by the search are the correct ones. If there are multiple Create connection statements, ensure that you locate the one that corresponds to the original search statement. To do this, match the timestamp to the timestamp found in Step 1.

    The following extract of the Directory Proxy Server access log shows all operations returned for s_conn=ds-d1m1-9389:34.


    [19/Jul/2006:16:32:51 -0500] - SERVER_OP  - INFO - Created BIND LDAP connection
     s_conn=ds-d1m1-9389:34 client=0.0.0.0:57153 
     server=idm160.central.example.com:9389 main
    [20/Jul/2006:18:01:49 -0500] - SERVER_OP  - INFO  - conn=31 op=0 
    BIND dn="cn=directory manager" method="SIMPLE" s_msgid=3 s_conn=ds-d1m1-9389:34
    [20/Jul/2006:18:01:49 -0500] - SERVER_OP  - INFO  - conn=31 op=0 
    BIND RESPONSE err=0 msg="" s_conn=ds-d1m1-9389:34
    [20/Jul/2006:18:01:49 -0500] - SERVER_OP  - INFO  - conn=31 op=1 
    SEARCH base="dc=example,dc=com" scope=2 s_msgid=4 s_conn=ds-d1m1-9389:34
    [20/Jul/2006:18:01:49 -0500] - SERVER_OP  - INFO  - conn=31 op=1 
    SEARCH RESPONSE err=0 msg="" nentries=1 s_conn=ds-d1m1-9389:34

    With this information, you can see that the connection ID for this search operation on Directory Proxy Server is 31 (conn=31).

  5. Locate the client connection IP address that corresponds to the connection ID found in the previous step.

    To obtain this information, search the Directory Proxy Server access log for all operations with the correct connection ID and timestamp. The timestamp to use is the one in the original search statement in Step 1.

    For example, on UNIX systems, run the following grep command to locate the client connection IP address:


    $ grep "20/Jul/2006:18:01" access | grep conn=31

    The line you are interested in is similar to this:


    [20/Jul/2006:18:01:49 -0500] - CONNECT - INFO  - conn=31 client=129.150.64.156:2031
    server=0.0.0.0:11389 protocol=LDAP
  6. Determine who owns the IP address found in the previous step.

    With this information, you can establish precisely who was responsible for the operation performed on Directory Server.

Chapter 28 Directory Proxy Server Monitoring and Alerts

Monitoring detects failure of Directory Proxy Server and of data sources.

For a description of the monitoring framework for Directory Proxy Server, and for a detailed layout of the cn=monitor entry, see Monitoring Directory Proxy Server in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This chapter covers the following topics:

Retrieving Monitored Data About Directory Proxy Server

To retrieve monitored data about Directory Proxy Server, use the cn=monitor entry. This entry is managed by Directory Proxy Server in a local, in-memory database. You can retrieve attributes under cn=monitor by performing an LDAP search on the cn=monitor entry. You must bind as the Proxy Manager to search this entry.

For information about using the JVM to retrieve monitored data, see Retrieving Monitored Data About Directory Proxy Server by Using the JVM.

Retrieving Monitored Data About Data Sources

For a description of how Directory Proxy Server monitors the health of data sources, see Monitoring Data Sources in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. This section describes how to configure the monitoring of data sources.


Note –

In addition to LDAP data source, you can also monitor the health of JDBC data source using monitoring-inactivity-timeout, monitoring-interval, and monitoring-mode properties.

The proactive monitoring is implemented for LDAP data source as well as for JDBC data source. The implementation for both the data sources is not the same as the nature of the data sources is different.


ProcedureTo Monitor a Data Source by Listening for Errors

In this type of monitoring, Directory Proxy Server listens for errors on the traffic between Directory Proxy Server and the data sources. This type of monitoring is called reactive monitoring because Directory Proxy Server reacts if an error is detected, but does not actively test data sources.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the monitoring mode for the data source to reactive.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-mode:reactive
  2. Configure an alert to be sent when an error is detected or when a data source goes offline or online, as described in Configuring Administrative Alerts for Directory Proxy Server.

ProcedureTo Monitor a Data Source by Periodically Establishing Dedicated Connections

Directory Proxy Server creates a dedicated connection to a data source if there have been no requests to or responses from the data source for a specified interval.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the monitoring mode for the data source to proactive.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-mode:proactive
  2. Configure the monitoring search request that is performed by Directory Proxy Server.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource \
      monitoring-bind-timeout:timeout monitoring-entry-dn:dn \
      monitoring-search-filter:filter monitoring-entry-timeout:timeout
    

    The following properties are used in the search request:

    monitoring-bind-timeout

    The length of time that Directory Proxy Server waits to establish a connection to the data source. By default, the value of this property is 5 seconds.

    monitoring-entry-dn

    The DN of the target entry in the search request. By default, this property is the root DSE entry ("").

    monitoring-search-filter

    The search filter.

    monitoring-entry-timeout

    The length of time that Directory Proxy Server waits for the search response. By default, the value of this property is 5 seconds.

  3. (Optional) Configure the proactive monitoring to bind as a specific user.


    $ dpconf set-ldap-data-source-prop ldap-data-source \
    monitoring-bind-dn:uid=user-id monitoring-bind-pwd-file:password-file
    

    Replace the user-id with a valid dn such as uid=bjensen,dc=example,dc=com and password-file with a path to the file containing password.

    By default, the bind is performed as anonymous, that is, both the monitoring-bind-dn and monitoring-bind-pwd attributes are set to none.

  4. Set the polling interval.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource \
    down-monitoring-interval:interval
    

    If a connection is down, Directory Proxy Server polls the connection at this interval to detect its recovery. If the interval is not specified, the value of monitoring-interval is used.

  5. (Optional) Configure the availability monitor to specify the number of times it will poll the connection when it is first detected as down.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-retry-count:count
    
  6. Configure an alert to be sent when a data source is detected as offline or online, as described in Configuring Administrative Alerts for Directory Proxy Server.

ProcedureTo Monitor a Data Source by Testing Established Connections

In this type of monitoring, Directory Proxy Server performs a search on each connection to each data source at a regular interval. In this way, Directory Proxy Server detects closed connections and prevents connections from being dropped because of inactivity.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the monitoring mode for the data source to proactive.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-mode:proactive
  2. Set the time interval after which Directory Proxy Server sends a request to a data source to prevent connections from being dropped.


    $ dpconf set-ldap-data-source-prop -h host -p port datasource \
     monitoring-inactivity-timeout:time
    

    By default, the inactivity timeout is 120 seconds.

  3. (Optional) Configure the proactive monitoring to bind as a specific user.


    $ dpconf set-ldap-data-source-prop ldap-data-source
    monitoring-bind-dn:uid=user-id monitoring-bind-pwd-file:password-file
    

    Replace the user-id with a valid dn such as uid=bjensen,dc=example,dc=com and password-file with a path to the file containing password.

    By default, the bind is performed as anonymous, that is, both the monitoring-bind-dn and monitoring-bind-pwd attributes are set to none.

  4. Configure an alert to be sent when a data source is detected as offline or online, as described in Configuring Administrative Alerts for Directory Proxy Server.

Configuring Administrative Alerts for Directory Proxy Server

For information about how to configure administrative alerts, see the following procedures.

ProcedureTo Enable Administrative Alerts

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the enabled alerts.


    % dpconf get-server-prop -h host -p port enabled-admin-alerts
  2. Enable one or more administrative alerts.


    % dpconf set-server-prop -h host -p port enabled-admin-alerts:alert1 \
      [enabled-admin-alerts:alert2 ...]

    For example, to enable all available alerts, run this command:


    % dpconf set-server-prop -h host -p port \
     enabled-admin-alerts:error-configuration-reload-failure-with-impact \
     enabled-admin-alerts:error-resource-limit-exceeded \
     enabled-admin-alerts:error-server-shutdown-abrupt \ 
     enabled-admin-alerts:info-configuration-reload \
     enabled-admin-alerts:info-data-source-available \
     enabled-admin-alerts:info-server-shutdown-clean \
     enabled-admin-alerts:info-server-startup \
     enabled-admin-alerts:warning-configuration-reload-failure-no-impact \
     enabled-admin-alerts:warning-data-source-unavailable \
     enabled-admin-alerts:warning-data-sources-inconsistent \
     enabled-admin-alerts:warning-listener-unavailable \
     enabled-admin-alerts:warning-resource-limit-exceeded

    To disable all email alerts, run this command:


    % dpconf set-server-prop -h host -p port email-alerts-enabled:false

    To add an alert to an existing list of enabled alerts, run this command:


    % dpconf set-server-prop -h host -p port enabled-admin-alerts+:alert-name
    

    To remove an alert from an existing list of enabled alerts, run this command:


    % dpconf set-server-prop -h host -p port enabled-admin-alerts-:alert-name
    

    By default, all alerts are enabled. For example, once all the email alerts are enabled (email-alerts-enabled:true), run the following command to receive all the email alerts :


    % dpconf set-server-prop -h host -p port enabled-admin-alerts:all 
See Also

For more information, see enabled-admin-alerts(5dpconf).

ProcedureTo Configure Administrative Alerts to Be Sent to Syslog

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Select the alerts that will be sent to the syslog daemon, as described in To Enable Administrative Alerts.

  2. Enable alerts to be sent to the syslog daemon.


    $ dpconf set-server-prop -h host -p port syslog-alerts-enabled:true

    All alerts are sent to the syslog with the facility of USER.

  3. Set the host name of the syslog daemon to which alerts are to be sent.


    $ dpconf set-server-prop -h host -p port syslog_hostname:hostname
    

ProcedureTo Configure Administrative Alerts to Be Sent to Email

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Select the alerts that will be sent to the syslog, as described in To Enable Administrative Alerts.

  2. Configure the address and characteristics of the email.


    $ dpconf set-server-prop -h host -p port email-alerts-smtp-host:host-name \
      email-alerts-smtp-port:port-number \
      email-alerts-message-from-address:sender-email-address \
      email-alerts-message-to-address:receiver-email-address \
      [email-alerts-message-to-address:receiver-email-address ...] \
      email-alerts-message-subject:email-subject
    
  3. Enable alerts to be sent to email.


    $ dpconf set-server-prop -h host -p port email-alerts-enabled:true
  4. (Optional) Set a flag to include the alert code in the email


    $ dpconf set-server-prop -h host -p port \
     email-alerts-message-subject-includes-alert-code:true

ProcedureTo Configure Administrative Alerts to Run a Script

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Select the alerts that will be sent to the syslog, as described in To Enable Administrative Alerts.

  2. Enable alerts to run a script.


    $ dpconf set-server-prop -h host -p port scriptable-alerts-enabled:true
  3. Set the name of the script that will be run.


    $ dpconf set-server-prop -h host -p port scriptable-alerts-command:script-name
    

Retrieving Monitored Data About Directory Proxy Server by Using the JVM

Directory Proxy Server runs inside a Java Virtual Machine (JVM) and depends on the memory of the JVM machine. To ensure that Directory Proxy Server is running correctly, you must monitor the memory consumption of the JVM machine.

For information about how to tune parameters for the JVM machine, see Hardware Sizing For Directory Proxy Server in Oracle Fusion Middleware Deployment Planning Guide for Oracle Directory Server Enterprise Edition.

By default, the heap size of the JVM machine is 250 Mbytes. If Directory Proxy Server does not have enough physical memory, the heap size might be less than 250 Mbytes.

When Directory Proxy Server is running, you can monitor the heap size of the JVM machine to ensure that it is not running out of memory. To do this, use the standard tools delivered with the Java Development Kit (JDK). These tools are located in these directories: $JAVA_HOME/bin/jps and $JAVA_HOME/bin/jstat.

ProcedureTo View the Heap Size of the JVM

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. View the heap size of JVM.


    $ dpadm get-flags instance-path jvm-args
    jvm-args: -Xms250M  -Xmx250M

ProcedureTo Monitor the Heap Size of JVM When Directory Proxy Server is Running

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. View the PID of your instance of Directory Proxy Server.


    $ jps
  2. View the memory used by the JVM machine.


    $ jstat -gcutil PID
    
    • If the zero column is near to 100%, the JVM machine does not have enough memory.

    • FGC is the number of full garbage collection (GC) events. Garbage collection is expansive.

    • GCT (garbage collection time) is the amount of time spent by the GC.