vps/runbooks/rustdesk-health.md

RustDesk server health (hk2)

Purpose

Read-only health check of the /opt/rustdesk server stack.

Scope

• Applicable: hk2.chans.xyz, /opt/rustdesk.
• Read-only: does not change RustDesk configuration or service state.

Ownership

• Owner: personal ops (Windy)
• Last reviewed: 2026-08-17
• Related systems: hk2.chans.xyz (/opt/rustdesk)

Read-only checks for the /opt/rustdesk stack on hk2.chans.xyz.

Facts: hosts/hk2.chans.xyz.md

Prefer the Ansible health report for routine checks and the rustdesk playbook for reviewed config changes. Keep the SSH commands below for focused diagnosis.

Focused SSH diagnostics

Use these only after the Ansible health report needs investigation.

Quick remote

ssh -4 windy@hk2.chans.xyz 'cd /opt/rustdesk && docker compose ps -a'

Expect hbbs and hbbr both Up. Ignore any stopped orphans unless cleaning up.

Version / image pin

Expect rustdesk/rustdesk-server:1.1.14 (or the documented pin). Startup logs should show the relay list and no errors.

ssh -4 windy@hk2.chans.xyz 'docker inspect hbbs --format "{{.Config.Image}}"; docker inspect hbbr --format "{{.Config.Image}}"'

Relay address (the critical check)

The hbbs -r <host>:21117 value is advertised to every client as the relay (hbbr) address. It must resolve to this host's public IP 154.36.174.161. hk2.chans.xyz is the correct value; hk2.wsvc.info has no DNS record and must never be used.

# The value hbbs is actually serving (definitive):
ssh -4 windy@hk2.chans.xyz 'docker inspect hbbs --format "{{json .Config.Cmd}}"'
# expect ["hbbs","-r","hk2.chans.xyz:21117"]

# Confirm the relay hostname resolves to the public IP:
dig +short hk2.chans.xyz A @1.1.1.1          # expect 154.36.174.161

# Confirm the relay hostname is what hbbs logs as its relay list:
ssh -4 windy@hk2.chans.xyz 'docker logs hbbs 2>&1 | grep "relay-servers" | tail -1'
# expect relay-servers=["hk2.chans.xyz:21117"]

Ports (from laptop / WSL)

IP=154.36.174.161
nc -vz -w 5 $IP 21117   # hbbr relay TCP
nc -vz -w 5 $IP 21116   # hbbs rendezvous TCP
nc -vz -u -w 5 $IP 21116  # hbbs rendezvous UDP
nc -vz -w 5 $IP 21115   # hbbs NAT type test

Scheduled local check

The sanitized Ansible health profile is rustdesk (deployed via ansible/playbooks/healthchecks.yml on hosts whose inventory lists it). It runs locally through vps-healthcheck.timer, writes a sanitized JSON result to /var/lib/vps-health/latest.json, and never exposes secrets.

Safety

• Read-only: never mutate configuration or service state during this check.
• If live state conflicts with an expected value, STOP and report.

After config changes

Reviewed changes to /opt/rustdesk/compose.yml (relay address, image pin, port mapping) are applied through the gated rustdesk playbook:

cd ansible
ansible-playbook playbooks/rustdesk.yml --limit rustdesk \
  -e '{"rustdesk_confirm": true}'

Re-run the health report afterwards.