dsh-plugin-debugging

Configuration

Fields

These fields configure this plugin in the profile composition. enableRestart also has a switch on this plugin's card on the Plugins page.

Field	Default	Meaning
enableRestart	false	Whether dsh_restart is allowed to run (Web only, Windows). Takes effect immediately, with no host restart.
dshHome	$DSH_HOME, otherwise /.dsh	Where the instance keeps profiles, logs, and credentials.
profile	$DSH_PROFILE, otherwise the default profile	Which profile the tools inspect.
port	0	Host port to probe; 0 means find the listening port automatically.
timeoutMs	60000	Timeout budget for quick work: reading a file, running one command, or one HTTP probe.
schemaDumpTimeoutMs	240000	Timeout budget for running --dump-config-schema (measured 10.2–15.7 s; 32 s under load).

Budgets

Inside a tool, every external command or HTTP probe gets a timeout 2 seconds shorter than the tool's total budget. The transport layer must time out before the host's tool deadline; otherwise the agent receives a bare TimeoutError with no error kind, and cannot tell whether retrying is useful.

Debugging another instance

When you need it: you are debugging one instance, but the evidence is on another — a second profile, or another DSH_HOME. An isolated instance must be given a template profile; otherwise the new home has no profile to start with and reports that the profile does not exist.

Which tools take dshHome: dsh_dump_config, dsh_check_effect_mode, dsh_diagnose_plugin_load, dsh_sign_cookie. Both path resolution and the spawned dsh subprocess use the home you pass in, and the output says which one was actually read (dshHomeSource: tool-argument). A value passed as an argument is never silently reported as the configured default.

Which do not, and why:

• dsh_check_auth: it answers about a host:port's authentication state, and already has host / port.
• dsh_list_instances: it only does discovery, and all it can give is a host:port.
• dsh_hot_reload: it swaps modules in the current process's memory, which cannot cross to another instance.
• dsh_restart: it kills the host it runs in, so there is no "other instance" it could be aimed at.

One trap: discovery tools can only give a host:port, and nothing maps that to a corresponding DSH_HOME; so you must supply dshHome yourself. Accordingly, dsh_diagnose_plugin_load splits its answer in two: disk evidence comes from the home you passed in, and the loader tree half reflects the current process only.