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

• Configuring Directory Proxy Server Instances

• Backing Up and Restoring Directory Proxy Server Instances

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

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

To 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

To 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

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

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

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

To 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

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

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

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

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

• If a property has an rws (read, write, static) keyword, the server must be restarted when the property is changed.

• If a property has an rwd (read, write, dynamic) keyword, modifications to the property are implemented dynamically (without restarting the server).

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.

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

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