How to Run Byteman Scripts, Dynamically Submit Rules, and Perform Offline Checks

Running Byteman with the bmjava Script

The bin directory contains a script named bmjava that combines Byteman agent options with other Java command‑line arguments. The syntax is:

bmjava [-p port] [-h host] [ -l script|-b jar|-s jar|-nb|-nl|-nj ]* [--] javaargs

-l script

: Load rules from the specified script file at program start. -b jar: Add the jar file to the bootstrap class path. -s jar: Add the jar file to the system class path. -p port: Specify the listener port (default 9091). -h host: Specify the listener hostname (default localhost). -nb: Prevent adding the Byteman JAR to the bootstrap class path. -nl: Prevent starting the agent listener. -nj: Prevent injection of java.lang classes.

Dynamically Submitting Rules with the bmsubmit Script

The bmsubmit script in the bin directory communicates with a Byteman listener started with listener:true. It supports uploading, unloading, querying injected rules, and installing helper JARs.

Command syntax:

submit [-p port] [-h host] [-l|-u] [script1 ... scriptN]
submit [-p port] [-h host] [-b|-s] jarfile1 ...
submit [-p port] [-h host] -c
submit [-p port] [-h host] -y [prop1[=[value1]] ...]
submit [-p port] [-h host] -v

-p port

and -h host: Listener port and host (default 9091 and localhost). -l: Upload rule scripts; without arguments, list current rule states. -u: Unload rules; with script arguments, unload rules matching the script. -b and -s: Add JAR files to the bootstrap or system class path (no undo). -c: List helper JARs installed on the bootstrap or system class path. -y: List or dynamically update system properties of the agent. Without arguments, shows all properties prefixed with org.jboss.byteman.; with arguments, modifies or clears specified properties.

Offline Rule Checking with the bmcheck Script

The bmcheck script parses and type‑checks Byteman rules offline before injection.

bmcheck [-cp classpath] [-p package]* script1 ... scriptN

-cp

: Specify classpath to locate classes referenced in rules. -p: Provide package names to resolve unqualified target classes, e.g., CLASS myClass becomes org.myApp.myClass when -p org.myApp is used.

Installing and Submitting Rules from Java

The bminstall and bmsubmit scripts are packaged in the byteman-install and byteman-submit JARs, allowing any Java program to load the agent or rules.

BMUnit : Extends JUnit and TestNG to load and unload rules dynamically during test execution.

DTest : Enables fault injection into a server JVM from a client.

Byteman Agent Load and Unload Lifecycle

Byteman implements the JVMTI Java agent API, allowing early loading and execution of bytecode transformations.

Agent Loading : Loaded at JVM startup via -javaagent or dynamically via bminstall, which loads the agent immediately.

Rule Injection : When the listener option is enabled, a daemon listener thread runs continuously, permitting dynamic rule load/unload without interrupting the JVM.

Agent Limitations : The Byteman agent can be loaded only once and cannot be unloaded; the agent classes must be loaded by the system or bootstrap class loader.

Environment Configuration

org.jboss.byteman.compileToBytecode

: Enable bytecode compilation of rules (default is interpretation). org.jboss.byteman.dump.generated.classes: Dump transformed class bytecode. org.jboss.byteman.dump.generated.classes.directory: Set dump directory. org.jboss.byteman.verbose / org.jboss.byteman.debug: Enable debug logging. org.jboss.byteman.transform.all: Allow rule injection into java.lang classes. org.jboss.byteman.skip.overriding.rules: Skip rule execution in overridden methods for performance. org.jboss.byteman.allow.config.updates: Permit dynamic configuration updates via bmsubmit. org.jboss.byteman.sysprops.strict: Restrict system property modifications to those prefixed with org.jboss.byteman..