FAQ
Here are some frequently asked questions and common issues about TunGuard. If you have a question that is not answered here, feel free to open an issue or discussion on GitHub.
Do I need to install WireGuard?⚓
No. TunGuard runs WireGuard entirely in userspace. You do not need to install the WireGuard kernel module or run apt install wireguard.
How do I install TunGuard?⚓
On a fresh Linux server, run:
The installer installs and starts TunGuard automatically.
After installation, open:
What are the default dashboard credentials?⚓
On a fresh installation:
You will be required to change the credentials after the first login. Until you do,
http://YOUR_SERVER_IP:9000/login.html is the only page you reach, and it asks for
new credentials before anything else loads.
Why can my devices not see each other?⚓
Check which policy group each device is in, on the Policy page.
Devices in different groups never talk, even when the group is set to allow inter-device traffic — including over P2P, which the server refuses to punch for a cross-group pair. Devices that need to reach each other must be in the same group, with inter-device traffic switched on for it.
That group also needs its own internet access switched on: a sealed group can talk to its own group and nothing beyond the tunnel. Reaching the server itself is never part of that — the server's own addresses always pass, which is how you would come back here and turn the switch on again.
I cannot access the dashboard⚓
TunGuard's dashboard and API use port 9000 by default.
Make sure the port is reachable from your network and that your server or cloud provider firewall allows TCP traffic on port 9000.
You can also check the service status:
What ports does TunGuard use?⚓
The default ports are:
| Service | Port | Protocol |
|---|---|---|
| WireGuard | 13231 |
UDP |
| Dashboard/API | 9000 |
TCP |
| SSH Gateway | 2222 |
TCP |
| P2P control channel | 7000 |
TCP |
| P2P rendezvous/relay | 7001 |
UDP |
The last two are only needed for the P2P mesh.
How do I create a WireGuard peer?⚓
Open Peers in the dashboard and create a new peer.
TunGuard can generate the client configuration and QR code.
The default VPN network is:
My peer cannot connect⚓
Check that:
- The WireGuard UDP port
13231is reachable from the internet. - The client configuration uses the correct server address and port.
- The server is running.
- The peer exists in Peers in the dashboard.
You can check the service with:
My peer connects but cannot access the internet⚓
Check that the server has internet connectivity and that the client's configuration routes the required traffic through TunGuard.
For full-tunnel routing, the peer configuration normally contains:
Server-side routing and NAT must also be correctly configured for your environment.
I forgot my dashboard password⚓
Reset the dashboard credentials with:
This removes the stored dashboard credentials and restores:
You can then log in and set new credentials.
How do I change the dashboard credentials?⚓
Open Settings → Dashboard Login in the dashboard.
Changes take effect immediately.
How do I update TunGuard?⚓
Run the installer again:
The installer updates the TunGuard binary while preserving the existing service configuration and persistent data.
Will updating TunGuard delete my peers?⚓
No. Peer data is stored in the persistent DATA_DIR and is preserved when updating the binary.
How do I back up TunGuard?⚓
From the dashboard, open:
Settings → Backup & Restore → Download Backup
You can also create a backup from the command line:
How do I restore a backup?⚓
Use Settings → Backup & Restore in the dashboard and upload a TunGuard backup.
The restored peer and server state is applied immediately.
If the restored server private key is different, existing clients will need updated configurations.
Does TunGuard support existing WireGuard keys?⚓
Yes. You can add an existing peer key through the Peers section instead of generating a new key.
How do I block ads for my devices?⚓
TunGuard includes a managed AdGuard Home DNS filter. Create a policy group, turn on Allow AdGuard DNS filtering (and Allow standard WireGuard internet access), and move the device — for example your phone — into that group on the Policy page.
The server enforces it: the port-53 DNS of an AdGuard-group device is redirected to AdGuard, so protection applies immediately, no matter what DNS server the WireGuard profile says, and no re-import is needed. Moving the device back to Default turns the filter off.
Why do I still see ads on my phone?⚓
Check, in order:
- The phone is actually connected to the VPN (its traffic goes through the tunnel).
- The phone is in an AdGuard-enabled policy group on the Policy page — the built-in Default group does not filter.
- AdGuard is running — Settings → AdGuard, or
adguard status. - On Android, Private DNS is set to Off (or Automatic). Private DNS uses DNS-over-HTTPS/TLS, which is encrypted and bypasses the server-side port-53 redirect entirely.
You can watch filtered queries in real time in the AdGuard web UI at
http://YOUR_SERVER_IP:9000/adguard-ui/ → Query Log.
How do I publish a service on a public domain?⚓
Use the Domains & HTTPS Proxy. Point the domain's A record at your server, then add a mapping from the Domains page, the API, or the console:
for a service on a WireGuard peer, or --trp <id> for a service behind a TRP
port mapping. TunGuard issues a Let's Encrypt certificate automatically; keep
ports 80 and 443 reachable.
What is the SSH Gateway?⚓
The optional SSH Gateway allows SSH access to WireGuard-connected devices through the TunGuard server.
It uses port 2222 by default and can be enabled with:
For example:
See SSH Access for the jump host, the in-browser SSH terminal,
and the built-in ssh client.
How do I use the API?⚓
TunGuard provides an API under /api/*.
Most API endpoints require dashboard authentication or an API key.
API keys can be generated from Settings → API Key and supplied using either:
or:
The /api/health endpoint does not require authentication.
How do I build a P2P mesh?⚓
Install the client on each device:
Then open P2P → Enroll device in the dashboard and run the command it shows:
Nothing else is needed. Devices sharing a PSK discover each other and punch a direct path automatically. See P2P Mesh.
Is the P2P mesh a VPN?⚓
No. The mesh moves UDP datagrams directly between devices and has no tunnel, no
assigned addresses, and no WireGuard underneath. A device on the mesh never receives a
wg0 address. If you need a VPN, use a peer instead — the two features are independent
and can run at the same time.
My mesh devices are online but see no peers⚓
They are almost certainly not sharing a PSK. Peers only ever discover other devices in their own group, so two different PSKs means two separate meshes that cannot see each other. Compare the group keys on the P2P page.
My mesh links are online but never go direct⚓
A link only turns direct once a packet genuinely arrives from the peer. When a NAT or
firewall blocks the hole punch it stays relayed, which is normal and still carries
traffic — the server just stays in the path. Check that 7001/UDP is open and
bidirectional on the server. See
When the relay is used.
Does mesh traffic between my devices get encrypted?⚓
Not by TunGuard itself — the client relays datagrams as they arrive. If you need confidentiality on the direct path, run a WireGuard peer over the mesh.
Where can I report a bug?⚓
Open an issue in the TunGuard repository.
Include:
- TunGuard version
- Linux distribution
- Relevant logs
- Steps to reproduce the problem