Administration Guide

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

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 provided administration tools are:

jonas admin, which is a command line tool, and
Jadmin, which is a graphical tool based on the JMX technology.

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

Moreover, since the MX4J open source JMX implementation was integrated in JOnAS, the server administrator can also used the MC4J generic administration console.

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 Jadmin administration console.

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

Since JOnAS 2.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 web, tomcat or jetty service.

How to install Jadmin ?

The JOnAS delivery include jar files for Sun JMX Reference Implementation and for the MX4J open source JMX implementation. The choice, for the JOnAS server, between the two implementations is made in the JOnAS configuration file as explained in the Configuring JOnAS services chapter. Concerning Jadmin configuration, currently a new configuration file is provided in $JONAS_ROOT/config/ directory: the Jadmin.properties file. The value of the Jadmin.ConnectorFactory.class property must be consistent with the chosen JMX implementation:

org.objectweb.jonas.jmx.vjadmin.ManagementReprImpl if using SUN RI
org.objectweb.jonas.jmx.vjadmin.Mx4jManagementReprImpl if using MX4J

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 find 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:

If you are using the "web container service", go directly to the next step. Else, if you are using the deprecated Tomcat service, you have to copy the $JONAS_ROOT/webapps/jadmin.war file in the $TOMCAT_HOME/webapps directory, or to 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 one of web, 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. We noticed that when running the Servlet container on top of Unix, the DISPLAY environment variable must be set in order to use the JOnAS server monitoring feature of Jadmin.

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 JOnAS servers running and using different registries, you have the possibility to set the registry URL in order to manage the corresponding 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. You may stop a JOnAS server using the provided link, if the jadmin.war containing the Jadmin application components was not loaded in that server. That's the reason why, in order to really stop the server, you should click a second time on the stop link after the alert message was printed.

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 the server monitoring, one index for each service, one for the logging system management, and a last one for the MBeans.
Note that you can go back to the Jadmin Home Page from any other page, allowing 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 EJB 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 'SessionMailer' EJB in the EJB container 'mailsb').

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 element 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.

In some cases, JMX attributes allow to modify a set of configuration properties. For example, suppose you need to configure a Mail Factory ressource loaded by the Mail Service. The configuration properties used to create the javax.mail.Session object are presented in a TEXTAREA element as shown in the picture below. If you need to define a new property, add a string containing the name of the property followed by '=' and then, by the property value, ending with ';'.

In this example, the Mail Session configuration properties are presented in a TEXTAREA element.

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 'secusb', 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 possibilility to load stand alone J2EE components (jar or war packages) or J2EE applications (ear packages) from the Jadmin console. These functions are provided by the Container Service, Web Service and Ear Service respectively. For instance, in order to load one of the provided example samples (sb, eb, etc.), click on the Container Service index, and use 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.