Guide Universel de Diagnostic — RustDesk sur Debian 13
Guide Universel de Diagnostic de problèmes possibles sur RustDesk
CHECKLIST RAPIDE — À exécuter en début d'épreuve
uptime && free -h && df -h
systemctl status hbbs hbbr
ss -tlnup | grep -E '2111[5-7]'
ps aux | grep -E 'hbbs|hbbr'
docker ps -a 2>/dev/null || echo "Docker absent ou non démarré"
journalctl -p err -n 30 --no-pager
ip a && ip route
PHASE 1 — Identification du symptôme
1.1 Table de correspondance symptôme / phase prioritaire
| Symptôme observé | Phase prioritaire | |-----------------------------------------------|-------------------------| | Client RustDesk ne se connecte pas | Phase 3, puis Phase 4 | | Service planté ou inactif | Phase 4, puis Phase 6 | | Erreur de permission au démarrage | Phase 7, puis Phase 8 | | Connection refused | Phase 3, puis Phase 4 | | Timeout sans réponse | Phase 3, puis Phase 5 | | Panne apparue après un redémarrage | Phase 4, puis Phase 7 | | Conteneur Docker défaillant | Phase 5, puis Phase 6 | | Comportement aléatoire ou instable | Phase 2, puis Phase 6 |
1.2 Questions préalables
- Depuis quand la panne est-elle apparue ?
- Y a-t-il eu une modification récente (config, mise à jour, redémarrage) ?
- Le problème est-il total ou partiel ?
- Le problème est-il constant ou intermittent ?
- Y a-t-il un message d'erreur visible côté client ou serveur ?
PHASE 2 — Vérifications système de base
2.1 Charge CPU
uptime
Attendu : charge moyenne inférieure au nombre de cœurs CPU.
SI surcharge détectée :
top -b -n1 | head -20
ps aux --sort=-%cpu | head -10
2.2 Mémoire
free -h
Attendu : mémoire disponible supérieure à 200 Mo.
SI mémoire saturée :
ps aux --sort=-%mem | head -15
2.3 Espace disque
df -h
Attendu : aucune partition au-delà de 90 % d'utilisation.
SI disque plein :
du -sh /var/log/* | sort -rh | head -10
journalctl --disk-usage
2.4 Intégrité des binaires
ls -lh /opt/rustdesk-server/
Attendu : présence de hbbs, hbbr, et des fichiers de clés (.key, .pub).
SI fichiers manquants : corruption ou suppression — restaurer les binaires.
stat /opt/rustdesk-server/hbbs /opt/rustdesk-server/hbbr
Attendu : bit exécutable présent, propriétaire cohérent avec l'utilisateur du service.
SI permissions incorrectes :
chmod +x /opt/rustdesk-server/hbbs /opt/rustdesk-server/hbbr
2.5 Utilisateur système du service
id rustdesk 2>/dev/null || echo "Utilisateur rustdesk inexistant"
SI inexistant : le service tourne probablement en root ou avec un utilisateur différent.
Vérifier le champ User= dans les fichiers unit systemd (Phase 4).
2.6 Synchronisation horaire
timedatectl
Attendu : System clock synchronized: yes et fuseau horaire correct.
SI désynchronisé :
systemctl restart systemd-timesyncd
timedatectl set-ntp true
PHASE 3 — Vérifications réseau
3.1 Interfaces et adressage
ip a
Attendu : interface principale avec une adresse IP valide, état UP.
SI interface absente ou DOWN :
ip link set <interface> up
systemctl restart networking
ip route
Attendu : route par défaut présente (default via ...).
SI route manquante :
ip route add default via <passerelle>
3.2 Ports en écoute
ss -tlnup | grep -E '2111[5-7]'
Attendu :
tcp LISTEN 0 128 0.0.0.0:21115 ... hbbs
tcp LISTEN 0 128 0.0.0.0:21116 ... hbbs
tcp LISTEN 0 128 0.0.0.0:21117 ... hbbr
SI un port n'est pas en écoute :
- Processus mort → aller Phase 4.
- Processus actif mais port absent → mauvaise configuration → aller Phase 7.
ss -ulnup | grep 21116
Attendu : port 21116 UDP également en écoute (utilisé par hbbs).
3.3 Pare-feu
nft list ruleset 2>/dev/null || iptables -L -n -v
Attendu : aucune règle DROP ou REJECT sur les ports 21115 à 21117.
SI règles bloquantes détectées :
nft add rule inet filter input tcp dport { 21115, 21116, 21117 } accept
nft add rule inet filter input udp dport 21116 accept
Ou avec iptables :
iptables -I INPUT -p tcp --dport 21115:21117 -j ACCEPT
iptables -I INPUT -p udp --dport 21116 -j ACCEPT
Identifier le pare-feu actif :
systemctl status nftables iptables ufw 2>/dev/null
3.4 Connectivité locale
nc -zv 127.0.0.1 21115
nc -zv 127.0.0.1 21116
nc -zv 127.0.0.1 21117
Attendu : Connection to 127.0.0.1 2111X port [tcp] succeeded
SI échec : port non ouvert localement — service arrêté ou mauvaise configuration d'écoute.
3.5 Résolution DNS (si applicable)
dig +short <nom_du_serveur>
cat /etc/resolv.conf
Attendu : résolution fonctionnelle et serveur DNS défini.
PHASE 4 — Vérifications des services RustDesk
4.1 État des services
systemctl status hbbs
systemctl status hbbr
Attendu : Active: active (running) pour les deux.
SI inactive (dead) :
systemctl start hbbs
systemctl start hbbr
systemctl status hbbs hbbr
SI redémarrage en boucle → aller Phase 6.
SI failed :
journalctl -u hbbs -n 50 --no-pager
journalctl -u hbbr -n 50 --no-pager
4.2 Activation au démarrage
systemctl is-enabled hbbs
systemctl is-enabled hbbr
Attendu : enabled pour les deux.
SI disabled :
systemctl enable hbbs hbbr
4.3 Contenu des fichiers unit
cat /etc/systemd/system/hbbs.service
cat /etc/systemd/system/hbbr.service
Points à vérifier :
- ExecStart pointe vers /opt/rustdesk-server/hbbs (ou hbbr)
- WorkingDirectory est défini sur /opt/rustdesk-server
- User= correspond à un utilisateur existant
- Restart= est défini (on-failure ou always)
- Les arguments de la commande sont corrects (-r <ip_ou_domaine>)
SI fichier unit modifié :
systemctl daemon-reload
systemctl restart hbbs hbbr
4.4 Processus actifs
ps aux | grep -E 'hbbs|hbbr' | grep -v grep
Attendu : deux processus distincts visibles.
SI processus absent malgré un status "running" → incohérence systemd :
systemctl daemon-reexec
systemctl restart hbbs hbbr
PHASE 5 — Vérifications Docker (si utilisé)
5.1 État du démon Docker
systemctl status docker
Attendu : Active: active (running).
SI inactif :
systemctl start docker
systemctl enable docker
5.2 État des conteneurs
docker ps -a
Attendu : conteneurs RustDesk avec statut Up.
SI statut Exited :
docker logs <nom_du_conteneur>
docker start <nom_du_conteneur>
SI statut Restarting (boucle de redémarrage) :
docker logs --tail 50 <nom_du_conteneur>
5.3 Réseau Docker
docker network ls
docker inspect <nom_du_conteneur> | grep -A 20 '"NetworkSettings"'
Attendu : conteneur attaché au bon réseau avec une IP assignée.
5.4 Ports Docker exposés
docker port <nom_du_conteneur>
Attendu : ports 21115, 21116, 21117 mappés vers l'hôte.
SI ports non mappés : corriger le docker-compose.yml ou la commande docker run.
5.5 Volumes Docker
docker inspect <nom_du_conteneur> | grep -A 10 '"Mounts"'
Attendu : volume monté sur /opt/rustdesk-server ou équivalent, avec les fichiers de clés présents.
5.6 Fichier docker-compose (si utilisé)
cat /opt/rustdesk-server/docker-compose.yml 2>/dev/null \
|| find / -name "docker-compose.yml" 2>/dev/null | head -5
Points à vérifier :
- Image utilisée et version
- Ports exposés corrects
- Variables d'environnement définies
- Volumes montés correctement
- Restart policy définie (unless-stopped ou always)
PHASE 6 — Analyse des logs
6.1 Logs systemd en temps réel
journalctl -u hbbs -f
journalctl -u hbbr -f
6.2 Logs systemd historiques
journalctl -u hbbs --since "1 hour ago" --no-pager
journalctl -u hbbr --since "1 hour ago" --no-pager
6.3 Logs au démarrage du service
journalctl -u hbbs -n 100 --no-pager | grep -E 'error|warn|fail|panic|fatal'
journalctl -u hbbr -n 100 --no-pager | grep -E 'error|warn|fail|panic|fatal'
6.4 Logs Docker
docker logs --tail 100 <nom_du_conteneur>
docker logs --since 1h <nom_du_conteneur>
6.5 Logs système globaux
journalctl -p err --since "1 hour ago" --no-pager
tail -n 100 /var/log/syslog
6.6 Logs de l'API RustDesk (si présente)
journalctl -u rustdesk-api -n 50 --no-pager 2>/dev/null \
|| docker logs rustdesk-api 2>/dev/null \
|| find /opt /var/log -name "*.log" 2>/dev/null | xargs grep -l rustdesk
PHASE 7 — Analyse des fichiers de configuration
7.1 Fichiers de clés
ls -lh /opt/rustdesk-server/*.key /opt/rustdesk-server/*.pub 2>/dev/null
Attendu : id_ed25519 et id_ed25519.pub présents et lisibles par le service.
SI absents : hbbs les génère au premier démarrage — vérifier que le répertoire est accessible en écriture :
ls -ld /opt/rustdesk-server/
SI permissions incorrectes sur les clés :
chown rustdesk:rustdesk /opt/rustdesk-server/*.key /opt/rustdesk-server/*.pub
chmod 600 /opt/rustdesk-server/*.key
7.2 Arguments de démarrage hbbs / hbbr
Dans le fichier unit, vérifier la ligne ExecStart :
Exemple attendu pour hbbs :
ExecStart=/opt/rustdesk-server/hbbs -r <adresse_publique_ou_domaine>
Exemple attendu pour hbbr :
ExecStart=/opt/rustdesk-server/hbbr
SI l'adresse passée à -r est incorrecte : corriger, puis :
systemctl daemon-reload && systemctl restart hbbs
7.3 Configuration réseau système
cat /etc/network/interfaces 2>/dev/null
cat /etc/hosts
cat /etc/resolv.conf
7.4 Variables d'environnement (si API ou Docker)
cat /opt/rustdesk-server/.env 2>/dev/null \
|| find /opt -name ".env" 2>/dev/null
Points à vérifier :
- RELAY (adresse du serveur relay)
- RUSTDESK_API_KEY ou équivalent
- PORT si redéfini
- Toute variable vide ou mal formatée
PHASE 8 — Isolation de la panne
8.1 Méthode de bisection
1. Confirmer que le problème est reproductible.
2. Diviser le système en deux parties : réseau / service.
3. SI réseau OK et service KO → aller Phase 4 et Phase 7.
4. SI réseau KO → aller Phase 3.
5. SI les deux sont KO → commencer par le réseau.
8.2 Test de connectivité depuis l'extérieur
# Depuis une machine externe ou en simulant :
nc -zv <ip_publique_serveur> 21115
nc -zv <ip_publique_serveur> 21116
nc -zv <ip_publique_serveur> 21117
SI connexion locale OK mais externe KO :
- Règle de pare-feu sur la passerelle ou le fournisseur.
- NAT / redirection de port manquante.
- IP publique incorrecte dans la configuration hbbs.
8.3 Test de redémarrage contrôlé
systemctl stop hbbs hbbr
sleep 2
systemctl start hbbr
sleep 2
systemctl start hbbs
systemctl status hbbs hbbr
Attendu : les deux services active (running) après démarrage séquentiel.
8.4 Vérification des dépendances entre services
systemctl list-dependencies hbbs
systemctl list-dependencies hbbr
SI une dépendance est en échec : la corriger avant de redémarrer RustDesk.
8.5 Collecte finale pour diagnostic
systemctl status hbbs hbbr --no-pager > /tmp/status_rustdesk.txt
journalctl -u hbbs -u hbbr -n 200 --no-pager >> /tmp/status_rustdesk.txt
ss -tlnup >> /tmp/status_rustdesk.txt
cat /etc/systemd/system/hbbs.service >> /tmp/status_rustdesk.txt
cat /etc/systemd/system/hbbr.service >> /tmp/status_rustdesk.txt
cat /tmp/status_rustdesk.txt
Coller le contenu de ce fichier dans le chat pour analyse complète.
SECTION LECTURE DES ERREURS
Connection refused
Signification : le port est fermé ou rien n'écoute dessus.
Causes possibles :
- Service arrêté
- Mauvais port dans la configuration
- Pare-feu DROP sur le port
Vérifier : Phase 4 → Phase 3 → Phase 7
Connection timed out
Signification : les paquets n'arrivent pas à destination.
Causes possibles :
- Pare-feu qui drop silencieusement
- Mauvais routage réseau
- IP publique incorrecte
- Interface réseau DOWN
Vérifier : Phase 3 → Phase 7
Permission denied
Signification : droits insuffisants sur un fichier, répertoire ou port.
Causes possibles :
- Mauvais propriétaire sur le binaire ou les clés
- Utilisateur du service sans accès au répertoire
- Port réservé (< 1024) sans privilèges root
Vérifier : Phase 2.4 → Phase 7.1 → Phase 4.3
No such file or directory
Signification : un fichier attendu est absent.
Causes possibles :
- Binaire supprimé ou mal installé
- Chemin incorrect dans le fichier unit
- Fichier de clé non généré
Vérifier : Phase 2.4 → Phase 4.3 → Phase 7.1
Address already in use
Signification : un autre processus occupe déjà le port.
Causes possibles :
- Double instance du service
- Ancien processus zombie non terminé
- Autre service sur le même port
Vérifier :
ss -tlnup | grep 2111
fuser -k 21115/tcp 21116/tcp 21117/tcp
Failed to start / Start request repeated too quickly
Signification : le service tente de démarrer et échoue en boucle.
Causes possibles :
- Erreur dans ExecStart (chemin, argument)
- Fichier de clé manquant ou illisible
- Dépendance système absente
Vérifier : Phase 6 → Phase 7 → Phase 4.3
Exec format error
Signification : le binaire est incompatible avec l'architecture du système.
Causes possibles :
- Binaire compilé pour une architecture différente (ex. amd64 sur arm)
- Fichier binaire corrompu
Vérifier :
file /opt/rustdesk-server/hbbs
uname -m
No route to host
Signification : le système ne sait pas comment joindre la destination.
Causes possibles :
- Route par défaut absente
- Interface réseau DOWN
- VLAN ou sous-réseau mal configuré
Vérifier : Phase 3.1
PROCÉDURE D'ANALYSE SUR DEMANDE
Lorsque tu fournis une sortie de commande, un log ou un fichier de configuration, préciser :
1. La commande exécutée
2. Le contexte (phase en cours, symptôme observé)
3. La sortie complète, sans troncature
Format attendu pour soumission :
Commande : systemctl status hbbs
Contexte : service signalé comme failed au démarrage
L'analyse portera sur :
- Les codes d'erreur et messages systemd
- Les lignes de log anormales
- Les incohérences de configuration
- Les chemins, permissions et utilisateurs
- Les ports et adresses mal définis