How To Install WGDashboard on Ubuntu 24.04 LTS
Managing WireGuard VPN configurations through command-line interfaces can be time-consuming and error-prone, especially when dealing with multiple peers and complex network setups. WGDashboard provides an elegant solution by offering a web-based management interface that simplifies the entire process. This comprehensive guide walks through installing WGDashboard on Ubuntu 24.04 LTS, from initial system preparation to advanced configuration and security hardening. WGDashboard transforms WireGuard administration into an intuitive experience with features like real-time peer monitoring, QR code generation for mobile devices, and centralized configuration management. Whether managing a small home VPN or enterprise infrastructure, this tutorial provides everything needed for a successful deployment.
Understanding WGDashboard and WireGuard
What is WireGuard?
WireGuard represents the next generation of VPN technology, built on modern cryptographic principles that prioritize simplicity and performance. Unlike legacy VPN protocols that require thousands of lines of code, WireGuard’s lean codebase contains approximately 4,000 lines, making it easier to audit and significantly reducing potential security vulnerabilities. The protocol is integrated directly into the Linux kernel, eliminating overhead associated with userspace implementations and delivering speeds that often exceed traditional solutions like OpenVPN and IPSec.
The protocol employs state-of-the-art cryptography including Curve25519 for key exchange, ChaCha20 for symmetric encryption, Poly1305 for authentication, and BLAKE2s for hashing. WireGuard’s cross-platform compatibility extends across Linux, Windows, macOS, iOS, and Android, making it an ideal choice for heterogeneous network environments. Performance benchmarks consistently show WireGuard outperforming competitors in both throughput and latency, particularly on modern hardware with AES-NI support.
What is WGDashboard?
WGDashboard is an open-source web interface written in Python and Vue.js that brings graphical administration capabilities to WireGuard. The dashboard automatically discovers and displays existing WireGuard configurations stored in the /etc/wireguard directory, eliminating the need to manually import settings. Its intuitive interface provides comprehensive peer management, real-time connection status monitoring, configuration editing, and instant QR code generation for mobile client deployment.
Security features include built-in authentication mechanisms and optional TOTP (Time-based One-Time Password) two-factor authentication to protect administrative access. The project maintains active development on GitHub with a responsive community that addresses issues and implements feature requests. WGDashboard simplifies operations that would otherwise require extensive command-line knowledge, making WireGuard accessible to administrators of all skill levels while maintaining the protocol’s inherent security and performance advantages.
Prerequisites and System Requirements
Server Requirements
A successful WGDashboard deployment on Ubuntu 24.04 LTS requires modest hardware resources, making it suitable for both dedicated servers and virtual machines. Minimum specifications include a single CPU core, 1GB of RAM, and 10GB of storage space, though these requirements increase proportionally with the number of active peers. The system must have root or sudo user access for installing packages and modifying system configurations.
Network connectivity requirements include an active internet connection during installation for downloading packages and dependencies. For remote VPN access, the server needs either a static public IP address or dynamic DNS configuration to ensure clients can consistently reach the endpoint. Cloud providers like DigitalOcean, Vultr, and AWS offer pre-configured Ubuntu 24.04 LTS instances that work perfectly for this deployment.
Required Software and Dependencies
WGDashboard relies on several software components that must be present before installation begins. The WireGuard kernel module and associated tools form the foundation of the VPN infrastructure. Git version control system enables cloning the WGDashboard repository from GitHub. Python 3 serves as the runtime environment for the dashboard application, with pip managing Python package dependencies.
Network utilities provided by the net-tools package assist with interface configuration and troubleshooting. A properly configured firewall, either UFW (Uncomplicated Firewall) or iptables, protects the server while allowing necessary VPN traffic. These dependencies integrate seamlessly on Ubuntu 24.04 LTS, which includes most components in its default repositories.
Network Prerequisites
Network configuration plays a critical role in WireGuard functionality and requires opening specific ports through the server’s firewall. WireGuard typically listens on UDP port 51820, though this can be customized based on network requirements. WGDashboard’s web interface defaults to TCP port 10086, which must be accessible from administrator workstations.
IPv4 forwarding capability allows the server to route traffic between VPN clients and destination networks, a fundamental requirement for most VPN deployments. Understanding basic networking concepts including subnet masks, CIDR notation, and routing helps when configuring allowed IP ranges for peers. Firewall rules must permit both inbound VPN connections and forwarding of packets between network interfaces.
Pre-Installation Setup
System Update
Ensuring the Ubuntu 24.04 LTS system runs the latest packages prevents compatibility issues and closes known security vulnerabilities. Begin by refreshing the package repository index:
sudo apt updateThis command synchronizes package lists from Ubuntu’s repositories, making the system aware of available updates. Next, upgrade all installed packages to their latest versions:
sudo apt upgrade -yThe -y flag automatically confirms the upgrade without prompting for user input. Verify the Ubuntu version to confirm the system runs 24.04 LTS:
lsb_release -aIf the upgrade process installs kernel updates, reboot the server to load the new kernel before proceeding. A system restart ensures all services run with updated libraries and prevents potential conflicts during the WGDashboard installation process.
Installing WireGuard
WireGuard installation on Ubuntu 24.04 LTS has become straightforward since the protocol’s inclusion in the mainline Linux kernel. Install the WireGuard package using apt:
sudo apt install wireguard -yThis command installs both the kernel module and userspace tools required for WireGuard operation. Verify the installation succeeded by checking the WireGuard version:
wg --versionLoad the WireGuard kernel module explicitly to ensure it’s available:
sudo modprobe wireguardCreate the WireGuard configuration directory if it doesn’t exist:
sudo mkdir -p /etc/wireguard
sudo chmod 700 /etc/wireguardSetting restrictive permissions on this directory protects sensitive key material from unauthorized access. The WireGuard installation now stands ready for configuration through WGDashboard.
Installing Dependencies
WGDashboard requires additional software components that work together to provide its web-based interface. Install Git for cloning the repository:
sudo apt install git -yInstall net-tools for network diagnostics and interface management:
sudo apt install net-tools -yUbuntu 24.04 LTS typically includes Python 3 by default, but verify its presence and install pip:
sudo apt install python3 python3-pip -yConfirm successful installation of each component by checking their versions:
git --version
python3 --version
pip3 --versionThese dependencies enable WGDashboard to function properly, providing the development tools and runtime environment necessary for the application. With all prerequisites satisfied, the system is prepared for WGDashboard installation.
Installing WGDashboard
Method 1: Automated Installation (Recommended)
The automated installation method represents the most reliable approach for deploying WGDashboard on Ubuntu 24.04 LTS. Navigate to an appropriate installation directory where the application will reside:
cd /optThe /opt directory conventionally houses optional or third-party software on Linux systems. Clone the WGDashboard repository from GitHub:
sudo git clone https://github.com/WGDashboard/WGDashboard.gitThis command downloads the complete application source code, including installation scripts and dependencies. Change into the source directory:
cd WGDashboard/srcMake the installation script executable:
sudo chmod u+x wgd.shExecute the automated installer with superuser privileges:
sudo ./wgd.sh installThe installation script performs several critical tasks automatically. It creates a Python virtual environment to isolate WGDashboard’s dependencies from system packages, preventing potential conflicts. The installer downloads and installs required Python modules specified in the requirements.txt file. It configures a systemd service unit for managing WGDashboard as a system service, enabling automatic startup on boot.
During installation, the script may prompt for confirmation or display progress information as it installs dependencies. The process typically completes within a few minutes, depending on internet connection speed and system performance.
Setting Proper Permissions
WGDashboard requires specific permissions on the WireGuard configuration directory to read and modify configuration files. Set appropriate permissions:
sudo chmod -R 755 /etc/wireguardThis command grants read and execute permissions to all users while maintaining write access exclusively for the root user. The dashboard process runs with elevated privileges to access WireGuard configurations, making these permissions essential for proper functionality.
Security considerations require balancing accessibility with protection. While WGDashboard needs to read configurations, overly permissive settings could expose sensitive key material to unauthorized users. The 755 permission level provides appropriate access without compromising security on single-user systems.
Starting WGDashboard
With installation complete and permissions configured, start the WGDashboard service:
sudo ./wgd.sh startThe dashboard initializes and begins listening on the default port 10086. Verify the service is running properly:
sudo systemctl status wg-dashboardThis command displays the service status, including whether it’s active and any recent log messages. Access the web interface by opening a browser and navigating to:
http://your-server-ip:10086Replace your-server-ip with the actual IP address or hostname of the server. The login screen appears, requesting credentials to access the dashboard.
Default credentials use “admin” for both username and password. Change these immediately after first login to prevent unauthorized access. The dashboard’s welcome screen provides an overview of available features and detected WireGuard configurations.
Initial Configuration
First Login and Dashboard Overview
The WGDashboard web interface presents a clean, modern design that organizes functionality into logical sections. After authentication, the main dashboard displays an overview of all WireGuard configurations present in the /etc/wireguard directory. Each configuration appears as a card showing the interface name, current status (active or inactive), number of peers, and basic statistics.
Navigation menus provide access to key areas including configuration management, peer administration, and system settings. Real-time monitoring displays active connections, data transfer rates, and the last handshake time for each peer. The interface updates dynamically without requiring page refreshes, providing an efficient administrative experience.
Dashboard features include color-coded status indicators that show connection health at a glance. Green indicators represent active, healthy connections, while red highlights problems requiring attention. This visual feedback helps administrators quickly identify issues across multiple configurations and peers.
Changing Default Credentials
Security best practices demand changing default credentials immediately after deployment. Navigate to the Settings section using the main menu. Locate the account management area where username and password modifications are available.
Enter a strong, unique password that combines uppercase and lowercase letters, numbers, and special characters. WGDashboard stores passwords using bcrypt hashing, a computationally intensive algorithm that resists brute-force attacks. Update the username if desired, choosing something less predictable than “admin”.
Enable Two-Factor Authentication (TOTP) for an additional security layer. This feature requires a time-based one-time password from an authenticator app like Google Authenticator or Authy in addition to the regular password. Scan the provided QR code with the authenticator app, then verify the setup by entering a generated code.
Save all changes and test the new credentials by logging out and logging back in. Store credentials securely using a password manager to prevent lockout situations.
Configuring Dashboard Settings
WGDashboard’s behavior can be customized through the wg-dashboard.ini configuration file located in the installation directory. Key settings control network binding and security features.
The app_ip parameter determines which network interface the dashboard binds to. The default value of 0.0.0.0 allows connections from any interface, suitable for most deployments. Restricting this to a specific IP address enhances security by limiting access to a particular network.
The app_port setting controls which TCP port the web interface listens on. The default port 10086 can be changed to any available port, which may be necessary to avoid conflicts or comply with organizational standards.
The wg_conf_path parameter specifies where WGDashboard looks for WireGuard configuration files. The standard location is /etc/wireguard, though alternative paths can be configured if configurations are stored elsewhere.
Authentication requirements are controlled by the auth_req setting. This should remain enabled to prevent unauthorized access to the dashboard.
After modifying the configuration file, restart WGDashboard for changes to take effect:
sudo ./wgd.sh restartCreating and Managing WireGuard Configurations
Creating Your First Configuration
WGDashboard streamlines the process of creating new WireGuard configurations through its intuitive interface. Click the “Add Configuration” button to begin. The configuration wizard prompts for essential parameters including interface name, listen port, and address range.
Choose a descriptive name for the interface, typically following the wg0, wg1 naming convention. Select a UDP port for WireGuard to listen on, defaulting to 51820 but customizable if that port is already in use. Define the private network address range using CIDR notation, such as 10.0.0.1/24 for a small network.
The dashboard automatically generates cryptographic key pairs using WireGuard’s secure key generation functions. These keys form the foundation of the VPN’s security, with private keys never leaving the server and public keys shared with peers. Configure the server’s internal IP address within the chosen subnet, typically using the first available address like 10.0.0.1.
Additional advanced settings include DNS servers for clients, MTU (Maximum Transmission Unit) values, and persistent keepalive intervals. Save the configuration when all parameters are set. The dashboard creates the appropriate files in /etc/wireguard and makes the interface available for activation.
Adding Peers/Clients
Peer management represents one of WGDashboard’s most valuable features, simplifying client provisioning significantly. Access the peer management section within a configuration to add new clients. Click “Add Peer” to launch the peer creation wizard.
Assign each peer a descriptive name identifying the device or user, such as “John-iPhone” or “Office-Laptop”. Specify the allowed IP addresses for the peer, which defines what traffic routes through the tunnel. For full tunnel VPN access, use 0.0.0.0/0, which routes all traffic through WireGuard. For split-tunnel configurations, specify only the networks that should traverse the VPN.
WGDashboard automatically generates key pairs for each peer, ensuring cryptographic isolation between clients. The dashboard calculates the next available IP address within the configuration’s subnet, preventing address conflicts. Optional parameters include endpoint configuration for peer-to-peer connections and persistent keepalive settings for peers behind restrictive NAT.
Configure expiration dates for temporary access, ideal for guest users or time-limited connections. Data transfer limits can restrict bandwidth consumption per peer when managing shared infrastructure.
Generating Client Configurations
WGDashboard excels at distributing client configurations through multiple convenient methods. After creating a peer, the dashboard displays options for configuration distribution.
The built-in QR code generator creates scannable codes containing the complete client configuration. Mobile devices running the official WireGuard app can scan these codes to import settings instantly, eliminating manual entry. This proves particularly useful for iOS and Android deployments where typing configuration details is cumbersome.
Download peer configuration files as .conf files suitable for desktop and laptop clients. These text files contain all necessary parameters including private keys, endpoint addresses, and allowed IP ranges. Distribute configuration files securely through encrypted channels to protect key material during transit.
Test peer connectivity immediately after configuration by monitoring the dashboard’s real-time status display. Successful connections show active status with recent handshake timestamps. The data transfer counters increment as traffic flows through the tunnel, confirming proper operation.
Enabling IPv4 Forwarding and Firewall Configuration
Enable IP Forwarding
IPv4 forwarding allows the server to route packets between network interfaces, essential for VPN functionality. Without forwarding enabled, the server receives packets but cannot relay them to their destinations.
Edit the system’s sysctl configuration file:
sudo nano /etc/sysctl.confLocate the line containing net.ipv4.ip_forward=1 and remove the comment character if present. If the line doesn’t exist, add it to the file:
net.ipv4.ip_forward=1Save the file and exit the editor. Apply the changes immediately without rebooting:
sudo sysctl -pVerify forwarding is active by checking the kernel parameter:
cat /proc/sys/net/ipv4/ip_forwardA return value of 1 confirms IP forwarding is enabled. This change persists across reboots since it’s stored in sysctl.conf.
Configuring UFW Firewall
Proper firewall configuration balances security with accessibility, allowing legitimate VPN traffic while blocking unwanted connections. Ubuntu’s Uncomplicated Firewall (UFW) provides straightforward rule management.
Allow WireGuard’s UDP port through the firewall:
sudo ufw allow 51820/udpPermit access to the WGDashboard web interface:
sudo ufw allow 10086/tcpConsider restricting dashboard access to specific source IP addresses for enhanced security:
sudo ufw allow from 192.168.1.0/24 to any port 10086This rule limits access to clients on the 192.168.1.0/24 network, preventing internet-wide exposure.
Configure Network Address Translation (NAT) to allow VPN clients to access internet resources through the server. Edit UFW’s before rules:
sudo nano /etc/ufw/before.rulesAdd NAT rules at the top of the file, before the filter rules section:
*nat
:POSTROUTING ACCEPT [0:0]
-A POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE
COMMITReplace 10.0.0.0/24 with the WireGuard subnet and eth0 with the server’s internet-facing interface. Enable the firewall:
sudo ufw enableVerify all rules are active:
sudo ufw status verboseThe output should display both the WireGuard and dashboard port rules along with their status.
Setting Up Autostart on Boot
System administrators require services that automatically start after server reboots, ensuring VPN availability without manual intervention. WGDashboard integrates with systemd for robust service management.
Enable the WGDashboard service to start automatically:
sudo systemctl enable wg-dashboardThis command creates symbolic links in systemd’s startup directories, instructing the system to launch WGDashboard during the boot sequence.
Enable individual WireGuard interfaces at boot using wg-quick:
sudo systemctl enable wg-quick@wg0Replace wg0 with the actual interface name if using different identifiers. Multiple interfaces require separate enable commands for each configuration.
Test autostart functionality by rebooting the server:
sudo rebootAfter the system restarts, verify services started correctly:
sudo systemctl status wg-dashboard
sudo systemctl status wg-quick@wg0Both services should show “active (running)” status. Access the dashboard web interface to confirm full functionality.
Check service logs if autostart fails:
sudo journalctl -u wg-dashboard -n 50This displays the last 50 log entries for the WGDashboard service, revealing startup errors or configuration problems. Common issues include missing dependencies, permission problems, or configuration file syntax errors.
Security Best Practices
Securing WGDashboard and WireGuard infrastructure requires a multi-layered approach addressing authentication, network access, and system maintenance. Change default administrative credentials immediately after installation to prevent unauthorized access from automated scanning tools that target known defaults.
Enable TOTP two-factor authentication for dashboard access, adding a significant obstacle for attackers who might compromise passwords. Even if an attacker obtains the password, they cannot access the dashboard without the time-based token generated by the authenticator app.
Restrict dashboard access to specific IP addresses or configure it to only accept connections through the VPN itself. This creates a bootstrapping scenario where administrators must first connect to the VPN before managing it, but provides robust protection against internet-based attacks.
Use strong, cryptographically secure keys for all WireGuard peers. WireGuard’s automatic key generation produces appropriate entropy, but administrators should rotate keys periodically for long-lived connections. Document key rotation schedules and procedures for systematic security maintenance.
Regular system updates close security vulnerabilities in both WGDashboard and underlying system components. Configure automatic security updates for Ubuntu packages while manually updating WGDashboard when new releases appear.
Implement fail2ban to protect against brute-force attacks targeting the dashboard login page. This intrusion prevention system automatically bans IP addresses that generate excessive failed login attempts. Configure appropriate thresholds balancing security with usability to avoid locking out legitimate administrators who mistype passwords.
Maintain comprehensive firewall rules limiting exposed ports to only those required for VPN and dashboard operation. Regularly audit firewall configurations to ensure rules remain appropriate as network requirements evolve.
Back up WireGuard configurations and WGDashboard settings regularly to prevent data loss from hardware failures or accidental deletions. Store backups securely since they contain sensitive key material that could compromise the VPN if exposed.
Monitor dashboard access logs for suspicious activity including unusual login times, unfamiliar source IP addresses, or repeated failed authentication attempts. Establish baseline patterns for normal administrative activity to better identify anomalies warranting investigation.
Deploy HTTPS encryption for production environments by configuring a reverse proxy like Nginx or Apache in front of WGDashboard. This protects administrative credentials and configuration data from interception during transit across untrusted networks.
Troubleshooting Common Issues
Dashboard Won’t Start
WGDashboard startup failures typically stem from dependency problems or configuration conflicts. Check that all Python dependencies installed correctly by reviewing the installation log. Navigate to the installation directory and verify the virtual environment exists:
cd /opt/WGDashboard/src
ls -la venv/Reinstall dependencies if the virtual environment appears corrupted:
sudo ./venv/bin/python3 -m pip install -r requirements.txtThis command forces reinstallation of all required Python packages. Review error logs in the ./log/ directory for specific failure messages:
sudo tail -f ./log/error.logPort conflicts prevent startup if another service already listens on port 10086. Identify the conflicting process:
sudo netstat -tlnp | grep 10086Either stop the conflicting service or change WGDashboard’s port in the configuration file.
WireGuard Interface Issues
WireGuard interface problems often relate to kernel module availability or configuration syntax errors. Verify the WireGuard kernel module is loaded:
lsmod | grep wireguardLoad the module manually if absent:
sudo modprobe wireguardCheck configuration file syntax using WireGuard’s built-in validation:
sudo wg showconf wg0This command parses the configuration and displays any syntax errors. Examine file permissions on the /etc/wireguard directory:
ls -la /etc/wireguard/Configuration files should be owned by root with restrictive permissions preventing unauthorized access. Review system logs for WireGuard-specific error messages:
sudo dmesg | grep wireguardKernel log messages often reveal module loading failures or configuration problems.
Peers Cannot Connect
Connectivity issues between peers and the server require systematic troubleshooting across multiple layers. Verify the firewall allows UDP traffic on WireGuard’s listen port:
sudo ufw status | grep 51820Add the rule if missing using the commands from the firewall configuration section. Confirm IP forwarding is active:
cat /proc/sys/net/ipv4/ip_forwardA value of 0 indicates forwarding is disabled, requiring the configuration steps described earlier.
Compare peer configurations against server settings to ensure parameters match. The peer’s endpoint must specify the correct server IP address and port. Allowed IPs on both sides must permit the desired traffic patterns.
Test basic connectivity using ping from the client after establishing the VPN connection:
ping 10.0.0.1Success confirms the tunnel is operational while failures indicate routing or firewall issues. Use traceroute to identify where packets stop:
traceroute 10.0.0.1Review peer allowed IPs configuration in the dashboard to ensure they include necessary networks. Overly restrictive allowed IPs prevent traffic from traversing the tunnel even when properly configured elsewhere.
Check NAT and routing rules are correctly configured for the WireGuard subnet. Missing masquerade rules prevent VPN clients from accessing internet resources through the server.
Advanced Configuration Tips
Experienced administrators can enhance WGDashboard deployments through advanced configurations addressing specific needs. Changing the default dashboard port improves security by obscuring the service from automated scanners:
sudo nano /opt/WGDashboard/src/wg-dashboard.iniModify the app_port value to an uncommon port number outside standard service ranges.
Setting up a reverse proxy with Nginx provides HTTPS encryption and additional security features. Configure Nginx to terminate SSL connections and proxy requests to WGDashboard’s local port:
server {
listen 443 ssl;
server_name vpn.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:10086;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}This configuration secures dashboard access with TLS encryption. Configure multiple WireGuard interfaces for segregating different user populations or network segments. Each configuration appears independently in the dashboard with separate peer management.
WGDashboard automatically detects and manages existing WireGuard setups, making it useful for retrofitting graphical management onto command-line configured deployments. Simply ensure configuration files exist in /etc/wireguard with proper permissions and restart the dashboard.
Implement automatic peer cleanup by regularly auditing inactive connections and removing obsolete peers. This prevents configuration bloat and simplifies ongoing management. Integrate WGDashboard with external monitoring systems by exposing metrics through custom scripts or API endpoints.
Maintenance and Updates
Maintaining WGDashboard ensures continued security and access to new features released by the development team. Check for updates by visiting the GitHub repository or subscribing to release notifications.
Update WGDashboard using the built-in update mechanism:
cd /opt/WGDashboard/src
sudo ./wgd.sh updateThe update script pulls the latest code from GitHub and reinstalls dependencies as needed. Back up configurations before updating to protect against unexpected issues:
sudo cp -r /etc/wireguard /etc/wireguard.backup
sudo cp wg-dashboard.ini wg-dashboard.ini.backupThese backups enable quick recovery if updates introduce problems. Monitor dashboard logs regularly for errors and performance indicators:
sudo tail -f /opt/WGDashboard/src/log/access.logAccess logs reveal usage patterns and potential security concerns. Conduct periodic security audits reviewing peer access, removing departed users, and verifying key rotation schedules.
Clean up inactive peers and archived logs to prevent excessive disk usage over time. Establish maintenance windows for updates and configuration changes to minimize disruption to VPN users.
Congratulations! You have successfully installed WGDashboard. Thanks for using this tutorial for installing WGDashboard GUI management of WireGuard VPN servers on your Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official WGDashboard website.
