Administration Guide

JOnAS Team

Adriana Danes


1. Introduction
1.1. Terminology
1.1.1. Server or JOnAS instance
1.1.2. Service
1.1.3. Container
1.1.4. Domain
1.1.5. Master server
1.1.6. Cluster
1.2. Administration targets
1.3. Administration tools
1.4. Administration functions
1.4.1. Server administration
1.4.2. Domain administration
1.4.3. Cluster administration
2. JonasAdmin
2.1. Installing JonasAdmin
2.2. Using JonasAdmin
2.2.1. Running JonasAdmin
2.2.2. Server management
2.2.3. Note regarding persistent reconfiguration facilities
2.2.4. Domain management
3. The administration components
3.1. Management EJB Component
3.2. The JOnAS MBeans
3.2.1. Standard MBean
3.2.2. Other MBeans MBeans
4. JMX Remote connectors support
4.1. JSR 160 support in JOnAS
4.1.1. Target Audience and Rationale
4.1.2. What is JSR 160 ?
4.1.3. Connector servers created by JOnAS

Introduction

1.1. Terminology

1.1.1. Server or JOnAS instance

A server, or JOnAS instance, is a java process started via one of the jonas bootstrap or jonas start commands, or via the administration tool Java EE.

Several servers may run on the same physical host.

1.1.2. Service

When a server starts, services are started.

A service typically provides system resources to containers. Most of the components of the JOnAS application server are pre-defined services. However, it is possible and easy for an advanced user to define a new service and to integrate it into JOnAS.

JOnAS services are manageable through JMX.

1.1.3. Container

A container consists of a set of Java classes that implement the Java EE specification. The role of the container is to provide the facilities for executing Java EE components.

There are three types of containers:

  • EJB container in which Enterprise JavaBeans are deployed and run

  • Web container for JSPs and servlets

  • Client container

1.1.4. Domain

A domain represents an administration perimeter which is under the control of an administration authority.

This perimeter contains management targets like servers and clusters.

If a domain contains several elements, it provides at least one common administration point represented by a master server.

1.1.5. Master server

A master is a JOnAS instance having particular management capabilities within the domain:

  • it is aware of the domain's topology

  • it allows management and monitoring of all the elements belonging to the domain

1.1.6. Cluster

A cluster is a group of JOnAS servers having common properties within a domain. It usually allows to run a J2EE application, or a J2EE module, on the cluster members as if they were a single server. The objective is to achieve applications scalability and high availability.

JOnAS supports several cluster types:

  • Clusters for Web level load-balancing

  • Clusters for high availability of Web components

  • Clusters for EJB level load-balancing

  • Clusters for high availability of EJB components

  • Clusters for JMS destination scalability and high availability

  • Clusters for administration purpose which facilitate management operations like deployment /undeployment.

From the administrator point of view, a cluster represents a single administration target.

Note that a particular JOnAS server may belong to zero, one or more clusters.

1.2. Administration targets

This section presents the possible targets of a JOnAS administrator. An administrator may act on the following targets:

  • An individual JOnAS server.

  • A management domain.

  • A management cluster.

The servers composing a management domain can be grouped into one ore more clusters. These are clustered servers. A domain may have clustered and un-clustered servers.

Each target is identified by a unique name.

  • A JOnAS server name is given by the value of the -n option used in the jonas start command (the default name is jonas).

  • The domain name is given by the value of the domain.name environment variable (by default, a server is started in a domain having the server's name). See How to configure a domain for more details.

  • The naming of the clusters depend on configuration parameters which are different for the different cluster types.

1.3. Administration tools

This section presents the means offered to a JOnAS administrator to act on an administration target:

  • The JOnAS commands, particulary the jonas admin command.

  • Management applications deployed on a JOnAS server. This may by the JonasAdmin web application, or any custom J2EE management application based on the Section 3.1, “Management EJB Component”.

  • Any generic JMX management console connected to a target server via a JMX Remote Connector Section 4.1, “JSR 160 support in JOnAS”.

  • WebService clients using the WebService end-point exposed by the Management EJB

  • Other mechanisms like ant tasks.

1.4. Administration functions

This section presents the operations provided to the JOnAS administrator.

These operations depend on the management target.

1.4.1. Server administration

JOnAS administration mainly provides monitoring and configuration functions. Moreover, administrator can dynamically install/deploy/undeploy applications and/or resources on a running server.

All the functions are proposed by the JonasAdmin application, wereas the jonas admin command supports only a part of these functions.

1.4.2. Domain administration

Domain administration is mainly based on JonasAdmin.

It allows consulting the domain map (shows the servers and clusters in the domain) and modify this map.

Moreover, monitoring of the domain is provided: shows state evolution of servers and clusters, and statistics on resources used by the different servers in the domain.

Finally, dynamic install/deploy/undeploy operations are extended at the domain level: the applications source is the administaror server and operation's target may be one ore more servers and/or clusters in the domain.

1.4.3. Cluster administration

Administrator may create clusters, add and/or remove servers to/from clusters. Allowed operations depend on the cluster type.

JonasAdmin

JonasAdmin is an administration tool providing a user friendly graphical console.

JonasAdmin was developed using the Struts framework; it uses standard technologies such as Java Servlets and JavaServer Pages and JMX.

2.1. Installing JonasAdmin

As with any web application, JonasAdmin requires a servlet server to be installed. Make sure that the web service is listed in the jonas.services property in the jonas.properties configuration file.

Designed as a web application, JonasAdmin is packed in a WAR and installed under the JONAS_BASE/deploy/ directory.

Once the server started, JonasAdmin is automatically deployed if the depmonitor service is activated. Otherwise, JonasAdmin can be deployed manually using the jonas admin command.

When accessing JonasAdmin, the administrator must provide identification and authentication. The jonas-realm.xml configuration file contains a memory realm definition named memrlm_1 , which is referenced in both server.xml (for Tomcat) and jetty.xml (for Jetty) configuration files. The default user name ( jonas ) and password ( jonas ) corresponding to the admin role can be modified here.

2.2. Using JonasAdmin

Once started, JonasAdmin can administer the JOnAS server in which it is running. If the host server is a master, JonasAdmin can also administer the rest of the servers running in the domain.

2.2.1. Running JonasAdmin

Once the JonasAdmin application deployed on a server, the administration console is accessible at the URL: http://<hostname>:<portnumber>/jonasAdmin/ using any web browser.

<hostname> is the name of the host where the Servlet container is running and <portnumber> is the http port number (default is 9000).

After logging in, the left-hand frame in the Welcome page displays the management tree associated with the JOnAS server running JonasAdmin. The management tree's root is Domain , which allows to the domain management facilities in case of a master server.

In the image below, JonasAdmin is running on the master server named jonas within a domain also named jonas. It is immediately apparent that this is a master server, as we have a Monitoring and a Deployment sub-tree under the Domain root node.

The management tree in this figure allows access to the following main management facilities:

  • Domain administration with domain level deployment facilities.

  • Current server administration

    • Server monitoring

    • Logging management

    • Communication protocols management

    • Active services presentation and configuration

    • Dynamic deployment at the current server level

    • Resources management

    • Security management

  • Joram platform administration

  • MBeans browsing

2.2.2. Server management

Displays general information about the administered JOnAS server, including the JMX server and the WEB server, and provides the capability of listing the content of the Registry.

2.2.2.1. Server monitoring

Presents memory usage, a count of the threads created by JOnAS, and other monitoring information concerning managed services and resources.

2.2.2.2. Logging management

Allows the administrator to configure the JOnAS Logging system. Additionally, if Tomcat is used as the WEB container service implementation, it allows creation of new access log valves.

2.2.2.3. Communication protocols management

This management facility relates to the integration of Tomcat management in JonasAdmin. It currently presents connectors defined in the Tomcat configuration and allows for the creation of new HTTP, HTTPS, or AJP connectors. Note that the Protocols sub-tree is not presented if Jetty is used as the WEB container service implementation.

2.2.2.4. Active services presentation and configuration

All the active services have a corresponding sub-tree in the Services tree.

Managing the various container services consists of presenting information about the components deployed in these containers. New components can be deployed using the dynamic deployment facilities presented in the next section.

Similarly, the services that allow management of the different types of resources (DataSources, Resource Adapters and Mail resources) also provide information about the resources being deployed. Additionally, deployed resources (DataSources or MailFactories) can be reconfigured and their new configuration made persistent by using a Save button.

The transaction service management allows reconfiguration (possibly persistent) and presents monitoring information about transactions managed by JOnAS.

2.2.2.5. Dynamic deployment with JonasAdmin

A very useful management operation is the capability of installing (upload), deploying, undeploying or removeing stand-alone J2EE components (JAR, WAR, RAR packages) or J2EE applications (EAR packages) in the administered server using the Deployment sub-tree.

The administrator's task is facilitated by the display of the list of deployable modules, the list of deployed modules, and the capability of transferring modules from one list to another (which corresponds to deploy/undeploy operations.

The deployable modules can be installed in directories specific to their type, for example, the deployable JARs are un-deployed JARs installed in JONAS_BASE/ejbjars/ directory, or in the JONAS_BASE/deploy directory.

The Deployment sub-tree also allows a J2EE package to be uploaded from the local file system to the corresponding directory of the administered server ( install operation), and the opposite remove operation.

2.2.2.6. Resources management

The Resources sub-tree provides the capability of loading or creating new resources managed by the active services.

2.2.2.7. Security management

The Security sub-tree presents existing security realms and allows the creation of new realms of different types: memory, datasource, and ldap realms.

2.2.3. Note regarding persistent reconfiguration facilities

It is important to note that JOnAS and Tomcat have different approaches to reconfiguration persistency. In JOnAS, every Save operation is related to a service or a resource reconfiguration. For example, the administrator can reconfigure a service and a resource, but choose to save only the new resource configuration. In Tomcat, the Save operation is global to all configuration changes that have been performed. For example, if a new HTTP connector is reconfigured and a new context created for a web application, both configuration changes are saved when using the Save button.

2.2.4. Domain management

First recall that domain management functions are accessible only when JonasAdmin is deployed on a master server. The Domain tree contains only one Server sub-tree, the currently administered server, which is initially the server hosting JonasAdmin.

Domain management principal function is to present the domain topology: list all the servers and clusters belonging to the domain. It also allows modification of the domain topology by adding new servers and clusters to the domain, removing servers and moving servers to/from clusters.

The domain management page also presents servers that are not yet started but are specified as belonging to the domain in the new configuration file named domain.xml . Also, a server can be added to the domain when it has been started without having the discovery service enabled.

An essential domain management function is that the administrator can switch from the master to any of the other servers in the domain. Currently, JonasAdmin allows only one category of global domain level management operation, the deployment operation. Using any other management operation requires switching to the server to be administered.

Domain level deployment allows for deploying one or more J2EE packages (JARs, WARs, RARs or EARs), which are installed in the corresponding master directory (ejbjars, webaps, rars or apps), into any running server in the domain. A deployment operation target may be a server but also a cluster. The deploy operation may have three semantics:

  • deploy only (create container) - which is useful when the package is already installed on the target server.

  • distribute only - which means install the package in the target's corresponding directory

  • distribute and (re)deploy the package, with optionally replacing the current package with the new one.

Note that at domain level deployment the Upload and Remove operations are only related to the master server itself.

The administration components

3.1. Management EJB Component

The MEJB is specified by the J2EE Management Specification which defines the J2EE Management Model.

The MEJB component exposes the managed objects within the JOnAS platform as JMX manageable resources (MBeans). It is packed in an ejb-jar file installed in the JONAS_ROOT/deploy directory, and therefore it can be loaded at server start-up.

The MEJB component is registered in JNDI under the name java:comp/env/ejb/MEJB .

3.2. The JOnAS MBeans

JOnAS administration is based on the standard MBeans defined by the J2EE Management Specification, and on more MBeans provided by JOnAS itself and by components integrated integrated in JOnAS: Tomcat/Jetty server, JORAM platform, JMX Server, etc.

3.2.1. Standard MBean

All the MBeans defined by the J2EE Management Specification are provided by JOnAS. These MBeans respect the naming conventions and are registered in the JMX server embeded in any JOnAS instance.

3.2.1.1. J2EEServer

The J2EEServer MBean provides attributes and methods for the server management. For example, it supports resource and application deployment. It also provides server configuration and monitoring information.

3.2.1.2. J2EEDomain

The J2EEDomain MBean provides domain management operation support. Most of the exposed operations are usefull only in the case of a master instance.

3.2.2. Other MBeans MBeans

Proprietary MBeans are registered by JOnAS and by the integrated components in order to allow management of services or specific resources.

JMX Remote connectors support

4.1. JSR 160 support in JOnAS

4.1.1. Target Audience and Rationale

JOnAS provides support for remote connection to the MBean server in a standard way based on the JMX Remote API.

4.1.2. What is JSR 160 ?

The JSR 160 specifies the JMX Remote API which extends the JMX specification by providing a standard way to connect to remote JMX-enabled applications.

Currently, JSR 160 has defined a mandatory connector based on RMI (that supports both RMI/JRMP and RMI/IIOP).

4.1.3. Connector servers created by JOnAS

JSR 160 support implies providing standard connector server objects. The JMX service creates at start-up one or several such objects, depending on the protocols configuration (defined in carol.properties file). To create a client connector, the client side needs to know the URL of the connector server. Below we present the URLs that can be used by the clients depending on the protocol they choose.

Currently only 2 protocols can be used by JSR-160 connectors: RMI/JRMP and RMI/IIOP.

4.1.3.1. Using a RMI/JRMP Connector

This connector can be used if the jrmp protocol is set in the carol.protocols list.

The client has to construct a JMXServiceURL using the following String , possibly modified according to the JOnAS-specific configuration: service:jmx:rmi:///jndi/rmi://host:port/jrmpconnector_ jonasServerName where host is the host on which is running the JOnAS server to be managed. The port number is given in the carol.properties file.

Then, a JMXConnector has to be created and connected to the connector server using the JMX Remote API.

4.1.3.2. Example 1:


  Hashtable environment = null;
  JMXServiceURL address = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://host:1099/jrmpconnector_jonas");
  JMXConnector connector = JMXConnectorFactory.newJMXConnector(address, environment);
  connector.connect(environment);
      

4.1.3.3. Using a RMI/IIOP Connector

This connector can be used if the iiop protocol is set in the carol.protocols list.

The client code is similar to the JRMP case, but the String to be used to construct the JMXServiceURL must adhere to the following model: "service:jmx:iiop:///jndi/iiop://host:port/iiopconnector_ jonasServerName"

4.1.3.4. Example 2:


  Hashtable environment = null;
  JMXServiceURL address = new JMXServiceURL("service:jmx:iiop:///jndi/iiop://host:2001/iiopconnector_jonas");
  JMXConnector connector = JMXConnectorFactory.newJMXConnector(address, environment);
  connector.connect(environment);