🚀 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
• 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.

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, tablet, and mobile
• 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 (localhost only, not exposed to internet)
• 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

• 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

Mobile Responsive

Fully responsive design for mobile devices

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   RustDesk Clients                      │
│              (Desktop, Mobile, 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)  │
│  (Localhost)   │   │                 │
└────────┬───────┘   └─────────────────┘
         │
         ▼
┌─────────────────────────────┐
│   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

🪟 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.

What's New in v1.1.0

• Device Banning System: Ban/unban devices with reason tracking
• Soft Delete: Devices marked as deleted instead of permanent removal
• Enhanced Security: Input validation, XSS protection, SQL injection prevention
• Improved UI: Visual ban indicators, new statistics card, confirmation dialogs

🔒 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:
   • HTTP API listening on 127.0.0.1:21120 (localhost only)
   • RustDesk ports 21115-21117 operational
   • Port 21120 NOT accessible from external network

Post-installation verification:

# On server (should work)
curl http://localhost:21120/api/health

# From outside (should FAIL with "Connection refused")
curl http://SERVER_IP:21120/api/health

To access API remotely, use SSH tunnel:

# Create tunnel
ssh -L 21120:localhost:21120 your-user@your-server

# Then access locally
curl http://localhost:21120/api/health

---

⚙️ Configuration

HBBS API Port

Default: 21120 (localhost only - not exposed to internet)

Security: The API is bound to 127.0.0.1 (localhost) by design. This means:

• ✅ API is only accessible from the same machine
• ✅ Cannot be accessed from network/internet even without firewall
• ✅ Web console connects locally or via SSH tunnel
• ✅ No risk of unauthorized data exposure

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

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

Web Console Port

Default: 5000

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

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

Firewall Configuration

# Allow web console (if needed externally)
sudo ufw allow 5000/tcp

# HBBS API (usually internal only)
# Port 21120 does NOT need to be opened - it's localhost only!
# Only open 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://localhost:21120/api

Note: API is bound to localhost only and cannot be accessed from external networks.

Endpoints

Health Check

GET /api/health

Response:

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

List All Peers

GET /api/peers

Response:

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

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
│   └── mobile-view.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
• DEPRECATION_NOTICE.md - Deprecated features info
• RELEASE_NOTES_v1.2.0.md - Latest release notes
• RELEASE_NOTES_v1.3.0.md - Version 1.3.0 release notes
• UPDATE_GUIDE.md - Update instructions
• DEVELOPMENT_ROADMAP.md - Future plans
• PROJECT_STRUCTURE.md - Project structure overview
• PROJECT_ORGANIZATION.md - Project organization details
• PORT_SECURITY.md - Port security information
• GITHUB_RELEASE_GUIDE.md - GitHub release guide
• RELEASE_READY.md - Release readiness checklist
• SECURITY_CLEANUP_REPORT.md - Security cleanup report
• SECURITY_PLACEHOLDERS.md - Security placeholders
• SECURITY_URGENT.md - Urgent security items

Technical Documentation

• hbbs-patch/ - HBBS modification documentation
• archive/ - Archived scripts and old files
• 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