imbajin commented on code in PR #528: URL: https://github.com/apache/hugegraph-doc/pull/528#discussion_r4301489588
########## content/en/docs/clients/restful-api/other.md: ########## @@ -273,29 +273,91 @@ PUT http://localhost:8080/whiteiplist?status=true #### 11.1.6 Start the Arthas agent -Attaches the [Arthas](https://arthas.aliyun.com/en/) agent to the running server process for diagnosis. The ports, the bind IP and the disabled commands are taken from the `arthas.telnetPort`, `arthas.httpPort`, `arthas.ip` and `arthas.disabledCommands` options, see [Config Options](/docs/config/config-option/). +Starting with HugeGraph 1.8.0, Server and Store bundle Arthas 4.1.5 (PD does not embed an Arthas agent). +You can attach it to a running JVM for live troubleshooting via the local script or the administrator HTTP endpoint. + +> [!IMPORTANT] +> **Security Requirements for Diagnostics** +> - **Loopback Only**: Arthas defaults to `127.0.0.1` and accepts only loopback addresses. Non-loopback addresses (such as `0.0.0.0`) are rejected. +> Diagnostic ports must not be exposed via reverse proxies or container port mappings. +> - **Unauthenticated Agent Access**: A running Arthas agent has no authentication of its own. Processes in the same network namespace, including +> other OS users or containers in the same pod, can execute commands. Restrict host, pod, and port-forward access to trusted operators. +> The local helper stops Arthas when it exits; API-only activation still requires an explicit `stop`. +> - **Administrator Privilege**: HTTP API activation requires authentication to be enabled on Server with administrator privileges; +> requests without authentication enabled return `403`. +> - **Offline Local Diagnostics**: For routine troubleshooting, run `bin/arthas.sh` on the host as the service OS user without restarting +> the JVM or editing configuration. + +| Deployment | Recommended Activation | Access & Permissions | +|------------|------------------------|----------------------| +| Server ([auth](/docs/config/config-authentication/)) | `PUT /arthas` or `bin/arthas.sh` | Admin HTTP access; helper requires service OS user | +| Server (auth disabled) | Local helper `bin/arthas.sh` | HTTP activation returns `403` | +| Store | Local helper `bin/arthas.sh` | `GET /v1/arthasstart` is disabled and returns `403` | + +##### Activation & Diagnostics + +```bash {tab="Local Diagnostics (Recommended)"} +# 1. Run on the host as the service OS user (uses bundled agent offline, no restart or download needed) +bin/arthas.sh + +# 2. For multiple instances on one host, specify PID and port explicitly +bin/arthas.sh --pid <PID> --telnet-port 3659 + +# 3. Exit: enter 'quit' or 'stop'; the helper stops Arthas when the session ends (the service JVM keeps running) +``` -##### Method & Url +```bash {tab="Administrator HTTP Activation"} +# 1. Invoke REST API to attach diagnostic agent (requires Server authentication; enter admin password) +curl --user admin -X PUT http://127.0.0.1:8080/arthas -```text -PUT http://localhost:8080/arthas +# 2. On success, returns applied configuration (default ports 8562/8561 on 127.0.0.1) +# 3. Connect to the active agent using the local helper +bin/arthas.sh --telnet-port 8562 ``` -##### Response Status - -```json -200 +The helper reads `bin/pid` by default and requires JDK 17. Both distributions include the agent files in `lib/arthas`, so no download, +runtime extraction, or persistent user cache is needed. For a newly activated agent, telnet defaults to `127.0.0.1:3658`; HTTP, MCP, +and tunnel connections are disabled. Interactive mode requires a terminal. For pipes, scripts, or `docker exec` without `-it`, +use `bin/arthas.sh --command version` instead. + +The helper automatically stops Arthas when the client exits, including after `--command` completes or `quit`, and handles `INT`, `TERM`, +and `HUP` for cleanup. `SIGKILL` prevents cleanup; verify the agent is stopped after a forced termination. This does not change the Review Comment: The paired code PR now fixes the in-flight attach case: the attach JVM ignores INT/TERM/HUP until loadAgent completes, and exit cleanup waits before checking and stopping the target agent. The added Linux process-group regression fails on the previous helper with a late listener and passes after the fix; the application JVM remains alive. The documentation claim is now backed by that fix, so the SIGKILL limitation remains unchanged. Both PRs are still paired for coordinated merging. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
