{"id":33598368,"url":"https://github.com/oussrh/rose-link","last_synced_at":"2026-04-11T01:11:48.400Z","repository":{"id":322716289,"uuid":"1090620334","full_name":"oussrh/ROSE-LINK","owner":"oussrh","description":"Home VPN Router on Raspberry Pi","archived":false,"fork":false,"pushed_at":"2025-11-28T10:25:50.000Z","size":2226,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T04:19:36.236Z","etag":null,"topics":["adguard","fastapi","homelab","htmx","networking","networking-in-python","nodejs","openvpn","privacy","pytho","raspberry","raspberry-pi","raspberry-pi-os","raspberrypi","raspberrypi-router","router","self-hosted","tailwindcss","vpn","wireguard"],"latest_commit_sha":null,"homepage":"https://www.rose-link.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oussrh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-05T23:04:31.000Z","updated_at":"2025-11-28T10:25:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oussrh/ROSE-LINK","commit_stats":null,"previous_names":["oussrh/rose-link"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/oussrh/ROSE-LINK","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oussrh%2FROSE-LINK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oussrh%2FROSE-LINK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oussrh%2FROSE-LINK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oussrh%2FROSE-LINK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oussrh","download_url":"https://codeload.github.com/oussrh/ROSE-LINK/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oussrh%2FROSE-LINK/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27376104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-30T02:00:05.582Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adguard","fastapi","homelab","htmx","networking","networking-in-python","nodejs","openvpn","privacy","pytho","raspberry","raspberry-pi","raspberry-pi-os","raspberrypi","raspberrypi-router","router","self-hosted","tailwindcss","vpn","wireguard"],"created_at":"2025-11-30T04:01:37.332Z","updated_at":"2026-04-11T01:11:48.369Z","avatar_url":"https://github.com/oussrh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"web/Logo.webp\" alt=\"ROSE Link Logo\" width=\"200\"\u003e\n\n# ROSE Link\n\n**Home VPN Router on Raspberry Pi**\n\n\u003cimg src=\"web/icon.webp\" alt=\"ROSE Link Icon\" width=\"64\"\u003e\n\nTransform your Raspberry Pi into a professional WiFi router/access point that establishes a secure VPN tunnel to your remote network, allowing you to access local resources and obtain the public IP of your VPN server from anywhere in the world.\n\n![Version](https://img.shields.io/badge/version-1.6.4-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Platform](https://img.shields.io/badge/platform-Raspberry%20Pi%203%2F4%2F5%2FZero%202W-red)\n\n**[Version Francaise](README.fr.md)**\n\n\u003c/div\u003e\n\n---\n\n## Objective\n\nROSE Link creates a complete VPN solution that:\n\n- **Connects to Internet** via Ethernet RJ45 (priority) or WiFi client (automatic fallback)\n- **Establishes a WireGuard tunnel** to your VPN server (Fritz!Box, pfSense, OpenWrt, VPS...)\n- **Creates a local WiFi hotspot** for your devices (PC, smartphone, tablet)\n- **Routes all traffic** through VPN for remote network access + server's public IP\n- **Modern Web interface** to configure WAN, VPN and Hotspot easily\n- **Flexible configuration** via web interface (country, WiFi channels, VPN settings)\n\n```\n📱 Device ── WiFi ──▶ 🍓 ROSE Link (Pi) ── WireGuard ──▶ 🔐 VPN Server ──▶ 🌍 Internet\n```\n\n---\n\n## Features\n\n### Intelligent WAN Connectivity\n- Auto-failover: Ethernet RJ45 priority -\u003e WiFi client fallback\n- Easy configuration: Scan and connect to WiFi from web interface\n- Real-time monitoring: WAN connection status\n\n### Multi-Protocol VPN Support\n- **WireGuard**: Fast, modern VPN with .conf file import\n- **OpenVPN**: Support for .ovpn files with embedded certificates\n- Multi-profile: Import and manage multiple VPN configurations\n- Kill-switch: Blocks all traffic if VPN drops (no leaks)\n- Watchdog: Automatic monitoring and reconnection\n- Detailed status: Handshake, endpoint, data transfer\n\n### AdGuard Home Integration (DNS Ad Blocking)\n- DNS-level ad blocking: Pi-hole alternative built-in\n- Blocking statistics: Queries, blocked percentage, top domains\n- Easy toggle: Enable/disable from web interface\n- AdGuard web UI: Full access to AdGuard Home settings\n\n### Configurable WiFi Hotspot\n- Custom SSID: Choose your network name\n- WPA2/WPA3 security: WPA3 if hardware supports it\n- Country configuration: Channels and power compliant with regulations\n- Channel selection: Optimize performance (2.4GHz and 5GHz)\n- Connected clients: Real-time counter\n\n### Connected Clients Management\n- Device tracking: See all connected and historical devices\n- Device identification: Auto-detect manufacturer and device type\n- Custom naming: Assign friendly names to devices\n- Client control: Block, unblock, or kick devices\n- Per-client statistics: Traffic and connection history\n\n### QoS Traffic Prioritization\n- VPN priority: Prioritize VPN traffic over local traffic\n- Simple toggle: Enable/disable from web interface\n- Bandwidth allocation: Configure VPN vs other traffic ratio\n\n### First-Time Setup Wizard\n- Guided configuration: Step-by-step initial setup\n- Network setup: Configure WAN connection\n- VPN import: Upload VPN profile during setup\n- Hotspot configuration: Set SSID and password\n- Security setup: Configure admin password\n\n### Grafana Monitoring Dashboard\n- **Native installation**: Runs directly on Raspberry Pi (no Docker required)\n- **Docker option**: Also available via Docker Compose for development\n- Status overview: VPN, WAN, Hotspot, Clients, Uptime, Temperature\n- System resources: CPU, Memory, Disk gauges and history\n- Network traffic: Throughput, packets, total traffic per interface\n- Prometheus alerts: VPN/WAN down, high CPU temp, low disk space\n- Resource-optimized: Memory/CPU limits for Raspberry Pi\n\n### Modern User Interface\n- Dark mode: Elegant and eye-friendly interface\n- Responsive: Works on desktop, tablet and mobile\n- Real-time: WebSocket-based live status updates\n- HTTPS: Secure connection (self-signed certificate)\n- Bilingual: English and French support\n\n### Enhanced Security\n- **Backend isolation**: API accessible only via Nginx reverse proxy\n- **Restricted sudoers**: Minimal system command access with validation\n- **Protected files**: VPN configurations in mode 600, WireGuard directory mode 700\n- **iptables kill-switch**: Leak protection blocks all traffic if VPN drops\n- **SSL/TLS**: RSA 4096-bit certificates with Subject Alternative Names\n- **Secure passwords**: Auto-generated 12-character random WiFi passwords\n- **Systemd hardening**: `ProtectSystem=strict`, `PrivateTmp=true`, `NoNewPrivileges=true`\n- **Resource limits**: Memory and CPU limits on backend service\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Hardware**: Raspberry Pi 3, 4, 5, or Zero 2W\n- **OS**: Raspberry Pi OS (Bullseye/Bookworm) or Debian 11/12\n- **Memory**: 512MB RAM minimum, 1GB+ recommended\n- **Storage**: 300MB free disk space minimum\n\n### Method 1: APT Repository (Recommended)\n\n```bash\n# Quick setup - adds repository and installs\ncurl -sSL https://oussrh.github.io/ROSE-LINK/install.sh | sudo bash\nsudo apt install rose-link\n```\n\nOr manually:\n```bash\n# Add GPG key\ncurl -fsSL https://oussrh.github.io/ROSE-LINK/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/rose-link.gpg\n\n# Add repository\necho \"deb [arch=arm64,armhf signed-by=/usr/share/keyrings/rose-link.gpg] https://oussrh.github.io/ROSE-LINK stable main\" | sudo tee /etc/apt/sources.list.d/rose-link.list\n\n# Install\nsudo apt update\nsudo apt install rose-link\n```\n\n### Method 2: One-Line Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/oussrh/ROSE-LINK/main/install.sh | sudo bash\n```\n\n### Method 3: Download and Install\n\n```bash\n# Download archive\nwget https://github.com/oussrh/ROSE-LINK/releases/latest/download/rose-link.tar.gz\n\n# Extract and install\ntar -xzf rose-link.tar.gz\ncd rose-link\nsudo bash install.sh\n\n# Or with custom options\nsudo bash install.sh --ssid \"MyVPN\" --country US\n```\n\n### Installation Options\n\n| Option | Description |\n|--------|-------------|\n| `-h, --help` | Show help message |\n| `-y, --yes` | Non-interactive mode (accept defaults) |\n| `-f, --force` | Force installation (skip hardware checks) |\n| `--ssid NAME` | Custom WiFi SSID (default: ROSE-Link) |\n| `--password PASS` | Custom WiFi password (min 8 chars, auto-generated if not set) |\n| `--country CODE` | Country code for WiFi regulations (default: BE) |\n\n**Examples:**\n```bash\n# Silent installation with defaults\nsudo bash install.sh -y\n\n# Custom hotspot configuration\nsudo bash install.sh --ssid \"HomeVPN\" --password \"MySecure123\" --country FR\n\n# Force install on non-Pi hardware (testing)\nsudo bash install.sh -f\n```\n\n### Uninstallation\n\n```bash\n# Interactive uninstall\nsudo bash uninstall.sh\n\n# Quick uninstall (keep VPN profiles)\nsudo bash uninstall.sh -y\n\n# Complete removal\nsudo bash uninstall.sh -y -f\n\n# If installed via Debian package\nsudo apt remove rose-link-pro    # Keep config\nsudo apt purge rose-link-pro     # Remove all\n```\n\n---\n\n## Monitoring Stack (Optional)\n\nROSE Link includes a built-in Grafana + Prometheus monitoring stack optimized for Raspberry Pi. The monitoring is **included in the package** but **not enabled by default** to keep the system lightweight.\n\n### Enable Monitoring\n\nAfter installing ROSE Link, enable monitoring with a single command:\n\n```bash\n# Enable monitoring (downloads and configures Prometheus + Grafana)\nsudo rose-monitoring enable\n\n# Or with custom Grafana password\nsudo GRAFANA_PASSWORD=MySecurePass rose-monitoring enable\n```\n\n### Monitoring Commands\n\n```bash\nrose-monitoring status      # Check monitoring status\nsudo rose-monitoring enable   # Install and enable monitoring\nsudo rose-monitoring disable  # Stop services (keeps installed)\nsudo rose-monitoring restart  # Restart all monitoring services\nsudo rose-monitoring uninstall # Completely remove monitoring\n```\n\n### What Gets Installed\n\n| Component | Version | Port | Purpose |\n|-----------|---------|------|---------|\n| Prometheus | 2.47.0 | 9090 | Metrics collection \u0026 storage |\n| Node Exporter | 1.6.1 | 9100 | System metrics (CPU, RAM, disk) |\n| Grafana | Latest | 3000 | Dashboard visualization |\n\n### Access Dashboards\n\nAfter enabling:\n- **Grafana**: `https://roselink.local/grafana/` or `http://192.168.50.1:3000`\n- **Prometheus**: `http://192.168.50.1:9090`\n\nDefault Grafana credentials:\n- Username: `admin`\n- Password: `roselink` (or your custom password)\n\n### Pre-configured Alerts\n\nThe monitoring stack includes alerts for:\n- VPN disconnected (critical)\n- WAN disconnected (critical)\n- High CPU temperature \u003e 70°C (warning) / \u003e 80°C (critical)\n- High memory usage \u003e 85% (warning) / \u003e 95% (critical)\n- Low disk space \u003e 80% (warning) / \u003e 95% (critical)\n- Hotspot inactive (warning)\n- ROSE Link backend down (critical)\n\n### Resource Limits\n\nOptimized for Raspberry Pi with strict resource limits:\n- Prometheus: max 256MB RAM, 50% CPU\n- Node Exporter: max 64MB RAM, 20% CPU\n- Data retention: 15 days (saves disk space)\n\n### Requirements\n\n- Raspberry Pi 4 or 5 recommended (1GB+ RAM)\n- ~500MB additional disk space\n- Internet connection (to download Prometheus/Grafana on first enable)\n\n### Docker Alternative (Development)\n\nFor development or systems with more resources, you can use the Docker Compose stack instead:\n\n```bash\ncd monitoring\ndocker-compose up -d\n```\n\n---\n\n## Quick Configuration\n\n### 1. Access the Web Interface\n\nAfter installation, connect to the hotspot:\n- **SSID**: `ROSE-Link` (or your custom name)\n- **Password**: Displayed at end of installation (randomly generated for security)\n\nThen open your browser:\n- **URL**: `https://roselink.local` or `https://192.168.50.1`\n\n\u003e **Note**: Accept the self-signed certificate warning (the certificate uses RSA 4096-bit encryption)\n\n### 2. Configure WireGuard VPN\n\n1. Go to the **VPN** tab\n2. Click **\"Import WireGuard profile (.conf)\"**\n3. Select your `.conf` file from your VPN server\n4. The VPN starts automatically!\n\n### 3. Customize the Hotspot\n\n1. Go to the **Hotspot** tab\n2. Configure:\n   - SSID (network name)\n   - Password (min. 8 characters)\n   - Country (regulatory settings)\n   - Channel (1, 6 or 11 recommended for 2.4GHz)\n   - Band (2.4GHz or 5GHz)\n   - WPA3 (check if supported)\n3. Click **\"Apply\"**\n\n### 4. Configure VPN Watchdog\n\n1. Go to the **System** tab\n2. Set the ping IP to verify VPN connectivity\n3. Adjust check interval if needed\n4. Save settings\n\n---\n\n## Device Compatibility\n\nROSE Link intelligently detects your hardware and adapts its configuration accordingly. The key factors are:\n\n- **WiFi Interfaces**: Single vs Dual WiFi (determines if WiFi WAN is available)\n- **Ethernet Port**: Required for single-WiFi devices, optional for dual-WiFi\n- **WiFi Bands**: 2.4GHz only vs Dual-band (2.4GHz + 5GHz)\n\n### Compatibility Matrix\n\n#### Raspberry Pi Devices (Officially Supported)\n\n| Device | WiFi Interfaces | Ethernet | WiFi WAN | Hotspot Band | Support Level |\n|--------|----------------|----------|----------|--------------|---------------|\n| **Raspberry Pi 5** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐⭐ Full |\n| **Raspberry Pi 4 Model B** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐⭐ Full |\n| **Raspberry Pi 4 + USB WiFi** | 2 | Gigabit | ✅ Yes | 5GHz / 2.4GHz | ⭐⭐⭐⭐⭐ Full |\n| **Raspberry Pi 3 Model B+** | 1 (2.4GHz only) | 100Mbps | ❌ Ethernet only | 2.4GHz | ⭐⭐⭐ Limited |\n| **Raspberry Pi 3 Model B** | 1 (2.4GHz only) | 100Mbps | ❌ Ethernet only | 2.4GHz | ⭐⭐⭐ Limited |\n| **Raspberry Pi Zero 2 W** | 1 (2.4GHz only) | ❌ None | ❌ USB Ethernet req. | 2.4GHz | ⭐⭐ Basic |\n| **Raspberry Pi 400** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐ Good |\n| **Raspberry Pi CM4 + IO Board** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐⭐ Full |\n\n#### Other ARM Single-Board Computers (Community Tested)\n\n| Device | WiFi Interfaces | Ethernet | WiFi WAN | Hotspot Band | Support Level |\n|--------|----------------|----------|----------|--------------|---------------|\n| **Orange Pi 5** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐ Good* |\n| **Banana Pi M5** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐ Good* |\n| **ODROID-C4** | ❌ None | Gigabit | ❌ USB WiFi req. | USB WiFi | ⭐⭐⭐ Limited* |\n| **Rock Pi 4** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐ Good* |\n| **Libre Computer Le Potato** | ❌ None | 100Mbps | ❌ USB WiFi req. | USB WiFi | ⭐⭐⭐ Limited* |\n| **Khadas VIM3** | 1 (Dual-band) | Gigabit | ❌ Ethernet only | 5GHz / 2.4GHz | ⭐⭐⭐⭐ Good* |\n| **NanoPi R4S** | ❌ None | Dual Gigabit | ❌ USB WiFi req. | USB WiFi | ⭐⭐⭐⭐ Good* |\n| **BeagleBone Black** | ❌ None | 100Mbps | ❌ USB WiFi req. | USB WiFi | ⭐⭐ Basic* |\n\n\u003e **\\*** Community tested - may require manual configuration. These devices must run Debian-based Linux (Armbian, DietPi, etc.) and may need driver installation for WiFi chipsets.\n\n### Understanding Single vs Dual WiFi\n\n#### Single WiFi Interface (Most Common)\nMost Raspberry Pi models have **only one WiFi interface**. In this configuration:\n- The WiFi is **reserved for the hotspot** (Access Point mode)\n- Internet connection **must come from Ethernet** (RJ45)\n- WiFi WAN scanning is **automatically disabled** in the web interface\n\n```\n🌐 Internet ── Ethernet ──▶ 🍓 ROSE Link ── WiFi Hotspot ──▶ 📱 Your Devices\n                                   │\n                                   └── WireGuard VPN ──▶ 🔐 VPN Server\n```\n\n#### Dual WiFi Interface (With USB Adapter)\nAdding a USB WiFi adapter gives you **two WiFi interfaces**:\n- One WiFi for **WAN connection** (connects to your existing WiFi)\n- One WiFi for **Hotspot** (creates the ROSE-Link network)\n- Ethernet becomes **optional** (but still prioritized if connected)\n\n```\n🌐 Internet ── WiFi WAN ──▶ 🍓 ROSE Link ── WiFi Hotspot ──▶ 📱 Your Devices\n                                   │\n                                   └── WireGuard VPN ──▶ 🔐 VPN Server\n```\n\n### Recommended Configurations\n\n#### Best Performance (Recommended)\n- **Raspberry Pi 5** or **Raspberry Pi 4** (4GB RAM)\n- **Ethernet connection** for WAN (most stable)\n- **5GHz hotspot** for faster client connections\n- **Active cooling** (fan or heatsink)\n\n#### Budget Option\n- **Raspberry Pi 3 Model B+**\n- **Ethernet connection** required\n- **2.4GHz hotspot** only\n- Suitable for 1-5 devices, light usage\n\n#### Portable/Travel Setup\n- **Raspberry Pi 4** + USB WiFi adapter\n- **WiFi WAN** (connect to hotel/cafe WiFi)\n- **USB-C power bank** compatible\n- No Ethernet required\n\n### Hardware Requirements\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| **RAM** | 512 MB | 2 GB+ |\n| **Storage** | 8 GB microSD | 32 GB Class A2 |\n| **Power** | 5V 2.5A | 5V 3A (5V 5A for Pi 5) |\n| **OS** | Raspberry Pi OS Lite | Raspberry Pi OS (64-bit) |\n| **Debian** | Bullseye (11) | Bookworm (12) / Trixie (13) |\n\n### Automatic Hardware Detection\n\nROSE Link automatically detects and adapts to your hardware:\n- **Raspberry Pi model** and generation\n- **Number of WiFi interfaces** (single vs dual)\n- **WiFi capabilities** (2.4GHz only, 5GHz, 802.11ac/ax)\n- **Ethernet availability** and link status\n- **System resources** (RAM, disk space, CPU temperature)\n\nWhen a single WiFi interface is detected:\n- WiFi WAN options are **hidden** in the web interface\n- Setup wizard shows an **\"Ethernet Required\"** notice\n- Installation displays a clear warning about the limitation\n\n---\n\n## REST API\n\n### Available Endpoints\n\n#### Health and Status\n- `GET /api/health` - Health check\n- `GET /api/status` - Global status (WAN, VPN, AP)\n- `GET /api/metrics` - Prometheus metrics endpoint\n- `GET /api/metrics/performance` - Request latency and performance metrics (JSON)\n\n#### WebSocket\n- `WS /api/ws` - Real-time status updates\n- `GET /api/ws/status` - WebSocket connection info\n\n#### WiFi WAN\n- `POST /api/wifi/scan` - Scan WiFi networks *(requires auth)*\n- `POST /api/wifi/connect` - Connect to network *(requires auth)*\n- `POST /api/wifi/disconnect` - Disconnect *(requires auth)*\n\n#### VPN (WireGuard + OpenVPN)\n- `GET /api/vpn/status` - VPN status\n- `GET /api/vpn/profiles` - List profiles *(requires auth)*\n- `POST /api/vpn/upload` - Upload profile *(requires auth)*\n- `POST /api/vpn/import` - Import and activate *(requires auth)*\n- `POST /api/vpn/activate` - Activate existing profile *(requires auth)*\n- `POST /api/vpn/start` - Start VPN *(requires auth)*\n- `POST /api/vpn/stop` - Stop VPN *(requires auth)*\n- `POST /api/vpn/restart` - Restart VPN *(requires auth)*\n\n#### AdGuard Home (v1.0.0+)\n- `GET /api/adguard/status` - AdGuard status and stats\n- `POST /api/adguard/enable` - Enable DNS protection\n- `POST /api/adguard/disable` - Disable DNS protection\n- `GET /api/adguard/stats` - Blocking statistics\n- `GET /api/adguard/querylog` - DNS query log\n\n#### Connected Clients (v1.0.0+)\n- `GET /api/clients` - List all clients\n- `GET /api/clients/connected` - Currently connected clients\n- `GET /api/clients/{mac}` - Get client details\n- `PUT /api/clients/{mac}` - Update client name\n- `POST /api/clients/{mac}/block` - Block client\n- `POST /api/clients/{mac}/unblock` - Unblock client\n- `POST /api/clients/{mac}/kick` - Disconnect client\n\n#### QoS (v1.0.0+)\n- `GET /api/qos/status` - QoS status and config\n- `POST /api/qos/enable` - Enable traffic prioritization\n- `POST /api/qos/disable` - Disable QoS\n- `PUT /api/qos/config` - Update QoS settings\n\n#### Setup Wizard (v1.0.0+)\n- `GET /api/setup/status` - Check if setup required\n- `POST /api/setup/start` - Start setup wizard\n- `GET /api/setup/step/{step}` - Get step data\n- `POST /api/setup/step/{step}` - Submit step data\n- `POST /api/setup/complete` - Complete setup\n- `POST /api/setup/skip` - Skip setup\n\n#### Hotspot\n- `GET /api/hotspot/status` - Hotspot status\n- `GET /api/hotspot/clients` - List connected clients *(requires auth)*\n- `POST /api/hotspot/apply` - Apply configuration *(requires auth)*\n- `POST /api/hotspot/restart` - Restart hotspot *(requires auth)*\n\n#### Backup/Restore\n- `GET /api/backup/list` - List available backups\n- `POST /api/backup/create` - Create new backup\n- `POST /api/backup/restore/{filename}` - Restore from backup\n- `GET /api/backup/download/{filename}` - Download backup file\n- `POST /api/backup/upload` - Upload backup file\n- `DELETE /api/backup/{filename}` - Delete backup\n\n#### Speed Test\n- `GET /api/speedtest/status` - Check if test running\n- `POST /api/speedtest/run` - Start speed test\n- `GET /api/speedtest/history` - Get test history\n- `GET /api/speedtest/last` - Get last result\n\n#### SSL Certificates\n- `GET /api/ssl/status` - Certificate status\n- `POST /api/ssl/request` - Request Let's Encrypt certificate\n- `POST /api/ssl/renew` - Renew certificates\n- `POST /api/ssl/self-signed` - Generate self-signed certificate\n\n#### Settings\n- `GET /api/settings/vpn` - Get VPN watchdog settings *(requires auth)*\n- `POST /api/settings/vpn` - Update VPN watchdog settings *(requires auth)*\n\n#### System\n- `GET /api/system/info` - System information (Pi model, RAM, CPU, WiFi)\n- `GET /api/system/interfaces` - Detected network interfaces\n- `GET /api/system/logs?service=xxx` - Service logs *(requires auth)*\n- `POST /api/system/reboot` - Reboot system *(requires auth)*\n\n### Usage Example\n\n```bash\n# Health check\ncurl -k https://roselink.local/api/health\n\n# Global status\ncurl -k https://roselink.local/api/status | jq\n\n# Scan WiFi\ncurl -k -X POST https://roselink.local/api/wifi/scan | jq\n\n# VPN status\ncurl -k https://roselink.local/api/vpn/status | jq\n\n# System information\ncurl -k https://roselink.local/api/system/info | jq\n```\n\n---\n\n## Roadmap\n\n### Version 1.6.4 (Current - Latest)\n- [x] **AdGuard Home v0.107+ Support**: Updated configuration schema for latest AdGuard\n- [x] **DNS Resolution Fix**: System DNS now properly configured for VPN hostname resolution\n- [x] **dnsmasq/AdGuard Integration**: Port conflict resolution and proper upstream DNS forwarding\n\n### Version 1.6.0 - 1.6.3\n- [x] **Single WiFi Device Detection**: Smart detection hides WiFi WAN on single-interface devices\n- [x] **Extended VPN File Support**: Import .conf, .wg, .wireguard, .vpn files\n- [x] **Expanded Countries List**: 40+ countries with region-appropriate WiFi regulations\n- [x] **Pydantic/FastAPI Fix**: Resolved UploadFile compatibility issues\n- [x] **resolvconf Dependency**: Added openresolv for WireGuard DNS management\n- [x] **UX Improvements**: Reboot/restart confirmation buttons, wizard skip button fix\n\n### Version 1.5.x\n- [x] **AdGuard UI Fixes**: Buttons properly hidden when not installed\n- [x] **VPN UI Improvements**: Better error handling and button states\n- [x] **FastAPI Response Model Fixes**: Return type validation corrections\n\n### Version 1.3.x\n- [x] **AdGuard Home Integration**: New \"Ad Blocker\" tab in web UI\n  - Real-time protection status and controls (enable/disable/restart)\n  - Blocking statistics dashboard (DNS queries, blocked count, block rate)\n  - Top blocked domains and clients lists\n  - DNS query log viewer\n- [x] **Dynamic Version System**: Version fetched from single `VERSION` file\n- [x] **Single-WiFi Hotspot Fix**: Fixed hotspot on Pi 3B/Zero 2W with Ethernet\n\n### Version 1.2.x\n- [x] **Grafana Monitoring Dashboard**: Complete monitoring stack with Docker Compose\n  - Grafana + Prometheus + Node Exporter\n  - Status overview, system resources, network traffic panels\n  - Template variables for interface/instance filtering\n  - Pre-configured Prometheus alert rules\n- [x] **E2E Test Improvements**: Comprehensive Playwright tests\n- [x] **Accessibility Enhancements**: Keyboard navigation, ARIA labels\n\n### Version 1.0.0 - 1.1.0 (Production Ready)\n- [x] **AdGuard Home Integration**: DNS-level ad blocking with statistics\n- [x] **OpenVPN Support**: In addition to WireGuard (.ovpn file import)\n- [x] **Connected Clients Management**: Track, name, block/unblock devices\n- [x] **Simple QoS**: VPN traffic prioritization\n- [x] **First-Time Setup Wizard**: Guided initial configuration\n- [x] Performance metrics endpoint (`/api/metrics/performance`)\n- [x] Rate limiting for API abuse protection\n\n### Previous Releases (v0.x)\n- [x] WebSocket for real-time status updates\n- [x] Configuration backup/restore\n- [x] Let's Encrypt SSL certificate option\n- [x] Speed test integration\n- [x] Prometheus metrics endpoint\n- [x] Complete i18n support (English \u0026 French)\n- [x] Mobile-first responsive design\n\n### Future Releases\n- [ ] Email notifications for VPN failures\n- [ ] Full QoS profiles (Gaming, Streaming, Work)\n- [ ] Multi-WAN load balancing\n- [ ] Automatic updates\n\n---\n\n## Troubleshooting\n\n### Quick Service Check\n\n```bash\n# Check all ROSE Link services at once\nfor svc in rose-backend rose-watchdog hostapd dnsmasq nginx; do\n    status=$(systemctl is-active $svc 2\u003e/dev/null || echo \"inactive\")\n    echo \"$svc: $status\"\ndone\n```\n\n### Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| Can't connect to hotspot | `sudo systemctl restart hostapd` |\n| VPN not connecting | `sudo systemctl restart wg-quick@wg0` |\n| Web interface not loading | `sudo systemctl restart nginx rose-backend` |\n| No internet on clients | Check VPN: `sudo wg show` and IP forwarding: `cat /proc/sys/net/ipv4/ip_forward` |\n\n### View Logs\n\n```bash\n# Backend logs\nsudo journalctl -u rose-backend -f\n\n# VPN logs\nsudo journalctl -u wg-quick@wg0 -n 50\n\n# Hotspot logs\nsudo journalctl -u hostapd -n 50\n\n# Installation log\ncat /var/log/rose-link-install.log\n```\n\n### Full Documentation\n\nSee [QUICKSTART.md](QUICKSTART.md) for detailed troubleshooting steps.\n\n---\n\n## Contributing\n\nContributions are welcome!\n\n### How to Contribute\n\n1. Fork the project\n2. Create a branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add AmazingFeature'`)\n4. Push to branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n### Local Development\n\n```bash\n# Clone\ngit clone https://github.com/oussrh/ROSE-LINK.git\ncd ROSE-LINK\n\n# Backend\ncd backend\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\npython main.py\n\n# Web: open web/index.html in a browser\n```\n\n---\n\n## License\n\nThis project is under MIT License. See the `LICENSE` file for details.\n\n---\n\n## Acknowledgments\n\n- **WireGuard**: Modern and performant VPN\n- **FastAPI**: Fast and elegant Python framework\n- **Tailwind CSS**: Utility-first CSS framework\n- **htmx**: Modern HTML interactivity\n- **Raspberry Pi Foundation**: Extraordinary hardware\n\n---\n\n## Support\n\n- **Documentation**: [GitHub Wiki](https://github.com/oussrh/ROSE-LINK/wiki)\n- **Issues**: [GitHub Issues](https://github.com/oussrh/ROSE-LINK/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/oussrh/ROSE-LINK/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with love for secure remote access**\n\n[Star this project](https://github.com/oussrh/ROSE-LINK) | [Report a bug](https://github.com/oussrh/ROSE-LINK/issues) | [Suggest a feature](https://github.com/oussrh/ROSE-LINK/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foussrh%2Frose-link","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foussrh%2Frose-link","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foussrh%2Frose-link/lists"}