Configuring a Server Instance

The dsconfig command is the recommended utility for accessing the server configuration. Accessing the configuration directly over LDAP, using the ldap* utilities is discouraged.

To Display the Properties of a Component

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.

• To display the properties of the default LDAP connection handler, run the following command:

  $ 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.

  ---

To List Components

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.

• To list all of the available connection handlers, run this command:

  $ 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 : - : -

To Create a Component

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.

1. Display the types of connection handler that can be created by accessing the help for the connection handler component.

   $ 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

2. Create a new LDAP connection handler, specifying values for the mandatory enabled and the listen-port properties.

   $ 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

To Modify the Properties of a Component

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.

• To configure the LDAP connection handler to accept LDAPv2 connections, run this command:

  $ 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

To Modify the Values of a Multi-Valued Property

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.

• To restrict connections through the LDAP connection handler to specific clients, run these commands:

  $ 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

To Delete a Component

Existing instances of a component can be removed using the component's delete-xxx.

• Delete the LDAP connection handler that was created in the previous example:

  $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
    delete-connection-handler \
    --handler-name "My LDAP Connection Handler"

To Use dsconfig in Batch Mode

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:

1. Create a file that contains all of the required commands.

   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

2. Run the dsconfig command with that file as a parameter.

   $ dsconfig -h localhost -p 4444 -D cn="directory manager" -w password \
     -F new-backend.txt -X -n