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

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 its GUI is accessible with a web browser.
Designed as a web application, it is packed in a WAR and installed under the JONAS_ROOT/webapps/autoload directory. You may install jadmin.war in JONAS_BASE/webapps/autoload if you have defined JONAS_BASE variable in your environment. Starting a JOnAS server in this environment will also start Jadmin. Once started, Jadmin can administrate not only the JOnAS server within which it is running, but also other JOnAS servers running on the same or on different hosts.

Since JOnAS 2.5.3 JOnAS can use either Tomcat or Jetty Servlet container in the same JVM as JOnAS.

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 between the two implementations is made in the JOnAS configuration file as explained in the Configuring JOnAS services chapter. Concerning Jadmin configuration, a Jadmin.properties configuration file is provided in the $JONAS_ROOT/conf directory. 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 (4.1.x) 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:

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 $CATALINA_BASE/conf directory for Tomcat 4.1.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 web service for jetty is to use the jetty configuration file found under JONAS_ROOT/conf directory and to launch the jadmin.war file found under JONAS_ROOT/webapps so no extra manipulation is needed.
For authentication the JONAS_ROOT/conf/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.

Run Jadmin

Be sure the web service is listed in the jonas.services property in the jonas.properties configuration file. Depending on the Servlet container you want to use, you must have set CATALINA_HOME (for Tomcat4.1.x) or JETTY_HOME 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).

Jadmin Home Page

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 on this page, and you will be able to choose the one you intend to manage (check button).

It is important to note that the management information appearing in the different Jadmin pages is 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. The jonas server is selected for management.

The name of a JOnAS server is specified on the jonas start command line using -n option.

You may stop a JOnAS server using the provided link. We recommend not to use this link if the jadmin.war containing the Jadmin application components was loaded by that server. That's the reason why, in order to really stop the server, you are asked to click a second time on the stop link after an alert message was printed.

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.

General principles of the Jadmin GUI

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 listing the MBeans.

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

An example of the tree structures for the Container Service index

Show SessionMailer EJB within EJB container mailsb

The above picture shows the browsing tree for the SessionMailer EJB in the 'mailsb' EJB container. After the general information about the EJB, the resources used by it are listed. The SessionMailer EJB uses only a session mail factory named MailSession1. The MailSession1 resource, preceded by its JNDI name, 'mailSession_1', is presented as a reference allowing to go to the page presenting it in the Mail Service.

Dynamic deployment with Jadmin

One management operation which is especially important, it is the possibility 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 EJB JAR file: either with the complete path, or just the name if the file is in the JONAS_BASE/ejbjars directory.
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.

JOnAS configuration with Jadmin

Jadmin presents the JOnAS server configuration parameters read from the jonas.properties configuration file and the configuration parameters of loaded resources like Datasources or Mail Factories. When a parameter is writable, it is displayed in a TEXT INPUT allowing thus the server's reconfiguration. The Apply button sends the new value to the server, the Reset button reset the text input to its initial value, and the Save Changes button sends order to the server to save reconfigured values making the reconfiguration operations persistent.

Reconfiguration of the Current transaction time out parameter

In the above example, the Current transaction time out is a configurable parameter for the Transaction service. If this parameter is reconfigured and then made persistent, the jonas.properties file is updated using the new value.

In some cases, Jadmin allow to modify a set of configuration properties. For example, suppose you need to configure a Mail Factory resource 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 ';'.

Mail Factory configuration

In this example, if the Mail Session properties are presented in a TEXTAREA element. Note that you can reconfigure other properties like the JNDI name of this resources, and the authentication parameters. If the Mail Factory resource is persistently reconfigured using the Save Changes button, the corresponding configuration file is updated (here the MailSession1.properties file).

Note the following restriction of persistent reconfiguration in JOnAS: Can be persistently reconfigured only resources loaded from a configuration file. If a resource (Mail Factory or Datasource) is created using an empty form, currently there is no configuration file generated for it.

How to customize Jadmin ?

Jadmin use the Velocity 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:

un-jar 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.