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:

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:

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:

For using Jadmin with Jetty:

How to use Jadmin ?

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:


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

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: