Add JAVA_AGENTS and JVM_AGENTS to load agents from URLs and paths (#4356)

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:<file>` or `-agentpath:<file>`, 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:

docs/variables.md

@@ -147,6 +147,18 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
             <td><code></code></td>
             <td>⬜️</td>
         </tr>
+        <tr>
+            <td><code>JAVA_AGENTS</code></td>
+            <td>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 <code>-javaagent</code></td>
+            <td><code></code></td>
+            <td>⬜️</td>
+        </tr>
+        <tr>
+            <td><code>JVM_AGENTS</code></td>
+            <td>Comma or newline delimited list of native JVM agent URLs, container paths to agents, or container paths to directories of <code>.so</code> agents, which are loaded with <code>-agentpath</code></td>
+            <td><code></code></td>
+            <td>⬜️</td>
+        </tr>
         <tr>
             <td><code>EXTRA_ARGS</code></td>
             <td>Arguments that would usually be passed to the jar file (those which are written after the filename)</td>

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<source entries
+  local manifest="$outDir/.var-list-manifest.json"
+  if [ -f "$manifest" ]; then
+    while read -r agent; do
+      JVM_OPTS="${JVM_OPTS} ${option}:${outDir}/${agent}"
+    done < <(jq -r '.files[]' "$manifest" | sort)
+  fi
+}
+
+if isFamily NATIVE; then
+  : # Native server, so no JVM to load agents into
+else
+  if [[ -v JVM_AGENTS ]]; then
+    addAgents "$JVM_AGENTS" /data/agents/jvm '*.so' -agentpath
+  fi
+  if [[ -v JAVA_AGENTS ]]; then
+    addAgents "$JAVA_AGENTS" /data/agents/java '*.jar' -javaagent
+  fi
+fi
+
 # Set up log4j2 configuration with templating support
 LOGFILE="${SERVER_DIR}/log4j2.xml"
 if isFamily NATIVE; then

tests/setuponlytests/agents/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      VERSION: ${MINECRAFT_VERSION:-LATEST}
+      # The image's own directory holds a Java agent among other files
+      JAVA_AGENTS: /image
+      # The JDK's debugger is a native JVM agent
+      JVM_AGENTS: /opt/java/openjdk/lib/libjdwp.so
+    volumes:
+      - ./data:/data

tests/setuponlytests/agents/require_inside.sh

@@ -0,0 +1 @@
+[[ -f /opt/java/openjdk/lib/libjdwp.so ]] || exit 1

tests/setuponlytests/agents/verify.sh

@@ -0,0 +1,3 @@
+mc-image-helper assert fileExists agents/java/Log4jPatcher.jar
+mc-image-helper assert fileNotExists agents/java/server.properties
+mc-image-helper assert fileExists agents/jvm/libjdwp.so