Parent: DerbyJMX

This page is intended to provide examples and information that may help you get started using Derby's JMX (Monitoring and Management) features.

For more information about Derby's JMX features, see DerbyJMX.



What are Derby's JMX features?

In short, Derby's JMX features consist of a set of MBeans (Managed Beans) and their attributes and operations, providing monitoring and management capabilities. MBean implementations instrument one or more parts of a running Derby system, potentially giving you real-time access to Derby-specific information and features from a host of your choice. The word potentially here indicates that JMX access may depend on how you configure your JVM and (for example) Derby's security features.

The documentation of each MBean describes the features in more detail, see also DerbyJMX.

When can I use Derby's JMX features?

Derby's JMX features were first introduced with the the 10.4.1 release in April 2008.

Derby's JMX features are automatically available when Derby is started in a Java Virtual Machine (JVM) supporting the platform MBean Server. This includes JVMs supporting J2SE 5.0, Java SE 6, or newer.

Derby's JMX features are not available when using J2SE 1.4.2 or Java ME (as per April 2008).

You start Derby by loading Derby's embedded driver. If you are using Derby's Network Server, the embedded driver is automatically loaded in the server JVM when the server is started.

You may access Derby's MBeans using for example an existing JMX client utility, such as JConsole, or programmatically by writing your own Java code utilizing JMX.


If you are unfamiliar with JMX technology, it may be a good idea to take a look at some of the references provided here before you continue.

Enabling JMX

Note: In the following, local basically means on the same host (machine) and running as the same user. For example, this means that local JMX access is possible only if the JVM you want to access is running on the same host and as the same user as the user running JConsole (or a different user with sufficient file system permissions). In order to allow other users to access the JVM, or to allow access from other hosts, remote JMX must be enabled.

Local JMX access

If you are using a Java SE 6 JVM, local JMX management and monitoring is most likely enabled by default.

Some JVMs, for example J2SE 5.0 JVMs, do not enable local JMX management by default. Refer to the documentation for your JVM for details. It seems that the de-facto standard way to enable (local) JMX access is to include on the command line when starting the JVM.

Remote JMX access

Remote JMX management and monitoring is a powerful Java feature, letting you monitor a specific JVM from a remote location. Enabling remote JMX requires explicit actions by the JVM administrator (you), since it may involve exposing sensitive information about your system.

The most common way to enable remote JMX access to your JVM is to specify a TCP/IP port number and some basic security (authentication, SSL (Secure Sockets Layer)) settings when starting the JVM. Derby attempts to use the JVM's built-in platform MBean server. For a list of (seemingly de-facto standard) command line options (system properties) and their meaning, refer to the Java SE Monitoring and Management Guide, the Platform Monitoring and Management guide for J2SE 5.0, or your JVM's documentation.

Example: Enabling Remote JMX, no authentication/SSL

The following example starts the Derby Network Server on the command line with (insecure) remote JMX management and Monitoring enabled, using the JVM from Sun's JDK 6. Password authentication over SSL is enabled by default, but in this example these security features are disabled, to keep the example simple. It is not recommended to disable authentication or SSL in production environments.

-jar lib/derbyrun.jar server start

When starting the Derby Network Server from the command line, it automatically installs a security manager using a basic default security policy unless you provide the -noSecurityManager option. You may need to customize this policy to make it suit your needs. See below for details.

Example: Enabling Remote JMX, password authentication, no SSL

Some JVMs include built-in support for JMX password authentication. For example, with Sun's JDK 6, authentication is enabled by default, and it is possible to specify a properties file specifying usernames and passwords.

Note that when authentication is enabled and a Java Security Manager is installed, additional permissions may need to be granted to users in the security policy used. See Security policy for details.

Example password file (syntax same as Java properties files), called jmxremote.password:

## Defining two "roles", each with its own password
monitorRole  derbym
controlRole  derby

The security of the password file relies on your file system's access control mechanisms. The file must be readable by the owner only. Also, you may need to change the permissions on the password file to be readable only by the user starting the server. To do this on Windows (NTFS) use:  cacls jmxremote.password /P <username>:R 

FAT file systems do not support this feature (details).

The following example starts the Derby Network Server on the command line with built-in JMX password authentication enabled.

SSL is disabled, meaning that JMX information including usernames and passwords most likely will be transferred unprotected on the computer network, which is not recommended in production environments. The command line is presented on multiple lines to improve readability; though you should enter everything as a single java command.

-jar lib/derbyrun.jar server start

Example: Enabling Remote JMX, password authentication, client/server SSL, RMI registry SSL

This example shows how to start the Derby network server...

This level of protection may or may not be adequate for you, but it is definitely more secure that the previous examples.

The command line is presented on multiple lines to improve readability; though you should enter everything as a single java command.

-jar lib/derbyrun.jar server start -h

Note that when password authentication is enabled and a Java Security Manager is installed, a number of JMX-related permissions need to be granted to trusted users in the security policy used. See Security policy for details.

In the example above, system properties specify the keystore containing the server's key pair, the keystore password, the truststore containing the client certificates and the truststore password. Setting up SSL keystores and truststores is partly described in the Derby Server and Administration Guide, under "Derby Network Server advanced topics" --> "Network encryption and authentication with SSL/TLS" --> "Key and certificate handling". You should also refer to that guide if you want to protect the actual database network traffic using SSL. You should also be able to find Java-related SSL tutorials elsewhere on the web.

When configuring SSL as described above, the following caveats apply:

The system property specifies that clients must use SSL to authenticate themselves. This requirement is optional. This property as well as the truststore properties may be removed if you do not want to authenticate clients using SSL (note that there may be security risks associated with using password authentication only).

The system property is new in JDK 6 and aims at resolving security issues with the RMI registry used in relation with JMX. This property must be used in conjunction with in order to fully secure the RMI registry.

Note that when enabling SSL protection of the registry, clients must provide an additional entry in the environment map passed to the JMXConnector (JConsole/JDK6 handles this automatically):

   env.put("com.sun.jndi.rmi.factory.socket", new SslRMIClientSocketFactory());

(see Connecting to the MBean Server for details)

Note that clients must also specify and use proper keystores and/or truststores (the truststores must contain the server's SSL certificate).

For more information about the system properties used above and potential security risks, see the Java SE Monitoring and Management Guide.

Simple authorization

Some JVMs support a simple access file system for controlling JMX access. An access file is formatted the same way as password files (described above), and associates roles with an access level. Valid access levels are readonly and readwrite, where readonly only allows the JMX client to read an MBean's attributes and receive notifications. readwrite also allows setting attributes, invoking operations, and MBean creation/removal.

To use an access file for JMX authorization, you may specify the name of the access file using a system property upon JVM startup:

The contents of such an access file may look like this:

monitorRole   readonly
controlRole   readwrite

For more information, see the Java SE Monitoring and Management Guide.

Fine-grained authorization: Security policy

When starting the Derby Network Server from the command line, it installs a security manager and a basic security policy by default. This policy includes the required permissions to allow JMX users to access Derby's MBeans if JMX user authentication is disabled. If JMX user authentication is enabled, you may need to grant additional permissions to specific users (JMXPrincipals).

The NetworkServerMBean's ping operation requires that an additional permission is granted to derbynet.jar, that is not included in the default security policy:

    // If the server is listening on the loopback interface only (default).
    permission "localhost", "connect,resolve";

    // If the server's network interface setting (-h or is non-default.
    // Note: Allows outbound connections to any host!
    permission "*", "connect,resolve";

If you are using a custom security policy, refer to the public API of Derby's MBeans and Derby's template security policy file ($DERBY_HOME/demo/templates/server-policy) for details about the permissions you may need to set to allow or restrict specific JMX access. See also JMXSecurityExpectations. This also applies if you are running Derby embedded with a security manager installed.

Some example permissions are included below. Note that these permissions are not necessarily suitable for any particular application or environment; some customization is probably needed.

Only permissions relating to the Derby 10.4.1 JMX features have been included in the example below. Additional permissions are needed in order to enjoy regular use of Derby. (You may want to copy and paste the text into a text editor without line wrapping to increase redability.)

// permissions for the user/principal "controlRole", for all codebases:
grant principal "controlRole" {

  // Derby system permissions (what is the user allowed to do?)
  //  See Javadocs for SystemPermission and the specific MBeans for details.
  permission "jmx", "control";
  permission "engine", "monitor";
  permission "server", "monitor,control";

  // MBean permissions (which mbeans and associated actions should be allowed for this user?)
  //  Target name format is: className#member[objectName], where objectName is: domain:keyProperties
  //  * means "all". See MBeanPermission Javadocs for details.
  permission "org.apache.derby.mbeans.*#*[org.apache.derby:*]", "getAttribute";
  permission "org.apache.derby.mbeans.JDBCMBean#acceptsURL[org.apache.derby:*]", "invoke";
  permission "org.apache.derby.mbeans.drda.NetworkServerMBean#ping[org.apache.derby:*]", "invoke";
  permission "org.apache.derby.mbeans.ManagementMBean#*[org.apache.derby:*]", "invoke";

  // Extra permissions for application controlled ManagementMBean:
  //   Not needed if you do not intend to create/register your own Derby Management MBean.
  //   Wildcards (*) allow all domains, key properties and MBean members. You may want to be more specific here.
  permission "org.apache.derby.mbeans.Management#-[*:*]", "instantiate,registerMBean,unregisterMBean";
  permission "org.apache.derby.mbeans.Management#*[*:*]", "invoke";

  // jconsole:
  //  - most of these permissions are needed to let JConsole query the MBean server and display information
  //    about Derby's mbeans as well as some default platform MBeans/MXBeans.
  //  - if you don't use jconsole, but query the MBean server from your JMX client app, 
  //    some of these permissions may be needed.
  permission "org.apache.derby.mbeans.*#-[org.apache.derby:*]", "getMBeanInfo,queryNames,isInstanceOf";
  permission "*#-[java.*:*]", "getMBeanInfo,isInstanceOf,queryNames";
  permission "*#*[java.*:*]", "getAttribute,invoke";
  permission "*#-[*:*]", "getMBeanInfo,isInstanceOf,queryNames";
  permission "*#-[java.*:*]", "getMBeanInfo,isInstanceOf,queryNames";
  permission "*#*[java.*:*]", "getAttribute,invoke";
  permission "java.*#-[java.*:*]", "getMBeanInfo,isInstanceOf,queryNames";
  permission "[JMImplementation:type=MBeanServerDelegate]", "getMBeanInfo,isInstanceOf,queryNames,addNotificationListener";
  permission "*", "resolve";
  permission java.util.PropertyPermission "java.class.path", "read";
  permission java.util.PropertyPermission "java.library.path", "read";
  permission "monitor";
  // end jconsole

grant codeBase "${derby.install.url}derby.jar"
  // Allows Derby to create an MBeanServer:
  permission "createMBeanServer";

  // Allows access to Derby's built-in MBeans, within the domain org.apache.derby.
  // Derby must be allowed to register and unregister these MBeans.
  // It is possible to allow access only to specific MBeans, attributes or 
  // operations. To fine tune this permission, see the javadoc of 
  // or the JMX Instrumentation and Agent 
  // Specification. 
  permission "org.apache.derby.*#[org.apache.derby:*]", "registerMBean,unregisterMBean";

  // Trusts Derby code to be a source of MBeans and to register these in the MBean server.
  permission "register";

  // Gives permission for JMX to be used against Derby.
  // If JMX user authentication is being used, a whole set of fine-grained
  // permissions need to be granted to allow specific users access to 
  // MBeans and actions they perform (see JMXPrincipal permissions above).
  // Needed to allow access to all actions related to mbeans in the
  // org.apache.derby.mbeans pagage.
  permission "jmx", "control";
  permission "engine", "monitor";
  permission "server", "monitor";

  // add additonal derby.jar related permissions here...

grant codeBase "${derby.install.url}derbynet.jar"
  // Accept connections from any host (only localhost access is required for JMX).
  permission "*", "accept"; 

  // For outbound MBean operations such as NetworkServerMBean's ping:
  // The wildcard "*" is to allow pings to both localhost and any other server host.
  permission "*", "connect,resolve"; 

  // Gives permission for JMX to be used against Derby.
  // If JMX user authentication is being used, a whole set of fine-grained
  // permissions need to be granted to allow specific users access to 
  // MBeans and actions they perform (see JMXPrincipal permissions above).
  // Needed to allow access to all actions related to the NetworkServerMBean.
  permission "server", "control,monitor";

  // add additonal derbynet.jar related permissions here...

For a full version of the above example policy, see the attachment jmx-example.policy (use Save as...).

Note that in the example above the system property derby.install.url is used to tell the security manager/policy implementation where to find the codebases derby.jar and derbynet.jar. Using a property provides flexibility - however, you may avoid the use of such a property by specifying the full codebase URLs directly in the policy file. The value of this property may be specified on the command line, for example




For more information about policy files, granting permissions, and property expansion, see Default Policy Implementation and Policy File Syntax and Policy File Creation and Management.

Debugging permission issues

Dealing with security managers, policy files and permissions is not always easy. Sometimes, some action you want to perform fails due to some security/permission issue, and you don't know why. Well, here's a tip that may help you along the way:

When starting the JVM being protected by the seurity manager, add a flag to see detailed output relating to security policy and permission usage. For a list of valid options, run


or see Sun's online training documents for Java security.

For example, setting

when starting the Derby Network Server from the command line will print lots of output to the console which allows you to find out specifically which permissions are granted and which are missing when a failure occurs. Due to the amount of output generated when setting the debug flag, it may be wise to store the output in a file and search through it afterwards.

For example, to find out details about a missing permission, search for the text "access denied" in the output, and you will see something like

access: access denied ( engine monitor)
java.lang.Exception: Stack trace
        at java.lang.Thread.dumpStack(
        at Source)
        at Source)
access: domain that failed ProtectionDomain  (file:/home/user/derby/ <no signer certificates>)
 <no principals> (
 ( org.apache.derby.*#[org.apache.derby:*] registerMBean,unregisterMBean)
 ( getPolicy)
 ( localhost:1024- listen,resolve)

The above example output shows that the derby.jar code base is missing the permission "engine", "monitor",

as the JMX client was accessing the VersionString attribute of the VersionMBean for derby.jar. In this example, JMX user authentication was disabled, hence <no principals>.

Troubleshooting JMX connection issues

If you experience problems connecting "remotely" to an MBean server using JMX (see examples of such connections below), getting some tracing information may be helpful. Sun's JMX implementation uses the java.util.logging API to log JMX traces. For example, in order to trace SSL connection issues, set the system property java.util.logging.config.file, e.g

java MyJmxClient

With JConsole, a separate logging window will appear if you specify

upon JConsole startup, as long as the file is found.

The file should specify log handlers and logging levels, for example:

handlers = java.util.logging.ConsoleHandler
.level = INFO

java.util.logging.ConsoleHandler.level = FINEST
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

 // Level FINEST is suitable for diagnosing SSL-related JMX remote connection issues. = FINEST = FINEST

See also this blog entry for further hints and tips.

Using JConsole to access Derby's MBeans

JConsole is a graphical JMX-compliant tool originally developed by Sun Microsystems, and is available in recent versions of Sun's Java Development Kits (JDKs). JConsole enables you to monitor and manage Java applications and virtual machines on a local or remote machine.

Note that you may use JConsole from JDK 6 even if you are running Derby using JDK 5.0 (or just the JRE), or vice versa. It is recommended that you use the newest version possible. More information about JConsole is available in the Java SE Monitoring and Management Guide and in the OpenJDK project.

Starting JConsole and connecting to Derby

In Sun's JDK 5.0 and JDK 6, the JConsole binary is available in the bin directory of JDK_HOME, where JDK_HOME is the directory in which the JDK is installed. You can simply start JConsole by running the jconsole executable, for example (Unix):


If you did not disable SSL when booting the managed JVM, you most likely have to provide a truststore containing the server's SSL certificate to be able to establish JMX connections. If SSL client authentication is enabled, a keystore must be configured as well (see server-side SSL configuration example for details). Example (SSL client+server authentication):


A graphical user interface (GUI) should appear. For additional startup options, refer to the references mentioned above. Once the GUI starts, you will be presented with a list of JVMs that are accessible on the local host. Locate the JVM running Derby in that list and connect to it.

Accessing MBeans

Once connected to a JVM via JConsole, the JVM's MBeans should be available on a separate tab in the internal JConsole window. Under the domain "org.apache.derby" you should see a list of MBeans. Browse the MBeans and their attributes and operations by navigating the hierarchy presented.

Below is a screenshot showing how JConsole (from JDK 6, monitoring the network server of Derby 10.4.1 beta) presents the attributes of the NetworkServerMBean.


Another useful JConsole feature is that you can view dynamic data represented as JMX attributes as graphs. You may view these graphs by double clicking an attribute value that is a number (in bold in the screenshot above). The partial screenshot below shows some of the attribute values of the NetworkServerMBean as graphs, after the Network Server has been running with some load.


Accessing Derby's MBeans using custom Java code

Besides using generic tools as described above, it is also possible to access Derby's MBeans programmatically, that is from a Java application. How to do this may depend on how you configure the JVM running Derby, for example how you configure user authentication and authorization, or from which host(s) you want to access the MBeans.

Below is some example code which should help you get started. It is assumed that the client JVM will be supporting J2SE 5.0 or newer (you will find the JMX classes you need in the packages and Most examples include code which throws exceptions that would have to be caught or re-thrown when appropriate (not shown).

Note that you do not need any Derby libraries in the JMX client application's classpath (unless MBean proxies are used).


Connecting to the MBean Server

Derby will attempt to register its MBeans with the Platform MBean Server of the JVM running the Derby system (embedded or Network Server). The following examples assume that you have configured the Derby JVM to enable remote JMX, which means that you have set a port number ( to be used by the JMX Server Connector.

For local management, there may be alternative ways to access the MBean server; however this outside the scope of this document.

The examples below assume that the port configured for remote JMX is 9999, and that the host name of the host running Derby is and that this host is reachable from the client host. (This host name is fictitious, and is used for example purposes only.)

The following example code shows how to connect to the MBean Server when JMX security has been disabled:

   1     JMXServiceURL url = new JMXServiceURL(
   2             "service:jmx:rmi:///jndi/rmi://");
   3     JMXConnector jmxc = JMXConnectorFactory.connect(url, null);
   4     MBeanServerConnection mbeanServerConn = jmxc.getMBeanServerConnection();

The following code shows how to connect to the MBean server when JMX password authentication is enabled (default):

   1     JMXServiceURL url = new JMXServiceURL(
   2             "service:jmx:rmi:///jndi/rmi://");
   3     // Assuming the following JMX credentials: username=controlRole, password=derby
   4     String[] credentials = new String[] { "controlRole" , "derby" };
   5     HashMap<String,Object> env = new HashMap<String,Object>();
   6     // Set credentials (jmx.remote.credentials, see JMX Remote API 1.0 spec section 3.4)
   7     env.put(JMXConnector.CREDENTIALS, credentials);
   8     // if the server's RMI registry is protected with SSL/TLS (JDK 6)
   9     // (, then the following entry must be included:
  10     //env.put("com.sun.jndi.rmi.factory.socket", new SslRMIClientSocketFactory());  // uncomment if needed
  12     // Connect to the server
  13     JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
  14     MBeanServerConnection mbeanServerConn = jmxc.getMBeanServerConnection();

(Not specifying SslRMIClientSocketFactory when required may result in "java.rmi.ConnectIOException: non-JRMP server at remote endpoint".)

Creating a ManagementMBean

The only Derby MBean that can be created by a JMX client is the ManagementMBean. This MBean is useful for controlling Derby management (for example enabling and disabling management/MBeans), and to obtain information such as the system identifier (may be needed to specify MBeans later).

If you create such an MBean from your application, and Derby has already registered a ManagementMBean instance, the new MBean cannot have the same object name as the ManagementMBean already registered with the server. It is therefore recommended to use different object name domain (i.e. different from org.apache.derby) and/or a different type key property value (different from Management).

The following example code shows how to create and register a new ManagementMBeanwith the MBean server:

   1     ObjectName mgmtObjName = new ObjectName("", "type", "DerbyManagement");
   2     try {
   3         ObjectInstance mgmtObj = mbeanServerConn.createMBean("org.apache.derby.mbeans.Management", mgmtObjName);
   4     } catch (InstanceAlreadyExistsException e) {
   5         // A management MBean with this object name already exists!
   6     }

Activating Derby management

Derby attempts to activate its JMX management service by default, so it will usually be active unless you explicitly deactivate it, providing that Derby has permissions to do so. If Derby management is not active, you will not be able to access any other MBeans but the ManagementMBean.

By accessing the attribute ManagementActive of the ManagementMBean, you can check whether Derby's JMX management service is active or not.

The following example code checks if Derby's management service is active, and activates it if it isn't:

   1     // assuming we already have a reference to the ManagementMBean's object name
   2     Boolean active = (Boolean) mbeanServerConn.getAttribute(mgmtObjName, "ManagementActive");
   3     if (!active.booleanValue()) {
   4         // start management
   5         mbeanServerConn.invoke(mgmtObjName, "startManagement", new Object[0], new String[0]);
   6     }

Obtaining the system identifier

The system identifier is a unique String distinguishing one running Derby system from another. All MBeans that are instantiated by Derby include the system identifier in their object names.

One way to access an MBean is to fully specify its object name when contacting the MBean server. For this, you need to know the current system identifier. (Alternative ways to access MBeans include querying the MBean server for all MBeans, or MBeans which object names match a specific pattern.)

The following example shows how to obtain the system identifier by accessing a ManagementMBean:

   1     // assuming we already have a reference to the ManagementMBean's object name
   2     String systemID = (String) mbeanServerConn.getAttribute(mgmtObjName, "SystemIdentifier");

The following example shows how to obtain the system identifier from a Derby MBean's object name:

   1     // assuming we already have a reference to the ObjectName of an MBean registered by Derby, 
   2     // for example the Derby-registered ManagementMBean
   3     String systemID = derbyMgmtObjectName.getKeyProperty("system");

Accessing a specific Derby-registered MBean

In the above examples you have already seen how to read a single MBean attribute, and how to invoke an MBean operation. In order to do this, you usually need a reference to the MBean's ObjectName.

If you have access to the (Javadoc) API of Derby's MBeans as well as the system identifier of the Derby system you are accessing through JMX, you have all the information you need to be able to instantiate an object directly, by fully specifying its String representation (see the ObjectName API for details).

This example code shows how to obtain a reference to the VersionMBean for derby.jar:

   1     // Assuming we already know the system idenfifier (see examples above), systemID.
   2     // A list of key properties is available is each MBean's Javadoc API.
   3     Hashtable<String, String> keyProps = new Hashtable<String, String>();
   4     keyProps.put("type", "Version");
   5     keyProps.put("jar", "derby.jar");
   6     keyProps.put("system", systemID);
   7     // MBeans registered by Derby always belong to the "org.apache.derby" domain
   8     ObjectName versionObjectName = new ObjectName("org.apache.derby", keyProps);
  10     // we can now use the object name to read an attribute
  11     String versionString = (String) mbeanServerConn.getAttribute(versionObjectName, "VersionString");
  12     System.out.println("VersionString: " + versionString);

Example output:

VersionString: - (645238)

There are 3 attachment(s) stored for this page.

DerbyJMXQuickStart (last edited 2011-02-03 07:59:51 by gmp-ea-fw-1b)