Enabling Byteman Script With Red Hat JBoss Fuse and AMQ

In a production or customer environment, it is not always possible to identify issues by looking at logs, nor is it always possible to set up remote debugging using an integrated development environment (IDE) and a remote debug port. Often the issues are specific to the environment and can't be reproduced. Having scripts can help in these situations to identify issues without actual code changes. Whenever a certain Java class or logic is invoked, scripts will also be invoked as per a defined class and method in the Byteman script.

Here are the steps to follow:

1. Download Byteman binary here. I downloaded version 3.0.10.

2. Extract it on the same machine where Red Hat JBoss Fuse exists.

3. Once extracted, create a text file (Byteman script) script.btm (file at location /path/to/byteman-download-3.0.10). Here byteman-download-3.0.10 is the folder created after extracting the binary.

4. The content of this script should be:

RULE check authpassword
CLASS org.apache.karaf.shell.ssh.KarafJaasAuthenticator
METHOD authenticate(java.lang.String, java.lang.String, org.apache.sshd.server.session.ServerSession)
AT ENTRY
IF true
DO 
traceOpen("file.out", "byteman.log");
traceln("file.out"," password: "+ $2);
ENDRULE

Point to note here:

• We want to analyze the authenticate method of the KarafJaasAuthenticator class. We want to check the value of the 2nd parameter, which is password.
• We are using traceOpen so that traceln logs are finally written to byteman.log. If we don't use traceOpen, then traceln logs will be printed in Karaf's terminal, thus we might lose logs.

5. In Red Hat JBoss Fuse, we have to edit the file  ${karaf.home}/etc/config.properties and modify the property org.osgi.framework.bootdelegation so that it includes the package   org.jboss.byteman.* as well, like below:

org.osgi.framework.bootdelegation=org.apache.karaf.jaas.boot,sun.*,com.sun.*,javax.transaction,javax.transaction.*,org.apache.xalan.processor,org.apache.xpath.jaxp,org.apache.xml.dtm.ref,org.apache.xerces.jaxp.datatype,org.apache.xerces.stax,org.apache.xerces.parsers,org.apache.xerces.jaxp,org.apache.xerces.jaxp.validation,org.apache.xerces.dom,org.jboss.byteman.*

6. Now edit the ${karaf.home}/bin/setenv file and include the JAVA_OPTS JVM argument as below. This argument refers to the Byteman jar and the Byteman script, script.btm.

export JAVA_OPTS="-javaagent:/path/to/byteman-download-3.0.10/lib/byteman.jar=script:/path/to/byteman-download-3.0.10/script.btm,boot:/path/to/byteman-download-3.0.10/lib/byteman.jar"

7. The purpose of this script is to check to see if the password entered for authentication is being passed correctly into the code or not. Similarly, there may be other use-cases where one wants to check the code execution.

The actual Java class that is invoked to log in is: org.apache.karaf.shell.ssh.KarafJaasAuthenticator  
The method invoked:  

public boolean authenticate(final String username, final String password,

final ServerSession session)

We can get these details while troubleshooting issues. I found this class in the DEBUG level logs. So troubleshooting always starts with logs.

8. To test, first start Red Hat JBoss Fuse using the start script.

[cpandey@cpandey bin]$ pwd
/path/to/jboss-fuse-6.3.0.redhat-310/bin
[cpandey@cpandey bin]$ ./start

9. Now run the client script to access the karaf terminal. The password we entered is 'wrongpassword.'

[cpandey@cpandey bin]$ ./client -u admin
Logging in as admin
Password: 
Password:

10. Now check byteman.log which we configured above in script file, script.btm. We should get the password entered in logs.

[cpandey@cpandey jboss-fuse-6.3.0.redhat-310]$ pwd
/path/to/jboss-fuse-6.3.0.redhat-310

[cpandey@cpandey jboss-fuse-6.3.0.redhat-310]$ tail -f byteman.log 
 password: wrongpassword

The example above was a real use-case. We can troubleshoot other issues if we want to get information from code where logs are not sufficient or not available. This has also been tested in a Fabric environment.

That's it. Thanks for reading!