@@ -79,11 +79,138 @@ existing precedence; see [container heap sizing](../docker/README.md#server-heap
7979
8080### Arthas diagnostics
8181
82- Server bundles Arthas 4.1.5. Activate the agent with ` PUT /arthas ` using the Server's
83- configured authentication. The existing ` arthas.ip ` , ` arthas.httpPort ` ,
84- ` arthas.telnetPort ` and ` arthas.disabledCommands ` options still configure the agent.
85- HugeGraph disables the bundled agent's optional MCP endpoint and keeps the existing
86- activation response and diagnostic HTTP/telnet interfaces.
82+ Server and Store bundle Arthas 4.1.5, managed by the root POM. PD does not embed
83+ an Arthas agent. Diagnostic ports bind to ` 127.0.0.1 ` by default. Administrators
84+ can explicitly configure another valid address, including wildcard ` 0.0.0.0 ` or
85+ ` :: ` ; ` localhost ` is normalized to ` 127.0.0.1 ` . Wildcard listeners can accept both
86+ IPv4 and IPv6 depending on the OS/JVM configuration; restrict both in firewall
87+ rules. Server's ` PUT /arthas `
88+ requires authentication to be enabled and the caller to be an authenticated administrator.
89+ Without authentication, the Server endpoint returns HTTP 403, including requests
90+ from localhost or through a reverse proxy. Store has no equivalent administrator
91+ authentication, so ` GET /v1/arthasstart ` always returns HTTP 403.
92+
93+ For local diagnosis of either running service, use its distribution's bundled
94+ helper as the same OS user that owns the JVM:
95+
96+ ``` bash
97+ bin/arthas.sh
98+ ```
99+
100+ The distribution prepares the agent in ` lib/arthas ` at build time. The helper
101+ requires JDK 17 and uses ` bin/pid ` , without downloads, runtime extraction, a user
102+ cache, service restarts or configuration edits. A new local agent listens on
103+ ` 127.0.0.1:3658 ` , with HTTP, MCP and reverse tunnels disabled. Use ` --pid ` or
104+ ` --telnet-port ` for another running instance, and ` --command version ` for a one-time
105+ command. Interactive mode requires a terminal; for pipes, scripts or ` docker exec `
106+ without ` -it ` , use ` --command ` instead. Run ` bin/arthas.sh --help ` for usage.
107+ When the helper exits, including after ` --command ` , ` quit ` , or INT/TERM/HUP, it
108+ stops the agent and all its diagnostic sessions; the application JVM keeps running.
109+ SIGKILL or a host failure cannot run this cleanup: stop any surviving agent manually.
110+ For remote diagnosis, log in to the service host over SSH and run the same command,
111+ or explicitly configure a reachable listener with appropriate authentication and
112+ network access controls as described below.
113+ Official Server (including HStore) and Store images include JDK 17, so the same
114+ helper works inside the container, for example
115+ ` docker exec -it <store-container> /hugegraph-store/bin/arthas.sh ` .
116+ A JRE-only installation needs JDK 17 for this helper.
117+ If the Server API has already activated Arthas, connect to its existing telnet
118+ port instead: ` bin/arthas.sh --telnet-port 8562 ` with the default configuration.
119+ Use ` --target-ip ` to select another bind address, for example
120+ ` bin/arthas.sh --target-ip 0.0.0.0 ` or
121+ ` bin/arthas.sh --target-ip ::1 --telnet-port 8562 --command version ` .
122+ The default is ` 127.0.0.1 ` ; ` localhost ` maps to ` 127.0.0.1 ` . Wildcard addresses
123+ ` 0.0.0.0 ` and ` :: ` may accept both IPv4 and IPv6; the helper connects and cleans
124+ up through ` 127.0.0.1 ` for either wildcard. Remote clients connect
125+ to the service host's actual reachable address, not the wildcard address.
126+ An already running agent retains its listener and authentication settings;
127+ helper options do not reconfigure it. To switch to the helper's
128+ HTTP-disabled defaults, run ` bin/arthas.sh --telnet-port 8562 --command stop ` , then
129+ ` bin/arthas.sh ` ; this stops only Arthas, and leaves the service JVM running.
130+ Arthas can execute code inside the JVM. OS attach permissions control initial
131+ activation; HugeGraph administrator authentication protects only the activation
132+ API, not subsequent diagnostic connections. We recommend enabling Arthas native
133+ authentication, especially when binding beyond loopback. However, native defaults
134+ allow connections from ` 127.0.0.1 ` to skip authentication even with credentials;
135+ other OS users or containers in the same Pod can still connect this way. To disable
136+ this bypass, set ` -Darthas.localConnectionNonAuth=false ` on the service JVM and
137+ restart it. Restrict host/Pod and port-forward access to trusted operators, and
138+ limit firewall rules, port mappings and SSH forwarding accordingly. Authentication
139+ does not encrypt telnet
140+ or ordinary HTTP traffic; use a protected network or encrypted transport for
141+ remote access. Avoid concurrent helper sessions because exiting one stops the
142+ shared agent. A disabled-command list is optional and is not access control.
143+
144+ Pass native Arthas credentials when starting or reusing an agent:
145+
146+ ``` bash
147+ bin/arthas.sh --target-ip 0.0.0.0 \
148+ --username diagnostics --password ' <arthas-password>'
149+ ```
150+
151+ Use single-line credentials; printable ASCII avoids the bundled Arthas 4.1.5
152+ telnet client's Unicode limitation. Password-only use defaults to username ` arthas ` .
153+ Native JVM credentials also apply to helper-started agents: if the target JVM has
154+ ` -Darthas.username ` or ` -Darthas.password ` , supply the effective credentials with
155+ ` --username ` / ` --password ` for authenticated commands and cleanup, especially
156+ when ` -Darthas.localConnectionNonAuth=false ` is set. The helper does not clear
157+ native credentials when the corresponding option is omitted.
158+ These credentials are separate from HugeGraph accounts. Batch commands and exit
159+ cleanup use the supplied credentials automatically. For interactive diagnosis,
160+ if prompted, enter ` auth --username diagnostics <arthas-password> ` in the Arthas
161+ console. Existing agents require their existing credentials; passing new values
162+ does not change them. Password arguments may appear in shell history and process
163+ listings, so handle them on a trusted host. With ` --username ` alone, native Arthas
164+ generates a password only when none is already configured in the target JVM's
165+ native settings; otherwise it uses that inherited password. Supply ` --password ` for
166+ authenticated batch commands and automatic cleanup. If cleanup fails, the helper
167+ returns nonzero and the agent may remain running; use the configured or generated credentials with
168+ native ` auth ` , then ` stop ` , to close it without stopping the service JVM.
169+
170+ [ Arthas native authentication] ( https://arthas.aliyun.com/en/doc/auth.html ) remains
171+ optional and follows upstream defaults: ` arthas.localConnectionNonAuth=true `
172+ allows connections from ` 127.0.0.1 ` to skip authentication. The helper uses a private
173+ configuration, so editing ` lib/arthas/arthas.properties ` does not configure it.
174+ If required, the target JVM property ` -Darthas.localConnectionNonAuth=false ` is
175+ honored after restarting the service JVM. Arthas 4.1.5 generates a password when
176+ binding ` 0.0.0.0 ` or ` :: ` without an effective native password and prints it in the target
177+ JVM output and Arthas log; explicitly supplying credentials is more convenient
178+ for remote diagnosis and authenticated cleanup.
179+
180+ Authenticated Server administrators can continue using ` PUT /arthas ` without an
181+ additional enable switch or restart. Its HTTP/telnet interfaces use the configured
182+ bind address; HugeGraph disables the optional MCP endpoint. The activation response
183+ still contains the same four Arthas configuration keys. For API activation with
184+ native credentials, add ` -Darthas.username=diagnostics ` and
185+ ` -Darthas.password=<arthas-password> ` to the Server JVM startup options and restart
186+ Server before activation. These are native JVM properties, not new REST
187+ configuration keys, and also apply to agents started by the local helper as described
188+ above. They may expose secrets in process listings. Without native
189+ credential settings, a specific non-loopback bind address does not require login; wildcard
190+ binds use the generated password described above. API activation alone
191+ leaves the agent running until an operator sends ` stop ` ; connecting through the
192+ helper applies the helper's exit cleanup to that existing agent too.
193+
194+ Before reusing an API-started agent, leave ` session ` and ` stop ` out of
195+ ` arthas.disabled_commands ` (or its legacy alias). ` session ` verifies the target
196+ PID; ` stop ` closes Arthas without stopping the service JVM. Existing configurations
197+ remain accepted, but failed PID verification or listener cleanup makes the helper
198+ print an error and exit nonzero; the agent may remain running. To recover from an
199+ agent with ` stop ` disabled, remove that restriction and restart the service before
200+ activating Arthas again. Newly attached local agents keep both commands available.
201+
202+ No commands are disabled by default. Administrators can optionally set
203+ ` arthas.disabled_commands=jad,mc ` to restrict selected commands for API activation;
204+ new local agents do not inherit this list.
205+
206+ The existing ` arthas.ip ` , ` arthas.httpPort ` , ` arthas.telnetPort ` and
207+ ` arthas.disabledCommands ` options configure the Server API-activated agent.
208+ The distribution uses ` arthas.telnet_port ` , ` arthas.http_port ` and
209+ ` arthas.disabled_commands ` . These snake_case keys take precedence over the legacy
210+ camelCase aliases when both are present, including explicit default values.
211+ Conflicting values produce a warning naming both keys and the effective key when
212+ the agent is activated. Remove the unused alias to avoid ambiguity. Store's legacy
213+ configuration fields are retained; the local helper does not read them.
87214
88215For a synchronous one-time command, POST ` {"action":"exec","command":"version"} `
89216to the agent's ` /api ` endpoint without a ` sessionId ` . Check ` state=SUCCEEDED ` , the
0 commit comments