diff --git a/docs/configuration/jvm-options.md b/docs/configuration/jvm-options.md index e16150bd..35c4bb02 100644 --- a/docs/configuration/jvm-options.md +++ b/docs/configuration/jvm-options.md @@ -89,6 +89,33 @@ you can use JVM_DD_OPTS: fml.queryResult=confirm,name=value ``` +## Java and JVM Agents + +Java agents, such as [authlib-injector](https://github.com/yushijinhun/authlib-injector), can be loaded into the server by setting `JAVA_AGENTS`, and native JVM agents by setting `JVM_AGENTS`. Like [the `MODS` / `PLUGINS` variables](../mods-and-plugins/index.md#modsplugins-list), both are a comma or newline delimited list of + +- URL of an agent file +- container path to an agent file +- container path to a directory containing agent jar files for `JAVA_AGENTS`, or `.so` files for `JVM_AGENTS` + +The agents are copied into `/data/agents/java` and `/data/agents/jvm`, and each one is passed to the JVM as `-javaagent:` or `-agentpath:`, in file name order. + +!!! example + + ```yaml + environment: + JAVA_AGENTS: | + https://www.example.com/agents/agent.jar + /agents + ``` + +!!! note "Auto-removal" + + Entries that are removed from the `JAVA_AGENTS` or `JVM_AGENTS` list will be automatically removed from the agents directory, so they are no longer loaded. + +!!! note "Agent options" + + An agent that needs options, such as `-javaagent:agent.jar=options`, can still be passed with `JVM_OPTS` instead. + ## Enable Remote JMX for Profiling To enable remote JMX, such as for profiling with VisualVM or JMC, set the environment variable `ENABLE_JMX` to "true", set `JMX_HOST` to the IP/host running the Docker container, and add a port forwarding of TCP port 7091, such as: diff --git a/docs/variables.md b/docs/variables.md index 7f49ecce..a34513f3 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -147,6 +147,18 @@ alternatively, you can mount: /etc/localtime:/etc/localtime:ro ⬜️ + + JAVA_AGENTS + Comma or newline delimited list of Java agent jar URLs, container paths to jars, or container paths to directories of jars, which are loaded with -javaagent + + ⬜️ + + + JVM_AGENTS + Comma or newline delimited list of native JVM agent URLs, container paths to agents, or container paths to directories of .so agents, which are loaded with -agentpath + + ⬜️ + EXTRA_ARGS Arguments that would usually be passed to the jar file (those which are written after the filename) diff --git a/scripts/start-finalExec b/scripts/start-finalExec index 2402e8bf..475f7930 100755 --- a/scripts/start-finalExec +++ b/scripts/start-finalExec @@ -125,6 +125,39 @@ elif versionLessThan 1.18.1; then fi fi +function addAgents() { + local agents=$1 outDir=$2 glob=$3 option=$4 + + mkdir -p "$outDir" + if ! mc-image-helper mcopy \ + --glob="$glob" \ + --scope=var-list \ + --to="$outDir" \ + "$agents"; then + logError "Failed to get agents from $agents" + exit 1 + fi + + # The manifest lists the files that the list resolved to, also in subdirectories, as for destination