Chapter 12. Using Services with Penrose Virtual Directory

Chapter 12. Using Services with Penrose Virtual Directory

12.1. About Services in Penrose Virtual Directory
12.2. Configuring Additional Services
12.2.1. Adding Services in Penrose Studio
12.2.2. Adding and Editing Services Manually
12.3. Enabling and Disabling Services

Services are front-end components of Penrose Virtual Directory which communicate directly with client applications. This chapter gives an overview of what services are and how they are used, as well as instructions for creating custom services to use in addition to the default Penrose Virtual Directory services.

12.1. About Services in Penrose Virtual Directory

Services provide a communication avenue between clients and Penrose Server. By default, Penrose Virtual Directory provides services that communicate with LDAP servers (ApacheDS, OpenDS, and MINA) and Java clients (JMX).

Penrose Virtual Directory provides three different LDAP services, ApacheDS, OpenDS, and MINA. By default, only OpenDS is enabled.

NOTE

All three LDAP services can be configured to run for Penrose Virtual Directory, as long as they are listening on different ports.

The JMX service connects to any client which uses the JMX protocol, including Penrose Studio.

Each service configured in Penrose Virtual Directory is located in /opt/vd-server-2.0/services; similarly to the partition configuration, each service has a folder named for the service and a subfolder called SERVICE-INF. There can also be additional folders for libraries, databases, LDIF files, configuration files, and other files used by the specific service. The files used by the default services are listed in Table 12.1, “Default Service Configuration Files”.

Service Folder Description
ApacheDS /opt/vd-server-2.0/services/ApacheDS The main service directory.
ApacheDS /opt/vd-server-2.0/services/ApacheDS/bin Contains the schema.sh and schema.bat files to compile custom schema to allow it to be used by ApacheDS.
ApacheDS /opt/vd-server-2.0/services/ApacheDS/conf Contains a server.xml file which defines the MBeans object used to run the service.
ApacheDS /opt/vd-server-2.0/services/ApacheDS/SERVICE-INF Contains the service.xml file, which defines the service for Penrose Server, and a lib/ directory which contains the libraries used by the LDAP service.
ApacheDS /opt/vd-server-2.0/services/ApacheDS/SERVICE-INF/lib Contains the libraries used by the LDAP service.
JMX /opt/vd-server-2.0/services/JMX The main service directory.
JMX /opt/vd-server-2.0/services/JMX/conf Contains a log4j.xml file which defines logging for the JMX service.
JMX /opt/vd-server-2.0/services/JMX/SERVICE-INF Contains the service.xml file, which defines the service for Penrose Server, and a lib/ directory which contains the libraries used by the JMX service.
JMX /opt/vd-server-2.0/services/JMX/SERVICE-INF/lib Contains the libraries used by the JMX service.
MINA /opt/vd-server-2.0/services/LDAP The main service directory.
MINA /opt/vd-server-2.0/services/LDAP/SERVICE-INF Contains the service.xml file, which defines the service for Penrose Server, and a lib/ directory which contains the libraries used by the MINA LDAP service.
MINA /opt/vd-server-2.0/services/LDAP/SERVICE-INF/lib Contains the libraries used by the MINA LDAP service.
OpenDS /opt/vd-server-2.0/services/OpenDS The main service directory.
OpenDS /opt/vd-server-2.0/services/OpenDS/config Contains LDIF files, scripts, schema, and templates used by the OpenDS service.
OpenDS /opt/vd-server-2.0/services/OpenDS/db Contains database files used by the OpenDS service.
OpenDS /opt/vd-server-2.0/services/OpenDS/locks Contains lock files used by different components of the OpenDS service.
OpenDS /opt/vd-server-2.0/services/OpenDS/logs Contains access, error, and replication logs generated by the OpenDS service.
OpenDS /opt/vd-server-2.0/services/OpenDS/SERVICE-INF Contains the service.xml file, which defines the service for Penrose Server, and a lib/ directory which contains the libraries used by the OpenDS LDAP service.
OpenDS /opt/vd-server-2.0/services/OpenDS/SERVICE-INF/lib Contains the libraries used by the OpenDS LDAP service.
Table 12.1. Default Service Configuration Files

Creating a custom service requires creating a new service directory in /opt/vd-server-2.0/services such as /opt/vd-server-2.0/services/service_name. The service is defined in the SERVICE-INF/service.xml file. Put any custom libraries in the SERVICE-INF/lib directory. The default class, if none are specified, is org.safehaus.penrose.service.Service.

12.2. Configuring Additional Services

Other services can be added to operate with Penrose Server, giving a new or extended interface to communicate with server clients.

  1. In the top menu, click the Services menu, and select New Service....

    Alternatively, open the server, and right-click the Services folder, then select New Service....

  2. Fill in the name of the service, the service's class, and whether the service is enabled.

    Any custom class must be listed in the service's configuration folder in the proper locate for all classes used by the service, /opt/vd-server-2.0/services/service_name/SERVICE-INF/lib. The default class, if none are specified, is org.safehaus.penrose.service.Service.

  3. Fill in any configuration parameters that will be used by clients to connect to the service, such as port numbers or bind credentials.

  4. Click Finish.

To edit a service's configuration, double-click the service under the Services folder to open the entry editor, and then edit or add configuration settings as desired.

All of the service configuration, for a basic configuration, is stored in a subdirectory under /opt/vd-server-2.0/services/. This subdirectory is named whatever the Penrose Server service name is. For example, a JBoss service may be defined in /opt/vd-server-2.0/services/JBoss/; in Penrose Studio, this service is displayed as JBoss.

Within the service_name folder is, at least, a SERVICE-INF/ folder which contains a service.xml file to define the service and a lib/ directory which holds all of the JAR files used by the service.

NOTE

Depending on the type of service created, there can be additional database, configuration, tool, or log folders. The service can be as complex as required.

The service.xml file contains three pieces of information:

  • Whether the service is enabled

  • The class name used by the service

  • Optional parameters to define connections to the service

This is illustrated in Example 12.1, “Annotated Example service.xml File”. 

<service enabled="true"> whether the service is active  

  <service-class>org.safehaus.penrose.mina.MinaLDAPService</service-class>  class used by the service  

  <parameter>  optional connection or configuration parameters  
    <param-name>ldapPort</param-name>
    <param-value>10389</param-value>
  </parameter>

</service>
Example 12.1. Annotated Example service.xml File

IMPORTANT

Always restart Penrose Server after editing the configuration file. For example: 

service vd-server restart

The configuration options for the service.xml file are listed in Table 12.2, “Tags and Parameters for service.xml”.

Source Parameters Description Example
<service> The main file tag.
enabled="..." Sets whether the service is available to communicate with clients. 
<service enabled="true">
<parameter> Contains an attribuate-value pair of tags. 
<parameter>
     <param-name>ldapPort</param-name>
     <param-valuee>10389</param-valuee>
</arameter>
<param-name> Contains the name of the attribute or configuration parameter. 
<param-name>
  ldapPort
</param-name>
<param-value> Contains the value of the attribute or configuration parameter specified in the <param-name> tag. 
<param-value>
  10389
</param-value>
Table 12.2. Tags and Parameters for service.xml

12.3. Enabling and Disabling Services

A service must be enabled for a client to be able to use it to communicate with Penrose Server. To enable or disable services in Penrose Studio, open the properties editor for the service and check the Enable checkbox.

To enable or disable a service manually, edit its service.xml file and change the enabled= to true (enabled) or false (disabled). 

<service enabled="true">

IMPORTANT

Always restart Penrose Server after editing the configuration file. For example: 

service vd-server restart