🚀 BetterDesk Console

A modern, feature-rich web management console for RustDesk with real-time device monitoring and bidirectional ban enforcement

Features • Screenshots • Installation • Documentation • Contributing

---

📋 Table of Contents

• Overview
• Features
• Screenshots
• Architecture
• Installation
  • Automatic Installation
  • Manual Installation
  • 🔑 Key Protection
• Troubleshooting
• Configuration
• API Documentation
• Development
• Technology Stack
• Contributing
• License
• Credits

---

🌟 Overview

BetterDesk Console is an enhanced web management interface for RustDesk - the open-source remote desktop solution. It extends the standard RustDesk HBBS (HBB Signal Server) with a powerful HTTP API and provides a beautiful, modern web interface for managing your RustDesk infrastructure.

🤖 AI-Assisted Development: This project was developed with significant assistance from AI coding tools (Claude/GitHub Copilot). While all code has been reviewed, tested, and validated for production use, users should be aware of this development approach.

Why BetterDesk Console?

• Real-Time Monitoring: See which devices are online/offline instantly
• Beautiful UI: Modern glassmorphism design with Material Icons
• Authentic Status Detection: Uses the same algorithm as RustDesk desktop client
• RESTful API: Easy integration with other tools and scripts
• Device Management: Add notes, search, filter, and organize your devices
• Open Source: Fully transparent and customizable

---

✨ Features

🎨 Modern Web Interface

• Glassmorphism Design: Sleek, modern UI with blur effects and gradients
• Material Icons: Google Material Design icons (fully offline)
• Responsive Layout: Works on desktop and tablet
• Dark Theme: Easy on the eyes, perfect for NOC environments
• Real-Time Updates: Auto-refresh device status
• Search & Filter: Quickly find devices in large deployments

🔧 Enhanced HBBS Server

• HTTP API: RESTful API on port 21120 with X-API-Key authentication (LAN accessible)
• Real-Time Status: Memory-based device status (no database lag)
• Authentic Algorithm: Uses RustDesk's official 30-second timeout logic
• Thread-Safe: Shared PeerMap with Arc/RwLock for concurrent access
• Zero Breaking Changes: Fully compatible with existing RustDesk clients
• CORS Support: Easy web console integration
• 🔥 Bidirectional Ban Enforcement (v8):
  • Prevents banned devices from initiating connections (source check)
  • Prevents connections to banned devices (target check)
  • Works for both P2P and relay connections
  • Real-time database sync - no restart required

📊 Device Management

• Dashboard View: Overview with statistics cards (Total, Active, Inactive, Banned, With Notes)
• Device List: Sortable table with ID, notes, status, and timestamps
• Device Details: View complete device information including ban status
• Add Notes: Label devices with custom descriptions
• 🔒 Device Banning: Ban/unban devices with reason tracking and administrator info
  • Bidirectional Enforcement (v8): Banned devices blocked in both directions
  • Source ban: Banned device cannot initiate any connections
  • Target ban: Cannot connect to banned devices
  • Enforced at punch hole and relay request stages
  • 100% reliability with real-time sync
• Soft Delete: Devices marked as deleted (recoverable) instead of permanent removal
• Batch Operations: Search and filter multiple devices
• Public Key Display: Quick access to server public key
• Visual Indicators: Color-coded status badges, banned device highlighting

🛡️ Security & Reliability

• Authentication System (v1.5.0):
  • User login with bcrypt password hashing
  • Role-based access control (Admin, Operator, Viewer)
  • Session management with 24-hour tokens
  • \ud83c\udf10 Sidebar navigation with 5 main sections (Dashboard, Public Key, Settings, User Management, About)
  • \ud83d\udd11 Password-protected public key access - requires password verification
  • \u2699\ufe0f Settings page with password change functionality
  • \ud83d\udc65 User management panel (admin only) - create, edit, delete, activate/deactivate users
  • \ud83d\udcdd Extended About page with open source credits and license information
  • Audit logging for all actions
• API Security (v1.4.0):
  • X-API-Key header authentication for HBBS API
  • 64-character random API keys
  • Secure key storage with 600 permissions
  • LAN accessible (0.0.0.0) with authentication protection
• Input Validation: Comprehensive validation for all user inputs
• XSS Protection: Sanitization of user-provided content
• SQL Injection Prevention: Parameterized queries throughout
• Bidirectional Ban Enforcement (v8):
  • Source device ban check (prevents banned devices from connecting)
  • Target device ban check (prevents connections to banned devices)
  • No race conditions or timing vulnerabilities
  • Minimal performance impact (~1ms per check)
• Ban Management: Track who banned devices, when, and why
• Confirmation Dialogs: Explicit confirmation for destructive operations
• Automatic Backups: Installation and update scripts create safety backups
• Precompiled Binaries: No compilation needed, faster deployment
• Service Management: Systemd integration for auto-restart
• Graceful Degradation: Web console works even if API is unavailable
• No External Dependencies: All assets served locally (offline-ready)
• Audit Trail: Timestamps for all device modifications

---

📸 Screenshots

Dashboard Overview

Real-time statistics and device status overview

Device Management

Comprehensive device list with search and filtering

Device Details

Detailed device information modal

Public Key Management

Secure public key access with password protection

Settings

User settings and password management

User Management

Multi-user administration panel

About

System information and version details

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   RustDesk Clients                      │
│              (Desktop, Tablet, Web)                      │
└──────────────────────┬──────────────────────────────────┘
                       │ Heartbeat (~30-45s)
                       ▼
         ┌─────────────────────────────┐
         │   Enhanced HBBS Server      │
         │   (Port 21115-21119)        │
         └──────────┬──────────────────┘
                    │
                    ▼
         ┌─────────────────────────────┐
         │   Arc<PeerMap>              │
         │   (Shared Memory)           │
         │   • In-memory peer storage  │
         │   • last_reg_time tracking  │
         └──────────┬──────────────────┘
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
┌────────────────┐   ┌─────────────────┐
│  HTTP API      │   │  SQLite DB      │
│  (Port 21120)  │   │  (Persistence)  │
│  (LAN Access)  │   │                 │
└────────┬───────┘   └─────────────────┘
         │
         ▼
┌─────────────────────────────┐
│   Web Management Console    │
│   (Flask on Port 5000)      │
│   • Dashboard               │
│   • Device Management       │
│   • Statistics              │
└─────────────────────────────┘

Key Components

1. Enhanced HBBS: Modified RustDesk signal server with HTTP API
2. HTTP API: Axum-based REST API for device queries
3. PeerMap: Thread-safe in-memory peer storage (Arc)
4. Web Console: Flask application with modern UI
5. SQLite Database: Original RustDesk database (unchanged)

---

🚀 Installation

Prerequisites

• Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+
• Windows: Windows 10+, Windows Server 2016+
• Existing RustDesk: Working HBBS installation (optional - can be fresh install)
• Linux Dependencies: python3, pip3, curl, systemd
• Windows Dependencies: Python 3.8+, PowerShell 5.1+
• No Compilation Required: Uses precompiled binaries

🐧 Linux Installation

Enhanced installer with Docker support and custom path detection:

# Clone the repository
git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Make the installer executable
chmod +x install-improved.sh

# Run as root (creates backup automatically)
sudo ./install-improved.sh

Features:

• ✅ Automatic Docker/containerized environment detection
• ✅ Custom RustDesk path detection (searches /opt, /usr/local, /home)
• ✅ --break-system-packages support for Debian 3.11+
• ✅ File validation and verification
• ✅ 🔑 Encryption key protection - preserves existing keys
• ✅ Dynamic .pub file scanning - works with any public key filename
• ✅ Multiple backup options - automatic, manual, or existing backup
• ✅ Key regeneration with warnings - prevents accidental key changes
• ✅ API key generation - automatic X-API-Key authentication setup
• ✅ LAN access configuration - web console and API accessible on network

🔄 Updating Existing Installation

If you already have BetterDesk Console installed and want to upgrade to v1.4.0 with authentication:

cd Rustdesk-FreeConsole

# Make the update script executable
chmod +x update-to-v1.4.0.sh

# Run as root
sudo ./update-to-v1.4.0.sh

Update features:

• ✅ Automatic backup before changes
• ✅ Database migration to add authentication tables
• ✅ API key generation and configuration
• ✅ Preserves existing configuration
• ✅ Creates default admin user (if needed)
• ✅ Updates systemd services for LAN access
• ✅ Rollback capability if update fails

🪟 Windows Installation

Enhanced installer with automatic path detection:

# Clone the repository
git clone https://github.com/UNITRONIX/Rustdesk-FreeConsole.git
cd Rustdesk-FreeConsole

# Run as Administrator
.\install-improved.ps1

Features:

• ✅ Automatic RustDesk installation detection
• ✅ Multiple installation path support
• ✅ File validation and verification
• ✅ Windows service configuration

⚠️ Important: Platform-Specific Binaries

The installers automatically use the correct binaries for your platform:

• Linux: Uses hbbs-patch/bin-with-api/hbbs-v8-api (Linux ELF binary)
• Windows: Uses hbbs-patch/bin-with-api/hbbs-v8-api.exe (Windows PE binary)

Do not mix binaries between platforms! Each installer is designed to work only on its respective operating system.

🔑 Key Protection (IMPORTANT!)

v1.5.0+ includes comprehensive encryption key protection:

⚠️ Your RustDesk encryption keys are CRITICAL!

• Losing keys = ALL clients disconnected
• Changing keys = "Key mismatch" errors on all devices
• Keys must be backed up before any installation

BetterDesk v1.5.0+ automatically:

• ✅ Detects existing encryption keys
• ✅ Scans for ANY .pub file (not just id_ed25519.pub)
• ✅ Offers multiple backup options (automatic, manual, existing)
• ✅ Warns before any key changes
• ✅ Never regenerates keys without explicit confirmation

During installation, you'll see:

🔑 EXISTING ENCRYPTION KEYS DETECTED 🔑
Found: id_ed25519.pub

Options:
  1) Keep existing keys (RECOMMENDED)
  2) Regenerate keys (⚠️ BREAKS client connections)
  3) Show key information

Always choose Option 1 unless you know what you're doing!

If you experience "Key mismatch" errors:

# Restore from automatic backup
BACKUP=$(ls -d /opt/rustdesk-backup-* | sort | tail -1)
sudo cp $BACKUP/id_ed25519* /opt/rustdesk/
sudo systemctl restart rustdesksignal

📖 Full guide: docs/KEY_TROUBLESHOOTING.md

What's New in v1.5.0 (Latest)

• 🔐 Authentication System: User login with bcrypt password hashing
• 👥 Role-Based Access Control: Admin, Operator, and Viewer roles
• 🌐 Sidebar Navigation: Modern UI with 5 main sections
• 🔑 Password-Protected Public Key: Requires verification to view
• ⚙️ Settings Page: Change password functionality with token regeneration
• 👤 User Management: Admin panel to create, edit, delete users
• 📝 Extended About Page: Open source credits and license info
• 🛡️ CSRF Protection: Flask-WTF security
• ⏱️ Rate Limiting: 5 login attempts per minute

🔒 Manual Installation on SSH Server (Security Update)

If you compiled new binaries with security fixes on your SSH server:

# Upload the manual installation script
scp hbbs-patch/MANUAL_INSTALL.sh your-user@your-server:~/

# SSH to server and run
ssh your-user@your-server
sudo bash ~/MANUAL_INSTALL.sh

The script will:

1. Stop HBBS/HBBR services
2. Backup old binaries (timestamped)
3. Install new binaries from ~/build/hbbs-patch/rustdesk-server/target/release/
4. Restart services
5. Verify API is responding on port 21120

---

🔧 Troubleshooting

🚨 "The keys do not match" Error

This is the most common issue after installation. Don't panic!

Quick Fix:

cd /path/to/Rustdesk-FreeConsole
sudo bash repair-keys.sh
# Select option 5: Restore from backup

If BetterDesk broke your setup:

# Find most recent backup
BACKUP=$(ls -d /opt/rustdesk-backup-* | sort | tail -1)

# Restore keys
sudo systemctl stop rustdesksignal rustdeskrelay
sudo cp $BACKUP/id_ed25519* /opt/rustdesk/
sudo chmod 600 /opt/rustdesk/id_ed25519
sudo chmod 644 /opt/rustdesk/id_ed25519.pub
sudo systemctl start rustdesksignal rustdeskrelay

# Verify
cat /opt/rustdesk/id_ed25519.pub

📚 Comprehensive Troubleshooting Guides

• QUICK_FIX.md - Fast solutions for common issues
• KEY_TROUBLESHOOTING.md - Complete key management guide
• UPDATE_GUIDE.md - Updating existing installations

🔧 Using the Repair Tool

The repair-keys.sh tool can fix most key-related issues:

sudo bash repair-keys.sh

Available options:

1. 📋 Show current key information
2. 🔐 Verify and fix key permissions
3. 📤 Export public key
4. 🔄 Regenerate keys (⚠️ BREAKS connections)
5. 💾 Restore keys from backup

🐳 Docker Issues

Problem: "Docker RustDesk installation detected" message

Solutions:

1. Use Docker-compose (recommended for Docker setups)
2. Install web console only (option 2 during installation)
3. Continue with native installation (if intentional)

Common Issues & Solutions

Symptom	Cause	Solution
"Key mismatch"	Keys changed during install	Restore from backup or use repair tool
Wrong key in WebConsole	Multiple .pub files	Remove incorrect files or upgrade to v9+
Services won't start	Permission issues	Run sudo bash repair-keys.sh → option 2
Can't find backups	Skipped backup during install	Check /opt/rustdesk-backup-* directories
Docker detected	Running RustDesk in container	Choose "Web Console only" option

📞 Getting Help

Before asking for help:

1. Check the troubleshooting guides above
2. Try the repair tool: sudo bash repair-keys.sh
3. Collect diagnostics:

   sudo journalctl -u rustdesksignal -n 50 > ~/rustdesk_logs.txt
   ls -lah /opt/rustdesk/*.pub >> ~/rustdesk_logs.txt
   

Where to get help:

• 🐛 GitHub Issues
• 📖 Documentation
• 💬 RustDesk Discussions

---

⚙️ Configuration

HBBS API Port

Default: 21120 (LAN accessible with X-API-Key authentication)

Security (v1.4.0): The API now supports LAN access with proper authentication:

• \u2705 Binds to 0.0.0.0:21120 (accessible on LAN)
• \u2705 Requires X-API-Key header for all requests
• \u2705 64-character random API key generated during installation
• \u2705 Key stored securely in /opt/rustdesk/.api_key with 600 permissions
• \u2705 Web console automatically uses API key
• \u2705 No authentication = no access (secure by design)

API Key Location: /opt/rustdesk/.api_key

To change port, edit /etc/systemd/system/rustdesksignal.service:

ExecStart=/opt/rustdesk/hbbs -k _ -p 21115 --api-port 21120

Web Console Port

Default: 5000 (accessible on LAN)

The web console binds to 0.0.0.0:5000 for LAN access and includes:

• User authentication (bcrypt passwords)
• Session management (24-hour tokens)
• Role-based access control
• Audit logging

To change, edit /opt/BetterDeskConsole/app.py:

app.run(host='0.0.0.0', port=5000)

Firewall Configuration

# Allow web console on LAN
sudo ufw allow from 192.168.0.0/16 to any port 5000 proto tcp

# Allow HBBS API on LAN (if needed for external tools)
sudo ufw allow from 192.168.0.0/16 to any port 21120 proto tcp

# Standard RustDesk ports
sudo ufw allow 21115/tcp
sudo ufw allow 21116/tcp
sudo ufw allow 21116/udp
sudo ufw allow 21117/tcp

---

📚 API Documentation

Base URL

http://<server-ip>:21120/api

Authentication

All API requests require X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY_HERE" http://192.168.1.100:21120/api/health

API Key Location: /opt/rustdesk/.api_key

To retrieve your API key:

sudo cat /opt/rustdesk/.api_key

Endpoints

Health Check

GET /api/health
Headers: X-API-Key: <your-api-key>

Response:

{
  "success": true,
  "data": "RustDesk API is running",
  "error": null
}

List All Peers

GET /api/peers
Headers: X-API-Key: <your-api-key>

Response:

{
  "success": true,
  "data": [
    {
      "id": "1234567890",
      "note": "Production Server",
      "online": true
    },
    {
      "id": "9876543210",
      "note": null,
      "online": false
    }
  ],
  "error": null
}

Error Response (No/Invalid API Key):

{
  "error": "Unauthorized: Invalid or missing API key"
}

Status Code: 401

Status Detection Algorithm

A device is considered online if:

1. It exists in the PeerMap (in-memory storage)
2. Last registration time is less than 30 seconds ago

const REG_TIMEOUT: i32 = 30_000; // milliseconds

online = peer_exists && (last_reg_time.elapsed() < REG_TIMEOUT)

This is the exact same algorithm used by RustDesk desktop client.

---

🛠️ Development

Running Demo Version (Mock Data)

For screenshots or testing without real devices:

cd web
python3 app_demo.py

Access at: http://localhost:5001

Project Structure

BetterDeskConsole/
├── README.md                    # This file
├── LICENSE                      # MIT License
├── install.sh                   # Automatic installer
├── screenshots/                 # UI screenshots
│   ├── dashboard.png
│   ├── devices-list.png
│   ├── device-details.png
│   ├── public_key_page.png
│   ├── settings_page.png
│   ├── user_mgmt.png
│   └── about.png
├── web/                         # Web console
│   ├── app.py                   # Flask application
│   ├── app_demo.py              # Demo with mock data
│   ├── requirements.txt         # Python dependencies
│   ├── betterdesk.service       # Systemd service file
│   ├── templates/
│   │   └── index.html           # Main HTML template
│   └── static/
│       ├── style.css            # Glassmorphism CSS
│       ├── script.js            # Frontend JavaScript
│       └── material-icons.woff2 # Material Icons font
└── hbbs-patch/                  # HBBS modifications
    ├── README.md                # Patch documentation
    └── src/
        ├── http_api.rs          # HTTP API server (NEW)
        ├── main.rs              # Modified entry point
        ├── peer.rs              # Modified PeerMap
        └── rendezvous_server.rs # Modified server logic

Building from Source

# Clone RustDesk server
git clone https://github.com/rustdesk/rustdesk-server.git
cd rustdesk-server

# Copy patched files
cp ../hbbs-patch/src/* src/

# Add dependencies
cargo add axum --features "http1,json,tokio"
cargo add tower-http --features "cors"
cargo add tokio --features "full"

# Build
cargo build --release --bin hbbs

Running Tests

# Test HBBS API
curl http://localhost:21120/api/health

# Test Web Console
curl http://localhost:5000

# Check services
sudo systemctl status rustdesksignal.service
sudo systemctl status betterdesk.service

---

🎨 Technology Stack

Backend

• RustDesk HBBS: Original signal server (AGPL-3.0)
• Rust: Systems programming language
• Axum: Web framework for Rust
• Tokio: Async runtime for Rust
• Flask: Python web framework
• SQLite: Database (RustDesk original)

Frontend

• HTML5: Semantic markup
• CSS3: Glassmorphism effects, animations, gradients
• JavaScript (ES6+): Dynamic UI updates
• Material Icons: Icon set (offline)

DevOps

• Systemd: Service management
• Bash: Installation scripting
• Git: Version control

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

• Use the GitHub Issues page
• Include system info (OS, RustDesk version, etc.)
• Provide logs from systemd: journalctl -u betterdesk.service

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Update documentation for new features
• Test with real RustDesk clients
• Ensure backward compatibility

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: The HBBS patches maintain RustDesk's original AGPL-3.0 license. The web console and installation scripts are MIT licensed.

---

🙏 Credits

Open Source Components

• RustDesk: The amazing open-source remote desktop solution
• RustDesk Server: Original HBBS and HBBR servers
• Axum: Modern web framework for Rust
• Flask: Micro web framework for Python
• Material Icons: Google's Material Design icons
• Font Awesome: Icon inspiration (not used in final version)

Inspiration

• RustDesk's simple yet powerful architecture
• Modern web design trends (glassmorphism, neumorphism)
• NOC (Network Operations Center) monitoring dashboards

Special Thanks

• RustDesk development team for creating an excellent open-source alternative
• The Rust community for amazing tools and libraries
• Contributors and testers who helped improve this project

---

📞 Support

• Documentation: Check the docs/ folder
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• RustDesk Community: RustDesk Discord

---

🗺️ Roadmap

Known Limitations (v1.0.0)

• Device ID Modification: Changing device IDs is not recommended and may cause access issues
  • Workaround: Use the Note field to assign custom names/labels
• Device Deletion: Delete functionality is currently unstable
  • Status: Under investigation, fix planned for v1.0.1
• No Authentication: Web console has no user authentication (suitable for internal networks only)

Version 1.0.1 (Bug Fixes - In Progress)

• Fix device deletion functionality
• Improve device ID change handling
• Add confirmation dialogs for destructive operations
• Better error messages for failed operations

Version 1.1 (Planned)

• Multi-language support (i18n)
• User authentication system
• Role-based access control (RBAC)
• Connection history logs
• Performance metrics dashboard

Version 1.2 (Future)

• Mobile app (React Native)
• WebSocket for real-time updates
• Device grouping and tagging
• Scheduled maintenance windows
• Email/Slack notifications
• REST API authentication (JWT)

Version 2.0 (Vision)

• Multi-server support
• High availability (HA) setup
• Advanced analytics
• Custom themes
• Plugin system

---

🌐 Links

• GitHub: https://github.com/UNITRONIX/Rustdesk-FreeConsole
• RustDesk: https://rustdesk.com/
• RustDesk GitHub: https://github.com/rustdesk/rustdesk

---

📚 Documentation

Core Documentation

• README.md - This file (overview and installation)
• LICENSE - MIT License
• VERSION - Current version number

Additional Documentation (docs/)

• CHANGELOG.md - Complete version history
• CONTRIBUTING.md - How to contribute
• INSTALLATION_V1.4.0.md - Detailed installation guide
• UPDATE_GUIDE.md - Update instructions
• KEY_TROUBLESHOOTING.md - Key troubleshooting guide
• PORT_SECURITY.md - Port security information
• PROJECT_STRUCTURE.md - Project structure overview

Technical Documentation

• hbbs-patch/ - HBBS modification documentation
• dev_modules/ - Development and testing tools

---

Made with ❤️ by the community

If you find this project useful, please consider giving it a ⭐ on GitHub!

⬆ Back to Top