| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
1. Starting and Stopping the Server
2. Configuring the Server Instance
Managing the Server Configuration With dsconfig
Overview of the dsconfig Command
dsconfig and Certificate Checking
Using dsconfig in Interactive Mode
Finding the Correct Subcommand
Getting Help for an Individual Subcommand
Displaying a Summary of a Component's Properties
Displaying Detailed Help on a Property
Configuring a Server Instance With dsconfig
To Display the Properties of a Component
To Modify the Properties of a Component
To Modify the Values of a Multi-Valued Property
Configuring the Connection Handlers With dsconfig
To Display All Connection Handlers
Configuring the LDAP Connection Handler
Configuring the LDIF Connection Handler
Configuring the JMX Connection Handler
Configuring Network Groups With dsconfig
Modifying Network Group Properties
Setting an Allowed or Denied Client List
Creating a Network Group Quality of Service Policy
Creating a Request Filtering Policy
Creating a Network Group Resource Limit
Creating an Affinity Quality of Service Policy
Creating a Referral Quality of Service Policy
To Modify a Network Group Quality of Service Policy
Configuring Workflows With dsconfig
Configuring Workflow Elements With dsconfig
Managing the Server Configuration With Oracle Directory Services Manager
Modify the General Server Configuration
Managing Administration Traffic to the Server
Accessing Administrative Suffixes
To Configure the Administration Connector
Commands That Can Schedule Tasks
Controlling Which Tasks Can Be Run
Scheduling and Configuring Tasks
To Configure Task Notification
To Configure Task Dependencies
Managing and Monitoring Scheduled Tasks
To Obtain Information About Scheduled Tasks
Deploying and Configuring the DSML Gateway
Deploying the DSML Gateway in Oracle WebLogic Server
Configuring WebLogic Server for the DSML Gateway
Deploying the DSML Gateway WAR File
Confirming the DSML Gateway Deployment
To Confirm the DSML Gateway Deployment with JXplorer
Confirming the DSML Gateway Deployment with the Directory Server Resource Kit
3. Configuring the Proxy Components
4. Configuring Security Between Clients and Servers
5. Configuring Security Between the Proxy and the Data Source
6. Managing Oracle Unified Directory With Oracle Directory Services Manager
10. Managing Users and Groups With dsconfig
11. Managing Password Policies
The topics in this section are intended for administrators or users who want to configure and manage a deployed Oracle Unified Directory instance. These topics provide an overview of the dsconfig command-line utility and its use in server configuration.
The dsconfig command can be used to configure both the Oracle Unified Directory directory server and the Oracle Unified Directory proxy. For a list of the supported sub-commands for the directory server or proxy instance, and for more specific information about this command, see dsconfig in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.
You can also use dsconfig to configure a number of proxy—specific components. For more information, see .
The dsconfig command provides a simple mechanism for accessing the server configuration. dsconfig presents the configuration as a set of components, each of which can be managed through one or more sub-commands.
dsconfig can also be used interactively. In interactive mode, dsconfig functions much like a wizard, walking you through the server configuration. For more information, see Using dsconfig in Interactive Mode.
Note -
dsconfig can only be used to configure a running server instance. Offline configuration is not supported by dsconfig.
Like the other administration commands, dsconfig uses the administration connector to access the server. For more information, see Managing Administration Traffic to the Server. All of the examples in this section assume that the administration connector is listening on the default port (4444) and that the command is accessing the server running on the local host. If this is not the case, the --port and --hostname options must be specified.
dsconfig accesses the server over a secured connection with certificate authentication. If you run dsconfig in interactive mode, you are prompted as to how you want to trust the certificate.
If you run dsconfig in non-interactive mode (that is, with the -n option), specification of the trust store parameters depends on whether you run the command locally or remotely.
Running dsconfig locally. (The command is launched on the server that you are administering.) If you do not specify the trust store parameters, the server uses the local instance trust store by default. Unless you specify otherwise, the local instance trust is instance-dir/OUD/config/admin-truststore.
Running dsconfig remotely. (The command is launched on a different server to the one you are administering.) You must specify the trust store parameters or the -X (--trustAll) option. The easiest way to specify the trust store parameters is to run the command once in interactive mode and to save the certificate that is presented by the server in your trust store.
$ dsconfig
>>>> >>>> Specify Oracle Unified Directory LDAP connection parameters
Directory server hostname or IP address [host1.example.com]:
Directory server administration port number [4444]:
How do you want to trust the server certificate?
1) Automatically trust
2) Use a truststore
3) Manually validate
Enter choice [3]: 3
Administrator user bind DN [cn=Directory Manager]:
Password for user 'cn=Directory Manager':
Server Certificate:
User DN : CN=host1.example.com, O=Administration Connector Self-Signed Certificate
Validity : From 'Wed Apr 29 11:13:21 MEST 2009'
To 'Fri Apr 29 11:13:21 MEST 2011'
Issuer : CN=host1.example.com, O=Administration Connector Self-Signed Certificate
Do you trust this server certificate?
1) No
2) Yes, for this session only
3) Yes, also add it to a truststore
4) View certificate details
Enter choice [2]: 3
Truststore path: /local/instances/certificates/jctruststore
Password for keystore '/local/instances/certificates/jctruststore':
...
When you have saved the certificate in the trust store, you can specify those trust store parameters in non-interactive mode.
$ dsconfig -h localhost -p 4444 list-connection-handlers -n \ --trustStorePath /local/instances/certificates/jctruststore \ --trustStorePasswordFile /local/instances/certificates/jctruststore.pin -w password Connection Handler : Type : enabled : listen-port : use-ssl -------------------------:------:---------:-------------:-------- JMX Connection Handler : jmx : false : 1689 : false LDAP Connection Handler : ldap : true : 1389 : false LDAPS Connection Handler : ldap : false : 636 : true LDIF Connection Handler : ldif : false : -
dsconfig provides an intuitive list of sub-commands to manage various elements of the configuration.
You can use these sub-commands to add, delete, list, view, and modify different components:
|
For example, the following five sub-commands are used to manage connection handlers:
|
Not all types of components can be created and deleted. For example, a directory server has only a single global configuration. For this reason, the global configuration is managed with only two sub-commands:
|
The configurable properties of all components can be queried and modified to change the behavior of the component. For example, an LDAP connection has properties that determine its IP listener address, its port, and its SSL configuration.
There are a number of component properties that are considered advanced properties. The advanced properties are not displayed by default, and have default values that apply in most cases. If you want to modify the values or the advanced properties, use --advanced before the subcommand. For example:
$ dsconfig --advanced get-extension-prop
Unless you specify all configuration parameters and the -n (--no-prompt) option, dsconfig runs in interactive mode. Interactive mode functions like a wizard, walking you through the server configuration. Interactive mode is a good approach to start using dsconfig.
When you run dsconfig in interactive mode, you can specify that you want the equivalent command (including all your selections) to be displayed, or to be written to a file. The following example shows how to use the --displayCommand option to display the equivalent non-interactive command when configuring the trust manager. Note that the equivalent command is displayed at the point at which the command has been applied and validated by the directory server.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password --displayCommand ... The TrustStore Manager Provider was modified successfully The equivalent non-interactive command-line is: dsconfig --hostname "localhost" --port "4444" --bindDN "cn=directory manager" --bindPassword ****** --trustAll set-trust-manager-provider-prop --provider-name "PKCS12" --set "enabled:true"
To copy the equivalent command to a file, use the --commandFilePath option, as shown in the following example:
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password --commandFilePath /tmp/filename
The dsconfig command has extensive online help that is accessed using the --help option.
Use the following command to display dsconfig's global usage:
$ dsconfig --help
The global usage information does not include the list of available sub-commands. To retrieve the list of sub-commands, use one of the --help-xxx options, where xxx determines the group of sub-commands to be displayed.
Note - Use the --help-all option used to display all of the available sub-commands.
For example, to find all the sub-commands relating to caching and back-end configuration, use the following command:
$ dsconfig --help-core-server
When you have determined which subcommand you want, you can get more detailed help on that subcommand by using the subcommand's --help option as follows:
$ dsconfig create-monitor-provider --help
The dsconfig command has built-in documentation for all of the components and their properties. This documentation can be accessed by using the list-properties subcommand. For example, a summary of the properties associated with a work queue can be displayed by using the following command:
$ dsconfig list-properties -c work-queue
Note - If the -c option is not specified, a summary of the properties for all components is displayed.
The summary table displays only brief usage information for each property. More detailed information are available using the verbose mode of the list-properties subcommand:
$ dsconfig list-properties -c work-queue --property num-worker-threads -v
Note - If the --property option is not specified, verbose help is provided for all the work-queue properties.
The dsconfig command is the recommended utility for accessing the server configuration. Accessing the configuration directly over LDAP, using the ldap* utilities is discouraged.
Each component has one or more properties that can be displayed by using the component's get-xxx-prop subcommand. Each component is associated with a single LDAP entry in the server configuration, and each property is associated with a single LDAP attribute.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n\ get-connection-handler-prop \ --handler-name "LDAP Connection Handler" Property : Value(s) ------------------------:------------------------------------------------------- allow-ldap-v2 : true allow-start-tls : false allowed-client : - denied-client : - enabled : true keep-stats : true key-manager-provider : - listen-address : 0.0.0.0 listen-port : 1389 ssl-cert-nickname : server-cert ssl-cipher-suite : - ssl-client-auth-policy : optional ssl-protocol : - trust-manager-provider : - use-ssl : false
Note - The dsconfig command displays the default values or behavior for properties that have not been customized.
You can view a list and summary of the instances of one component by using the component's list-xxxs subcommand. This can be particularly useful if you have more than one instance of the same component.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ list-connection-handlers
Depending on your installation, the output will be similar to the following.
Connection Handler : Type : enabled : listen-port : use-ssl -------------------------:------:---------:-------------:-------- JMX Connection Handler : jmx : false : 1689 : false LDAP Connection Handler : ldap : true : 1389 : false LDAPS Connection Handler : ldap : true : 1636 : true LDIF Connection Handler : ldif : true : - : -
New instances of a component can be created by using the component's create-xxx subcommand. Often there are several subtypes of the component. For example, there are currently three types of connection handler: LDAP, JMX, and LDIF. Because all of these are created by using the same subcommand, you must specify the type of component that you want to create. Do this by using the subcommand's -t or --type.
When you create a new component, you must specify the component's mandatory properties. The mandatory properties depend on the type of component that is being created. For example, an LDAP connection handler might have different mandatory properties to a JMX connection handler. If a mandatory property is left undefined, dsconfig enters interactive mode and prompts you for the undefined properties. If you include the -n (non-interactive) option, dsconfig fails to create the component and displays an error message indicating which properties need to be defined.
$ dsconfig create-connection-handler --help
Usage: dsconfig create-connection-handler {options}
Creates Connection Handlers
Global Options:
See "dsconfig --help"
SubCommand Options:
--handler-name {NAME}
The name of the new Connection Handler
--set {PROP:VALUE}
Assigns a value to a property where PROP is the name of the property and
VAL is the single value to be assigned. Specify the same property multiple
times in order to assign more than one value to it
-t, --type {TYPE}
The type of Connection Handler which should be created. The value for TYPE
can be one of: custom | jmx | ldap | ldif$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ create-connection-handler \ -t ldap --handler-name "My LDAP Connection Handler"
An error message similar to the following will be displayed.
The LDAP Connection Handler could not be created because the following mandatory properties were not defined: Property Syntax ---------------------------------- enabled false | true listen-port 1 <= INTEGER <= 65535
The properties of a component can be modified by using the component's set-xxx-prop subcommand. Multiple properties can be modified at the same time by using multiple occurrences of the --set option. The following example uses the set-connection-handler-prop subcommand to modify the properties of a connection handler.
Note - Many components have a Java class property that specifies the name of a Java class to be used as the implementation of the component. Do not modify this property, as doing so could prevent your server from operating correctly. These properties are treated as advanced properties and hidden from view unless you run dsconfig with the --advanced option.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ set-connection-handler-prop \ --handler-name="LDAP Connection Handler" --set allow-ldap-v2:true
You can set multiple values for a property by using the --set and --add options in successive dsconfig commands.
Note - You cannot use the --set and --add options simultaneously in the same command.
To set more than one value for a property that currently has no values, use the --set option to set the first value, and the --add option (in a separate command) for subsequent values. You cannot use the --add option if the property does not have an existing value, either a default value or a value that you have already set.
Note - Many components have a Java class property that specifies the name of a Java class to be used as the implementation of the component. Do not modify this property, as doing so could prevent your server from operating correctly. These properties are treated as advanced properties and hidden from view unless you run dsconfig with the --advanced option.
The following example sets multiple values for the allowed-client property.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ set-connection-handler-prop \ --handler-name "LDAP Connection Handler" --set allowed-client:myhost $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ set-connection-handler-prop \ --handler-name "LDAP Connection Handler" \ --add allowed-client:myhost.example --add allowed-client:myhost.example.com
Existing instances of a component can be removed using the component's delete-xxx.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \ delete-connection-handler \ --handler-name "My LDAP Connection Handler"
The -F or --batchFile option of the dsconfig command enables you to specify a number of operations that are completed in a single command by consolidating those operations in a file. This can significantly improve performance when several dsconfig commands are required.
To use dsconfig in batch mode, complete the following steps:
For example, the following file (named new-backend.txt) achieves three separate tasks:
creates a new back end
adds a set of indexes
sets the backend index entry limit
create-backend --set base-dn:cn=myexample,cn=com --set enabled:true \ --type local-db --backend-name myBackend create-local-db-index --backend-name myBackend --set index-type:equality \ --type generic --index-name cn create-local-db-index --backend-name myBackend --set index-type:equality \ --type generic --index-name telephoneNumber create-local-db-index --backend-name myBackend --set index-type:equality \ --set index-type:substring --type generic --index-name mail create-local-db-index --backend-name myBackend --set index-type:equality \ --type generic --index-name sn create-local-db-index --backend-name myBackend --set index-type:equality \ --type generic --index-name uniqueMember set-local-db-index-prop --backend-name myBackend --index-name uniqueMember \ --set index-entry-limit:5000 create-local-db-index --backend-name myBackend --set index-type:equality \ --type generic --index-name member create-local-db-index --backend-name myBackend --set index-type:equality \ --type generic --index-name uid set-backend-prop --backend-name myBackend --set index-entry-limit:6000
$ dsconfig -h localhost -p 4444 -D cn="directory manager" -w password \ -F new-backend.txt -X -n
Connection handlers are responsible for handling all interaction with client applications, including accepting connections, reading requests, and sending responses.
The following sections describe how to configure the connection handlers by using the dsconfig command. These sections provide examples on only a few aspects of the configuration. For details about all the configuration properties, use the following command: $ dsconfig list-properties -c connection-handler.
For information about configuring secure connections, see Configuring SSL and StartTLS for LDAP and JMX.
The following connection handlers are currently available for use in the directory server:
LDAP connection handler. This connection handler is used to interact with clients using LDAP. It provides full support for LDAPv3 and limited support for LDAPv2.
LDAPS connection handler. This connection handler is used to interact with clients using LDAP over SSL.
LDIF connection handler. This connection handler is used to process changes in the server using internal operations.
JMX connection handler. This connection handler allows interactions with clients using the Java Management Extensions (JMX) framework and the Remote Method Invocation (RMI) protocol.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ list-connection-handlers
Depending on your installation, the output will be similar to the following.
Connection Handler : Type : enabled : listen-port : use-ssl -------------------------:------:---------:-------------:-------- JMX Connection Handler : jmx : false : 1689 : false LDAP Connection Handler : ldap : true : 1389 : false LDAPS Connection Handler : ldap : true : 1636 : true LDIF Connection Handler : ldif : true : - : -
The following command displays the properties of the LDAP connection handler:
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ get-connection-handler-prop \ --handler-name "LDAP Connection Handler"
Depending on your installation, the output will be similar to the following.
Property : Value(s) -----------------------:------------ allow-ldap-v2 : true allow-start-tls : false allowed-client : - denied-client : - enabled : true keep-stats : true key-manager-provider : - listen-address : 0.0.0.0 listen-port : 1389 ssl-cert-nickname : server-cert ssl-cipher-suite : - ssl-client-auth-policy : optional ssl-protocol : - trust-manager-provider : - use-ssl : false
You can specify a list of clients that may or may not access the directory server over LDAP. To do this, set the allowed-client or denied-client property of the LDAP connection handler. These properties take an IP address or subnetwork with subnetwork mask as values.
By default, these properties are not set and all clients are allowed access. Changes to these properties take effect immediately but do not interfere with connections that are already established.
This example permits access only to clients in the subnet mask 255.255.255.10.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ set-connection-handler-prop \ --handler-name "LDAP Connection Handler" --set allowed-client:255.255.255.10
The LDIF connection handler is enabled by default. This connection handler can be used to process changes in the server using internal operations. The changes to be processed are read from an LDIF file.
The following command displays the default properties of the LDIF connection handler:
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ get-connection-handler-prop \ --handler-name "LDIF Connection Handler"
Depending on your installation, the output will be similar to the following.
Property : Value(s) ---------------:------------------------- allowed-client : - denied-client : - enabled : true ldif-directory : config/auto-process-ldif poll-interval : 5 s
The ldif-directory property specifies the directory in which the LDIF files are located. The connection handler checks if there are any files in this directory, at an interval specified by the poll-interval property. The connection handler then processes the changes contained in those files as internal operations and writes the result to an output file with comments indicating the result of the processing.
This example demonstrates how to enable the JMX alert handler through the LDIF connection handler.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ get-alert-handler-prop \ --handler-name "JMX Alert Handler"
Depending on your installation, the output will be similar to the following.
Property : Value(s) --------------------:--------- disabled-alert-type : - enabled : false enabled-alert-type : -
$ cd ../config/ $ mkdir auto-process-ldif $ cd auto-process-ldif/ $ cat > disable-jmx.ldif << EOM > dn: cn=JMX Alert Handler,cn=Alert Handlers,cn=config > changetype: modify > replace: ds-cfg-enabled > ds-cfg-enabled: true > EOM $
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ get-alert-handler-prop \ --handler-name "JMX Alert Handler" -n Property : Value(s) --------------------:--------- disabled-alert-type : - enabled : true enabled-alert-type : -
The following command displays the default properties of the JMX connection handler:
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password \ get-connection-handler-prop \ --handler-name "JMX Connection Handler" -n
Depending on your installation, the output will be similar to the following.
Property : Value(s) ---------------------:------------ allowed-client : - denied-client : - enabled : false key-manager-provider : - listen-port : 1689 ssl-cert-nickname : server-cert use-ssl : false
This example changes the port on which the server listens for JMX connections to 1789.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ set-connection-handler-prop \ --handler-name "JMX Connection Handler" --set listen-port:1789
Network groups are the single entry point of all client requests to the Oracle Unified Directory. The network group handles all client interactions, dispatching them and delegating the treatment of the request to workflows. A client connection is associated to the network group with the highest priority and for which all the criteria are met. During installation, a default network group with a priority of 1 is created. To set request filtering policies or resource limits, you must create a network group quality of service policy.
Each network group is associated with one or more workflows. The workflows provide access to a naming context (or suffix). By associating a workflow with a network group, you indicate to the network group which naming contexts are available. Typically to create a network group, you would already have a workflow created. For information about workflows, see Configuring Workflows With dsconfig.
The following examples describe how to configure network groups using the dsconfig command.
All the commands in the following procedures specify the proxy hostname (-h), the proxy admin port (-p), the bind DN (-D), and the bind password (-w). The following examples use the -X option to trust all certificates.
You can create many network groups, in which case the requests will be handled by the network group with the highest priority, for which the criteria are met. Therefore, when you create a network group, you must consider all the network groups you plan to create, and the priority of each. The priority can be 0 or above, where 0 is the highest priority.
Note - It is possible to create two network groups with the same priority. However if two or more network groups have the same priority and match the client request, the network group that will handle the request is random, among those matching the client request. Therefore, it is recommended to use a different priority for each network group created.
The default properties of a new network group are as follows.
Property Value(s)
----------------------------------------------------------------------
allowed-auth-method All authorization methods are allowed.
allowed-bind-dn All bind DNs are allowed.
allowed-bind-id All bind IDs are allowed.
allowed-client All clients with addresses that do not match
an address on the deny list are allowed. If
there is no deny list, then all clients are
allowed.
allowed-protocol All supported protocols are allowed.
certificate-mapper The global certificate mapper will be used.
denied-client If an allow list is specified, then only
clients with addresses on the allow list are
allowed. Otherwise, all clients are allowed.
enabled true
generic-identity-mapper The global generic identity mapper will be
used.
gssapi-identity-mapper The global GSSAPI identity mapper will be
used.
is-security-mandatory false
priority 1
workflow userroot0
Once you have created a network group, you can associate a network group quality of service policy to it. For information on creating a quality of service policy, see Creating a Network Group Quality of Service Policy.
For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-network-group \ --group-name network-group1 \ --set enabled:true \ --set workflow:workflow1 \ --set priority:1
The network group properties filter the traffic and indicate how a request is directed. To modify the network group properties, use the dsconfig set-network-group-prop command. The network group properties include the properties enabled, associated workflow name, priority, and criteria.
To modify any of the network group properties, use the dsconfig set-network-group-prop command. For example, to modify the priority of the network group:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-network-group-prop \ --group-name network-group1 \ --set priority:3
Using the network group properties, you can set the following criteria:
the authentication method allowed between the client and the network group (allowed-auth-method).
the bind DN allowed to connect to the network group (allowed-bind-dn).
the list of clients authorized to access the Oracle Unified Directory (allowed-client), expressed by the IP address or name of the client . If no allowed client list is provided, then all clients are allowed, assuming they are not listed on the denied client list.
the protocol allowed to connect to the Oracle Unified Directory (allowed-protocol). If none is specified, all protocols are allowed.
the name of the certificate mapper that should be used to match client certificates to user entries. (certificate-mapper). If none is specified, the global certificate mapper is used.
the list of clients not authorized to access the Oracle Unified Directory (denied-client). If no denied client list is provided, all clients are authorized, assuming there is no limitation set by an allowed client list.
the set of identity mappers that will be used by network group for mapping an identity while performing SIMPLE, non-GSSAPI SASL bind requests and proxy authorization controls (generic-identity-mapper).
the set of identity mappers that will be used by network for mapping an identity while performing GSSAPI/SASL bind requests (gssapi-identity-mapper).
whether security between the client and the Oracle Unified Directory is always required (is-security-mandatory).
the priority for this network group (priority). A client connection is first compared against the network group with the highest priority. If the client connection does not match its connection criteria, the client connection is compared against the network group with next highest priority, and so on. If no network group is selected, the client connection is rejected.
For example, you can ensure that no connections are accepted from the IP address 208.77.188.166, by network-group1 as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-network-group-prop \ --group-name network-group1 \ --set denied-client:208.77.188.166
For allowed-client and denied-client lists, you must be aware of the name service configuration on the server. For example, if the name service knows the host as myclienthost.example.com, you must specify myclienthost.example.com as the value, and not just myclienthost. Similarly, if the name service knows the host as myclienthost, you must specify the value as myclienthost. If you do not know how the name service is configured, you should specify both the fully qualified domain name (for example myclienthost.sun.com) and the short name (myclienthost) of the machine. Specifying multiple values will ensure that the name is resolved correctly. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-network-group-prop \ --group-name network-group1 \ --add denied-client:myhost \ --add denied-client:myhost.example \ --add denied-client:myhost.example.com
To avoid any issues, use the IP address for clarity.
Moreover, if you use localhost or the name of the local machine when connecting to Oracle Unified Directory proxy, the IP addresses of the client will be different. If you want to forbid connections from the localhost to Oracle Unified Directory proxy, you should specify both localhost and the name of the local machine in the list of denied-clients.
Creating a quality of service policy is optional and associated to a network group. There are four types of quality of service policy available:
request filtering policy
resource limits
affinity
referral
To create a network group quality of service policy, use the dsconfig create-network-group-qos-policy command. You must specify the name of the network group to which the quality of service policy applies, as well as the type of quality of service policy.
When you create a network group request filtering policy, you can set the following properties:
allowed-attributes: list of attributes that can be specified in the filter of a search request
allowed-operations: type of operation accepted by the network group. For example, you can set a network group to accept only read requests.
allowed-search-scopes: scope of a search accepted, for example one-level only.
allowed-subtrees: list of specific sub-trees that can be specified as base DN in a search request
prohibited-attributes: list of attributes which, if specified in the filter of a search request, will be rejected
prohibited-subtrees: list of specific sub-tress that will not manage a request
To create a network group quality of service request filtering policy, use the dsconfig create-network-group-qos-policy command. You must state the network group to which the quality of service policy applies.
For example, if you want to ensure that users can only search and not modify data, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-network-group-qos-policy \ --group-name network-group1 \ --type request-filtering \ --set allowed-operations:search
When you create a network group resource limit, you can set the following properties:
maximum number of simultaneous operations per connection (max-concurrent-ops-per-connection). If you want your Oracle Unified Directory proxy to run in synchronous mode, set the maximum to 1.
maximum number of operations per connection (max-ops-per-connection)
maximum number of connections (max-connections). If you do not set a maximum number of connections, the server limit is used.
maximum number of connections from the same IP (max-connections-from-same-ip). Set this parameter if you want to avoid Denial of Service attacks. However, this parameter should not be set if you know that the requests typically come from the same client.
maximum number of operations (max-ops-per-interval). For example, a setting of 1,000 will limit the number of operations to 1,000 per the interval set using max-ops-interval.
maximum interval during which the number of operations is counted (max-ops-interval). For example, an interval set to one second results in operations being counted for one second. The limit (max-ops-per-interval) is checked and enforced during each interval.
minimum search string length (min-substring-length). The shorter the search string, the more results that need to be found and displayed. Therefore, it may be useful to set a minimum search string length in the substring search filter to limit the resources used.
size limit (size-limit) limits the number of results of a query. It is recommended to use the default value.
time limit (time-limit) of a connection. It is recommended to use the default value.
To create a network group quality of service resource limit policy, use the dsconfig create-network-group-qos-policy command. You must state the network group to which the quality of service policy applies.
For example, if you want to ensure that a user enters a search string of at least 5 characters, to limit the number of return values, use the following command:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-network-group-qos-policy \ --group-name network-group1 \ --type resource-limits \ --set min-substring-length:5
In a load balancing deployment, you can use affinity to override the regular routing process.
When you create a network group quality of service, you can set the following affinity properties:
affinity-policy indicates that a certain routing policy is used, regardless of the regular routing process.
The affinity policy can take one of the following values:
all-requests-after-first-request
all-requests-after-first-write-request
all-write-requests-after-first-write-request
first-read-request-after-write-request
Specific operations will set affinity, depending on the affinity policy. For the first policy in the previous list (all-requests-after-first-request) all operations will set affinity. For the remaining policies (all-requests-after-first-write-request, all-write-requests-after-first-write-request, and first-read-request-after-write-request) only an ADD, DELETE, MOD or MODDN operation will set affinity.
affinity-timeout defines the duration during which the affinity applies.
Even when affinity has been set by a previous operation, the load balancing algorithm is only bypassed in specific situations, depending on the affinity policy and the current operation type. If the affinity policy is all-requests-after-first-request or all-requests-after-first-write-request, the affinity route will be used for every operation type, unless the affinity timeout has expired. If the affinity policy is all-write-requests-after-first-write, the affinity route will be used for any ADD, DELETE, MOD or MODDN operation, unless the timeout has expired. The affinity route will not be used for other operations. If the affinity policy is first-read-request-after-write-request, the affinity route will be used for all operations except ADD, DELETE, MOD or MODDN operations, unless the timeout has expired.
The following example sets an affinity policy that can be set by any operation and used for all operations, for a maximum of sixty seconds.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-network-group-qos-policy \ --group-name network-group1 \ --type affinity \ --set affinity-timeout:60s \ --set affinity-policy:all-requests-after-first-request
Note - The affinity feature can be used with all load balancing algorithms except for the failover algorithm. With the failover algorithm, only one route is active at a time. The active route changes when the remote server goes down, so all connections to the remote server are broken. Affinity can therefore not apply in a failover scenario.
You can configure the behavior of the Oracle Unified Directory proxy when a referral is received from the remote LDAP server.
Note - Referrals must be defined on the Oracle Unified Directoryserver or the Oracle Directory Server Enterprise Edition.
When you create a network group quality of service, you can set the following referral properties:
the maximum number of hops supported (referral-hop-limit) when the referral policy is set to follow. The default is set to 5.
define the type of referral policy (referral-policy), such as discard, forward, or follow. This defines how a referral will be treated by the network group.
For example, the referral-policy is set by default to forward. You can change it to discard or to follow, as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-network-group-qos-policy \ --group-name network-group1 \ --type referral \ --set referral-policy:follow
You must specify the network group name (network-group1) and the policy type.
Use the --set argument to modify the quality of service policy. In the example below, one of the network group resource limit policies (minimum search string limit) is set.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-network-group-qos-policy-prop \ --group-name network-group1 \ --policy-type resource-limits \ --set min-substring-length:5
A workflow is the link between the network group and the naming context (suffixes). It defines the naming context that will be accessible for a given network group, when handling a request to a load balancing or distribution configuration. To create a workflow, you must already have a load balancing or distribution workflow element created. For information on workflow elements, see Configuring Workflow Elements With dsconfig.
Oracle Unified Directory proxy automatically creates a number of private workflows. These workflows should not be modified or deleted. Privacy settings of the remote LDAP servers must be considered when configuring workflows. Privacy settings are as follows:
Privacy defined by the property ds-cfg-is-private-backend. This flag is set by default to private, but can be changed.
Always public, and contains user data.
Always private
Always private
Always private
Always private
Always private
Always private
The following examples describe how to configure workflows using the dsconfig command.
All the commands in the following procedures specify the proxy hostname (-h), the proxy admin port (-p), the bind DN (-D), and the bind password (-w). These following examples use the -X option to trust all certificates.
To display all the workflows that are part of your Oracle Unified Directory proxy, use the dsconfig list-workflows command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ list-workflows
Workflow : Type : enabled ---------------:---------:-------- adminRoot : generic : true ads-truststore : generic : true backup : generic : true config : generic : true monitor : generic : true schema : generic : true tasks : generic : true workflow1 : generic : true
In the example above, workflow1 is the workflow created during a basic installation using vdp-setup.
Note - The adminRoot, ads-truststore, backup, config, monitor, schema, and tasks workflows are default workflows created by the Oracle Unified Directory proxy during your installation. These workflows must not be deleted or modified, otherwise your Oracle Unified Directory proxy will no longer work.
To view the properties of a specific workflow, use the dsconfig get-workflow-prop command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ get-workflow-prop \ --workflow-name workflow1
Property : Value(s) -----------------:------------------- base-dn : "ou=people,o=test" enabled : true workflow-element : load-bal-we1 workflow-id : workflow1
The workflow-id is the workflow name. The base-dn indicates the base DN used for the workflow, and therefore for the deployment using that workflow. The workflow-element property indicates the workflow element (either a load balancing workflow element or a distribution workflow element) which will process the requests.
Note - The base-dn and workflow-id properties cannot be modified.
Each workflow is associated to a workflow element. When creating a workflow, you must specify the associated workflow element name (--set workflow-element). In other words, you must already have created the load balancing or distribution workflow element. See Configuring Workflow Elements With dsconfig.
To create a workflow, use the dsconfig create-workflow command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-workflow \ --workflow-name workflow1 \ --set base-dn:ou=people,o=test \ --set enabled:true \ --set workflow-element:load-bal-we1
Workflow elements are part of a routing structure, and are linked to workflows. There are different types of workflow elements within Oracle Unified Directory proxy:
LDAP proxy workflow elements, which connect to the remote LDAP servers
load balancing workflow elements (load balancing connectors)
distribution workflow elements (distribution connectors)
DN renaming workflow elements, which transform the entry DN and DN type attributes
In your Oracle Unified Directory proxy deployment, you must have LDAP proxy workflow elements and either a load balancing or distribution workflow element.
The following examples describe how to configure workflow elements using the dsconfig command.
All the commands in the following procedures specify the Oracle Unified Directory proxy hostname (-h), the Oracle Unified Directory proxy admin port (-p), the bind DN (-D), and the bind password (-w). The following examples use the -X option to trust all certificates.
To display all the workflow elements that are part of your Oracle Unified Directory proxy, use the dsconfig list-workflow-elements command. For example:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ list-workflow-elements
Workflow Element : Type : enabled -----------------:----------------:-------- adminRoot : local-backend : true ads-truststore : local-backend : true backup : local-backend : true config : local-backend : true load-bal-we1 : load-balancing : true monitor : local-backend : true proxy-we1 : proxy-ldap : true proxy-we2 : proxy-ldap : true schema : local-backend : true tasks : local-backend : true
In the example above, the workflow elements listed are the ones created by default when deploying a simple load balancing configuration using vdp-setup. The proxy-we1 and proxy-we2 are the LDAP proxy workflow elements. A load balancing workflow element (load-bal-we1) is also created. All other workflow elements are default workflow elements and should not be modified or deleted.
To create workflow elements in interactive mode, use the dsconfig create-workflow-element command. If you have configured your Oracle Unified Directory proxy using vdp-setup, then the basic workflow elements required will already be created.
You can create the following types of workflow elements:
proxy LDAP. For more information, see Creating a Proxy LDAP Workflow Element
load balancing. For more information, see Creating a Load Balancing Workflow Element
distribution. For more information, see Creating a Distribution Workflow Element
DN renaming. For more information, see To Configure DN Renaming
To configure DN renaming, you must create a DN renaming workflow element.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ create-workflow-element \ --type dn-renaming \ --element-name RenameorgDN \ --set client-base-dn:ou=myorg,dc=example,dc=com \ --set next-workflow-element:load-bal-we1 \ --set source-base-dn:ou=people,dc=example,dc=com \ --set enabled:true
--set client-base-dn indicates the client base DN, which is the workflow entry point
--set source-base-dn indicates the base DN which the entries should have after transformation, which is the workflow exit point.
--set next-workflow-element indicates the workflow element that will follow the DN renaming workflow element in the proxy architecture. This can be any type of workflow element.
Once you have created a workflow element, you can modify some of the properties using the dsconfig set-workflow-element-prop command.
Once you have configured DN renaming, you can modify the following DN renaming properties:
client base DN
source base DN
next workflow element
black list attributes
white list attributes
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-workflow-element-prop \ --element-name RenameorgDN \ --set source-base-dn:ou=admin,dc=example,dc=com
In the example above, only the source-base-dn is modified. There is no need to specify the old source base DN. Only the new one is required.
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ set-workflow-element-prop \ --element-name RenameorgDN \ --set black-list-attributes:manager
The attribute must have a DN type.
Plug-ins are responsible for providing custom logic in the course of processing an operation or at other well-defined points within the directory server. The dsconfig command is used to manage the configuration of the directory server. For information about using dsconfig, see Managing the Server Configuration With dsconfig.
The dsconfig plugin-type property can be used to configure a plug-in to use one or more of the numerous plug-in types supported by the server. Usually a plug-in was written to perform a specific processing action for each of its default plug-in types. For this reason, a new default plug-in type cannot be added to a plug-in's configuration without changing the plug-in's underlying source code to add support for that plug-in type. A well-written plug-in checks the plug-in types passed to it from the configuration manager when it is enabled, and fails to start if it sees a plug-in type that it does not support.
Therefore, you can only remove one or more of the default plug-in type values from a plug-in's configuration. Care should be taken when doing this, because usually a plug-in has been engineered to support its default plug-in types for a reason. Removing one or more plug-in types might endanger the safe operation of the directory server.
Most of the plug-ins support more than one type, and multiple plug-ins are sometimes defined with the same plug-in type. The order in which these plug-ins are invoked during processing is undefined. If a specific order is required (for example, if the processing performed by one plug-in depends on the result of another), you can specify the order in which the plug-ins are invoked. For more information, see To Configure Plug-In Invocation Order.
The following sections show various examples of managing plug-in configuration using dsconfig. dsconfig uses the administration connector to access the server. All of the examples in this section assume that the administration connector is listening on the default port (4444) and that the command is accessing the server running on the local host. If this is not the case, the --port and --hostname options must be specified.
dsconfig always accesses the server over a secured connection with certificate authentication. If you run dsconfig in interactive mode, you are prompted as to how you want to trust the certificate. If you run dsconfig in non-interactive mode (that is, with the -n option) you must specify the -X or --trustAll option, otherwise the command will fail.
This example shows a directory server configured with the current supported plug-ins. For a description of these plug-ins and their purpose, see “The Plug-In Configuration” in .
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ list-plugins
Depending on your installation, the output will be similar to the following.
Plugin : Type : enabled --------------------------------:---------------------------------:-------- 7-Bit Clean : seven-bit-clean : false Entry UUID : entry-uuid : true LastMod : last-mod : true LDAP Attribute Description List : ldap-attribute-description-list : true Password Policy Import : password-policy-import : true Profiler : profiler : true Referential Integrity : referential-integrity : false UID Unique Attribute : unique-attribute : false
The output of the command shows (from left to right):
Plug-in. The name of the plug-in, usually descriptive of what it does.
Type. The type of plug-in. It is possible to have more then one plug-in of a specific type.
Enabled. Plug-ins can either be enabled of disabled. Disabled plug-ins remain in the server configuration but do not perform any processing.
The easiest way to configure plug-ins is to use dsconfig in interactive mode. Interactive mode walks you through the plug-in configuration, and is therefore not documented here.
This example creates a new Password Policy Import Plug-in by using dsconfig in non-interactive mode.
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \ create-plugin \ --type password-policy-import --plugin-name "My Password Policy Import Plugin" \ --set enabled:true
You can enable or disable a plug-in by setting the enabled property to true or false. This example disables the Password Policy Import plug-in created in the previous example.
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ set-plugin-prop \ --plugin-name "My Password Policy Import Plugin" --set enabled:false
To display the properties of a plug-in, use the get-plugin-prop subcommand. To change the properties of a plug-in, use the set-plugin-prop subcommand. This example displays the properties of the plug-in created in the previous example, then enables the plug-in and sets the default authentication password storage scheme to Salted SHA-512.
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ get-plugin-prop \ --plugin-name "My Password Policy Import Plugin"
Depending on your installation, the output will be similar to the following.
Property : Value(s) -------------------------------------:--------- default-auth-password-storage-scheme : - default-user-password-storage-scheme : - enabled : false
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ set-plugin-prop \ --plugin-name "My Password Policy Import Plugin" --set enabled:true\ --set default-auth-password-storage-scheme:"Salted SHA-512"
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ get-plugin-prop \ --plugin-name "My Password Policy Import Plugin" Property : Value(s) -------------------------------------:--------------- default-auth-password-storage-scheme : Salted SHA-512 default-user-password-storage-scheme : - enabled : true
By default, the order in which plug-ins are invoked is undefined. You can specify that plug-ins be invoked in a specific order by using the set-plugin-root-prop --set plugin-type:value subcommand. The value in this case is the plug-in order, expressed as a comma-delimited list of plug-in names. The plug-in order string should also include a single asterisk element, which is a wildcard that will match any plug-in that is not explicitly named.
This example specifies that the Entry UUID plug-in should be invoked before any other pre-operation add plug-ins.
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ get-plugin-root-prop Property : Value(s) --------------------------------------------:--------- plugin-order-intermediate-response : - plugin-order-ldif-export : - plugin-order-ldif-import : - plugin-order-post-connect : - ...
$ dsconfig -h localhost -p 4444 -D cn="Directory Manager" -w password -n \ set-plugin-root-prop \ --set plugin-order-pre-operation-add:"Entry UUID,*"
Note - Plug-in order values are not validated. Values that do not match defined plug-ins are ignored.
|