20. Troubleshooting

Reset Admin Password

If you have lost access to the web panel or forgotten the admin password, you can reset it using the recovery mode.

Step 1: Stop the Service

systemctl stop puqvpncp

Step 2: Run Recovery

puqvpncp --recover

This will:

=== PUQVPNCP Recovery Mode ===
[OK] Admin group reset to full access (*)
[OK] Admin user: already in admin group
[OK] Admin password reset to 'admin' (password change will be required)

Recovery complete. Login as admin / admin.
You will be prompted to change the password on first login.

The recovery command performs the following:

• Resets the admin permission group to full access (*)
• If the admin user does not exist — creates it with password admin
• If the admin user exists — resets password to admin and ensures the user is in the admin group
• Sets the ForcePasswordChange flag — you will be prompted to change the password on first login
• Recreates default permission groups (operator, viewer) if they are missing

Step 3: Start the Service

systemctl start puqvpncp

Step 4: Login

Open the web panel and login with:

You will be prompted to set a new password immediately.

Service Won't Start

Check the service status

systemctl status puqvpncp

Check the logs

tail -100 /var/log/puqvpncp/puqvpncp.log

Common causes

Web Panel Not Accessible

Check if the service is running

systemctl is-active puqvpncp

Check which port is in use

ss -tlnp | grep puqvpncp

Common causes

Binary Cannot Be Updated

If you get "Text file busy" error when trying to copy a new binary:

systemctl stop puqvpncp
cp puqvpncp /usr/sbin/puqvpncp
systemctl start puqvpncp

The service must be stopped before replacing the binary. The running process locks the file.

WireGuard Interface Not Created

Check if WireGuard kernel module is loaded

modprobe wireguard
lsmod | grep wireguard

Check WireGuard tools

wg --version

If missing, install:

apt install wireguard wireguard-tools

AmneziaWG Interface Not Created or Module Not Loaded

1. Check DKMS status and kernel module

# Check DKMS compilation status
dkms status
# Should show: amneziawg/..., ...: installed

# Check if the kernel module is currently loaded
lsmod | grep amneziawg

# Try loading the module manually
modprobe amneziawg

2. Module build failed or missing (Debian / Ubuntu)

On Debian, DKMS compilation fails if linux-headers-$(uname -r) and build tools are missing. To fix:

# Install kernel headers and build tools for the running kernel
apt-get update && apt-get install -y build-essential dkms linux-headers-$(uname -r)

# Reconfigure and recompile the DKMS module
dpkg-reconfigure amneziawg-dkms

# Load the compiled module into the kernel
modprobe amneziawg

# Verify
lsmod | grep amneziawg

3. Missing repository or packages

Debian (11 / 12 / 13):

apt-get update && apt-get install -y build-essential dkms linux-headers-$(uname -r)
mkdir -p /etc/apt/keyrings && curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x75C9DD72C799870E310542E24166F2C257290828" | gpg --dearmor --yes -o /etc/apt/keyrings/amnezia.gpg
echo "deb [signed-by=/etc/apt/keyrings/amnezia.gpg] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu noble main" > /etc/apt/sources.list.d/amnezia.list
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

Ubuntu (22.04 / 24.04 LTS):

add-apt-repository -y ppa:amnezia/ppa
apt-get update && apt-get install -y amneziawg-dkms amneziawg-tools
modprobe amneziawg

4. Check AmneziaWG tools

awg --version

5. DNS resolution error when using awg-quick manually

If awg-quick up awg0 fails with resolvconf: command not found on Debian:

apt-get install -y openresolv

Getting Help

• Documentation: https://puqvpncp.com/doc/
• Community: https://community.puqcloud.com
• Support: https://puqcloud.com/submitticket.php