Master Byteman: Install, Build, and Configure Java Fault Injection

Installation and Distribution

Download the latest Byteman zip from the project page. Extract it and set BYTEMAN_HOME to the extraction directory.

Binary distribution : contains JARs, scripts, programmer’s guide, example scripts, and helper JARs.

Full distribution : binary distribution plus source code and Javadoc JARs.

Ant Integration

Include the BMUnit JARs from the Byteman distribution in your Ant build.xml to combine Byteman with JUnit or TestNG. The BMUnit package provides tasks for loading rule scripts during test execution.

Note: Byteman 1.1 and later require JDK 6 or 7; earlier releases support JDK 5.

Maven Integration

Add a dependency on org.jboss.byteman:byteman in pom.xml. Maven will retrieve the JAR from Central. A Byteman Maven plugin can parse and type‑check rule scripts during the test phase.

Building From Source

Clone the main Git repository (e.g., git clone https://github.com/jboss-remoting/byteman.git) and build with Maven: mvn package The command creates binary, source, and Javadoc JARs in each module’s target directory (e.g., agent/target, submit/target) and zip files for the binary and full distributions in download/target.

Ant/Java users: unzip the generated zip and set BYTEMAN_HOME to that directory.

Maven users: install the Byteman JAR into the local repository with mvn install. Adjust the version in pom.xml beforehand to avoid overwriting the official Central version.

Running Applications with Byteman

Start the JVM with the Byteman Java agent: -javaagent:byteman.jar=options Typical tutorials include:

Command‑line tutorial – basic Byteman operations.

BMUnit tutorial – integration with JUnit/TestNG via Ant or Maven.

Fault‑injection tutorial – advanced testing features.

Agent Options

The -javaagent option accepts a comma‑separated list of parameters:

script:file – load the rule script located at file. Multiple script entries are allowed.

resourcescript:file – like script but searches the classpath.

listener:true|false – enable a listener thread for dynamic rule loading/unloading via bmsubmit scripts.

port:portnum – set the listener port (default 9091); specifying this option automatically enables the listener.

address:host – set the listener address (default localhost); also enables the listener.

manager:class – fully‑qualified class name of a custom manager that controls rule libraries.

sys:jarpath – add a JAR to the JVM system classpath for helper classes required by rules.

boot:jarpath – add a JAR to the JVM bootstrap classpath to allow rule injection into bootstrap‑loaded classes.

policy:true|false – enable a permissive security policy for JVMs running under a security manager (e.g., JBoss WildFly/EAP).

prop:name=value – set a system property; the name must start with org.jboss.byteman..

Note: If the target class is loaded by the bootstrap class loader, add Byteman to the bootstrap class path with boot:${BYTEMAN_HOME}/lib/byteman.jar . The bmjava script performs this automatically.

Module Support

Byteman provides a modules:classname option for environments that use modular class loading (e.g., JBoss Modules). The JBoss Modules plugin class is org.jboss.byteman.modules.jbossmodules.JBossModulesSystem and is included in the distribution.

Dynamic installation: Run bminstall -m to configure the module plugin automatically. The plugin JAR resides in ${BYTEMAN_HOME}/contrib/jboss-modules-system .