Sun Java System Directory Server Enterprise Edition 6.0 Installation Guide

Server Instance Creation

After installing server software as described in Software Installation, create server instances according to the procedures in this section.

ProcedureTo Create a Directory Server Instance With DSCC

Non-root users can create server instances.

Before You Begin

Install the component software as described in Software Installation.

  1. Access Directory Service Control Center through Java Web Console.

    The default URL for Java Web Console on the local system is https://localhost:6789.

  2. Follow the instructions in the Directory Service Control Center New Server wizard to create the server instance.

    Web-based wizard for creating a Directory Server instance

ProcedureTo Create a Directory Server Instance From the Command Line

In this procedure, you create a server instance on the local host using the dsadm command. You then create a suffix that you populate with data using the dsconf command.

Non-root users can create server instances.

A Directory Server instance contains the configuration and data necessary to respond to directory client applications. When you start or stop an instance, you start or stop the server process. The server process is what serves directory client requests corresponding to the data managed by that instance.

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

The dsconf command is an LDAP client. The command enables you to configure nearly all server settings on a running Directory Server instance from the command line. You can configure settings whether the server is on the local host or another host that is accessible across the network. The dsconf command has subcommands for each key configuration task. For a complete description, see dsconf(1M).

Before You Begin

Install the component software, then set your PATH as described in Software Installation.

  1. Create a new Directory Server instance.


    $ dsadm create -p port -P SSL-port instance-path
    

    For example, the following command creates an instance under the existing directory, /local/, in a new directory, /local/ds/. The new instance has default ports 389 for LDAP, 636 for LDAPS for root, and 1389 for LDAP, 1636 for LDAPS for non-root users.


    $ dsadm create /local/ds
    Choose the Directory Manager password:
    Confirm the Directory Manager password:
    Use 'dsadm start /local/ds' to start the instance

    Notice that the instance is created in a directory on the local file system, not a network file system.

  2. Start the instance.


    $ dsadm start instance-path
    

    For example, the following command starts the instance located under /local/ds/.


    $ dsadm start /local/ds
    Server started: pid=2845
  3. Verify that you can read the root DSE of the new instance.


    $ ldapsearch -h localhost -p 1389 -b "" -s base "(objectclass=*)"
    version: 1
    dn:
    objectClass: top
    …
    supportedLDAPVersion: 3
    vendorName: Sun Microsystems, Inc.
    vendorVersion: Sun-Java(tm)-System-Directory/6.0
    …

    Note –

    At this point in the procedure, you have a working server instance. You must further configure the server instance, however. Furthermore, the instance is not yet registered with Directory Service Control Center.


  4. (Optional) Use the new password policy mode, unless the instance belongs to a topology with version 5 instances.

    Your server instance might be standalone. Alternatively, your instance might belong to a replication topology that has already been migrated to the new password policy mode. In either case, perform this step.


    $ dsconf pwd-compat -h localhost -p 1389 to-DS6-migration-mode
    Certificate "CN=hostname, CN=1636, CN=Directory Server, O=Sun Microsystems"
     presented by the server is not trusted.
    Type "Y" to accept, "y" to accept just once, "n" to refuse, "d" for more details: Y
    Enter "cn=Directory Manager" password:
    ## Beginning password policy compatibility changes.
    ## Password policy compatibility changes finished.
    
    Task completed (slapd exit code: 0).
    $ dsconf pwd-compat -p 1389 to-DS6-mode
    Enter "cn=Directory Manager" password:
    ## Beginning password policy compatibility changes.
    ## Password policy compatibility changes finished.
    
    Task completed (slapd exit code: 0).
  5. (Optional) Prepare an example suffix.

    1. Create an empty suffix.

      For example, the following command creates a suffix with root dc=example,dc=com.


      $ dsconf create-suffix -h localhost -p 1389 dc=example,dc=com
      Enter "cn=Directory Manager" password:
      $ 
    2. Populate the suffix with LDIF data.

      If you plan to populate the suffix with data that is replicated from another Directory Server instance, skip this step.

      For example, the following command fills the suffix that you created with sample data from Example.ldif.


      $ dsconf import -h localhost -p 1389 install-path/ds6/ldif/Example.ldif dc=example,dc=com
      Enter "cn=Directory Manager" password:
      New data will override existing data of the suffix "dc=example,dc=com".
      Initialization will have to be performed on replicated suffixes.
      Do you want to continue [y/n] ?  y
      ## Index buffering enabled with bucket size 40
      ## Beginning import job...
      ## Processing file "install-path/ds6/ldif/Example.ldif"
      ## Finished scanning file "install-path/ds6/ldif/Example.ldif" (160 entries)
      ## Workers finished; cleaning up...
      ## Workers cleaned up.
      ## Cleaning up producer thread...
      ## Indexing complete.
      ## Starting numsubordinates attribute generation.
       This may take a while, please wait for further activity reports.
      ## Numsubordinates attribute generation complete. Flushing caches...
      ## Closing files...
      ## Import complete.  Processed 160 entries in 4 seconds. (40.00 entries/sec)
      
      Task completed (slapd exit code: 0).
    3. Verify that you can find an entry in the new instance.


      $ ldapsearch -h localhost -p 1389 -b dc=example,dc=com "(uid=bjensen)"
      version: 1
      dn: uid=bjensen, ou=People, dc=example,dc=com
      cn: Barbara Jensen
      cn: Babs Jensen
      sn: Jensen
      givenName: Barbara
      objectClass: top
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      ou: Product Development
      ou: People
      l: Cupertino
      uid: bjensen
      mail: bjensen@example.com
      telephoneNumber: +1 408 555 1862
      facsimileTelephoneNumber: +1 408 555 1992
      roomNumber: 0209
  6. (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 Servers tab of the Directory Servers tab.

      Access DSCC through the URL https://localhost:6789.

    • Use the command dsccreg add-server.


      $ dsccreg add-server -h dscchost --description "My DS" /local/ds
      Enter DSCC administrator's password:
      /local/ds is an instance of DS
      Enter password of "cn=Directory Manager" for /local/ds:
      This operation will restart /local/ds.
      Do you want to continue ? (y/n) y
      Connecting to /local/ds
      Enabling DSCC access to /local/ds
      Restarting /local/ds
      Registering /local/ds in DSCC on dscchost.

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

  7. (Optional) If you installed from native packages with the Java Enterprise System distribution, enable the server to restart when the operating system reboots.

    On Solaris 10 and Windows systems, use the dsadm enable-service command.


    root# dsadm enable-service /local/ds

    On Solaris 9, HP-UX, and Red Hat systems, use the dsadm autostart command.


    root# dsadm autostart /local/ds

    If you installed with the zip distribution, this step must be done manually, with a script run at system startup time, for example.

Next Steps

At this point, you can add more suffixes, configure replication with other server instances, tune the instance, and generally proceed with other configuration operations.

See the online help inside Directory Service Control Center for hints on configuring Directory Server through the graphical user interface.

See Part I, Directory Server Administration, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide for instructions on configuring Directory Server with command-line administration tools.

ProcedureTo Create a Directory Proxy Server Instance With DSCC

Non-root users can create server instances.

Before You Begin

Install the component software as described in Software Installation.

  1. Access Directory Service Control Center through Java Web Console.

    The default URL for Java Web Console on the local system is https://localhost:6789.

  2. Follow the instructions in the Directory Service Control Center New Server wizard to create the server instance.

    Web-based wizard for creating a Directory Proxy Server instance

ProcedureTo Create a Directory Proxy Server Instance From the Command Line

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

Before You Begin

Install the component software, then set your PATH as described in Software Installation.

  1. Create a new Directory Proxy Server instance.


    $ dpadm create -p port -P SSL-port instance-path
    

    For example, the following command creates an instance under the existing directory, /local/, in a new directory, /local/dps/. The default ports are 389 for LDAP, 636 for LDAPS for root, and 1389 for LDAP, 1636 for LDAPS for non-root users.


    $ dpadm create -p 1390 -P 1637 /local/dps
    Choose the Proxy Manager password:
    Confirm the Proxy Manager password:
    Use 'dpadm start /local/dps' to start the instance

    Notice that the instance must be created in a directory on the local file system, not a network file system.

  2. Start the instance.


    $ dpadm start instance-path
    

    For example, the following command starts the instance located under /local/dps/.


    $ dpadm start /local/dps
    …
    Directory Proxy Server instance '/local/dps' started: pid=28732
  3. Verify that you can read the root DSE of the new instance.


    $ ldapsearch -h localhost -p 1390 -b "" -s base "(objectclass=*)"
    version: 1
    dn:
    objectClass: top
    objectClass: extensibleObject
    supportedLDAPVersion: 2
    supportedLDAPVersion: 3
    …
    vendorName: Sun Microsystems, Inc
    vendorVersion: Directory Proxy Server 6.0
    …

    Note –

    At this point in the procedure, you have a working server instance. You must further configure the server instance, however. Furthermore, the instance is not yet registered with Directory Service Control Center.


  4. (Optional) Enable the Directory Proxy Server instance to function as an LDAP proxy.

    1. Create an LDAP data source.

      For example, the following command creates a data source, My DS, pointing to the directory instance created on the local host in To Create a Directory Server Instance From the Command Line.


      $ dpconf create-ldap-data-source -h localhost -p 1390 "My DS" localhost:1389
      Certificate "CN=hostname:1390" presented by the server is not trusted.
      Type "Y" to accept, "y" to accept just once, "n" to refuse, "d" for more details: Y
      Enter "cn=Proxy Manager" password:
    2. Create an LDAP data source pool.


      $ dpconf create-ldap-data-source-pool -h localhost -p 1390 "My Pool"
      Enter "cn=Proxy Manager" password:
    3. Attach the LDAP data source to the LDAP data source pool.


      $ dpconf attach-ldap-data-source -h localhost -p 1390 "My Pool" "My DS"
      Enter "cn=Proxy Manager" password:
    4. Create an LDAP data view into the LDAP data source pool.

      For example, the following command creates a data view, My View, which allows client applications to view the suffix dc=example,dc=com:


      $ dpconf create-ldap-data-view -h localhost -p 1390 "My View" \
       "My Pool" dc=example,dc=com
      Enter "cn=Proxy Manager" password:
    5. Enable the LDAP data source, then restart the server for the change to take effect.


      $ dpconf set-ldap-data-source-prop -h localhost -p 1390 "My DS" is-enabled:true
      Enter "cn=Proxy Manager" password:
      $ dpadm restart /local/dps
      Directory Proxy Server instance '/local/dps' stopped
      [31/Aug/2006:11:32:26 +0200] - STARTUP    - INFO  -
       Sun Java(TM) System Directory Proxy Server/6.0 (Build 0824060144) starting up
      Directory Proxy Server instance '/local/dps' started: pid=28901
    6. Enable searches on the LDAP data source.


      $ dpconf set-attached-ldap-data-source-prop -h localhost -p 1390 \
       "My Pool" "My DS" search-weight:100
      Enter "cn=Proxy Manager" password:
    7. Verify that you can read directory data through the new instance.


      $ ldapsearch -h localhost -p 1390 -b dc=example,dc=com "(uid=bjensen)"
      version: 1
      dn: uid=bjensen, ou=People, dc=example,dc=com
      cn: Barbara Jensen
      cn: Babs Jensen
      sn: Jensen
      givenName: Barbara
      objectClass: top
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      ou: Product Development
      ou: People
      l: Cupertino
      uid: bjensen
      mail: bjensen@example.com
      telephoneNumber: +1 408 555 1862
      facsimileTelephoneNumber: +1 408 555 1992
      roomNumber: 0209

      Note –

      Notice that LDAP search operations work for the suffix handled by your data view, but do not work for other suffixes. If you search a suffix for which no data view is configured, the server returns an error.


      $ ldapsearch -h localhost -p 1390 -b o=example.com "(uid=bjensen)"
      ldap_search: Operations error
      ldap_search: additional info: Unable to retrieve a backend SEARCH
       connection to process the search request

      For instructions detailed instructions on configuring Directory Proxy Server, see Part II, Directory Proxy Server Administration, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.


  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 through the URL https://localhost:6789.

    • Use the command dsccreg add-server.


      $ dsccreg add-server -h dscchost --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 dscchost.

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

  6. (Optional) If you installed from native packages with the Java Enterprise System distribution, enable the server to restart when the operating system reboots.

    On Solaris 10 and Windows systems, use the dpadm enable-service command.


    root# dpadm enable-service /local/dps

    On Solaris 9, HP-UX, and Red Hat systems, use the dpadm autostart command.


    root# dpadm autostart /local/dps

    If you installed with the zip distribution, this step must be done manually, with a script run at system startup time, for example.

Next Steps

At this point, you can continue to configure further data sources and data views. You can also configure load balancing, data distribution, and other server capabilities.

See the online help inside Directory Service Control Center for hints on configuring Directory Proxy Server through the graphical user interface.

See Part II, Directory Proxy Server Administration, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide for instructions on configuring Directory Proxy Server with command-line administration tools.