Support for the Java Attach API

Your application can connect to another target virtual machine using the Java™ Attach API. Your application can then load an agent application into the target virtual machine, for example to perform tasks such as monitoring status.

Code for agent applications, such as JMX agents or JVMTI agents, is normally loaded during virtual machine startup by specifying special startup parameters. Requiring startup parameters might not be convenient for using agents on applications that are already running, such as WebSphere® Application Servers. You can use the Java Attach API to load an agent at any time, by specifying the process ID of the target virtual machine. The Attach API capability is sometimes called the late attach capability.

Support for the Attach API is disabled by default.

Security considerations

Security for the Java Attach API is handled by POSIX file permissions.

The key security features of the Java Attach API are:

A process using the Java Attach API must be owned by the same UNIX user ID as the target process. This constraint ensures that only the target process owner or root can attach other applications to the target process.
The Java Attach API creates files and directories in a common directory. This directory uses the sticky bit to prevent a user from deleting or replacing a subdirectory belonging to another user. To preserve the security of this mechanism, set the ownership of the common directory to ROOT. This directory will contain files such as _attachlock, _master, and _notifier, which are used only for synchronization. These files can be owned by any user, and must have read and write permission. However, you can remove execute permission on these files, if present. The files are empty and will be re-created automatically if deleted.
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 subdirectory has owner read, write, and execute permissions plus group and world execute permissions. In this directory, read and write access are restricted to the owner only, except for the attachNotificationSync file, which must have world and group write permissions. This exception does not affect security because the file is used exclusively for synchronization and is never written to or read.
Information about the target process can be written and read only by the owner.

You must secure access to the Java Attach API capability to ensure that only authorized users or processes can connect to another virtual machine. You can enable the Attach API by setting this system property to yes in the options.default file; for example:

-Dcom.ibm.tools.attach.enable=yes

Using the Java Attach API

By default, the target virtual machine is identified by its process ID. To use a different target, change the system property com.ibm.tools.attach.id; for example:

-Dcom.ibm.tools.attach.id=<process_ID>

The target process also has a human-readable display name. By default, the display name is the command line used to start Java. To change the default display name, use the com.ibm.tools.attach.displayName system property. The ID and display name cannot be changed after the application has started.

The Attach API creates working files in a common directory, which by default is called .com_ibm_tools_attach and is created in the system temporary directory. The system property java.io.tmpdir holds the value of the system temporary directory. On UNIX systems, it is typically /tmp.

You can specify a different common directory from the default, by using the following Java system property:

-Dcom.ibm.tools.attach.directory=directory_name

This system property causes the specified directory, directory_name, to be used as the common directory. If the directory does not already exist, it is created. However the parent directory must already exist. For example, the following system property creates a common directory called myattachapidir in the existing usr directory:

-Dcom.ibm.tools.attach.directory=/usr/myattachapidir

The common directory must be located on a local drive; specifying a network mounted file system might result in incorrect behavior.

If your Java application ends abnormally, such as following a crash or a SIGKILL signal, the process subdirectory is not deleted. The Java VM detects and removes obsolete subdirectories where possible. The subdirectory can also be deleted by the owning user ID.

On heavily loaded system, applications might experience timeouts when attempting to connect to target applications. The default timeout is 120 seconds. Use the com.ibm.tools.attach.timeout system property to specify a different timeout value in milliseconds. For example, to timeout after 60 seconds:

-Dcom.ibm.tools.attach.timeout=60000

A timeout value of zero indicates an indefinite wait.

For JMX applications, you can disable authentication by editing the <JAVA_HOME>/jre/lib/management/management.properties file. Set the following properties to disable authentication in JMX:

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

Before service refresh 5, problems with the Attach API result in one of the following exceptions:

com.ibm.tools.attach.AgentLoadException
com.ibm.tools.attach.AgentInitializationException
com.ibm.tools.attach.AgentNotSupportedException
java.io.IOException

Problems with the Attach API result in one of the following exceptions:

com.sun.tools.attach.AgentLoadException
com.sun.tools.attach.AgentInitializationException
com.sun.tools.attach.AgentNotSupportedException
com.sun.tools.attach.AttachOperationFailedException
java.io.IOException

A useful reference for information about the Attach API can be found at https://docs.oracle.com/javase/8/docs/technotes/guides/attach/index.html. The J9 implementation of the Attach API is equivalent to the Oracle Corporation implementation. However, the J9 implementation cannot be used to attach to, or accept attach requests from, other virtual machine implementations.