395 lines
9.0 KiB
Markdown
395 lines
9.0 KiB
Markdown
# ⚡ Wake-on-LAN Dashboard
|
||
|
||
A modern, self-hosted web dashboard to remotely power on PCs via Magic Packet.
|
||
Built with Python (Flask) and a responsive HTML/CSS/JS frontend — works on desktop and mobile.
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 📋 Features
|
||
|
||
- ⚡ Wake up PCs remotely via Magic Packet (Wake-on-LAN)
|
||
- 🟢 Real-time Online/Offline status via Ping
|
||
- 🔍 Automatic network scan to discover devices (nmap)
|
||
- ➕ Manually add devices (Name, MAC, IP)
|
||
- 🗑 Remove devices from the list
|
||
- 📱 Fully responsive — works on mobile and desktop
|
||
- 🔄 Auto-refresh status every 30 seconds
|
||
|
||
---
|
||
|
||
## 🗂 Project Structure
|
||
wol-dashboard/
|
||
├── app.py # Flask backend for Windows
|
||
├── app_linux.py # Flask backend for Linux
|
||
├── devices.json # Device database (auto-created on first save)
|
||
├── README.md
|
||
└── templates/
|
||
└── index.html # Web frontend (shared for both platforms)
|
||
|
||
---
|
||
|
||
## 🖥️ Installation — Windows
|
||
|
||
### Step 1 — Install Python
|
||
|
||
Open **PowerShell or CMD as Administrator** and run:
|
||
|
||
```cmd
|
||
winget install -e --id Python.Python.3.13
|
||
```
|
||
|
||
Close and reopen CMD after installation. Verify:
|
||
|
||
```cmd
|
||
python --version
|
||
pip --version
|
||
```
|
||
|
||
> **Tip:** If `python` opens the Microsoft Store instead, go to:
|
||
> **Settings → Apps → Advanced App Settings → App Execution Aliases**
|
||
> and disable `python.exe` and `python3.exe`.
|
||
|
||
---
|
||
|
||
### Step 2 — Install nmap
|
||
|
||
```cmd
|
||
winget install -e --id Insecure.Nmap
|
||
```
|
||
|
||
Close and reopen CMD. Verify:
|
||
|
||
```cmd
|
||
nmap --version
|
||
```
|
||
|
||
---
|
||
|
||
### Step 3 — Set up the project
|
||
|
||
```cmd
|
||
cd C:\Users\<YourName>\Desktop\wol-dashboard
|
||
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
|
||
pip install flask wakeonlan
|
||
```
|
||
|
||
---
|
||
|
||
### Step 4 — Create project files
|
||
|
||
Make sure your folder contains these files:
|
||
wol-dashboard/
|
||
├── app.py
|
||
├── devices.json ← optional, auto-created
|
||
└── templates/
|
||
└── index.html
|
||
|
||
Create the templates folder if it doesn't exist:
|
||
|
||
```cmd
|
||
mkdir templates
|
||
```
|
||
|
||
---
|
||
|
||
### Step 5 — Start the server
|
||
|
||
```cmd
|
||
venv\Scripts\activate
|
||
python app.py
|
||
```
|
||
|
||
You should see:
|
||
Running on http://0.0.0.0:5000
|
||
|
||
|
||
Open in your browser: **http://localhost:5000**
|
||
|
||
---
|
||
|
||
### Optional — Allow port 5000 through Windows Firewall
|
||
|
||
```cmd
|
||
netsh advfirewall firewall add rule name="Flask WOL" dir=in action=allow protocol=TCP localport=5000
|
||
```
|
||
|
||
---
|
||
|
||
## 🐧 Installation — Linux (Debian / Ubuntu)
|
||
|
||
### Step 1 — Install system dependencies
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install python3 python3-venv python3-full nmap -y
|
||
```
|
||
|
||
Verify:
|
||
|
||
```bash
|
||
python3 --version
|
||
nmap --version
|
||
```
|
||
|
||
---
|
||
|
||
### Step 2 — Set up the project
|
||
|
||
```bash
|
||
cd ~/DEV/wol-dashboard
|
||
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
|
||
pip install flask wakeonlan
|
||
```
|
||
|
||
---
|
||
|
||
### Step 3 — Grant nmap network permissions (once)
|
||
|
||
nmap needs elevated privileges for ARP scans. Instead of running as root, grant capabilities once:
|
||
|
||
```bash
|
||
sudo setcap cap_net_raw,cap_net_admin+eip $(which nmap)
|
||
```
|
||
|
||
---
|
||
|
||
### Step 4 — Create project files
|
||
|
||
```bash
|
||
mkdir -p templates
|
||
# Place app_linux.py and templates/index.html in the folder
|
||
```
|
||
|
||
---
|
||
|
||
### Step 5 — Start the server
|
||
|
||
```bash
|
||
source venv/bin/activate
|
||
python app_linux.py
|
||
```
|
||
|
||
You should see:
|
||
Running on http://0.0.0.0:5000
|
||
|
||
|
||
Open in your browser: **http://localhost:5000**
|
||
|
||
---
|
||
|
||
### Optional — Auto-start on boot with systemd
|
||
|
||
Create a service file:
|
||
|
||
```bash
|
||
sudo nano /etc/systemd/system/wol-dashboard.service
|
||
```
|
||
|
||
Paste the following (adjust paths):
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Wake-on-LAN Dashboard
|
||
After=network.target
|
||
|
||
[Service]
|
||
User=YOUR_USERNAME
|
||
WorkingDirectory=/home/YOUR_USERNAME/DEV/wol-dashboard
|
||
ExecStart=/home/YOUR_USERNAME/DEV/wol-dashboard/venv/bin/python app_linux.py
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
Enable and start:
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable wol-dashboard
|
||
sudo systemctl start wol-dashboard
|
||
sudo systemctl status wol-dashboard
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 Accessing from Phone or Other Devices
|
||
|
||
1. Find your server IP:
|
||
- **Windows:** Open CMD → `ipconfig` → look for **IPv4 Address**
|
||
- **Linux:** Run `hostname -I`
|
||
|
||
2. Open on any device in the same network:
|
||
http://192.168.x.x:5000
|
||
|
||
|
||
---
|
||
|
||
## ⚙️ Wake-on-LAN Setup on Target PCs
|
||
|
||
For a PC to be woken up, it must be configured correctly.
|
||
|
||
### BIOS / UEFI
|
||
- Enter BIOS on boot (usually `DEL`, `F2`, or `F12`)
|
||
- Find and enable: `Wake-on-LAN`, `Power On By PCI-E`, or `Resume By LAN`
|
||
|
||
### Windows Target PC
|
||
1. Open **Device Manager**
|
||
2. Expand **Network Adapters** → right-click your adapter → **Properties**
|
||
3. Tab **Power Management**:
|
||
- ✅ Allow this device to wake the computer
|
||
4. Tab **Advanced**:
|
||
- Set `Wake on Magic Packet` → **Enabled**
|
||
|
||
### Linux Target PC
|
||
```bash
|
||
sudo apt install ethtool
|
||
|
||
# Check current WoL status
|
||
sudo ethtool eth0 | grep Wake
|
||
|
||
# Enable WoL (replace eth0 with your adapter name)
|
||
sudo ethtool -s eth0 wol g
|
||
```
|
||
|
||
To make it permanent, add to `/etc/rc.local` or create a systemd service.
|
||
|
||
Find your adapter name with:
|
||
```bash
|
||
ip link show
|
||
```
|
||
|
||
---
|
||
|
||
## 🗄 devices.json
|
||
|
||
Devices are stored in `devices.json` in the project root. It is created automatically when you save the first device via the UI.
|
||
|
||
You can also edit it manually:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "Gaming-PC",
|
||
"mac": "AA:BB:CC:DD:EE:FF",
|
||
"ip": "192.168.1.100"
|
||
},
|
||
{
|
||
"name": "Work Laptop",
|
||
"mac": "11:22:33:44:55:66",
|
||
"ip": "192.168.1.105"
|
||
}
|
||
]
|
||
```
|
||
|
||
| Field | Required | Description |
|
||
|--------|----------|--------------------------------------------------|
|
||
| `name` | ✅ | Display name shown on the dashboard card |
|
||
| `mac` | ✅ | MAC address — colons or dashes both accepted |
|
||
| `ip` | ❌ | IP address — required for online status ping |
|
||
|
||
---
|
||
|
||
## 🔄 Daily Usage
|
||
|
||
### Windows
|
||
```cmd
|
||
cd C:\Users\<YourName>\Desktop\wol-dashboard
|
||
venv\Scripts\activate
|
||
python app.py
|
||
```
|
||
|
||
### Linux
|
||
```bash
|
||
cd ~/DEV/wol-dashboard
|
||
source venv/bin/activate
|
||
python app_linux.py
|
||
```
|
||
|
||
Or create a startup script `start.sh`:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
cd ~/DEV/wol-dashboard
|
||
source venv/bin/activate
|
||
python app_linux.py
|
||
```
|
||
|
||
```bash
|
||
chmod +x start.sh
|
||
./start.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 Platform Differences
|
||
|
||
| Feature | `app.py` (Windows) | `app_linux.py` (Linux) |
|
||
|----------------------|------------------------|------------------------------|
|
||
| Ping command | `ping -n 1 -w 500` | `ping -c 1 -W 1` |
|
||
| ARP command | `arp -a` | `arp -n` |
|
||
| MAC format in ARP | `AA-BB-CC-DD-EE-FF` | `aa:bb:cc:dd:ee:ff` |
|
||
| nmap line endings | `\r\n` | `\n` |
|
||
| Elevated rights | Run CMD as Admin | `setcap` once |
|
||
| Auto-start | Task Scheduler | systemd service |
|
||
| `index.html` | ✅ Shared | ✅ Shared |
|
||
|
||
---
|
||
|
||
## 📦 Dependencies
|
||
|
||
| Package | Install via | Purpose |
|
||
|-------------|--------------|--------------------------|
|
||
| `flask` | pip | Web framework |
|
||
| `wakeonlan` | pip | Send Magic Packets |
|
||
| `nmap` | System | Network device scanning |
|
||
|
||
Install Python packages:
|
||
|
||
```bash
|
||
pip install flask wakeonlan
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 Security Notice
|
||
|
||
This dashboard is designed for **trusted local networks only**.
|
||
It has no authentication built in. Do not expose port 5000 to the internet without:
|
||
- A reverse proxy (e.g. nginx) with HTTPS
|
||
- HTTP Basic Auth or a login system
|
||
- A VPN (e.g. WireGuard, Tailscale)
|
||
|
||
---
|
||
|
||
## 🛠 Troubleshooting
|
||
|
||
| Problem | Solution |
|
||
|----------------------------------|--------------------------------------------------------------------------|
|
||
| `python` opens Microsoft Store | Disable App Execution Aliases in Windows Settings |
|
||
| `nmap` not found | Install nmap and restart terminal |
|
||
| `venv\Scripts\activate` fails | Run `python -m venv venv` first |
|
||
| PC does not wake up | Enable WoL in BIOS and network adapter settings |
|
||
| Status always shows Offline | Make sure IP is correct and target allows ping (check firewall) |
|
||
| Port 5000 blocked on Windows | Add firewall rule: `netsh advfirewall firewall add rule name="Flask WOL" dir=in action=allow protocol=TCP localport=5000` |
|
||
| Scan finds no devices | Run `setcap` on Linux or start CMD as Admin on Windows |
|
||
| Page not loading | Check Flask is running and no error in terminal |
|
||
| `externally-managed-environment` | Use a virtual environment: `python3 -m venv venv` |
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT License — free to use, modify and distribute.
|
||
>>>>>>> edfb358 (Initial commit)
|