Documentation for -XX:[+|-]EnableDynamicAgentLoading

eclipse-openj9#1140

Created a new topic for the -XX:[+|-]EnableDynamicAgentLoading option Updated the related topics.

Closes eclipse-openj9#1140
Signed-off-by: Sreekala Gopakumar <sreekala.gopakumar@ibm.com>

docs/attachapi.md

@@ -25,11 +25,11 @@
 
 With the Attach API, your application can connect to a running VM and load an agent into that VM to run tasks. The typical use case for this feature is to load an agent that can be used to monitor the application that's running in the target VM.
 
-For example, if you wanted to start monitoring an application that is already running with the Attach API enabled, you could use a tool such as the [IBM Health Center](https://www.ibm.com/support/knowledgecenter/en/SS3KLZ/com.ibm.java.diagnostics.healthcenter.doc/topics/introduction.html). In this case, a Health Center agent can start in its own VM and attach to the target VM where the application  is running to start recording and sending data to the Health Center client.
+For example, if you wanted to start monitoring an application that is already running with the Attach API enabled, you could use a tool such as the [IBM Health Center](https://www.ibm.com/support/knowledgecenter/en/SS3KLZ/com.ibm.java.diagnostics.healthcenter.doc/topics/introduction.html). In this case, a Health Center agent can start in its own VM and attach to the target VM where the application is running to start recording and sending data to the Health Center client.
 
-The Eclipse OpenJ9™ implementation of the Attach API is equivalent to the reference implementation (API documentation is available on the [Oracle website](https://docs.oracle.com/javase/8/docs/jdk/api/attach/spec/index.html)). However, you can only use the Attach API to connect to another OpenJ9 VM.
+The Eclipse OpenJ9™ implementation of the Attach API is equivalent to the reference implementation (API documentation is available on the [Oracle website](https://docs.oracle.com/javase/8/docs/jdk/api/attach/spec/index.html)). However, you can use the Attach API only to connect to another OpenJ9 VM.
 
-When you run a Java™ application, VM support for the Attach API is enabled by default on all platforms except z/OS®. For security reasons on  z/OS,
+When you run a Java™ application, VM support for the Attach API is enabled by default on all platforms except z/OS®. For security reasons on z/OS,
 processes that use the default z/OS OMVS segment cannot enable the Attach API.
 
 To enable or disable the Attach API, use the [`-Dcom.ibm.tools.attach.enable=[yes|no]`](dcomibmtoolsattachenable.md) command line option.
@@ -39,10 +39,12 @@ To enable or disable the Attach API, use the [`-Dcom.ibm.tools.attach.enable=[ye
 Because the Attach API can be used to connect to a running application, you must control access to it to ensure that only
 authorized users or processes can use it. Disable the Attach API if you do not intend to use it.
 
+If you do not want to disable the Attach API but want to control the unauthorized dynamic loading of agents into the VM by using the Attach API, use the [`-XX:-EnableDynamicAgentLoading`](xxenabledynamicagentloading.md) option.
+
 On Windows systems, the Attach API uses the system temporary directory, which is typically `C:\Users\<USERNAME>\AppData\Local\Temp`.
 The Attach API creates a common subdirectory, which is `.com_ibm_tools_attach` by default. Because files and directories in the system temporary directory are handled by Windows security, only the process owner can connect to their processes.
 
-On UNIX systems, the Attach API uses `/tmp` and creates a common subdirectory, which is `.com_ibm_tools_attach` by default. The common subdirectory must be on a local drive, not a network drive. Security is handled by POSIX file permissions. The Attach API directory must be owned by `root` user and must have read, write, and execute file permissions for `user`, `group`, and `other` (`drwxrwxrwx`). The sticky bit is set so that only the owner and `root` can delete or rename files or directories within it. A process using the Java Attach API must be owned by the same UNIX user ID as the target process.
+On UNIX systems, the Attach API uses `/tmp` and creates a common subdirectory, which is `.com_ibm_tools_attach` by default. The common subdirectory must be on a local drive, not a network drive. Security is handled by POSIX file permissions. The Attach API directory must be owned by `root` user and must have read, write, and execute file permissions for `user`, `group`, and `other` (`drwxrwxrwx`). The sticky bit is set so that only the owner and `root` can delete or rename files or directories within it. A process that uses the Java Attach API must be owned by the same UNIX user ID as the target process.
 
 ```
 ~/tmp $ ls -al

docs/version0.41.md

@@ -30,6 +30,7 @@ The following new features and notable changes since version 0.40.0 are included
 - ![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) [New `-XX:ContinuationCache` option added](#new-xxcontinuationcache-option-added) ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
 - ![Start of content that applies only to Java 11+ (LTS)](cr/java11plus.png) [`-XX:+CompactStrings` option enabled by default](#-xxcompactstrings-option-enabled-by-default) ![End of content that applies only to Java 11 and later](cr/java_close_lts.png)
 - [Change in behavior of `-Xshareclasses:readonly`](#change-in-behavior-of-xshareclassesreadonly)
+- [New `-XX:[+|-]EnableDynamicAgentLoading` option added](#new-xx-enabledynamicagentloading-option-added)
 
 ## Features and changes
 
@@ -63,6 +64,14 @@ In the earlier releases, if the `-Xshareclasses:readonly` option and the JITServ
 
 Now, with the change in behavior of the [`-Xshareclasses:readonly`](xshareclasses.md#readonly) option, the shared class cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.
 
+### New `-XX:[+|-]EnableDynamicAgentLoading` option added
+
+This option enables or disables the dynamic loading of agents into a running VM. The `-XX:+EnableDynamicAgentLoading` option is the default setting.
+
+![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) For Java 21 and later, warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the `-XX:+EnableDynamicAgentLoading` option and the same agents were not loaded at startup. ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
+
+For more information, see [`-XX:[+|-]EnableDynamicAgentLoading`](xxenabledynamicagentloading.md).
+
 ## Known problems and full release information
 
 To see known problems and a complete list of changes between Eclipse OpenJ9 v0.40.0 and v0.41.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.41/0.41.md).

docs/xxenabledynamicagentloading.md

@@ -0,0 +1,60 @@
+<!--
+* Copyright (c) 2017, 2023 IBM Corp. and others
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which accompanies this distribution and is available at
+* https://www.eclipse.org/legal/epl-2.0/ or the Apache
+* License, Version 2.0 which accompanies this distribution and
+* is available at https://www.apache.org/licenses/LICENSE-2.0.
+*
+* This Source Code may also be made available under the
+* following Secondary Licenses when the conditions for such
+* availability set forth in the Eclipse Public License, v. 2.0
+* are satisfied: GNU General Public License, version 2 with
+* the GNU Classpath Exception [1] and GNU General Public
+* License, version 2 with the OpenJDK Assembly Exception [2].
+*
+* [1] https://www.gnu.org/software/classpath/license.html
+* [2] https://openjdk.org/legal/assembly-exception.html
+*
+* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 OR GPL-2.0-only WITH OpenJDK-assembly-exception-1.0
+-->
+
+# -XX:\[+|-\]EnableDynamicAgentLoading
+
+This option enables or disables the dynamic loading of agents into a running VM.
+
+
+## Syntax
+
+        -XX:[+|-]EnableDynamicAgentLoading
+
+| Setting               | Effect  | Default                                                                            |
+|-----------------------|---------|:----------------------------------------------------------------------------------:|
+| `-XX:+EnableDynamicAgentLoading` |  Enable   |   :fontawesome-solid-check:{: .yes aria-hidden="true"}<span class="sr-only">yes</span>                                 |
+| `-XX:-EnableDynamicAgentLoading` |  Disable  |     |
+
+
+## Explanation
+
+With the [Attach API](attachapi.md), your application can connect to a running VM and load an agent dynamically into that VM to run tasks. Some libraries misuse the Attach API to dynamically load an agent to run tasks without the approval of the application owner.
+
+You can disable the dynamic loading of the agents into a VM after startup with the `-XX:-EnableDynamicAgentLoading` option.
+
+![Start of content that applies to Java 21 (LTS) and later](cr/java21plus.png) For Java&trade; 21 and later, the following warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the `-XX:+EnableDynamicAgentLoading` option and the same agents were not loaded at startup by using the [command-line options](interface_jvmti.md#overview):
+
+```
+WARNING: A {Java,JVM TI} agent has been loaded dynamically (file:/u/bob/agent.jar)
+WARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading to hide this warning
+WARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage for more information
+WARNING: Dynamic loading of agents will be disallowed by default in a future release
+```
+AIX&reg; systems cannot detect whether an agent library was previously loaded at startup or not. Therefore, the warnings are issued when an agent is loaded dynamically through the Attach API (`VirtualMachine.loadAgentLibrary(agent)`) even if the agent was loaded through the command-line option (`-agentpath:/Absolute/Path/to/agentLibrary`) at startup. ![End of content that applies to Java 21 (LTS) and later](cr/java_close_lts.png)
+
+## See also
+
+- [Java Virtual Machine Tool Interface](interface_jvmti.md)
+- [Java Attach API](attachapi.md)
+
+<!-- ==== END OF TOPIC ==== xxenabledynamicagentloading.md ==== -->

mkdocs.yml

@@ -388,6 +388,7 @@ nav:
             - "-XX:[+|-]DisclaimJitScratch"                                      : xxdisclaimjitscratch.md
             - "-XX:[+|-]Enable3164Interoperability"                              : xxenable3164interoperability.md
             - "-XX:[+|-]EnableCPUMonitor"                                        : xxenablecpumonitor.md
+            - "-XX:[+|-]EnableDynamicAgentLoading"                               : xxenabledynamicagentloading.md
             - "-XX:[+|-]EnsureHashed"                                            : xxensurehashed.md
             - "-XX:[+|-]ExitOnOutOfMemoryError"                                  : xxexitonoutofmemoryerror.md
             - "-XX:[+|-]GlobalLockReservation"                                   : xxgloballockreservation.md