Java Attach API

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. 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). 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, processes that use the default z/OS OMVS segment cannot enable the Attach API.

To enable or disable the Attach API, use the[yes|no] command line option.

Securing the Attach API

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 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 that uses the Java Attach API must be owned by the same UNIX user ID as the target process.

~/tmp $ ls -al
total 0
drwxr-xr-x   3 user_a staff    96  6 Aug 17:11 .
drwxr-xr-x+ 89 user_a staff  2848  6 Aug 17:11 ..
drwxrwxrwx+  7 root   staff   224  6 Aug 17:22 .com_ibm_tools_attach

In the default Attach API directory you can find certain files that start with an underscore _*, which are involved in synchronization. These files can be owned by any user but must have read and write permissions set. The files are empty and are automatically re-created if deleted. When your application attaches to a VM, a process directory is created.

~/tmp/.com_ibm_tools_attach $ ls -l
total 3
-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _attach_lock
-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _controller
-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _notifier
drwx--x--x  6 user_b  staff  192  6 Aug 17:21 process_a

The files in the subdirectory for a process, with the exception of a lock file, are accessible only by the owner of a process. The permissions for these files are rwxr-xr-x with the exception of the attachNotificationSync file, as shown in the following example.

~/tmp/.com_ibm_tools_attach/process_a $ ls -l
total 4
-rwxrw-rw-  1 user_b  staff  0  6 Aug 17:18 attachNotificationSync
-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_a
-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_b
-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_c

Notes for z/OS:


A number of system properties are available to configure the Attach API when you start a Java application, as shown in the following table:

System property Description<directory_name> Specify a different common directory for Attach API working files.<my_display_name> Change the display name recorded by an agent<my_vm_ID> Change the VM identifier recorded by an agent<value_in_milliseconds> Change the connection timeout<value_in_milliseconds> Specify the timeout for ending the Attach API wait loop thread<value_in_milliseconds> Specify the timeout for sending a command to the target VM after initial attachment

To learn more about each property, click the link in the table.


Problems with the Attach API generate one of the following exceptions:

Exceptions from agents on the target VM go to stderr or stdout for the target VM. These exceptions are not reported in the output of the attaching VM.

Here are some problems that you might encounter:

If you have checked for these potential issues but you are still experiencing problems, a number of command line system properties are available to help narrow down the cause. These options are shown in the following table:

System property Description<yes|no> Turn on tracing of attach API events<my_log_name> Specify the path and prefix for the log files

To learn more about each property, click the link in the table.