Administration Guide

JOnAS provides two tools to perform some administration tasks on a running JOnAS Server.
These tools allow to administrate several JOnAS Servers.
Each JOnAS Server is identified by a name which is the value of the JOnAS property jonas.name (default name is jonas).

The administration tools are:

jonas admin, which is a command line tool, and
Jadmin, which is a graphical tool.

How to install Jadmin ?
How to use Jadmin
How to customize Jadmin

The target audience of this guide is the JOnAS server administrator.

jonas admin

jonas admin is described in the JOnAS Commands chapter.

Jadmin

Server-side component model and middleware services are about to become a major stake today. That is why an application server such as JOnAS has to provide management and monitoring features.

This chapter provides information for installing, configuring and using the Java Management Extensions features of JOnAS called Jadmin for JOnAS administrator.

Jadmin is an administration tool developed with the Java servlets technology, so it is accessible with a web browser.

Since JOnAS2.5.3 JOnAS can use either Tomcat or Jetty servlet container in the same JVM as JOnAS. You only have to launch JOnAS with the tomcat or jetty service.

How to install Jadmin ?

The Sun JMX Reference Implementation is included in the jar files JOnAS delivery, so you have nothing to do about that.

Since the tool consists of servlets, you have to install a servlet server. In the following, it will be considered that you use Tomcat (either version 3.3 or 4.0.3) or Jetty. Tomcat installation and configuration are documented in the Tomcat user's guide. You may fin a quick installation guide for Tomcat with JOnAS in the Use Tomcat with JOnAS howto document.

The steps for installing Jadmin in Tomcat are described below:

First of all, you have to copy the $JONAS_ROOT/webapps/jadmin.war file in the $TOMCAT_HOME/webapps directory, or modify the $TOMCAT_HOME/conf/server.xml file in order to make Tomcat load the jadmin.war file on startup.
When accessing a Jadmin servlet, the user must identify and authenticate himself. Therefore, she/he must specify the jadmin role in the tomcat-users.xml file in the $TOMCAT_HOME/conf/users directory for Tomcat 3.3.x or in the $TOMCAT_HOME/conf/ directory for Tomcat 4.0.x:
```
<tomcat-users>
  <user name="jadmin" password="jonas" roles="jadmin,tomcat" />
  ...
</tomcat-users>
```
Of course, you can set another password.
For using Jadmin with Jetty:
- The default behavior of the jetty service is to use the jetty configuration file found under JONAS_ROOT/config directory and to launch the jadmin.war file found under JONAS_ROOT/webapps so no extra manipulation is needed.
- For authentication the JONAS_ROOT/config/jettyRealm.properties file is used and it is correctly set for using Jadmin. If you want to set another password you must modify this file.

How to use Jadmin ?

Be sure you have set tomcat or jetty in the jonas.services property in the jonas.properties file. Depending on the Servlet container you want to use you must set TOMCAT_HOME (for Tomcat3.3), CATALINA_HOME (for Tomcat4.0.3) or JETTY_HOME (for Jetty 4.0.4) environment variable.

Once you have launched JOnAS, Jadmin is accessible at this URL: http://<hostname>:<portnumber>/jadmin/ on your favorite web browser.

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

The first page you see after clicking on the entering page is the following:

Choosing the registry

The registry URL corresponding to your JOnAS configuration is displayed in the "Registry URL" text area. Note that if you have several EJB servers running and using different registries, you have the possibility to set the registry URL in order to manage the corresponding EJB servers.

If you have several JOnAS servers running on the same registry, they will appear in this page, and you will be able to choose which one you intend to manage (check button). The management information appearing in the different Jadmin pages will be related to the selected JOnAS server. For example in the figure above, two JOnAS servers are running, one is named jonas, the other one is named jonas_srv2, and the first one is selected. The name of a JOnAS server is specified in its jonas.properties configuration file, in the property jonas.name.

The following of this section explains the general principles of the graphical user interface of Jadmin.

The interface is divided in thumb indexes: one index for each service (container, database, resource, transaction, log, JMS, and security), one index for the EJB server monitoring and a last one for the MBeans. Note that on each page you will always find the Choose another JOnAS server or change the Registry link that will allow you to come back to the Jadmin entering page, and thus to change the registry, to change the managed server or to stop a server.

The picture above shows the thumb indexes and the top banner.

Since most of the management operations are not idempotent, the user should not use the browser reload button, but the Refresh link in the top banner.

Some thumb indexes are organized as tree structures. For example:

From the container index, you access the container service view.
From this view, you can access a specific container view.
Then, you can access a specific EJB view.

This picture shows an example of the tree structures for the container index.

This example shows the browsing tree (the user is currently looking at the 'AlarmListenerBean' EJB in the EJB container 'Alarm').

The JOnAS administration interface consists of JMX attributes and operations. Attributes could be readable and/or writable. When an attribute is writable, it is displayed in a text input area and there are two buttons beside it (the reset button reset the text input with its initial value, the submit button sends the new value to the server).

In this example, the Current transaction time out attribute is readable and writable. The three others attributes are only readable.

Sometimes, writables attributes are presented with a check box or a radio box, it depends on the attribute type (if it is a boolean for example).

Operations are presented as boldface characters links. When an operation needs a parameter, it is presented with an input text area and a button.

This picture shows the Remove operation, which is applicable on the EJB container Alarm, and the Load operation with a string parameter.

The All MBeans index thumb displays the exhaustive list of all MBeans.

One management operation is especially important, it is the possiblility to load a container from the Jadmin console. This is available in the Container index, via the "ejb-jar deployment descriptor or jar file" text input area:

The Container loading facility

In the text area, you should put

the name of an deployment descriptor file: either you give the complete path or just the name if the file is in the directory where the EJB server has been launched.
the name of an EJB jar file: either with the complete path, or just the name if the file is in the directory where the EJB server has been launched or if it is in the JONAS_ROOT/ejbjars directory.

How to customize Jadmin ?

Jadmin use theVelocity Template Engine that allows the user to customize the Jadmin aspect.
Velocity templates used by Jadmin are packaged in the jadmin.war located in $JONAS_ROOT/webapps.

For example in order to change the background color of the Jadmin panels you must:

unjar the jadmin.war
modify in the file templates/defs.vm the line #set ($cell_color = '"#C0C0C0"')
jar the new jadmin.war and install it in $JONAS_ROOT/webapps.