Byteman 使用指南（十二）

使用脚本 bmjava 运行 Byteman

安装目录下的 bin 包含一个名为 bmjava 的脚本，可用于组合 Byteman 代理选项，并将其与 Java 命令行中的其他选项整合。命令行语法如下：

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

• **-l script**：在程序启动时加载 script 文件中的规则。
• **-b jar**：将 jar 文件添加到引导类路径。
• **-s jar**：将 jar 文件添加到系统类路径。
• **-p port**：指定侦听器的端口（默认值：9091）。
• **-h host**：指定侦听器的主机名（默认值：localhost）。
• **-nb**：禁止将 Byteman JAR 添加到引导类路径（默认情况下会添加）。
• **-nl**：禁止启动代理侦听器（默认情况下会启动）。
• **-nj**：禁止注入 java.lang 类（默认情况下允许）。

使用脚本 bmsubmit 动态提交规则

bin 目录下的 bmsubmit 脚本用于与通过 listener:true 启动的 Byteman 代理侦听器通信。支持动态上传规则、卸载规则、查询已注入的规则，以及安装帮助器类的 JAR。

命令行语法如下：

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 和 **-h host**：指定代理侦听器的端口和主机地址（默认值：9091 和 localhost）。
• **-l**：上传规则脚本到代理。如果不提供参数，将列出当前应用的转换状态。
• **-u**：卸载规则。如果带有脚本文件参数，则卸载与脚本文件中定义规则同名的已加载规则。
• -b 和 **-s**：分别将 JAR 文件添加到引导或系统类路径。此模式无撤销功能，安装后无法卸载。
• **-c**：列出已安装到引导或系统类路径的帮助器 JAR。
• **-y**：列出或动态更新代理的系统属性。未提供参数时，显示所有前缀为 org.jboss.byteman. 的属性值；提供参数时，修改或清除指定属性。

使用脚本 bmcheck 离线检查规则

bmcheck 脚本用于在将规则注入程序前，离线解析和类型检查 Byteman 规则。命令行语法如下：

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

• **-cp**：指定类路径，用于定位规则中引用的类。
• **-p**：提供包名，用于解析未指定包名的目标类。例如，CLASS myClass 会通过 -p org.myApp 解析为 org.myApp.myClass。

从 Java 安装和提交规则

脚本 bminstall 和 bmsubmit 是 byteman-install 和 byteman-submit JAR 的封装，支持从任何 Java 程序调用以加载代理或规则。例如：

• BMUnit：扩展 JUnit 和 TestNG 框架，在测试执行时动态加载和卸载规则。
• DTest：支持从客户端注入服务器 JVM 中的故障。

Byteman 代理加载和卸载生命周期

Byteman 实现了 JVMTI Java 代理 API，允许在 JVM 中优先加载并执行字节码转换：

1. 代理加载：通过 -javaagent 启动时，代理代码在 JVM 引导时加载；通过 bminstall 动态安装时，代理代码立即加载。
2. 规则注入：listener 选项启用后，代理侦听器线程持续运行，可动态加载、卸载规则。侦听器线程为守护线程，不会中断 JVM 的运行。
3. 代理限制：Byteman 代理只能加载一次，且无法卸载。此外，代理类必须通过系统或引导类加载器加载。

环境设置

通过以下环境变量可配置代理行为：

• **org.jboss.byteman.compileToBytecode**：启用规则的字节码编译（默认通过解释执行规则）。
• **org.jboss.byteman.dump.generated.classes**：转储转换后的类字节码。
• **org.jboss.byteman.dump.generated.classes.directory**：设置转储目录。
• **org.jboss.byteman.verbose / org.jboss.byteman.debug**：启用调试日志输出。
• **org.jboss.byteman.transform.all**：允许规则注入 java.lang 类。
• **org.jboss.byteman.skip.overriding.rules**：禁止在覆盖方法中执行规则（提高性能）。
• **org.jboss.byteman.allow.config.updates**：允许通过 bmsubmit 动态更新配置。
• **org.jboss.byteman.sysprops.strict**：限制系统属性修改，仅允许前缀为 org.jboss.byteman. 的属性。