0
# Agent Attachment
1

2
Remote attachment capabilities for deploying Java agents to other JVM processes. Supports both JAR-based agents and native agent libraries with flexible process targeting and cross-platform compatibility.
3

4
## Capabilities
5

6
### JAR Agent Attachment
7

8
Attach Java agent JAR files to remote JVM processes. The agent JAR must contain proper manifest headers and implement the Java agent specification (premain/agentmain methods).
9

10
```java { .api }
11
/**
12
 * Attaches the given agent JAR to the target process. The agent is not provided an argument.
13
 * @param agentJar The agent jar file
14
 * @param processId The target process id
15
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
16
 */
17
public static void attach(File agentJar, String processId);
18

19
/**
20
 * Attaches the given agent JAR to the target process with an argument.
21
 * @param agentJar The agent jar file
22
 * @param processId The target process id
23
 * @param argument The argument to provide to the agent (may be null)
24
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
25
 */
26
public static void attach(File agentJar, String processId, @MaybeNull String argument);
27

28
/**
29
 * Attaches the given agent JAR using a custom attachment provider.
30
 * @param agentJar The agent jar file
31
 * @param processId The target process id
32
 * @param attachmentProvider The attachment provider to use
33
 * @throws IllegalStateException If attachment fails
34
 */
35
public static void attach(File agentJar, String processId, AttachmentProvider attachmentProvider);
36

37
/**
38
 * Attaches the given agent JAR with argument using a custom attachment provider.
39
 * @param agentJar The agent jar file
40
 * @param processId The target process id
41
 * @param argument The argument to provide to the agent (may be null)
42
 * @param attachmentProvider The attachment provider to use
43
 * @throws IllegalStateException If attachment fails
44
 */
45
public static void attach(File agentJar, String processId, @MaybeNull String argument, AttachmentProvider attachmentProvider);
46
```
47

48
### Process Provider Based Attachment
49

50
Attach agents using process providers for more flexible process targeting and discovery.
51

52
```java { .api }
53
/**
54
 * Attaches the given agent JAR using a process provider to resolve the target process.
55
 * @param agentJar The agent jar file
56
 * @param processProvider A provider of the target process id
57
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
58
 */
59
public static void attach(File agentJar, ProcessProvider processProvider);
60

61
/**
62
 * Attaches the given agent JAR with argument using a process provider.
63
 * @param agentJar The agent jar file
64
 * @param processProvider A provider of the target process id
65
 * @param argument The argument to provide to the agent (may be null)
66
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
67
 */
68
public static void attach(File agentJar, ProcessProvider processProvider, @MaybeNull String argument);
69

70
/**
71
 * Attaches the given agent JAR using process provider and custom attachment provider.
72
 * @param agentJar The agent jar file
73
 * @param processProvider A provider of the target process id
74
 * @param attachmentProvider The attachment provider to use
75
 * @throws IllegalStateException If attachment fails
76
 */
77
public static void attach(File agentJar, ProcessProvider processProvider, AttachmentProvider attachmentProvider);
78

79
/**
80
 * Attaches the given agent JAR with all custom options.
81
 * @param agentJar The agent jar file
82
 * @param processProvider A provider of the target process id
83
 * @param argument The argument to provide to the agent (may be null)
84
 * @param attachmentProvider The attachment provider to use
85
 * @throws IllegalStateException If attachment fails
86
 */
87
public static void attach(File agentJar, ProcessProvider processProvider, @MaybeNull String argument, AttachmentProvider attachmentProvider);
88
```
89

90
### Native Agent Attachment
91

92
Attach native agent libraries to remote JVM processes. Native agents are platform-specific shared libraries that implement the JVMTI interface.
93

94
```java { .api }
95
/**
96
 * Attaches the given native agent library to the target process.
97
 * @param agentLibrary The agent library
98
 * @param processId The target process id
99
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
100
 */
101
public static void attachNative(File agentLibrary, String processId);
102

103
/**
104
 * Attaches the given native agent library with an argument.
105
 * @param agentLibrary The agent library
106
 * @param processId The target process id
107
 * @param argument The argument to provide to the agent (may be null)
108
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
109
 */
110
public static void attachNative(File agentLibrary, String processId, @MaybeNull String argument);
111

112
/**
113
 * Attaches the given native agent library using a custom attachment provider.
114
 * @param agentLibrary The agent library
115
 * @param processId The target process id
116
 * @param attachmentProvider The attachment provider to use
117
 * @throws IllegalStateException If attachment fails
118
 */
119
public static void attachNative(File agentLibrary, String processId, AttachmentProvider attachmentProvider);
120

121
/**
122
 * Attaches the given native agent library with all options.
123
 * @param agentLibrary The agent library
124
 * @param processId The target process id
125
 * @param argument The argument to provide to the agent (may be null)
126
 * @param attachmentProvider The attachment provider to use
127
 * @throws IllegalStateException If attachment fails
128
 */
129
public static void attachNative(File agentLibrary, String processId, @MaybeNull String argument, AttachmentProvider attachmentProvider);
130

131
/**
132
 * Attaches the given native agent library using a process provider to resolve the target process.
133
 * @param agentLibrary The agent library
134
 * @param processProvider A provider of the target process id
135
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
136
 */
137
public static void attachNative(File agentLibrary, ProcessProvider processProvider);
138

139
/**
140
 * Attaches the given native agent library with argument using a process provider.
141
 * @param agentLibrary The agent library
142
 * @param processProvider A provider of the target process id
143
 * @param argument The argument to provide to the agent (may be null)
144
 * @throws IllegalStateException If the current VM does not support attachment or attachment fails
145
 */
146
public static void attachNative(File agentLibrary, ProcessProvider processProvider, @MaybeNull String argument);
147

148
/**
149
 * Attaches the given native agent library using process provider and custom attachment provider.
150
 * @param agentLibrary The agent library
151
 * @param processProvider A provider of the target process id
152
 * @param attachmentProvider The attachment provider to use
153
 * @throws IllegalStateException If attachment fails
154
 */
155
public static void attachNative(File agentLibrary, ProcessProvider processProvider, AttachmentProvider attachmentProvider);
156

157
/**
158
 * Attaches the given native agent library with all custom options.
159
 * @param agentLibrary The agent library
160
 * @param processProvider A provider of the target process id
161
 * @param argument The argument to provide to the agent (may be null)
162
 * @param attachmentProvider The attachment provider to use
163
 * @throws IllegalStateException If attachment fails
164
 */
165
public static void attachNative(File agentLibrary, ProcessProvider processProvider, @MaybeNull String argument, AttachmentProvider attachmentProvider);
166
```
167

168
## Usage Examples
169

170
### Basic JAR Agent Attachment
171

172
```java
173
import net.bytebuddy.agent.ByteBuddyAgent;
174
import java.io.File;
175

176
// Attach agent to a specific process
177
File agentJar = new File("/path/to/my-agent.jar");
178
String targetProcessId = "1234";
179

180
ByteBuddyAgent.attach(agentJar, targetProcessId);
181

182
// Attach with arguments
183
String agentArgs = "configuration=debug,output=/tmp/agent.log";
184
ByteBuddyAgent.attach(agentJar, targetProcessId, agentArgs);
185
```
186

187
### Native Agent Attachment
188

189
```java
190
import net.bytebuddy.agent.ByteBuddyAgent;
191
import java.io.File;
192

193
// Attach native agent library (e.g., profiler)
194
File nativeAgent = new File("/path/to/libprofiler.so");  // Linux
195
// File nativeAgent = new File("C:\\path\\to\\profiler.dll");  // Windows
196

197
String targetProcessId = "5678";
198
ByteBuddyAgent.attachNative(nativeAgent, targetProcessId);
199

200
// With configuration arguments
201
String profilerConfig = "sampling-rate=100,output-file=profile.log";
202
ByteBuddyAgent.attachNative(nativeAgent, targetProcessId, profilerConfig);
203
```
204

205
### Custom Attachment Provider
206

207
```java
208
import net.bytebuddy.agent.ByteBuddyAgent;
209
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
210
import java.io.File;
211

212
// Use specific attachment mechanism
213
File agentJar = new File("my-agent.jar");
214
String processId = "9999";
215

216
// Force use of JNA-based attachment
217
AttachmentProvider jnaProvider = AttachmentProvider.ForEmulatedAttachment.INSTANCE;
218
ByteBuddyAgent.attach(agentJar, processId, jnaProvider);
219

220
// Create custom provider chain
221
AttachmentProvider customProvider = new AttachmentProvider.Compound(
222
    AttachmentProvider.ForModularizedVm.INSTANCE,  // Try Java 9+ first
223
    AttachmentProvider.ForJ9Vm.INSTANCE,           // Then IBM J9
224
    AttachmentProvider.ForEmulatedAttachment.INSTANCE  // Finally JNA fallback
225
);
226
ByteBuddyAgent.attach(agentJar, processId, customProvider);
227
```
228

229
### Process Discovery and Attachment
230

231
```java
232
import net.bytebuddy.agent.ByteBuddyAgent;
233
import net.bytebuddy.agent.ByteBuddyAgent.ProcessProvider;
234
import java.io.File;
235
import java.lang.management.ManagementFactory;
236

237
// Get current process ID for self-attachment
238
ProcessProvider currentProcess = ProcessProvider.ForCurrentVm.INSTANCE;
239
File agentJar = new File("self-modifying-agent.jar");
240

241
// This is equivalent to ByteBuddyAgent.install() but using attach mechanism
242
ByteBuddyAgent.attach(agentJar, currentProcess);
243

244
// Custom process provider implementation
245
ProcessProvider customProvider = new ProcessProvider() {
246
    @Override
247
    public String resolve() {
248
        // Custom logic to find target process
249
        return findMyApplicationProcess();
250
    }
251
    
252
    private String findMyApplicationProcess() {
253
        // Implementation to locate specific application process
254
        return "1234";
255
    }
256
};
257

258
ByteBuddyAgent.attach(agentJar, customProvider);
259
```
260

261
### Error Handling and Diagnostics
262

263
```java
264
import net.bytebuddy.agent.ByteBuddyAgent;
265
import java.io.File;
266

267
File agentJar = new File("diagnostic-agent.jar");
268
String processId = "1234";
269

270
try {
271
    // Enable diagnostic dumping for troubleshooting
272
    System.setProperty("net.bytebuddy.agent.attacher.dump", "/tmp/attachment-debug.log");
273
    
274
    ByteBuddyAgent.attach(agentJar, processId);
275
    System.out.println("Agent attached successfully");
276
    
277
} catch (IllegalStateException e) {
278
    System.err.println("Attachment failed: " + e.getMessage());
279
    
280
    // Common failure reasons:
281
    // - Target process not found or not accessible
282
    // - Attachment mechanism not available
283
    // - Agent JAR malformed or missing manifest
284
    // - Insufficient permissions
285
    
286
    // Try with different provider
287
    try {
288
        ByteBuddyAgent.attach(agentJar, processId, 
289
            AttachmentProvider.ForEmulatedAttachment.INSTANCE);
290
        System.out.println("Attachment succeeded with JNA provider");
291
    } catch (IllegalStateException fallbackFailure) {
292
        System.err.println("All attachment methods failed");
293
    }
294
}
295
```
296

297
## Agent JAR Requirements
298

299
For successful attachment, agent JAR files must include proper manifest headers:
300

301
```
302
Manifest-Version: 1.0
303
Agent-Class: com.example.MyAgent
304
Can-Redefine-Classes: true
305
Can-Retransform-Classes: true
306
Can-Set-Native-Method-Prefix: true
307
```
308

309
And implement the agent specification:
310

311
```java
312
public class MyAgent {
313
    public static void agentmain(String agentArgs, Instrumentation inst) {
314
        // Agent implementation for attach API
315
    }
316
    
317
    public static void premain(String agentArgs, Instrumentation inst) {
318
        // Agent implementation for command-line loading
319
    }
320
}
321
```
322

323
## Security and Limitations
324

325
- **Same-user restriction**: Can only attach to processes executed by the same operating system user
326
- **JVM compatibility**: Attachment mechanisms vary by JVM implementation and version
327
- **Platform dependencies**: Some attachment methods require JDK tools or JNA library
328
- **External processes**: Java 9+ may require external process for self-attachment due to security restrictions
329
- **Permissions**: Target process must allow agent attachment (not all JVMs support this)