Skip to content

Health Checks

Jump to bottom
Marc Pope edited this page Oct 8, 2026 · 1 revision

Health checks

Since 1.8.1.

Two public endpoints for load balancers, uptime monitors and container orchestrators. Neither needs a session or a token, and neither reveals anything beyond true or false.

Endpoint Checks Status codes
GET /health/live The application answers. Nothing else. 200
GET /health/ready The database, the ID server and every relay. 200 ready, 503 not ready

Both can also answer 429 when probed too often. See rate limits.

Liveness

GET /health/live

{"live":true}

Use it to decide whether to restart the console. It does not touch the database or the RustDesk servers, so an outage elsewhere never restarts a healthy console.

Readiness

GET /health/ready

{"ready":true,"database":true,"id_server":true,"relay_server":true}
  • database: a select 1 succeeds.
  • id_server: a TCP connection to the ID server in Settings → Server opens within one second, on port 21116 unless the address names another. No ID server configured counts as true.
  • relay_server: the same for every address under Relay Servers in Settings → Server, or for the single Relay Server when that list is empty, on port 21117 unless the address names another. One unreachable relay makes it false. No relay configured counts as true.

ready is true only when all three are. When the database is down the server checks are skipped and reported false.

Point monitoring and load balancer health checks here.

Rate limits

Each endpoint has one counter shared by every caller, reset once a minute:

Endpoint Requests per minute
/health/live 120
/health/ready 30

Past the limit the endpoint answers 429 with Retry-After: 60 and every field false. The limit is shared, so add up everything that polls: three load balancer nodes checking /health/ready every five seconds make 36 requests a minute and will see 429s. Keep the total under 30 a minute, for example one probe every 10 seconds from no more than three sources.

The counter is kept in files on local disk, not in the database, so readiness still reports during a database outage.

1.8.1 and 1.9.0 had a bug where the counter never reset under steady probing, so Docker's own healthcheck drove /health/live to 429 and marked the container unhealthy. Fixed in 1.9.1.

Docker

The image's HEALTHCHECK calls /health/live every 30 seconds with a 5-second timeout and a 30-second start period, on CORTENDESK_HTTP_PORT inside the container. It uses liveness on purpose: when the ID server or relay runs elsewhere, a relay outage would otherwise mark the console unhealthy and restart it for nothing.

docker inspect --format '{{.State.Health.Status}}' <container>

Load balancers and uptime monitors

  • Health check path: /health/ready, expecting 200.
  • Behind a reverse proxy, probe the console directly or through the proxy; both work. See Reverse proxy and TLS.
  • For an alert that names the failing part, read the JSON body rather than only the status code.

/up also exists. It is the framework's built-in check: it returns an HTML page with 200 when PHP serves requests, checks nothing else, and has no rate limit. Prefer the two endpoints above.

Fleet diagnostics covers the same ground and more for a person looking at the console.

Related

Clone this wiki locally