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 enabled by default.

Support for the Attach API is enabled by default, except on z/OS® systems where it is disabled by default. On z/OS systems, processes that use the default z/OS OMVS segment cannot enable the Attach API for security reasons.

Security considerations

Windows systems: The Java Attach API creates files and directories in a common directory. On Windows platforms, security of the common directory and its subdirectories and files is handled by Windows security mechanisms. This means that only the process owner can connect to their processes.

AIX, Linux, and z/OS systems: Security for the Java Attach API is handled by POSIX file permissions.

Note: On z/OS, you must use UNIX user permissions to protect your applications. It is not sufficient to rely on RACF® or system level security to protect your applications. The reason is that these mechanisms do not have the necessary UNIX permissions set up and configured for the Java Attach API to remain secure.
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. If you do not intend to use the Java Attach API capability, disable this feature by setting the Java system property com.ibm.tools.attach.enable to no; for example:
-Dcom.ibm.tools.attach.enable=no
You can enable the Attach API by setting this system property to yes; 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 Windows systems, the system temporary directory is typically C:\Documents and Settings\<userid>\Local Settings\Temp. 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
Start of changes for service refresh 5Problems 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
End of changes for service refresh 5

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.