You can use James' built-in Java Management Extensions to administer the server.

Environment

To enable JMX you will need a running James instance (see JamesQuickstart).

Make James publish managed components

JMX uses a so called MBean server, which makes managed components available for you to access.

James is able to (a) start it's own MBean server or (b) use an already running MBean server. You'll probably want to do (a) under JDK 1.4.

IMPORTANT: Using James' built in MBean server will probably not work on JDK 1.5+ (see https://issues.apache.org/jira/browse/JAMES-701). If you're running on JDK 1.5+ please scroll down to the section "Use existing MBeans server" below.

Use James' built-in MBean server

If you want to make James start its own MBean Server, go to the home directory of your James installation and edit conf/kernel.xml

change

        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.components.manager.NoopSystemManager"
            logger="manager" />

        <!--
        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.components.manager.MX4JSystemManager"
            logger="manager">
        -->

into

        <!--
        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.components.manager.NoopSystemManager"
            logger="manager" />
        -->

        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.components.manager.MX4JSystemManager"
            logger="manager">

Then, change

            <!--
            <enable-rmi-adaptor>true</enable-rmi-adaptor>
            <rmi-naming-factory>com.sun.jndi.rmi.registry.RegistryContextFactory</rmi-naming-factory>
            <rmi-registry-port>1099</rmi-registry-port>
            -->

into

            <enable-rmi-adaptor>true</enable-rmi-adaptor>
            <rmi-naming-factory>com.sun.jndi.rmi.registry.RegistryContextFactory</rmi-naming-factory>
            <rmi-registry-port>1099</rmi-registry-port>

Finally, change

        <!--
        </component>
        -->

into

        </component>

Restart James now, it should come up like always, only now binding to port 1099, in addition to the other ports.

Use existing MBeans server

If you are running under Java SE 5 or newer, the virtual machine incorporates capabilities to start its own MBean server. http://java.sun.com/j2se/1.5.0/docs/guide/jmx/index.html

The advantage of this setup is that the JVM itself publishes additional useful MBeans. This is used, for example, by JamesPostage when profiling James.

Go to the home directory of your James installation and edit conf/kernel.xml

change

        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.components.manager.NoopSystemManager"
            logger="manager" />

into

        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.components.manager.HostedSystemManager"
            logger="manager">

Please note, that NoopSystemManager was changed into HostedSystemManager and the trailing slash has been removed!

Finally, change

        <!--
        </component>
        -->

into

        </component>

Now, edit file bin/phoenix.[sh|bat]

Replace line

JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS"

with (on one line)

JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.port=10201 "

Restart James now, it should come up like always, only now binding to port 10201, in addition to the other ports.

Connecting using MC4J

MC4J is a GUI application able to connect to and manage any JMX enabled application.

You can download it from http://mc4j.sourceforge.net. Please follow the instructions given there to run the installer and start the application up afterwards.

Choose "Connect to server..." from the menu to activate the Connection Wizzard.

Use James' built-in MBean server

On panel 1, choose "MX4J 1.x" from the drop-down list. Enter a name into the edit field: e.g. James. Click "next".

Panel 2 is magically skipped.

On panel 3, click "next".

On panel 4, click "finish".

Use existing MBeans server

On panel 1, choose "JSR160" from the drop-down list. Enter a name into the edit field: e.g. James. As Server URL, enter: service:jmx:rmi:///jndi/rmi://localhost:10201/jmxrmi Click "next".

Panel 2 is magically skipped.

On panel 3, click "next".

On panel 4, click "finish".

After completing the wizzard

MC4J now connects and tells you it is loading some MBeans.

Call management attributes and operations

MC4J offers you to browse all exposed management functions.

Browse to James/MBeans/Phoenix/application=james

There you will find all the components, ready to be managed by introspecting attributes or executing operations.

ConfigureJmx (last edited 2013-03-23 10:20:36 by JohnWood)