Enabling the remote trace controller

Enabling the remote trace controller involves enabling Java™ Management Extensions (JMX) in the IBM® Data Server Driver for JDBC and SQLJ, and making the JMX agent available to clients.

Before you begin

The remote trace controller requires Java Standard Edition, Version 6 or later.

Procedure

The steps for enabling the remote trace controller are:

Enable JMX to the IBM Data Server Driver for JDBC and SQLJ by setting the db2.jcc.jmxEnabled global configuration property to true or yes.
For example, include this string in DB2JccConfiguration.properties:
```
db2.jcc.jmxEnabled=true
```

Make the JMX agent (the platform MBean server) available to local or remote clients.

For local clients:
Monitoring and management capabilities are automatically made available when the JVM is started. After your application is started, you can use a JMX client such as JConsole to connect locally to your Java process.

For remote clients, use one of the following methods:

Use the out-of-the-box JMX agent.
Out-of-the-box management uses JMX built-in management utilities. To enable out-of-the-box management, you need to set a number of Java system properties. You must at least set the following property:
```
com.sun.management.jmxremote.port=portNum
```
In addition, you should ensure that authentication and SSL are properly configured.

Full information on enabling out-of-the-box management is at the following URL:
```
http://download.oracle.com/javase/6/docs/technotes/guides/management/agent.html
```

Write a JMX agent. This technique is also discussed at:

http://download.oracle.com/javase/6/docs/technotes/guides/management/agent.html

In the following example, an RMI connector server is created for the PlatformMBeanServer using the MyCustomJMXAuthenticator object. The MyCustomJMXAuthenticator class defines how remote credentials are converted into a JAAS Subject by implementing the JMXAuthenticator interface:

… 
HashMap<String> env = new HashMap<String>();
env.put(JMXConnectorServer.AUTHENTICATOR, new MyCustomJMXAuthenticator());
env.put("jmx.remote.x.access.file", "my.access.file");

MBeanServer mbs = 
  java.lang.management.ManagementFactory.getPlatformMBeanServer();
JMXServiceURL url = 
  new JMXServiceURL("service:jmx:rmi:///jndi/rmi://:9999/jmxrmi");

JMXConnectorServer cs = 
  JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs);
cs.start();
… 
public class MyCustomJMXAuthenticator implements JMXAuthenticator {

  public Subject authenticate(Object credentials) {
    // the hash contains username, password, etc...
    Hashtable <String> credentialsHash 
      = (Hashtable <String>) credentials;

    …
    // Authenticate using the provided credentials
    …
    if (authentication-successful) {
      return new Subject(true,
        Collections.singleton
          (new JMXPrincipal(credentialsHash.get("username"))),
        Collections.EMPTY_SET,
        Collections.EMPTY_SET);
    } 
    throw new SecurityException("Invalid credentials");
  }
}