Chapter 3. Basic Usage

Chapter 3. Basic Usage

3.1. Starting the Service
3.2. Configuring Penrose Server to Run as a Service
3.3. Configuring Penrose Server Host System Properties
3.3.1. Configuring the Host System Properties in Penrose Studio
3.3.2. Configuring the Host System Properties in the Configuration File
3.4. Setting up the Admin User
3.4.1. Editing the Admin User in Penrose Studio
3.4.2. Editing the Admin User in the Configuration File
3.5. Configuring and Viewing Logs
3.5.1. Configuring Log Settings
3.5.2. Access Logs
3.5.3. Error Logs
3.5.4. Debug Logs
3.6. Configuring Penrose Virtual Directory for SSL
3.6.1. Configuring SSL for Backend Sources
3.6.2. Configuring SSL for Frontend Services
3.7. Running Penrose Server Outside a Firewall

This chapter contains common information about the configuration files and directories used in Penrose Studio and information on basic server configuration options, such as starting and stopping the server, establishing secure connections, and changing the root user and host information.

3.1. Starting the Service

Penrose Server is started by running a shell script,, in the /opt/vd-server-2.0/bin directory. For example:

cd /opt/vd-server-2.0/bin

PenroseServer        [ 126] Penrose Server is ready.

To stop the server, simply close the script.

3.2. Configuring Penrose Server to Run as a Service

Penrose Server can also stopped, started, and restarted using system tools on Red Hat Enterprise Linux. Init scripts are included with the configuration files with Penrose Server. and then copy them over to the /usr/sbin directory.

  1. Log into the Penrose Server host machine as the root user.

  2. Open the Penrose Virtual Directory init script directory.

    cd /opt/vd-server-2.0/etc/init.d
  3. Edit the vd-server script so that the Penrose Server home and script locations are correct. For example:

  4. Copy the init file to the /etc/init.d directory.

    cp /opt/vd-server-2.0/etc/init.d/vd-server /etc/init.d
  5. Make the init script executable.

    chmod +x /etc/init.d/vd-server
  6. Test the new Penrose Virtual Directory service.

    service vd-server start

After setting Penrose Server up as a service, it can be managed using the service on Red Hat Enterprise Linux:

service vd-server {start|stop|restart}

The system properties for Penrose Virtual Directory define the connection information to access the Penrose Server. This is used by clients such as Penrose Studio and LDAP browsers.

3.3.1. Configuring the Host System Properties in Penrose Studio

To set the host system information in Penrose Studio:

  1. Click the System Properties link at the bottom of the server navigation window.

  2. Click the Add button to add new system properties, or select and existing property and click Edit to change it.

  3. Fill in the properties and values.

    The hostname (java.rmi.server.hostname) is required. There are four optional parameters, which are set in pairs:

    • and, which give the path to the server's certificate database and the password to access the database.

    • http.proxyHost and http.proxyPort, which give the hostname and port of a proxy web server to use to access the server.

The root user for Penrose Server has full access to the Penrose Server application. LDAP clients which bind to Penrose Server as the configured root user bypass all access control settings for the virtual directory; therefore, any management clients, including Penrose Studio, must bind to the Penrose Server as the (Penrose Server) root user.

There are three logs kept by Penrose Server:

  • Access logs

  • Error logs

  • Debug logs

These logs are stored in the /opt/vd-server-2.0/logs directory. Since these files apply to access to Penrose Server and Penrose Studio, one set of log files is kept, regardless of the number of partitions.

The log configuration file is located in the configuration directory, /opt/vd-server-2.0/conf.

The access logs record every transation that is performed through Penrose Server on the virtual directory or its sources. The access log entry has the following general format:

[date timestamp] session_ID type_of_operation operation_details

The session_ID gives the number for the connection thread.

There are several different types of transaction logged in the access log:

  • CONNECT shows the initial connection. The operation details include the IP address of the client, the IP address of the Penrose Server host, and the protocol used to connect to the server (either LDAP or JMX).

  • BIND shows that a user has authenticated to the server when the session was opened. This contains the DN of the user.

    After the initial log entry for the BIND operation, the result is shown in the result= tag and then the DN which connected (authDN).

  • SEARCH shows the search details for a search of the virtual directory. This contains the base DN, scope, and filter for the search, as well as the entry attributes returned.

    After the initial log entry for the SEARCH operation, the result is shown in the result= tag and, for a successful operation, the number of entries returned.

  • DISCONNECT shows when the connection is closed.

For example:

[10/29/2008 12:47:31] session="5" - CONNECT from="" to="" protocol="LDAP"
[10/29/2008 12:47:31] session="5" - BIND dn="uid=admin,ou=system"
[10/29/2008 12:47:31] session="5" - BIND result="Success" authDn="uid=admin,ou=system"
[10/29/2008 12:47:33] session="5" - SEARCH base="dc=example,dc=com" scope="one level" filter="(objectClass=*)" attrs="*,+"
[10/29/2008 12:47:45] session="5" - SEARCH result="Success" entries="2"
[10/29/2008 14:58:59] session="5" - DISCONNECT
Example 3.1. Access Logs

The error logs have a more simple format than the access logs, showing the time of the error and the error message.

[date timestamp] error_message

Many error messages contain Java exceptions, which can indicate which areas of the Penrose Virtual Directory service have a problem. For example:

[10/08/2008 19:19:40] An error occurred while attempting to calculate a SHA-1 digest of file /usr/local/penrose-server-2.0RC2/services/OpenDS/config/config.ldif:  SHA-1 MessageDigest not available (
org.opends.server.types.InitializationException: An error occurred while attempting to calculate a SHA-1 digest of file /usr/local/penrose-server-2.0RC2/services/OpenDS/config/config.ldif:  SHA-1 MessageDigest not available (
        at org.opends.server.extensions.ConfigFileHandler.initializeConfigHandler(
        at org.opends.server.core.DirectoryServer.initializeConfiguration(
        at org.opends.server.core.DirectoryServer.initializeConfiguration(
        at org.safehaus.penrose.opends.OpenDSLDAPService.init(
        at org.safehaus.penrose.service.Service.init(
        at org.safehaus.penrose.service.ServiceManager.startService(
        at org.safehaus.penrose.server.PenroseServer.start(
        at org.safehaus.penrose.server.PenroseServer.main(
Example 3.2. Error Logs

SSL can be configured two ways for Penrose Server. Front-end SSL means that Penrose Server uses SSL-secured connections to communicate with its OpenDS client services. Back-end SSL means that Penrose Server uses SSL-secured connections to communicate with LDAP and JDBC data sources.

3.6.1. Configuring SSL for Backend Sources


The source must be configured to run over SSL as well for Penrose Virtual Directory to connect to it using SSL.

  1. Configure the source to run in SSL.

  2. Configure the connection for the source, as described in Chapter 6, Configuring Connections, with the protocol and ports set for SSL.

  3. When the source is configured for SSL, an SSL client certificate is issued to the source. This certificate has to be imported into Penrose Server's certificate database for Penrose Server to connect to the source over SSL.

    1. Export the source's SSL client certificate to a PEM or PKCS #12 file.

    2. Open the Penrose Server configuration directory.

      cd /opt/vd-server-2.0/conf
    3. Import the certificate into the certificate database. This can be done using tools like certutil or keytool, depending on how the database was created. For example:

      keytool -import -trustcacerts -alias mydb -file certificate.pem -keystore conf/cacerts
      Enter keystore password:  secret
      Owner:, OU=Engineering, L=Raleigh, ST=North Carolina, C=US
      Issuer: CN=mydb, OU=Engineering, L=Raleigh, ST=North Carolina, C=US
      Serial number: 499ee484
      Valid from: Fri Feb 20 11:12:36 CST 2009 until: Thu May 21 12:12:36 CDT 2009
      Certificate fingerprints:
               MD5:  37:45:60:73:A8:DD:BB:1D:C0:7A:F3:82:49:99:B9:04
               SHA1: CE:2C:21:D4:91:D1:7E:94:92:29:24:33:EE:59:06:DD:F0:B5:B8:EA
      Trust this certificate? [no]:  yes
      Certificate was added to keystore
    4. Edit the server.xml file. Add two parameters, and, to give the location and password to access the certificate database.


To verify that SSL is properly configured for the backend, open Penrose Studio and open the source. If the source opens and can be browsed, then SSL is working.

3.6.2. Configuring SSL for Frontend Services

  1. Request or generate a certificate for Penrose Server to use.

    Penrose Server supports a JKS or PKCS #12 certificate. Certificates can be request from a third-party authority or can be self-generated using a tool such as keytool or certutil and pk12util.

    However the certificate is generated, make sure to use the hostname of the Penrose Server host machine as the common name (CN) part of the certificate.

    For example, this generates a JKS certificate:

    keytool -genkey -keyalg RSA -alias server-cert -keystore conf/keystore
    Enter keystore password:
    Re-enter new password:
    What is your first and last name?
    What is the name of your organizational unit?
      [Unknown]:  Engineering
    What is the name of your organization?
      [Unknown]:  Example Corp.
    What is the name of your City or Locality?
      [Unknown]:  Raleigh
    What is the name of your State or Province?
      [Unknown]:  North Carolina
    What is the two-letter country code for this unit?
      [Unknown]:  US
    Is, OU=Engineering, O=Example Corp., L=Raleigh, ST=North Carolina, C=US correct?
      [no]:  yes
    Enter key password for <server-cert>
            (RETURN if same as keystore password):

    For more information on keytool, see

  2. Edit the front-end service to support SSL. The only service which currently supports SSL for Penrose Server is the OpenDS service.

    1. Open the OpenDS directory.

    2. Copy the keystore from the Penrose Server conf directory to the OpenDS service configuration directory.

      cp /opt/vd-server-2.0/conf/keystore .
    3. In the OpenDS service configuration directory, there is a file called Add the password for the keystore database to this file. For example:

      echo secret >
    4. The OpenDS config.ldif file. This contains entries which enable and configure SSL for the service.

       vim config.ldif
    5. The OpenDS config.ldif file has an entry for a JKS key manager and a PKCS #12 key manager. Edit the appropriate entry so that it is enabled, depending on the type of certificate created. For example:

       dn: cn=JKS,cn=Key Manager Providers,cn=config
       objectClass: ds-cfg-file-based-key-manager-provider
       objectClass: ds-cfg-key-manager-provider
       objectClass: top
       ds-cfg-key-store-type: JKS
       cn: JKS
       ds-cfg-key-store-file: config/keystore
       ds-cfg-key-store-pin-file: config/
       ds-cfg-enabled: true

      If necessary, edit the other parameters in the entry to make sure it matches the certificate information. Make sure the directories given for the keystore and PIN files are relative to the OpenDS service directory, not the Penrose Server home directory.

    6. To accept client certificates, make sure the blind trust entry is enabled.

       dn: cn=Blind Trust,cn=Trust Manager Providers,cn=config
       objectClass: ds-cfg-blind-trust-manager-provider
       objectClass: top
       objectClass: ds-cfg-trust-manager-provider
       cn: Blind Trust
       ds-cfg-enabled: true
    7. Make sure that LDAPS connections are allowed. The entry should be enabled, SSL should be allowed, and Start TLS should be denied. Additionally, the certificate nickname in the entry should match the nickname of the certificate generated for Penrose Server.

       dn: cn=LDAPS Connection Handler,cn=Connection Handlers,cn=config
       .. snip...
       ds-cfg-allow-start-tls: false   
       ds-cfg-use-tcp-keep-alive: true
       ds-cfg-ssl-cert-nickname: server-cert
       .. snip...
       ds-cfg-enabled: true    
       .. snip...
       cn: LDAPS Connection Handler
       .. snip...
       ds-cfg-listen-port: 636
       .. snip...
       ds-cfg-use-ssl: true
  3. Restart Penrose Server.

    service vd-server restart
  4. The Penrose Server certificate has to be available in the certificate database of any LDAP tools used to manage Penrose Server. For example, for OpenLDAP tools:

    1. For a self-signed certificate, export a PEM file.

      keytool -export -alias server-cert -keystore conf/keystore -file penrose.pem -rfc
    2. Import the certificate into the certificate database, such as the default cacerts.

      cp penrose.pem /etc/openldap/cacerts
      c_rehash /etc/openldap/cacerts
  5. To use OpenLDAP's LDAP client tools with Penrose Server, edit the OpenLDAP configuration file, ldap.conf, to recognize Penrose Server's certificate.

    vim /etc/openldap/ldap.conf
    TLS_CACERTDIR /etc/openldap/cacerts

To test the frontend SSL configuration for Penrose Server, run an ldapsearch using the secure port, 636, and the secure protocol, ldaps.

ldapsearch -H ldaps://localhost:636 -x -b "" -s base

If SSL is properly configured the search returns the root DSE for Penrose Server.

3.7. Running Penrose Server Outside a Firewall

Penrose Server can run outside a firewall for additional network security, but, in that case, the firewall must be configured to allow access for the different client ports required for Penrose Server.

Port Number Client Description
1099 An RMI port used by Penrose Studio.
40888 An RMI transport port used by Penrose Studio.
8122 A web port used by web browsers.
10389 The LDAP standard port used by directory services.
10636 The LDAP secure (SSL) port used by directory services.


The ports used by these services can be changed; see Chapter 12, Using Services with Penrose Virtual Directory. Before changing the services ports or firewall settings, make sure that the client itself is configured to use a different port number.