Skip to content

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.

ToolMethodNeeds a running profile
Delay test through a proxyproxy.testDelayyes
NAT test through a proxyproxy.runNatTestyes
This computer's public IP and NATcore.probeHostno
Location of hostscore.locateHostsno
DNS lookupdns.lookupDns, dns.queryDnsyes, and Core's DNS resolver must run
Which rule a destination hitsrules.matchyes
SSH server inspectionssh.probeno
SSH server monitoringssh.watchServer (stream)no
SSH host keyssh.scanHostKeyno
SSH file accessssh.listFiles, ssh.readFile, ssh.writeFile and othersno

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.

FieldApp defaultNotes
proxy_idname of a [[proxy]]; groups, DIRECT and REJECT give -32004
protocoltcponly tcp is accepted
urlemptymust be http://; empty means http://www.gstatic.com/generate_204
timeout_ms5000kept between 100 and 60000; bounds the whole test
expected_status200-399status codes that count as success
  • The result has ok, delay_ms (-1 on failure) and message with the reason of a failure.
  • The test follows the proxy's dialer-proxy chain (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.

FieldApp defaultNotes
proxy_idname of a [[proxy]]
stun_serverstun.cloudflare.com:3478host:port; must not be empty
timeout_ms5000kept between 100 and 60000
  • The result has ok, udp_supported, nat_type, mapped_address, mapped_port, latency_ms (-1 on failure), mapping_behavior, filtering_behavior and message.
  • The proxy must carry UDP: Shadowsocks, VLESS, Hysteria2 and TUIC do, Trojan unless udp = false, SOCKS5 and VMess only with udp = true; HTTP and AnyTLS do not (Proxies).
  • Mapping and filtering behaviour (RFC 5780) need a STUN server that reports OTHER-ADDRESS, such as stun.voipgate.com:3478. With other servers only the mapped address is reported, and message says 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.lookupDns resolves 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.queryDns returns 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:

FieldNotes
aliasa Host entry of the ssh config on the Core machine; ssh.listConfigHosts lists them
host, port, usernamea direct target, when there is no alias
port_explicittrue makes port override the alias's Port
passwordpassword login
private_key_path, private_key_passphrasea key file on the Core machine; empty uses the SSH agent and the default keys
host_key_sha256the expected host key, SHA256:<base64> as OpenSSH prints it
  • A target without host_key_sha256 must be an alias whose host key is already in the Core machine's known_hosts. A direct target without it is refused.
  • ssh.scanHostKey reads 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].
  • ok means at least one category succeeded; check success_count and each entry's ok.

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_ms is 0); 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.listFiles lists 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.closeFiles or 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_ADVANCED accept the call, but no forward is ever defined: the profile sections ssh-port-forward, ssh-port-forwards and port-forwards are 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.