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.
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.
- 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 can enable the Attach API by setting this system property to yes; for example:
Using the Java Attach API
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.
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
myattachapidirin the existing
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.
A timeout value of zero indicates an indefinite wait.
<JAVA_HOME>/jre/lib/management/management.propertiesfile. Set the following properties to disable authentication in JMX:
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.