MasterDnsWeb is a web panel for managing your MasterDnsVPN instances on a Linux server. You get a clean dashboard where you can create, configure, start, and stop VPN instances — all from your browser.
This project is primarily designed for use on Iran-based VPS servers.
- Ubuntu 20.04 or newer (other distros are not supported yet)
- The release archive:
MasterDnsWeb-linux-amd64.tar.gz - Root access (required to manage system services)
tar -xzf MasterDnsWeb-linux-amd64.tar.gz
cd MasterDnsWebYou will see this folder:
MasterDnsWeb/
MasterDnsWeb ← the web panel (run this)
MasterDnsVPN ← the VPN client binary
.env ← your settings
Open .env in any text editor:
nano .envThe only things you must change before starting:
ADMIN_USERNAME=admin
ADMIN_PASSWORD=changeme ← change this to something strongEverything else already has safe defaults. Save and close.
sudo ./MasterDnsWebWhy sudo? The panel needs root access to create and control system services for each VPN instance.
The panel is now running. Open your browser and go to:
http://<your-server-ip>:8000
Log in with the username and password you set in .env.
If you want the panel to start automatically when your server reboots, create a system service.
Run this command (replace /root/MasterDnsWeb with your actual folder path):
sudo nano /etc/systemd/system/masterdnsweb.servicePaste this inside:
[Unit]
Description=MasterDnsWeb Panel
After=network.target
[Service]
WorkingDirectory=/root/MasterDnsWeb
ExecStart=/root/MasterDnsWeb/MasterDnsWeb
Restart=always
RestartSec=5
User=root
[Install]
WantedBy=multi-user.targetThen run:
sudo systemctl daemon-reload
sudo systemctl enable masterdnsweb
sudo systemctl start masterdnsweb- Go to the Instances page
- Click New Instance and give it a name
- Click the instance to open its Configuration page
Paste your client_config.toml content into the Configuration text box.
All fields from your config file are accepted — just paste the whole thing.
Add your resolver IPs in the Resolvers box (one per line), then click Apply & Restart.
Use the Start, Stop, and Restart buttons on the Instances page. Each instance runs as a separate system service in the background.
The panel creates these folders automatically next to the binary:
MasterDnsWeb/
MasterDnsWeb ← web panel binary
MasterDnsVPN ← VPN client binary
.env ← your settings
data/ ← instance profiles (auto-created)
runtime/
my-instance/ ← working files per instance (auto-created)
client_config.toml
client_resolvers.txt
MasterDnsVPN
All settings live in the .env file next to the binary.
| Setting | Default | Description |
|---|---|---|
ADMIN_USERNAME |
admin |
Login username |
ADMIN_PASSWORD |
changeme |
Login password — change this |
SECRET_KEY |
(generated at build) | Signs login sessions — do not share |
HOST |
0.0.0.0 |
Address the panel listens on |
PORT |
8000 |
Port the panel listens on |
COOKIE_SECURE |
false |
Set to true if using HTTPS |
MASTERVPN_SERVICE_USER |
root |
System user that runs VPN instances |
MASTERVPN_SERVICE_EXEC_START |
(auto) | Full path to MasterDnsVPN — only needed if it is not in the same folder |
flowchart TB
U[You — Browser] --> PANEL[MasterDnsWeb\nport 8000]
PANEL --> AUTH[Login and Session]
PANEL --> CFG[Instance Profiles\nstored in data/]
PANEL --> SVC[Service Manager]
PANEL --> STATS[Server Stats\nCPU · RAM · Disk]
SVC --> RUNTIME[runtime/instance-name/\nclient_config.toml\nclient_resolvers.txt\nMasterDnsVPN]
SVC --> SYSTEMD[systemd\nmasterdnsvpn-instance.service]
SYSTEMD --> VPN[MasterDnsVPN Process]
RUNTIME --> VPN
| Problem | What to do |
|---|---|
| Panel won't start | Make sure you run it with sudo. Root access is needed to manage services. |
| Can't open it in the browser | Check your firewall — port 8000 (or your custom PORT) must be open. |
| "MasterDnsVPN binary was not found" | Make sure MasterDnsVPN is in the same folder as MasterDnsWeb. Or set MASTERVPN_SERVICE_EXEC_START in .env to its full path. |
| Instance won't start | Open the instance in the panel and check the logs for details. |
A special thank you to @shimafallah for writing the backend.