Admin

Administrator 3.1 Guide

d, ed in

ir

by ,

in any

© 1997-1999 ObjectSpace, Inc. All rights reserved.

ObjectSpace, Inc., has used its best efforts in preparing this book. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. ObjectSpace, Inc., makes no warranties of any kinexpressed or implied, with regard to these programs or the documentation containthis book. ObjectSpace, Inc., shall not be liable in any event for incidental or consequential damages in connection with, or arising from, the furnishing, performance, or use of these programs.

Voyager, Space, and Dynamic Aggregation are trademarks of ObjectSpace, Inc.

Java is a trademark of Sun Microsystems.

All other brand or product names are trademarks or registered trademarks of therespective holders.

RESTRICTED RIGHTS LEGEND

Voyager ORB Professional, Voyager Security and Voyager Transactions arefurnished under a license and may not be used, copied, disclosed, and/or distributed except in accordance with the terms of said license. No classes, hierarchies, methods, binaries, or code may be copied for implementation inother systems.

This document and all online system documentation are copyrighted 1997-1999ObjectSpace, Inc. All rights reserved. No portion of this document may be copiedphotocopied, reproduced, transcribed, translated, or reduced into any language, form or by any means, without the prior written consent of ObjectSpace, Inc.

This document is subject to change without notice.

Software Version 3.0

Second Edition

Printed in the United States of America

Contents

1 Overview 1Configuring and Managing a Distributed System 2

2 Voyager Directory Server 3Using an LDAP Server 4Starting a Voyager Directory Server 8

Communicating with a Voyager Directory Server 9

3 Voyager Management Console 11Understanding the Structure of the VMC 12

Accessing an LDAP Directory Server 13Starting VMC 13

Initializing the Voyager Directory Server 15Installing Services 15

Creating Server Profiles 16Creating Clusters 16

4 Voyager Servers 21Configuring Voyager Servers 22

Defining System Properties 24Defining CORBA-to-Java Mappings 25

Startup Using Voyager Directory Server 26

Voyager Core Technology User Guide iii

Running Directory Server and Voyager Server in the Same VM 27Managing Running Voyager Servers 27

5 Security Service 31Securing the VMC and Directory Server 32Securing the VMC Using a Custom Policy Implementation 34

Securing Voyager Servers Using BasicPolicy 34Managing the Access Control List 39

6 Transaction Service 45Monitoring Transaction Statistics 46Viewing the Transaction Log 47

Viewing Active Transactions 49Viewing Transaction Errors 50

Configuring Transactions 51Communicating with the Server 52

7 JDBC Service 53Configuring Datasource Properties 54

8 EJB Service 57Monitoring EJB Container Statistics 58Configuring the EJB Container 60

Configuring an EJB Service with an LDAP Directory Service 67Monitoring a Component’s Statistics 69

Configuring a Component’s General Properties 70Viewing a Component’s Transactional Properties 72

Setting a Component’s Security Properties 73Setting a Component’s Environment Properties 75

Viewing a Method’s Transactional Properties 78Setting a Method’s Security Properties 79

iv

Voyager Configuration and Management

1
Overview
s.

re

y the nt

This manual details Voyager’s configuration and management capabilitieSeveral tools are used in deploying and maintaining a distributed systemusing Voyager:

� Voyager Directory Server–serves as a naming service, the central repository for configuration information, and a record of servers that acurrently running.

� Voyager Management Console–allows you to view and change information within the directory, as well as communicate directly with services running on remote Voyager servers.

� Voyager Server–can be configured remotely from the Voyager DirectorServer. At startup, servers retrieve their configuration information from directory and allow management of their services through ManagemeAgents.

1

and e hine rs

tual

the

MC)

,

our which

se

Configuring and Managing a Distributed System

When implementing any distributed system, you need a way of remotely initializingkeeping track of servers in the field. For example, you want to be able to set runtimparameters for any server in your system without having to physically sit at the macin question. You will also want to be able to know, at any point in time, which serveare running and what state those servers are in.

Voyager addresses these concerns with the following architecture:

A central Voyager Directory Server stores all server profile information. Server profiles are entries in the Voyager Directory Server that describe the services a particular Voyager server runs and their configuration. Server profiles are associated with acVoyager servers when those servers are brought online.

Management and administration tools discover from the Voyager Directory Server remote Voyager servers that are running along with their configuration. In addition,services running on each Voyager server can expose special “management agent”objects through which they can be observed and manipulated. Proxies to these management agents are also registered in the Voyager Directory Server under each server’s service profile so that tools such as the Voyager Management Console (Vcan interact with the service’s managed objects.

The VMC is a graphical tool for administering the directory and monitoring and configuring servers and services. Using the VMC you can set up a directory servercreate new server profiles, edit configuration information, and interact with management agents.

Voyager add-on services, such as Voyager Transactions, Voyager Security, and Voyager Application Server, are all managed using the VMC. You can also create yown services and management screens by extending the same frameworks upon Voyager’s add-ons are built.

When a directory server is initialized, if you have Voyager Security, Voyager Transactions, or Voyager Application Server, the console automatically installs theservices in the directory server.

2 Chapter 1 • Overview

2
Voyager Directory Server
n

bed

The Voyager Directory Server is a central repository for configuration information. The Voyager Directory Server uses Voyager’s implementatioof JNDI and its Persistent Directory feature to store information.

In this chapter, you will learn to:

� use an LDAP server

� start a Voyager Directory Server

� communicate with a Voyager Directory Server

Note: The content and structure of a Voyager Directory Server are descriin more detail in the Voyager ORB Developer Guide.

3

use a for

tions

e

ct as

ess

Using an LDAP Server

To use an LDAP server, you must:

� update the LDAP schema

� create the Voyager directory tree

� set up JNDI

Updating the LDAP Schema

Voyager stores information in a directory server as Java objects. The Internet Engineering Task Force’s (IETF) draft file “draft-ryan-java-schema-02.txt,” distributed as a text file on the Voyager 3.1 CD, defines an LDAP schema for Java objects. ToVoyager with an LDAP server that uses schema checking, you must add this schemJava objects to the server. Consult your directory server documentation for instrucregarding schema additions.

Creating the Voyager Directory Tree

Voyager assumes that the root directory object is a Java container as defined by thInternet draft “draft-ryan-java-schema-02.txt”. (See the text file that was distributed with your Voyager CD.) You must create a directory tree with a Java container objeits root. The distinguished name for this Java container object must be the cn attribute. Here is an example of a Voyager root directory object:

dn: cn=VoyagerDirectory cn: VoyagerDirectory objectclass: top objectclass: javaContainer

Given the above root directory object, Voyager will require the following URL to accthe directory. This URL specifies a directory server on a machine called dallas that is listening on port 389. Consult your directory server documentation for instructions oncreating directory root objects.:

//dallas:389/VoyagerDirectory

4 Chapter 2 • Voyager Directory Server

rvice ecific

of r. ssible

me

with ’s

nate l

n tem nate

JNDI Configuration

Voyager uses Java Naming and Directory Interface (JNDI) to access LDAP directory servers. JNDI is a Java API that provides a standard interface for accessing different naming and directory service implementations.

Setup

For each naming and directory service implementation, JNDI requires a specific seprovider. The service provider contains the Java classes necessary to access a spnaming or directory implementation. To use Voyager with LDAP directory servers, either an implementation-specific LDAP service provider or Sun’s LDAP service provider is required.

Consult your directory server documentation for instructions regarding installation the LDAP service provider, or consult Sun’s web site to obtain Sun’s LDAP provideOnce the service provider is installed, verify that the proper Java classes are accefrom the classpath environment variable. Also, note the name of the initial context factory class. The name of this class is provider-specific and will be needed later toproperly configure Voyager to use the LDAP directory server. For Sun, the class nais com.sun.jndi.ldap.LdapCtxFactory.

Initial Context Factory

When creating an initial context to access a specific naming or directory implementation, JNDI uses an initial context factory provided by the JNDI service provider. Voyager must always be configured to use its own initial context factory toaccess naming and directory implementations through JNDI. When using Voyagera naming or directory implementation other than Voyager Directory Server, Voyagerinitial context factory delegates the creation of initial contexts to an initial context factory from an alternate service provider, such as Sun’s LDAP provider. If an alterservice provider is used, Voyager will add Voyager-specific functionality to the initiacontext returned from the alternate service provider’s initial context factory before returning it to the client.

When used with LDAP, Voyager will use Sun’s LDAP service provider by default. Aalternate LDAP provider can also be used. The following section describes the sysproperties used to configure Voyager for use with LDAP and how to specify an alterLDAP provider.

Voyager Adminstrator Guide 5

ent ager

r

System Properties

JNDI uses system properties to communicate certain information from the JNDI clito the JNDI service provider. Voyager also uses system properties to configure Voyfor use with LDAP directory implementations. These system properties are specified in a Java properties file that is read by the Voyager Management Console on startup.

The name of the system property Voyager uses to determine the directory server implementation is objectspace.directory.server.implementation. For LDAP directory servers, the value of this property must be ldap. If this property is not set, Voyager Directory Server will be used. If LDAP is specified, Voyager will, by default, delegate initial context requests to Sun’s LDAP initial context factory. When using a different LDAPservice provider, set the objectspace.alternate.context.factory system property. The value of this property must be the initial context factory of the alternate service provider. Foexample:

java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactoryobjectspace.directory.server.implementation=ldapobjectspace.alternate.context.factory=com.company.LDAPInitialContextFactory

In the example, com.company.LDAPInitialContextFactory is the initial context factory delivered with the alternate LDAP service provider.

The following table summarizes the most common set of properties required by Voyager to access LDAP directory servers using JNDI.

Property Name Property Description

objectspace.directory.server.implementation This property is required when using Voyager with naming or directory implementations other than Voyager Directory Server unless the provider URL contains the LDAP protocol. See the following section for more information about the URL format. To use Voyager with LDAP the value must be ldap.


tem

The specific LDAP application or the LDAP service provider may require other sysproperties. Consult your directory server and service provider documentation for information regarding environment properties.

LDAP Security

Currently Voyager only supports simple text string user names and passwords for accessing LDAP directories.

objectspace.alternate.factory.initial The class name of the alternate initial context factory to be used by Voyager to access the LDAP server. This class is included in the LDAP service provider. This property is only required for LDAP service providers other than Sun’s.

java.naming.factory.initial The value of this property must always be com.objectspace.voyager.jndi.spi.VoyagerContextFactory.

java.naming.security.authentication Indicates the level of security authentication supported by the directory server client. Thevalue for this property will always be simple for this version of Voyager. This property is required.

java.naming.security.principal Identity or principal used by the authentication scheme. This will be a simpletext-string user name for this version of Voyager.

java.naming.security.credential Principal’s credential for the authentication scheme. This will be a simple text-string password for this version of Voyager.

Property Name Property Description


g

g

Starting a Voyager Directory Server

Initiate a Voyager Directory Server by starting Voyager from the command line usinthe -j and -f options.

voyager 8000 -j dir -f 8000.db

Required pieces of information follows:

� a port to listen on

� -j and a name to which to bind the directory

� -f and the file to write items that are bound into the directory

The URL of this directory is now //dallas:8000/dir, where dallas is the hostname of the system on which the directory was started.

Starting a Voyager Directory Server with LDAP

To associate a Voyager server with a server profile created by the VMC in an LDAPserver, start the Voyager server with the -d and -p options. For example, to use a serverprofile called Servers/server1 in a Voyager directory tree called VoyagerConfig on a machine called dallas that is listening on port 389, use the following command:

voyager -d //dallas:389/VoyagerConfig/Servers/server1 -p ldap.properties

The -p option requires a file containing system properties. The properties file shouldcontain all of the properties described in “System Properties” on page 6, as well as any properties that are required by the LDAP server and the JNDI service provider beinused. An example properties file with settings for the above example follows:

java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactoryjava.naming.security.authentication=simplejava.naming.security.principal=directoryUserjava.naming.security.credential=userPasswordobjectspace.directory.server.implementation=ldap

Note: The principal and credential property values should represent a user in the LDAPdirectory with all access permission to the Voyager directory tree.


rted

e or

Communicating with a Voyager Directory Server

Any JNDI client can communicate with a Voyager Directory Server. When a JNDI client is communicating with a Voyager Directory Server, the server needs to be stawith the -r parameter See the Voyager ORB Developer Guide for information on obtaining an initial context for a given directory.

The preferred method of communicating with a Voyager Directory Server, within the context of configuration and management, is via the Voyager Management ConsolVMC.


3
Voyager Management Console
r
The Voyager Management Console (VMC) communicates with a VoyageDirectory Server and manages its contents. It is also capable of communicating directly with services on remote Voyager servers.

� understand the structure of the VMC

� access an LDAP directory server

� start the VMC

� initialize the Voyager Directory Server

� install services

� create server profiles

� create clusters

11

ode status

Understanding the Structure of the VMC

The main window of the VMC consists of three sections. On the left side is the treeview. It represents the content of the Voyager Directory Server. When a particular nin the tree is selected, tabs for objects contained in that node are on the right. The window at the bottom relays status information and error messages.

Tree View Tabs Related to Selected Node Status Window

12 Chapter 3 • Voyager Management Console

ss an the

For

Accessing an LDAP Directory Server

The VMC uses a Java properties file to load the system properties required to acceLDAP directory server. The filename is specified on the command line when startingVMC. For example, to start the console with a file named ldap.properties, use the following command:

console ldap.properties

The following is a properties file example using Sun’s service provider:

java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactoryjava.naming.security.authentication=simpleobjectspace.directory.server.implementation=ldap

By default, VoyagerContextFactory delegates to Sun’s LDAP initial context factory.

Notice that the java.naming.security.principal and java.naming.security.credential entries are not included. The VMC will add the principal and credential from the login dialog to thesystem properties.

The directory URL entered in the VMC login dialog must be the URL of the LDAP directory server, without the protocol, plus the name of the Voyager directory tree. example, to access an LDAP directory tree named Voyager on a directory server on a machine called dallas that is listening on port 389, use the following URL:

//dallas:389/Voyager

Starting VMC

Run the console utility to start the VMC. On startup, the VMC presents a dialog that prompts you for a user name, password, and directory URL.

Note: Users of the VMC must be given all access permission to the Voyager directory tree.


you
If the directory server is not secured, leave the name and password fields blank. Ifhave the security service installed, see the "Security Service" chapter for more information. In the URL field, specify the location of a running Voyager Directory Server. For example, start a directory server on a machine called dallas with the following command:
voyager //dallas:8000 -j dir -f 8000.db

Then fill in the following as the directory URL:

//dallas:8000/dir


a

s to

Initializing the Voyager Directory Server

If the Voyager Directory Server has never been visited by a VMC before, the VMC informs you that the Voyager Directory Server is not initialized. Voyager presents adialog box asking whether you want to initialize the directory. This process createsdefault server profile template in the Voyager Directory Server from which server profiles are built.

Installing Services

Any time after the Voyager Directory Server is initialized, you may add new servicethe server profile template by selecting Install service… from the File menu. This brings up a file chooser dialog that is used to select either the jar file in which the desiredservice was distributed or a serialized configuration object, which is a file with the extension SER, distributed separately from the jar file. Information specific to that service is then added to the Voyager Directory Server’s server profile template.


new

ices

For

er of ters

Creating Server Profiles

Server profiles specify the runtime properties of servers in your system. To create aserver profile, select New server profile… from the File menu. A dialog opens that prompts you for a URL and allows you to select desired services from a list of servthat have been installed (see the "Installing Services" section on page 15).

The URL field is interpreted as relative to the root of the Voyager Directory Server.example, if you specify Servers/Test in the URL field, the server profile is at URL //dallas:8000/dir/Servers/Test, where dallas is the machine name of the directory server, 8000 is its port, and dir is the name to which the directory is bound.

Server profile URLs may be specified arbitrarily. There is no predefined directory structure for server profiles.

Creating Clusters

The Voyager Management Console makes it easy to create and administer a clustservers that all share a set of configuration information.You can create logical clusto manage multiple servers. A logical cluster contains settings common to multiple


ster or r

ialog

con

servers. Once a cluster has been created, any server profiles created under this clumoved to this cluster will acquire the settings for the cluster. Some settings may bemodified only for the entire cluster, and others may be modified only within a serveprofile.

How to Create a Cluster

Step 1. From the File menu, select New Server Cluster. The new server cluster dbox opens.

.

Step 2. Enter the name for the cluster you are creating, and select the services to be installed on that cluster.

Step 3. Click OK. A cluster icon will appear in the tree window.

Step 4. Configure the sharable information for that cluster by selecting the cluster iin the tree window.

Step 5. Configure the sharable service information for the installed services by selecting the service nodes directly under the cluster node in the tree window.


ation

the t of

new ble s

Adding Servers to a Cluster

Once you’ve created a server cluster you can add servers that shared the configurinformation for that cluster.

Step 1. To add a new server profile to a cluster, select the New Server Profile fromFile menu. The new server profile dialog box will open, displaying a drop-down listhe available clusters.

Step 2. In the available cluster list, select the cluster to which you want to add the server. The list of selectable services is disabled when you select one of the availaclusters. Since each server placed in a cluster is virtually identical, the only serviceinstalled for each server will be the services installed on that cluster.


to

er,

ove lect

ofile red

Step 3. Click OK. The new server profile will appear as a child node of the clusterwhich it was added.

Moving a Server from a Cluster

Step 1. To move a server to a different cluster or make a server a non-clustered servselect the server node in the tree window.

Step 2. In the Create in Cluster list, select the new cluster to which you wish to mthe server. The server profile will immediately be moved to its new cluster. If you se“No Cluster”, it will no longer be a part of any cluster.

Step 3. Once you move a server to a new cluster, that server begins to share the sharable configuration information of its new cluster. If you select “No Cluster” andmove the server profile out of all of the available clusters, the information that the prshared with its previous cluster will remain with the server, but it will no longer be shawith that cluster.


e r

e

to:

he

For more information on the administering either the individual servers or any of thservices installed on a cluster, see the sections on “Voyager Servers” and “VoyageServices: in the Voyager Administrator Guide.

Starting a Voyager Server in a Cluster

As specified in the section on starting Voyager with a directory server, if you start thdirectory server containing the configuration information by:

voyager 8000 –f dir.db dir

or

voyager 8000 –j dir –f dir.db

and a server is created with the name Server, the following command starts the server with the configuration information stored in the directory server:

voyager –d //dallas:8000/dir/Server

If that server profile is stored as a part of a cluster named Cluster, the startup command becomes:

voyager –d //dallas:8000/dir/Cluster/Server

If the server profile is moved back out of the cluster, the startup command returns

voyager –d //dallas:8000/dir/Server

Note: When a administering either a cluster or a server in a cluster, only certain information may be modified. Shared information may only be modified on tcluster node (or cluster services), and the server-specific information may only be modified on the server node.


4
Voyager Servers
an
With the VMC, you can view and change the configuration options and runtime setup of Voyager servers. Additionally, remote Voyager servers cnow discover configuration information from the directory during startup.

� configure Voyager servers

� define system properties

� define CORBA-to-Java mappings

� start Voyager servers

� run directory server and Voyager server in the same VM

� manage Voyager servers

21

e.

e trings

s.

uld

s

Configuring Voyager Servers

You can configure a number of aspects of a Voyager server within the server profilThe Server Configuration tab offers the following:

� Startup URL – the port on which the Voyager server should listen for incoming connections.

� Startup application – the class name and arguments for an application class to bexecuted on startup. The main method of the class is called with the remaining Spassed in as arguments.

� Maximum number of idle threads – an integer that tells the ThreadManager an upper bound for the size of the idle thread pool.

� Voyager security manager – a flag that toggles whether a VoyagerSecurityManager is installed on startup.

� Enable resource serving – a flag that enables the HTTP resource server.

� Enable resource loading – a flag that enables Voyager’s class loading mechanismIf this is disabled, dynamic proxy generation does not occur.

� Resource URLs – a list of addresses of HTTP servers that this Voyager server shoconsult for resources.

� Other resource loaders – a list of class names used as alternate resource loaderwithin this Voyager server.

22 Chapter 4 • Voyager Servers

le is
Note: Changes do not take effect while a Voyager server associated with this profirunning. Also, updating the configuration is not transactional, so there is no locking against multiple VMCs editing the same configuration.

dded p.

Defining System Properties

System properties for the server may also be set in the profile. The Server Properties tab allows editing of existing properties and the addition of new ones. Properties are ato the server after the virtual machine starts, but before Voyager finishes starting u


ngs he

e

Defining CORBA-to-Java Mappings

You can override the default CORBA mapping rules on the CORBA<->Java Mappipanel. These mappings will be considered in addition to any that are specified on tcommand line.

To add a mapping, press the add button and fill in the name of the IDL entity and thJava class name you want it mapped to.

See the CORBA section of the Voyager ORB Developer Guide for more information.


cific

the d rted, e

and

Startup Using Voyager Directory Server

To associate a Voyager server running on any computer on the network with a speentry in the Voyager Directory Server, run the voyager utility as follows:

voyager –d //dallas:8000/dir/Servers/Test

This example associates the Voyager server with an entry called Servers/Test in the Voyager Directory Server running at //dallas:8000 whose directory is bound to the namedir.

During startup, Voyager contacts the directory server and retrieves its server configuration object, which contains all of the runtime configuration information for Voyager server itself. Voyager also iterates through the other entries in the specifieprofile. It retrieves any configuration objects for services. When each service is stait is responsible for installing a Management Agent back into the server profile in thVoyager Directory Server if necessary.

To associate a Voyager server with a server profile created using the Voyager Management Console (VMC) that is stored in a Voyager Directory Server, run the Voyager utility with the -d option. For example, if a server profile named servers/test was created in a Voyager Directory Server running on a machine named dallas that is listening on port 8000 use the following command:

voyager –d //dallas:8000/servers/test

If the Voyager Directory server is secured using BasicPolicy, then BasicPolicy must also be used to secure the Voyager server being configured. In addition, a user name and password must be specified to allow the Voyager server to connect to the VoyagerDirectory Server. To specify the security policy implementation and the user name password, use the voyager utility -p option. The -p option loads system properties from afile. The file name is specified on the command line. For example:

voyager –d //dallas:8000/servers/test –p properties.file

In the above example properties.file is the file name of a file containing the information necessary to allow the Voyager server to access the Voyager Directory Server. An example file follows:


ibed

ning

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy,props/security.server.propertiesjava.naming.security.principal=directoryAdminjava.naming.security.credentials=directoryAdmin

In the above example, the property keys java.naming.security.principal and java.naming.security.credentials are JNDI environment properties that the Voyager JNDI service provider uses when connecting to the Voyager Directory Server. The objectspace.security.policy.1 property key specifies the security policy implementation tothe Voyager Security Framework. The process of loading a security policy is descrin more detail in the Voyager Administration Guide and the Voyager Security DeveloperGuide.

Running Directory Server and Voyager Server in the Same VM

If you need to have the Voyager Directory Server and a regular Voyager server runon the same VM, use the -j, -f and -d options together. For example:

voyager 8000 -j dir -f 8000.db -d 8000/dir/Servers/Test

This example assumes that there is already a file called 8000.db that is a valid Voyager Directory Server database and contains a profile called Servers/Test.

Managing Running Voyager Servers

To manage running Voyager servers, refer to the Voyager ORB Developer Guide.

Note: In this case only, when specifying the profile URL after the -d option, do not include the machine name or IP address for the local host.


Voyager Services

5
Security Service
rs
With the features of Voyager Security, you can secure both Voyager serveand the VMC.

� secure the VMC and Directory Server

� secure the VMC using a custom policy implementation

� secure Voyager servers using BasicPolicy

� manage the Access Control List (ACL)

Note: The security service is only available in the Voyager Security and Voyager Application Server products.

31

he

rom

reate

r must

his

y

Securing the VMC and Directory Server

Secure the Voyager Management Console and the Voyager Directory Server with tfollowing steps:

Step 1. Start an unsecured Voyager Directory Server. For example:

voyager 8000 -j dir -f 8000.db

Step 2. Start an unsecured Voyager Management Console.

Step 3. Install the security service. Select Install Service from the file menu of the VMC, then choose the Security Service's jar file or serialized configuration object fthe resulting file dialog.

Step 4. Create or import a system user using the Voyager Management Console. Ca user with the tools described in the "Managing the Access Control List" section on page 39. The user represents the system when it accesses the directory server. This usebe granted directory permission. Adding permissions to users is described in the "Managing the Access Control List" section. Optionally other users could be added at tstep, but the system user is required.

Step 5. Restart the Voyager Directory Server in a secured state. Stop the directorserver started in step 1. Restart it using the -p option. For example:

voyager 8000 -j dir -f 8000.db -p server.properties

The file specified with the -p option should contain the following text:

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy, filename

filename is the name of the file with the security properties. For example:

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy,security.properties

32 Chapter 5 • Security Service

in onsole,

d to

ame

This file must contain the following entries:

An example using the directory server example follows:

policy.server=true directory.url=//dallas:8000/dirdirectory.username= directory.password= security.owner.username= security.owner.password= security.system.username=systemUsersecurity.system.password=systemUserPassword

Step 6. Restart the VMC in a secured state. Stop the management console started step 2. Restart a secured management console. To start a secured management ctype console at the command line followed by a file name. For example:

console client.properties

The file client.properties should contain the following text:

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy

After this setup process is completed, the VMC requires a user name and passworlog in. For users to login to the console, they must have directory permission. Any Voyager server started using the voyager utility with the -d option will also require the user name and password of a user with directory permission. To specify the user nand password use the -p option of the voyager utility. The -p option requires a properties file. The properties file should include the following:

policy.server Must be set to true.

directory.url The URL of the directory server.

directory.username Leave blank.

directory.password Leave blank.

security.owner.username Leave blank.

security.owner.password Leave blank.

security.system.username Set to the user name of the system user created in step4.

security.system.password Set to the password of the system user created in step 4.

Voyager Administrator Guide 33

type

ission s

file

objectspace.config.password=usernameobjectspace.config.username=password

where username is the user name of the user that exists in the ACL with directory permission, and password is the password of this user.

Securing the VMC Using a Custom Policy Implementation

Custom security policy implementations can also be used with the Voyager Management Console. See the Voyager Security Developer Guide for information regarding implementing a security policy.

To secure the Voyager Management Console with a custom policy implementationconsole at the command line followed by a file name. For example:

console custom.policy.properties

The file custom.policy.properties should contain the text “objectspace.security.policy.1=” followed by the fully qualified class name of the custom policy implementation.

Securing Voyager Servers Using BasicPolicy

The Voyager BasicPolicy security policy implementation is a security policy that helps the development of secured applications and serves as a reference for domain-specific policy development. Do not deploy production-quality applications with this implementation.

BasicPolicy ensures that a user requesting a service from a Voyager server has permto use that service. BasicPolicy stores users and their access permissions in the AccesControl List (ACL). BasicPolicy obtains the ACL at startup from a Voyager Directory Server. The Voyager Directory Server is specified by a URL read from a properties


up.

ofile.

and

n

loaded by the BasicPolicy during startup. BasicPolicy on a running server will be notified by the VMC when changes are made to the ACL.

To secure a Voyager server, specify the security policy implementation during startVoyager obtains the configuration information from a properties file. Use the -p option when starting a Voyager server to specify the properties file. For example:

voyager -p server.properties 8000

To use BasicPolicy, the file specified with the -p option must contain the following text:

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy, filename

filename is the name of the file with the security properties. For example:

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy,security.properties

Alternatively, you can specify that BasicPolicy be the security policy implementation using the VMC Server Properties tab that defines system properties for a server prUse objectspace.security.policy.1 as the property key and com.objectspace.security.policy.BasicPolicy, filename as the property value where filename is the name of the file with the security properties as above.

The file can contain the following entries:

Note: BasicPolicy on a running server will not be notified of ACL changes if the VMC is run in an unsecure state. The following section explains how to secure the VMCthe Voyager Directory Server using BasicPolicy.

policy.server Must be set to true or false. Set to true on a server. If true,complete all subsequent fields.

directory.url The URL of the directory server.

directory.username The user name the BasicPolicy in the directory server will use to access the directory server. This user should exist ithe ACL on the directory server and be granted DirectoryPermission.

directory.password The password of the user the BasicPolicy in the directory server will use to access the directory server.


to

rties

An example of a properties file for the BasicPolicy follows:

// if true, all subsequent fields must be filled inpolicy.server=truedirectory.url=7000/JNDIdirectory.username=directoryAdmindirectory.password=directoryAdminsecurity.owner.username=securityOwnersecurity.owner.password=securityOwnersecurity.system.username=systemPrincipalsecurity.system.password=systemPrincipal

Clients that use servers secured by the BasicPolicy must also specify BasicPolicy as their security policy. The properties file is optional for the client and should only be usedspecify a security owner if needed. If a properties file is used by a client, policy.server should equal false.

Using Basic Policy with an LDAP Directory Server

To use Basic Policy with an LDAP directory server implementation, add the following properties to the Basic Policy properties file:

security.owner.username The user name of the security owner. The security owner isthe user with permission to access certain security functions on the server. These functions might include setting the default principal. For a complete list of owner permissions, see the Voyager Security Developer Guide.

security.owner.password The password of the security owner.

security.system.username

The user name the system uses to perform secure system actions.

security.system.password The password the system uses to perform secure system actions.

Note: Passwords are stored in clear text, so it is critical that you protect the propefile from unauthorized access on the native platform.


ies

write

The following is an example of a Basic Policy properties file with the above propertadded. In this example, Sun’s LDAP service provider is used:

// if true, all subsequent fields must be filled inpolicy.server=truedirectory.url=//localhost:7000/ACLDirectorydirectory.username=directoryAdmindirectory.password=directoryAdminsecurity.owner.username=securityOwnersecurity.owner.password=securityOwnersecurity.system.username=systemPrincipalsecurity.system.password=systemPrincipalobjectspace.directory.server.implementation=ldap

java.naming.factory.initial=com.objectspace.voyager.spi.jndi.VoyagerContextFactoryjava.naming.security.authentication=simple

Basic Policy uses the directory.username and the directory.password properties as the user name and password to access the directory server. This user must have read and access to the Voyager directory tree. Also the directory.url entry is the URL used by the Basic Policy to access the directory. In this example, //localhost:7000 is the URL to the directory server, and the Voyager directory tree name is ACLDirectory.

To use an initial ContextFactory other than Sun’s, use the objectspace.alternate.factory.initial property.

Property Key Property Value

objectspace.directory.server.implementation ldap

java.naming.factory.initial com.objectspace.voyager.jndi.spi.VoyagerContextFactory

java.naming.security.authentication simple

Note: Voyager servers using BasicPolicy which read the ACL from an LDAP directory server must be restarted for any changes to the ACL to take effect.


cond

the

ACL Installer

Installer is a command line tool used to load a Basic Policy ACL into the directory server. To use installer with an LDAP directory server, pass a properties file name as the separameter when invoking installer. For example:

aclinst //dallas:389/ACL simple.acl ldap.props

The above example specifies a directory server on a machine called dallas that is listening on port 389. The Voyager directory tree name is ACL.

The properties file must contain the following properties:

The following is an example properties file:

java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactoryjava.naming.security.authentication=simple java.naming.security.principal=directoryUserjava.naming.security.credential=userPassword objectspace.directory.server.implementation=ldap

The example properties file uses Sun’s service provider. The user represented by java.naming.security.principal and java.naming.security.credential entries must have read and write access to the Voyager directory tree. To use an initial ContextFactory other than Sun’s, use the objectspace.alternate.factory.initial property.

Property Key Property Value




java.naming.security.principal A simple text string user name that will be used to log into the directory server.

java.naming.security.credential A simple text string password that will be used to log into the directory server.


n h

ess types.

ion . The

Managing the Access Control List

The ACL is a list containing information about the users of the system. The ACL contains the user name, password, and access permissions granted to the user.

After the security service is installed in the VMC, the Security node appears under the VoyagerDirectory node in the tree view on the left side of the VMC main window. Wheyou select the Security node, the security management panels appear on the right wittabs for managing permission types and managing the ACL.

Use the Manage ACL panel to add users, change passwords, and grant users accpermissions. Use the Manage Permission Types List panel to add new permission Use the “Import” button to add users from a file.

Any changes including imports to the ACL are kept locally on the Voyager Management Console client. Press the Accept button to commit changes to the directory server. The accept function commits all changes, including changes to the permisstypes. Press the Cancel button to reload the previous ACL from the directory servercancel function rolls back all changes, including changes to the permission types.


r

user. e a user and

user

Adding and Removing Users

Maintain users from the Manage ACL panel. Add and remove users and change passwords from this panel.

Use the buttons below the “Users” list to add users, remove users, and update usepasswords.

Adding a User

Adding a user creates an entry in the ACL with the user name and password of theTwo users are equal when they have the same user name and password. Thereforcan have multiple passwords, and each ACL entry associated with that user namepassword combination might have different access permissions.

To add a user, press the “Add” button. The following dialog appears requesting thedata. Each field is required.


error

user, ialog

ord.

quired

s

sion n

data.

If the Password and the Confirm Password fields are not equal, an error occurs. Analso occurs when the given user name and password already exist.

Removing a User

Removing a user removes the ACL entry for that user from the ACL. To remove a select the user name from the list, and press the Remove button. A confirmation dis posted to allow the action to be canceled.

Changing a User Password

Changing a user password updates the ACL entry for the user with the new passw

To change a user password press the “Change Password” button, and enter the redata. A confirmation dialog will be posted to allow the action to be canceled.

Adding and Removing Permissions

User permissions are also maintained from the Manage ACL panel. Use the buttonbelow the Permissions list to add and remove permissions from a user.

Adding permissions

Adding a permission adds it to the ACL entry of the selected user. To add a permisto a user principal, select the user from the Users list, and then press the Add buttounder the “Permissions” list. The following dialog appears, requesting the required


t and on.

button.

L the llow

e anel t can

The Permission field is a drop-down list of available access permissions. The TargeActions fields are enabled when the chosen permission requires a target or an actiThe target refers to the entity requiring permission to be accessed. Actions refers to the type of access allowed by the target. For example, a target might be access to a particular file, and the actions might be read/write/execute. Choose the desired permission and enter the required data for that permission, and then press the OK

Removing permissions

Removing a permission from a user removes the selected permission from the ACentry for that user. To remove a permission from a user, select the permission frompermissions list, and press the Remove button. A confirmation dialog is posted to athe action to be canceled.

Adding and Removing Permission Types

If a developer creates a custom permission implementation, it must be added to thPermission Types list before it can be added to a user. Use the Permissions Type pto add and remove permission types. The panel displays the list of permissions thabe added to a user.


ssion

types a ons

class

To add the new permission type, the fully qualified class name of the custom permiis required.

Permission types may also be removed from the Permission Types list. Permissionthat are removed are no longer available to add to a user, but existing instances ofremoved permission type will not be removed from the user principal. Use the buttbelow the Permission Types list to add and remove Permission types.

Adding permission types

To add a permission type, press the Add button under the Permission Types list. Adialog is presented that prompts for the class name of the desired permission. If theis not found or cannot be constructed, an error occurs.


s list, be

he

ort n it is

he

Removing permission types

To remove a permission type, select the permission type from the Permission Typeand press the Remove button. A confirmation dialog is posted to allow the action tocanceled.

Importing Permissions

The Import button allows mass addition of user principals and their permissions. Timport function parses a file with the following format:

grant username "some user" password "users password"{permission com.objectspace.some.Permission "target", "actions";permission com.objectspace.security.policy.SecurityPermission;}; grant username "another user" password "users password"{permission com.objectspace.some.Permission "target", "actions";permission com.objectspace.security.policy.SecurityPermission;permission com.objectspace.security.policy.DirectoryPermission;};

The import merges the users from the imported file into the existing ACL. If the impfile contains a user and password that already exist in the ACL, any new permissiofrom the file is added to the existing user. If a new permission type is encountered,added to the Permission Types list.

To import an ACL file, press the Import button, and then select the file name from tfile dialog.


6
Transaction Service
ns

If a Voyager server was configured with the Transaction service, it has a subfolder named Transactions in its server profile. The panels in this folder are used to configure and monitor the transaction service. See the Voyager Setup Guide for information on how to install the Transaction Service.


� monitor transaction statistics

� view the transaction log

� view active transactions

� view transaction errors

� communicate with the server

Note: The transaction service is only available in the Voyager Transactioand Voyager Application Server products.

45

as it ted. If ding

Monitoring Transaction Statistics

The Statistics panel allows administrators to view the runtime server usage statisticsrelates to transactions. All statistics are relative to the time that the server was starthe server is not running, the value of each field is empty. Any numeric value, incluzero, indicates that the server is up and communicating with the console.

General Transaction Statistics

The following general transaction statistics are available:

� Transactions – total number of transactions begun.

46 Chapter 6 • Transaction Service

es. ce ay

the

sively

� Committed – number of transactions that have been committed successfully.

� Rolled Back – number of transactions that were rolled back.

� Heuristic Outcomes – number of heuristic decisions taken by transactional resourcA heuristic decision is a decision to commit or rollback that is made by a resourwithout waiting for the coordinator to propagate the decision. A large number mindicate excessively long transactions or bigger problems. See "Viewing Transaction Errors" for more information.

� Active Transactions – number of transactions still in progress.

Transaction Duration Statistics

The following transaction duration statistics are available:

� Minimum time – minimum transaction duration in milliseconds.

� Maximum time – maximum transaction duration in milliseconds.

� Average time – average transaction duration in milliseconds.

Viewing the Transaction Log

The transaction log is viewable from the Log panel. From this panel, you can view all transactions that have occurred since the last time the log was cleared. Check the checkbox, and set a date to view only those transactions that have occurred sincespecified date.

Choose the Heuristic outcomes radio button to filter the log so that only heuristic outcomes are viewed. The occurrence of a heuristic outcome indicates that a transactional resource had to make a commit/rollback decision before hearing from the master transaction coordinator. This may happen when the transactions are exceslong due to dropped clients, excessive client think-time, and so forth. A heuristic


ed by
outcome indicates a possible inconsistency in the application that should be resolvmanually synchronizing the resources.
Note: The transaction log grows with each new transaction which can present problems for less robust log implementations. For example, the default log implementation logs to a file. Excessive log file size can result in reduced performance, both for the server and the console. Use the Delete Log button to delete the log and reduce the risk of generating an excessively large log.


, and

Viewing Active Transactions

The Active panel allows administrators to view information about all currently activetransactions. The display shows the transaction id (TID), transaction name (if any)transaction start time. Heavily loaded servers may have many thousands of activetransactions. This panel should be viewed with caution under these conditions.


rative

Viewing Transaction Errors

The errors panel contains a stack dump for all errors that have occurred during anattempt to complete a transaction. Though these stack dumps are of little administvalue, they are important to a developer diagnosing a problem.


ce.

e

ot

Configuring Transactions

The configuration panel allows you to configure transactions.

� Log Address: The URL where the transaction service will locate the logging serviIf the transaction service does not already exist at this location, Voyager will create the transaction service at this URL. This optional feature can be useful if multiplnodes wish to use a single logging service.

� Log Factory: The name of the class implementing the ILogFactory interface that will be created locally (if no Log Address is specified) or remotely (if specified and nalready existing). Do not change this value.

� Service Address: The URL referring to a transaction factory that will create Coordinators and Recovery Coordinators for this node.

Note: This option is not recommended as all transaction effort will result in a significant increase in lag time due to network access.


d

tab

Communicating with the Server

The Transaction Service Console detects whether the remote server is running, ancommunicates directly with that server for statistics and log access. By default, theconsole automatically refreshes every 15 seconds. To turn off the auto-refresh feature, clear the check box. To change the refresh rate, enter it in the refresh rate field andout of the field. To manually refresh the console at any time, click on the Refresh button.


7
JDBC Service
r

d

If a Voyager server is configured with the JDBC service, it has a subfoldenamed JDBC in its server profile. The panels in this folder are used to configure JDBC datasources for a server. See the Voyager Setup Guide for information on how to install the JDBC Service.


� configure datasource properties

Note: The JDBC service is only available in the Voyager Transactions anVoyager Application Server products.

53

ces nce.

oyee

be

the

grows

d a of

Configuring Datasource Properties

The JDBC Service allows the administrator to specify one or more JDBC datasourfor use in the application. A datasource corresponds to a particular database instaDatasource configuration changes are not made on-the-fly. If a modification to an existing datasource is made or if a datasource is added or removed, the server must berestarted to detect the change.

Each of the following properties must be specified to create a valid datasource:

� Name

JNDI name to which the datasource is bound. This name should start with jdbc/ to remain compliant to the JDBC specification. For example, if a database of emplinformation is being configured as a datasource, it should be named jdbc/EmployeeDb.

� Driver

Classname of the JDBC driver. The classname must be fully qualified and mustavailable on the server.

� URL

URL of the database. The URL identifies the actual database instance to whichdriver connects.

� Login ID

Database user on whose behalf connections are made.

� Login PW

Password to use with the database user identity

� Initial Capacity

Number of database connections that should be created upon startup. The pool as needed.

� Growth Rate

Sets the rate at which database connections are created. If the pool is empty anconnection is requested by the application, the datasource creates the number connections specified in this field.

54 Chapter 7 • JDBC Service

m ing

� Max Capacity

Sets the maximum size of the connection pool.

Note: This parameter is not the maximum number of connections; it is the maximunumber of free-pooled connections. If the pool is full, and a connection is bereturned to the pool, the connection is not added, it is closed.


56 Chapter 7 • JDBC Service

8
EJB Service
e

re nt

If a Voyager server is configured with the EJB service, it has a subfolder named EJB in its server profile. Two panels are associated with the EJB subfolder: Statistics and Configuration. Three actions are associated with thEJB subfolder: Start Container, Stop Container, and Insert Jar.

The panels and subfolders in this folder deploy new components, configuexisting components, configure the EJB container, and monitor componeand container statistics. See the Voyager Setup Guide for information on how to install the EJB Service.


� monitor EJB container statistics

� configure the EJB container

� configure an EJB service with an LDAP directory server

� monitor a component’s statistics

� configure a component’s general properties

� view a component’s transactional properties

� set a component’s security properties

� set a component’s environment properties

� view a method’s transactional properties

� set a method’s security properties

57

e time iner

t in

The t add

use

d t

ed by

also

se.

ed tence

e

Monitoring EJB Container Statistics

The Statistics panel provides administrators a means of viewing the run-time serverusage statistics as it relates to Enterprise JavaBeans. All statistics are relative to ththat the server was started. In addition, statistics can be viewed for the entire contaor for a given component. To view statistics on the entire server, highlight the EJB folder in the tree. To view statistics on a given component, highlight that componenthe tree.

The following statistics are available:

� Created – This number represents component instances created in the system. number of active, removed, terminated and timed out component instances musup to this number.

� Active – This number represents the number of component instances currently inby clients.

� Removed – This number represents the number of component instances removenormally. A component instance is removed normally when the client removed ithrough the remove method.

� Terminated – This number represents the number of component instances removthe system. A component instance is terminated when an unhandled RuntimeException is thrown during the execution of one of its methods. Component instances are terminated when an administrator stops the EJB service, disables a particular component, or updates or deletes a jar file while the component instance is in u

� Timed Out – This number represents the number of component instances removbecause they timed out. A component instance times out when it has been in exisfor at least as long as the time-out set for the component. A component instanctypically times out when its client dies unexpectedly.

Note: The EJB service is only available in the Voyager Application Server product.

58 Chapter 8 • EJB Service

By

e

If the server is not running, the value of each statistic is empty. Any numeric value,including zero, indicates that the server is up and communicating with the console.default, statistics automatically refresh every 15 seconds. To turn off the auto-refresh feature, click on the check box. To change the refresh rate, enter it in the refresh rate field, and tab out of the field. To manually refresh the statistics at any time, click on thRefresh button.


be ystem

s to tions

will sole ded.

loy the

ts gure, To

as

nge.

e

Configuring the EJB Container

To configure the EJB container, the home directory URL/logical server name must set before starting the server. The second container configuration property is the sidentity. The system identity must be set when security is required for the server.

The Home Directory URL and Logical Server Name

The home directory is the JNDI directory that clients use to initiate their connectionthe server. This process is known as home lookup, because it involves a JNDI lookup ofthe home object of an EJB component. A description of three deployment configurafor the home directory follow.

� When the home directory is set to be the configuration directory server, all clientsbe performing their home lookup on the directory server that the management conuses to store server configuration information. this configuration is not recommenIt is generally preferred to keep the clients and the administration separate, thereby reducing the risk of security violations, data contamination, and so forth. To depwith this configuration, put the hostname and port of the configuration directory inHome Directory URL field.

� In the server configuration, a server binds its home objects in memory, and clienconnect directly to the server to perform home lookup. This is the easiest to confibut does not scale well. It is considered a reasonably lightweight configuration.

Note: Note for current Voyager 3.0 users: In Voyager 3.1 the logical server name hbeen combined with the home directory URL. For example, if your home directory URL was //dallas.8000 and your logical server name was FooServer, the new home directory URL is //dallas:8000/FooServer. This becomes the full path theserver will use to store home objects. Note that the client code does not chaUsing the above example, the client would create any initial context using //dallas:8000/FooServer for the PROVIDER_URL property.

If Voyager 3.1 is used with directory server data created with Voyager 3.0, thlogical server name will be appended to the home directory URL on the EJBconfiguration panel.


ile is

f ers the kup. r in

he

tart

is

ory

er ical

the

deploy in this configuration, put the hostname and port of the server whose profbeing edited in the Home Directory URL field.

� When a second directory server runs, the directory server is dedicated to the task oproviding clients with home lookup. A directory server is started, and multiple servare configured to bind their homes into this directory. This configuration removesburden of home lookup from each server but allows for a centralized directory looTo deploy with this configuration, put the hostname and port of a directory servethe Home Directory URL field. Start this directory before starting the servers.

For all configurations, set the Logical Server Name to some value. This value does nothave to be the same name as the server profile name. They are usually different. Tlogical server name provides an abstraction layer between the physical server andclients. This name can be any string, as long as it is unique to the server.

Changes to the directory URL and server name do not affect a running server. Resthe server to take advantage of the modified settings.

The logical server name becomes a JNDI context into which all home objects for thserver are bound. Clients can therefore connect to the URL created by the concatenation of the home directory URL and logical server name. For example, assume the directis on the local host, the logical server name is FooServer, and the bean home name is FooHome. The following code allows a client to look up the home object:

Hashtable env = new Hashtable();env.put( Context.PROVIDER_URL, "//localhost:8000/FooServer" );InitialContext ctx = new InitialContext( env );IFooHome home = (IFooHome) ctx.lookup( "FooHome" );

Note: Future versions of Voyager will allow multiple servers to share a logical servname. In this configuration, a logical server name includes a cluster of physservers to support load-balancing and fault-tolerance.

Note: If the Voyager server and the Directory Server are running in the same VM, logical server name should not be set to anything.


ry ate sed, e ase

n

Finding Home Objects

When using JNDI to find EJB home objects in an LDAP directory server, the objectspace.directory.server.implementation property must be added to the JNDI properties Hashtable prior to creating the initial context and looking up the home object for the bean. Its value must be ldap. For example:

java.util.Hashtable properties = new java.util.Hashtable();properties.put( java.naming.Context.INITIAL_CONTEXT_FACTORY, “com.objectspace.voyager.jndi.spi.VoyagerContextFactory” );properties.put( “objectspace.directory.server.implementation”, “ldap” );

Voyager’s initial context factory must always be specified as the INITIAL_CONTEXT_FACTORY property. When using Voyager with a naming or directoryimplementation other than Voyager Directory Server, Voyager’s initial context factowill delegate the creation of initial contexts to an initial context factory from an alternservice provider, such as Sun’s LDAP provider. If an alternate service provider is uVoyager will add Voyager-specific functionality to the initial context returned from thalternate service provider’s initial context factory before returning it to the client. Plerefer to the Voyager Administration Guide Addendum for more information regarding JNDI configuration.

When used with LDAP, Voyager will use Sun’s LDAP service provider by default. Aalternate LDAP provider can also be used. To use an initial context factory from analternate service provider when accessing LDAP servers, add the objectspace.alternate.factory.initial property to the JNDI properties Hashtable. For example:

java.util.Hashtable properties = new java.util.Hashtable();properties.put( java.naming.Context.INITIAL_CONTEXT_FACTORY, “com.objectspace.voyager.jndi.spi.VoyagerContextFactory” );properties.put( “objectspace.directory.server.implementation”, “ldap” );properties.put( “objectspace.alternate.factory.initial”, “com.some.alternate.LDAPContextFactory” );


ode

active e or e is k. ore

using not

System Identity

The container uses the System Identity field when a component’s security run-as mis set to System. The field allows a component to invoke another component as the system. The field is also used to connect to the home directory and should have directory permissions when the directory is secured.

Administrators can stop all usage of EJB components by clicking on the Stop button (for example, to perform server maintenance). Stopping the EJB container removes all component instances, and component instances are identified as Terminated in thStatistics panel. If the component instance is associated with a container-managedbean-managed transaction, the transaction is rolled back. If the component instancassociated with a client-managed transaction, the transaction is marked for rollbacAny component instances in the process of fulfilling a client request completes befbeing removed. To restart the EJB Container, click on the Start button.

New components are deployed into a system from the standard EJB jar file format the Insert Jar button. The server does not need to be running. The components areenabled until the administrator explicitly enables each component, allowing the


he

a jar: enu

s in

administrator to fully customize the home name, session time-out, environment properties, and security properties before the components are available to clients.

To insert a jar into the EJB Service, click on the Insert Jar button. A dialog opens askingyou to find the jar file in your file system. When inserting a jar, any errors found in tcomponents are written to the output panel. If any errors occur that prevent the component from running in the EJB Service, the component is not added.

A node is in the directory tree for each jar deployed into a server. No panels are associated with managing jar files. However, there are two actions associated withUpdate and Delete. These actions are available from the tool bar and from pop-up massociated with the jar node.

A deployed jar file must be updated as new versions of its components are released. To update a deployed jar file, click on the jar node in the tree and then click on the Update button. Select the new version of the jar file from the file system. If any of the classe


g jar lly

. the he

ver,

k on n

are n is n, the

nent you To

the jar file changed, stop the server while the jar file is being updated. When updatinfiles, if a component was already deployed and is being updated by the jar file, thefollowing properties are not updated, because the deployment information is typicamore appropriate.

� Bean Home Name

� Session Timeout

� All Security Properties

The following properties use the values from the new jar file:

� Bean Class

� Home Interface

� Remote Interface

� Bean Type

� All Transaction Properties

Environment properties merge, and new properties from the new jar file are addedProperties removed from the new jar file are removed. Properties that exist in bothdeployed jar and the new jar file use the deployed jar file’s values, because since tappropriate values are better known at deployment time, they are kept.

The Update Jar action can be performed whether or not the server is running. Howechanges are not reflected in the server until it is restarted.

To delete a deployed jar file, click on the jar node in the directory tree, and then clicthe Delete button. Deleting a jar removes all of its components from the configuratiodirectory. It also removes all of its components from the server when the server is currently running. If any of the components have active instances, these instancesremoved and identified as Terminated in the statistics panel. If a component instance isassociated with a container-managed or bean-managed transaction, the transactiorolled back. If a component instance is associated with a client-managed transactiotransaction will be marked for roll back. Any component instances that are in the process of fulfilling a client request complete the request before being removed.

The component nodes allow administrators to configure those aspects of a compothat are not design decisions. Configuration changes do not immediately take affect,must click on the Apply button first to apply all changes to the deployed component.


cancel your changes, click on the Cancel button. The statistics refresh rate takes effect immediately, and does not require pressing the Apply button.


I

nable rties.

Configuring an EJB Service with an LDAP Directory Service

The EJB service configuration panel in the VMC allows the user to specify the JNDenvironment properties of the directory server that will contain the home objects.

To specify that bean home objects should be stored in an LDAP directory server, ethe Replace System Properties check-box, and enter the necessary system propeThe following table summarizes the properties that must be specified.


Other properties may be required depending on the JNDI service provider and theLDAP directory server implementation.
To use an initial ContextFactory other than Sun’s, use the objectspace.alternate.factory.initial property.

Key Value




java.naming.security.principal A simple text-string user name that will be used to log into the directory server.

java.naming.security.credential A simple text-string password that will be used to log into the directory server.


ctive

Monitoring a Component’s Statistics

The statistics provided in the component Statistics panel are identical to the statistics provided in the EJB container Statistics panel except that the statistics provided here apply to the currently selected component only. For example, the Active statistic relates the current number of active instances of this component, not the total number of ainstances across all components.


Configuring a Component’s General Properties

The General panel contains general properties about the component, which include thebean class, home interface and remote interface specified at creation as well as the beanhome name, bean type, and time-out.


n

by the nce. urces

the

Home Name

Clients can create a component instance by placing its home object in a well-knowlocation in JNDI. The bean home name specifies the JNDI location where the home object should be put. Clients must know this name to create an instance.

Bean Type

The bean type is determined during design. This information is not editable by administrators and is displayed for informational purposes only.

Specifying the Session Timeout

Session components are used for a period of time by the client and then removed client. A problem occurs when the client dies before removing the component instaThe component instance never gets removed and therefore consumes server resounnecessarily. This is exactly the problem that time-outs are intended to solve. Thetimer starts when the component instance is created. If the component instance has not been removed by the time the time-out has finished, it is automatically removed bysystem. The default time-out is 24 hours.


.

Viewing a Component’s Transactional Properties

The transactional properties of a component are viewable from Transactions panel. These properties are decided during design, so an administrator cannot alter them


a

th

Setting a Component’s Security Properties

Use the Security panel is used to set the security properties for a component. Two aspects of security are managed by the EJB container:

� The container allows or denies access to a component or particular methods oncomponent based on the identity of the client

� The EJB container sets the identity that is used when a component interacts wianother component. The identity is compared to the client identity based on thesecurity policy.


d

he the

tity to

t

Allowed Identities

The users in the Allowed Identities list are the only users that can access the specifiecomponent or method. The one exception to this rule is that if no users are in the list, everyone has access to the component. To insert a new allowed identity, click on tInsert button, and select the correct user. To remove an allowed identity, select it inlist, and click on the Remove button.

When calling other components, choose one of three options to determine the idenuse:

� Client Identity – If Client Identity is chosen, the identity associated with the currenclient is used when interacting with other components.


ified

. For ion of llow nt er. ime.

� System Identity – If System Identity is chosen, the system identity is used when interacting with other components. The system identity is a special identity specby Voyager that has system privileges.

� Specified Identity – If Specified Identity is chosen, the administrator-specified useridentity is used when interacting with other components. By default, this is None, which means that no identity is used. To select a specified identity, click on the Specified Identity radio button to select the mode, click on the Browse button, and select the correct user identity. Specified Identity is the default value for interacting with other components, with no specified identity. As a result, no identity is propagated to called components by default.

Setting a Component’s Environment Properties

When developing a component, properties cannot be determined until deploymentexample, a component might use JDBC to interact with a database. Leave the locatthe database open, so that it can change at deployment. Environment properties aadministrators to specify runtime characteristics of the component. The environmeproperties that are used are completely at the discretion of the component developTypically, default values for the environment properties are put in at development tThe administrator then customizes the values.


e. To

new d as

on is

k on

To insert a new environment property, click on the Add button and insert a new row. Tochange the property name or value, click on the cell, and type the new name or valuremove a property, click on any cell in the row, and click on the Remove button.

Administrators can stop all usage of an EJB component by clicking on the Disable button (for example, to perform maintenance). Disabling a component prevents anyclient connections and removes all active component instances which are identifieTerminated in the statistics panel. If the component instance is associated with a container-managed or bean-managed transaction, the transaction is rolled back. If the component instance is associated with a client-managed transaction, the transactimarked for roll back. Any component instances that are in the process of fulfilling aclient request complete the request before removal. To restart the component, clicthe Enable button.


the vel.

of a ble and

that

The method nodes let administrators view and configure component properties at method level. These properties override the settings specified at the component le

Note: It is now possible to select multiple beans for simultaneous enable/disable.

Note: The Enable/Disable state of a component is persistent. The Start/Stop statecontainer is not maintained across server restarts, whereas the enable/disastate of a component is maintained. For example, if a component is disabledthe server is later taken down, the component is still disabled the next time server is restarted.

Note: A method that overrides a component’s properties with custom properties isindicated in the directory tree with a different icon.


e by

Viewing a Method’s Transactional Properties

The transactional properties of a method are viewable from Transactions panel. These properties may override the component’s properties. This information is not editabladministrators and is displayed for informational purposes only.


of etail a e on a

Setting a Method’s Security Properties

The method’s Security panel allows administrators to specify security at a finer level detail than is possible by setting security properties on the component level. This dis when particular component actions must be restricted to a subset (or opened to superset) of the clients capable of accessing the component. Security settings madmethod override the settings specified at the component level.


Admin

Documents

Transcript of Admin