Tools
Core's diagnostic tools are control API methods. The desktop app calls them from its pages; a script can call them too. They are not command-line subcommands of Core.
| Tool | Method | Needs a running profile |
|---|---|---|
| Delay test through a proxy | proxy.testDelay | yes |
| NAT test through a proxy | proxy.runNatTest | yes |
| This computer's public IP and NAT | core.probeHost | no |
| Location of hosts | core.locateHosts | no |
| DNS lookup | dns.lookupDns, dns.queryDns | yes, and Core's DNS resolver must run |
| Which rule a destination hits | rules.match | yes |
| SSH server inspection | ssh.probe | no |
| SSH server monitoring | ssh.watchServer (stream) | no |
| SSH host key | ssh.scanHostKey | no |
| SSH file access | ssh.listFiles, ssh.readFile, ssh.writeFile and others | no |
Request fields below are listed in wire order; a raw client sends all of them (see structs are positional arrays).
Delay test
proxy.testDelay sends one HTTP request through a proxy and reports how long it took.
| Field | App default | Notes |
|---|---|---|
proxy_id | name of a [[proxy]]; groups, DIRECT and REJECT give -32004 | |
protocol | tcp | only tcp is accepted |
url | empty | must be http://; empty means http://www.gstatic.com/generate_204 |
timeout_ms | 5000 | kept between 100 and 60000; bounds the whole test |
expected_status | 200-399 | status codes that count as success |
- The result has
ok,delay_ms(-1on failure) andmessagewith the reason of a failure. - The test follows the proxy's
dialer-proxychain (Proxy Chains). - The result also becomes the proxy's latest health, which the app's proxy list shows.
- Tests of different proxies run in parallel.
NAT test through a proxy
proxy.runNatTest sends STUN requests over a proxy's UDP path. It changes neither the route mode nor any group selection.
| Field | App default | Notes |
|---|---|---|
proxy_id | name of a [[proxy]] | |
stun_server | stun.cloudflare.com:3478 | host:port; must not be empty |
timeout_ms | 5000 | kept between 100 and 60000 |
- The result has
ok,udp_supported,nat_type,mapped_address,mapped_port,latency_ms(-1on failure),mapping_behavior,filtering_behaviorandmessage. - The proxy must carry UDP: Shadowsocks, VLESS, Hysteria2 and TUIC do, Trojan unless
udp = false, SOCKS5 and VMess only withudp = true; HTTP and AnyTLS do not (Proxies). - Mapping and filtering behaviour (RFC 5780) need a STUN server that reports
OTHER-ADDRESS, such asstun.voipgate.com:3478. With other servers only the mapped address is reported, andmessagesays why.
This computer
core.probeHost takes no fields and uses no proxy. It looks up this computer's public IP with its city, region, country and organization, and classifies the UDP NAT in front of it (full_cone, restricted_cone, port_restricted_cone, symmetric, open_internet, symmetric_udp_firewall, udp_blocked or unknown). It takes several seconds.
It contacts ipinfo.io for the address and stun.voipgate.com for the NAT test, directly from the Core machine.
Location of hosts
core.locateHosts takes up to 64 IP addresses or host names and returns the location of each, looked up on ipinfo.io without a proxy. Host names are resolved by the system resolver. Private addresses are not located. Results are cached while Core runs.
DNS lookup
Both methods take name and type (A or AAAA; empty means A). They work only while Core's DNS resolver runs: with Enhanced Mode on, or with [dns].listener enabled (DNS); otherwise they fail with -32007.
dns.lookupDnsresolves the name the way a captured query would be, and reports the rule that decided it, the route, the upstream that answered, the proxy the query went through, whether a captured query would get a Fake-IP instead, the time taken and the TTL.dns.queryDnsreturns only the answers.
Rule test
rules.match takes a target (a host name or IP, optionally with :port; IPv6 as [address]:port) and a network (tcp or udp). It reports the rule that would decide, its target, and whether the bypass list or the route mode decided first.
It reads the destination alone: no DNS lookup, so IP rules do not match a host name, and no process, so process rules never match.
SSH server tools
The ssh.* methods reach servers over SSH from the machine Core runs on. They need no profile and are available in every build.
Choosing the server
Every method takes an ssh target:
| Field | Notes |
|---|---|
alias | a Host entry of the ssh config on the Core machine; ssh.listConfigHosts lists them |
host, port, username | a direct target, when there is no alias |
port_explicit | true makes port override the alias's Port |
password | password login |
private_key_path, private_key_passphrase | a key file on the Core machine; empty uses the SSH agent and the default keys |
host_key_sha256 | the expected host key, SHA256:<base64> as OpenSSH prints it |
- A target without
host_key_sha256must be an alias whose host key is already in the Core machine'sknown_hosts. A direct target without it is refused. ssh.scanHostKeyreads a server's host key without logging in, so you can check it and pin it.- A host key that does not match is never retried.
- Prefer an alias with the SSH agent or a protected key over sending a password.
Inspection
ssh.probe opens a session, runs read-only commands and closes it.
categories(case-sensitive):System,Distribution,CPU,Memory,Disk,Uptime,Network,Docker,Processes,Monitor. Empty runs the first six. An unknown or repeated category is refused.- The commands assume a Linux server.
- Each output is cut at 32 KiB and marked
[truncated]. okmeans at least one category succeeded; checksuccess_countand each entry'sok.
Monitoring
ssh.watchServer is a stream. It keeps one SSH session open while the stream lasts and sends a sample every interval_ms (kept between 2 seconds and 5 minutes): CPU per core, memory and swap, disks, network and disk rates, load, uptime and the five busiest processes.
- After a failure Core reconnects after 5 seconds, doubling up to 60. It does not retry after a rejected login or a changed host key (
retry_in_msis0); watch again to retry. - Core keeps at most 64 watches at a time.
- Closing the stream closes the session.
Files
ssh.listFiles, ssh.makeDirectory, ssh.removeFile, ssh.moveFile, ssh.readFile, ssh.writeFile and ssh.closeFiles work over SFTP.
- Paths are absolute; an empty path in
ssh.listFileslists the login user's home. - Data travels as Base64, at most 1 MiB per call.
- An upload goes to a hidden partial file next to the target and replaces it only with the last chunk (
finish), so an interrupted upload never leaves half a file under the real name. - Core keeps the SFTP session for the next call until
ssh.closeFilesor a few idle minutes.
SSH port forwards
routing.setSshForward exists in the API, but forwards are not usable in the current Core:
- Standard builds answer
-32007:SSH port forwarding is not available in this build. - Builds made with
SPECOLA_ENABLE_ADVANCEDaccept the call, but no forward is ever defined: the profile sectionsssh-port-forward,ssh-port-forwardsandport-forwardsare ignored with a warning, and nothing else provides forwards. Turning them on starts nothing.
Not available
The current Core offers no ICMP ping, no layered connectivity diagnosis, no batch latency test of many proxies in one call, and no remote server deployment. Older /api/v1/... HTTP endpoints for them no longer exist. The app's latency column comes from proxy.testDelay and from the health checks of proxy groups.
