How To Install WGDashboard on Fedora 42
Managing WireGuard VPN configurations through command-line interfaces can become cumbersome, especially when handling multiple peers and configurations. WGDashboard offers an elegant solution—a modern, web-based management interface that simplifies WireGuard administration while providing real-time monitoring capabilities. This comprehensive guide walks through installing and configuring WGDashboard on Fedora 42, transforming complex VPN management into an intuitive, streamlined process.
WGDashboard stands out with its automatic configuration detection, built-in two-factor authentication, QR code generation for mobile devices, and multi-language support. The dashboard provides visual feedback on peer connections, data transfer statistics, and configuration health—features that make it invaluable for both novice users and experienced system administrators managing enterprise-scale VPN deployments.
Fedora 42 provides an excellent platform for hosting WGDashboard due to its cutting-edge kernel support, robust security features, and streamlined package management. The combination of WireGuard’s modern cryptographic protocols with WGDashboard’s user-friendly interface creates a powerful VPN management solution that rivals commercial alternatives.
Understanding WGDashboard and WireGuard
What is WireGuard?
WireGuard represents a paradigm shift in VPN technology. Unlike legacy protocols that rely on bloated codebases with thousands of lines of code, WireGuard maintains approximately 4,000 lines of easily auditable code. This lean design philosophy reduces attack surfaces while improving performance and security.
The protocol leverages state-of-the-art cryptographic primitives including Curve25519 for key exchange, ChaCha20 for encryption, Poly1305 for authentication, BLAKE2s for hashing, and SipHash24 for hashtable keys. These algorithms provide military-grade security while maintaining exceptional performance across diverse hardware platforms.
WireGuard operates at the network layer, creating a virtual network interface that handles encrypted tunneling transparently. Cross-platform compatibility ensures seamless deployment across Linux, Windows, macOS, iOS, and Android devices. Connection speeds often exceed traditional VPN solutions like OpenVPN or IPSec, with significantly reduced latency and improved throughput.
What is WGDashboard?
WGDashboard is an open-source web management interface written in Python and Vue.js that transforms WireGuard configuration management from a terminal-based chore into a visual, intuitive experience. The application automatically discovers existing WireGuard configurations on the system, eliminating the need to recreate established setups.
Core features include comprehensive peer management, real-time connection status monitoring, automatic QR code generation for mobile device onboarding, and integrated authentication with TOTP two-factor authentication support. The dashboard displays live statistics including handshake timestamps, data transfer counters, and peer endpoint information—all updated dynamically without page refreshes.
The project maintains active development on GitHub with a growing community contributing features, translations, and bug fixes. Regular updates introduce new capabilities while maintaining backward compatibility with existing installations.
Prerequisites and System Requirements
Server Requirements
A minimal Fedora 42 server with one CPU core, 1GB RAM, and 10GB storage suffices for small deployments managing fewer than 10 concurrent peers. Production environments handling 50+ simultaneous connections benefit from 2+ CPU cores and 2GB+ RAM to maintain responsive performance.
Root access or sudo privileges are essential for installing system packages, modifying network configurations, and managing systemd services. An active internet connection enables package downloads and repository updates.
Static IP addressing or Dynamic DNS (DDNS) configuration ensures clients can reliably connect to the VPN server. Without consistent addressing, mobile peers lose connectivity when the server IP changes.
Required Software and Dependencies
WireGuard kernel module and tools form the foundation of the VPN infrastructure. Fedora 42 includes WireGuard support in the mainline kernel, simplifying installation compared to older distributions requiring DKMS modules.
Git version control enables cloning the WGDashboard repository from GitHub. Python 3 and pip package manager are mandatory for installing WGDashboard’s Python dependencies. Network utilities like net-tools provide diagnostic capabilities for troubleshooting connectivity issues.
Firewalld manages Fedora’s firewall rules, controlling which ports accept incoming connections and configuring Network Address Translation (NAT) for routing VPN traffic.
Network Prerequisites
WireGuard listens on UDP port 51820 by default, though administrators can select alternative ports. The WGDashboard web interface defaults to TCP port 10086, accessible through web browsers.
IPv4 forwarding capability allows the server to route packets between the VPN network and external networks. Understanding CIDR notation and subnet masks proves essential when designing private network address spaces.
Firewall rules must permit both WireGuard VPN traffic and web interface connections while blocking unauthorized access attempts. Strategic rule configuration balances accessibility with security.
Pre-Installation Setup on Fedora 42
System Update
Begin by updating the package repository cache and upgrading all installed packages to their latest versions:
sudo dnf update -yThis command downloads package metadata from configured repositories and upgrades outdated software. The -y flag automatically confirms installation prompts.
Verify the Fedora version to ensure compatibility:
cat /etc/fedora-releaseThe output should confirm Fedora 42. Reboot the system if kernel updates were installed to activate new kernel modules:
sudo rebootInstalling WireGuard on Fedora 42
Install WireGuard tools from Fedora’s official repositories:
sudo dnf install wireguard-tools -yThis package includes wg for configuration management and wg-quick for interface startup/shutdown operations.
Verify successful installation:
wg --version
which wg-quickThe first command displays WireGuard version information. The second confirms wg-quick installation path, typically /usr/bin/wg-quick.
Load the WireGuard kernel module:
sudo modprobe wireguardConfirm module loading:
lsmod | grep wireguardSuccessful output displays the module name and memory usage statistics.
Create the WireGuard configuration directory with restrictive permissions:
sudo mkdir -p /etc/wireguard
sudo chmod 700 /etc/wireguardThe 700 permission grants read, write, and execute access exclusively to root, protecting sensitive cryptographic keys from unauthorized access.
Installing Required Dependencies
Install Git for repository cloning:
sudo dnf install git -yInstall network diagnostic tools:
sudo dnf install net-tools -yThese utilities include ifconfig, netstat, and route for network troubleshooting.
Install Python 3, pip, and virtual environment support:
sudo dnf install python3 python3-pip python3-virtualenv -yVerify installations:
git --version
python3 --version
pip3 --versionEach command should return version information confirming successful installation.
Installing WGDashboard on Fedora 42
Method 1: Automated Installation (Recommended)
The automated installation script handles dependency resolution, virtual environment creation, and systemd service configuration automatically.
Navigate to the installation directory:
cd /optClone the WGDashboard repository:
sudo git clone https://github.com/WGDashboard/WGDashboard.gitThis downloads the latest stable release to /opt/WGDashboard. Change to the source directory:
cd WGDashboard/srcMake the installation script executable:
sudo chmod u+x wgd.shExecute the installation script:
sudo ./wgd.sh installThe installer performs several operations: creates a Python virtual environment isolated from system packages, installs required Python libraries from requirements.txt, generates default configuration files, and registers a systemd service for automatic startup.
Installation typically completes within 2-5 minutes depending on network speed. The script displays progress indicators and confirms successful completion.
Method 2: Manual Installation
Manual installation provides greater control over installation paths and configuration parameters, ideal for custom deployments or containerized environments.
Clone the repository to a custom location:
sudo git clone https://github.com/WGDashboard/WGDashboard.git /home/username/wgdashboard
cd /home/username/wgdashboard/srcCreate a Python virtual environment:
python3 -m venv ./venvActivate the virtual environment:
source venv/bin/activateThe command prompt changes to indicate virtual environment activation, typically displaying (venv) as a prefix.
Install Python dependencies:
pip install -r requirements.txtThis installs Flask web framework, Gunicorn WSGI server, bcrypt password hashing library, and additional dependencies.
Setting Proper Permissions
Configure directory permissions to balance security with functionality:
sudo chmod -R 755 /etc/wireguardThe 755 permission allows the owner full access while granting read and execute permissions to other users. WGDashboard requires read access to WireGuard configuration files.
Starting WGDashboard
Launch the dashboard using the control script:
sudo ./wgd.sh startVerify service status:
sudo systemctl status wg-dashboardActive status indicates successful startup. The output displays process ID, memory usage, and recent log entries.
Access the web interface by navigating to http://your-server-ip:10086 in a web browser. Replace your-server-ip with the server’s actual IP address. Default credentials are username admin and password admin.
Initial WGDashboard Configuration
First Login and Dashboard Overview
Enter default credentials at the login screen. The dashboard loads displaying the main interface with several distinct sections.
Configuration cards occupy the central area, representing each WireGuard interface detected on the system. Status indicators use color coding—green for active configurations, red for stopped interfaces, and gray for disabled configurations.
The sidebar provides navigation to Settings, Peer Management, and Configuration sections. Real-time monitoring updates display current connection counts, data transfer totals, and system resource utilization.
Changing Default Credentials
Navigate to the Settings section via the sidebar menu. Locate the Account Settings panel containing username and password fields.
Update the username to a unique identifier not easily guessed. Create a strong password incorporating uppercase letters, lowercase letters, numbers, and special characters. Minimum length should exceed 16 characters for optimal security.
WGDashboard uses bcrypt hashing to store passwords securely. This algorithm applies salting and multiple hashing rounds, making rainbow table attacks computationally infeasible.
Enable TOTP two-factor authentication by clicking the “Enable 2FA” button. A QR code appears for scanning with authenticator applications like Google Authenticator, Authy, Microsoft Authenticator, or FreeOTP.
Scan the QR code with the mobile authenticator app, which generates six-digit time-based codes refreshing every 30 seconds. Enter a generated code to confirm 2FA activation. Store backup codes securely in case primary authenticator access is lost.
Test new credentials by logging out and authenticating with the updated username, password, and 2FA code. This verification prevents lockout from configuration errors.
Configuring Dashboard Settings
Edit the main configuration file:
sudo nano /opt/WGDashboard/src/wg-dashboard.iniKey configuration parameters include:
app_ip: Network interface binding address. Use 0.0.0.0 for all interfaces or specify a particular IP for restricted access.
app_port: TCP port for web interface. Default 10086 can be changed to avoid port conflicts or improve security through obscurity.
wg_conf_path: WireGuard configuration directory path, typically /etc/wireguard.
auth_req: Boolean controlling authentication requirement. Always leave enabled (true) for production environments.
Additional settings control dashboard themes, language preferences, session timeouts, and logging verbosity. Restart the dashboard to apply changes:
sudo ./wgd.sh restartCreating WireGuard Configurations
Creating Your First Configuration
Click the “Add Configuration” button in the dashboard interface. The configuration wizard launches, prompting for essential parameters.
Interface Name: Enter a descriptive identifier like wg0 for the first configuration or wg-vpn for clarity. Interface names must be unique.
Listen Port: Specify UDP port for WireGuard connections. Default 51820 works for most deployments. Multiple configurations require unique ports.
Address Range: Define the private network using CIDR notation. Common choices include 10.0.0.1/24 for 254 usable addresses or 10.8.0.1/24 for alternative addressing. Avoid overlaps with existing local networks.
The dashboard automatically generates cryptographic key pairs using Curve25519 elliptic curve cryptography. Private keys remain on the server, never transmitted to clients.
Server Internal IP: Specify the server’s address within the VPN network, typically the first usable IP in the defined range (e.g., 10.0.0.1 for a 10.0.0.0/24 network).
Advanced settings include:
DNS Servers: Specify DNS resolvers for client queries. Options include public DNS (1.1.1.1, 8.8.8.8), local resolvers, or the VPN server itself if running a DNS service.
MTU (Maximum Transmission Unit): Default 1420 accommodates most networks. Lower values (1280-1380) may improve performance on networks with restrictive MTU limits.
Persistent Keepalive: Interval in seconds for NAT traversal packets. Set to 25 for mobile clients behind NAT to maintain connection stability.
Save the configuration. WGDashboard creates the configuration file in /etc/wireguard/ with appropriate permissions and displays it in the configuration list.
Adding Peers/Clients
Select a configuration card and click “Add Peer” to launch the peer creation wizard.
Peer Name: Assign descriptive identifiers like “John-iPhone” or “Office-Laptop” for easy identification in logs and dashboards.
Allowed IPs: Define which traffic routes through the VPN tunnel. 0.0.0.0/0, ::/0 creates a full tunnel routing all IPv4 and IPv6 traffic through the VPN—ideal for privacy and security. Specific subnets like 10.0.0.0/8 enable split-tunneling, routing only internal network traffic through the VPN while sending internet traffic direct.
The dashboard generates unique cryptographic key pairs for each peer automatically. Public keys are stored in the server configuration while private keys are included in downloadable client configurations.
IP Address Allocation: WGDashboard assigns sequential IP addresses from the configuration’s address range. Manual override is possible for specific addressing requirements. The dashboard prevents IP conflicts by tracking allocated addresses.
Optional peer settings:
Endpoint Configuration: Specify if the peer initiates connections or acts as a listener. Most client peers use default settings.
Persistent Keepalive: Enable for mobile clients or peers behind NAT routers. 25-second intervals work well for most scenarios.
Expiration Dates: Set automatic peer deactivation dates for temporary access grants. Useful for guest access or time-limited deployments.
Data Limits: Configure maximum data transfer thresholds. Peers exceeding limits trigger automatic disconnection.
Generating and Distributing Client Configurations
WGDashboard includes a built-in QR code generator streamlining mobile device onboarding. Click the QR code icon next to a peer listing to display an encoded configuration.
Open the official WireGuard application on iOS or Android devices. Tap “Add Tunnel” and select “Create from QR code.” Scan the displayed code with the device camera. The app imports the configuration automatically, ready for immediate activation.
Desktop and laptop clients require configuration files. Click the download icon to retrieve the .conf file containing the peer’s complete configuration including private keys, server public key, endpoint address, allowed IPs, and DNS settings.
Configuration files contain sensitive cryptographic material. Distribute using secure channels—encrypted email, secure messaging platforms, or password-protected archives. Never transmit configuration files over unencrypted channels like plain email or instant messaging.
Test peer connectivity through the dashboard’s monitoring panel. Active connections display green status indicators with recent handshake timestamps. The “Latest Handshake” column updates when clients successfully establish connections.
Monitor real-time data transfer counters showing received and transmitted bytes for each peer. Sudden traffic spikes may indicate misconfiguration or unauthorized usage requiring investigation.
Enabling IPv4 Forwarding and Firewall Configuration
Enable IP Forwarding on Fedora 42
IP forwarding allows the server to route packets between the VPN network and external networks—essential for internet access through the VPN tunnel.
Create a sysctl configuration file:
sudo nano /etc/sysctl.d/99-custom.confAdd the following line:
net.ipv4.ip_forward=1Save and exit the editor. Apply changes immediately:
sudo sysctl -p /etc/sysctl.d/99-custom.confVerify forwarding activation:
cat /proc/sys/net/ipv4/ip_forwardOutput of 1 confirms successful activation. A 0 value indicates forwarding remains disabled, requiring configuration review.
Configuring Firewalld
Start and enable the firewalld service:
sudo systemctl start firewalld
sudo systemctl enable firewalldAllow WireGuard UDP traffic:
sudo firewall-cmd --zone=public --add-port=51820/udp --permanentThe --permanent flag ensures the rule persists across reboots.
Allow WGDashboard web interface access:
sudo firewall-cmd --zone=public --add-port=10086/tcp --permanentFor enhanced security, restrict dashboard access to specific IP ranges:
sudo firewall-cmd --zone=public --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="10086" protocol="tcp" accept' --permanentThis rule limits access to devices on the 192.168.1.0/24 subnet. Adjust the subnet to match trusted networks.
Configure Network Address Translation (NAT) masquerading for VPN traffic:
sudo firewall-cmd --zone=public --add-masquerade --permanentMasquerading rewrites source IP addresses of VPN packets to the server’s external IP, enabling bidirectional communication.
Reload firewall rules to activate changes:
sudo firewall-cmd --reloadVerify active rules:
sudo firewall-cmd --list-allThe output displays configured ports, services, and masquerading status.
Setting Up Autostart on Boot
Enable automatic WGDashboard startup:
sudo systemctl enable wg-dashboardThis creates systemd symlinks ensuring the dashboard launches during system boot.
Enable WireGuard interface autostart:
sudo systemctl enable wg-quick@wg0Replace wg0 with the actual interface name. Multiple interfaces require individual enable commands.
Alternative configuration through the dashboard settings file:
sudo nano /opt/WGDashboard/src/wg-dashboard.iniLocate the [WireGuardConfiguration] section and set autostart parameters for each interface. Multiple interfaces can be comma-separated.
Test autostart functionality by rebooting:
sudo rebootAfter restart, verify services:
sudo systemctl status wg-dashboard
sudo systemctl status wg-quick@wg0Both services should display active status. Check service logs for startup issues:
sudo journalctl -u wg-dashboard -n 50
sudo journalctl -u wg-quick@wg0 -n 50These commands display the most recent 50 log entries for each service.
Security Best Practices
Change default administrative credentials immediately after installation. Compromised credentials grant attackers full VPN management access.
Enable TOTP two-factor authentication on all administrator accounts. This security layer prevents unauthorized access even if passwords are compromised.
Restrict dashboard access to specific IP addresses or configure VPN-only access requiring users to connect through the VPN before accessing the dashboard. This approach provides defense-in-depth protection.
Use cryptographically secure keys generated by WireGuard tools or WGDashboard. Never manually create keys or reuse keys across multiple peers. Implement key rotation schedules for long-term deployments, regenerating keys annually or after personnel changes.
Configure automatic security updates for Fedora:
sudo dnf install dnf-automatic -y
sudo systemctl enable --now dnf-automatic.timerThis service downloads and installs security updates automatically, reducing exposure to known vulnerabilities.
Implement fail2ban for brute-force protection:
sudo dnf install fail2ban -y
sudo systemctl enable --now fail2banConfigure fail2ban to monitor WGDashboard access logs and ban IPs exceeding failed authentication thresholds.
Maintain comprehensive firewall rules audited regularly. Remove unused rules and verify that only necessary ports accept external connections.
Regularly backup WireGuard configurations and WGDashboard settings:
sudo tar -czf wg-backup-$(date +%Y%m%d).tar.gz /etc/wireguard /opt/WGDashboard/src/wg-dashboard.iniStore backups securely, preferably encrypted and off-site. Backup files contain sensitive cryptographic keys requiring protection equal to production systems.
Monitor dashboard access logs for suspicious activity. Unusual login times, geographic anomalies, or repeated failed authentication attempts warrant investigation.
Deploy HTTPS encryption using a reverse proxy like Nginx or Apache. HTTP transmits credentials and configuration data in plaintext, vulnerable to network eavesdropping.
Secure storage of backup files using encryption:
gpg --symmetric --cipher-algo AES256 wg-backup-20251008.tar.gzThis creates an encrypted archive requiring a passphrase for decryption.
Troubleshooting Common Issues
Dashboard Won’t Start
Check Python dependencies and virtual environment integrity:
cd /opt/WGDashboard/src
source venv/bin/activate
pip listMissing or outdated packages require reinstallation.
Review error logs:
sudo tail -f /opt/WGDashboard/src/log/error.logThe -f flag follows the log in real-time, displaying new entries as they occur. Look for Python tracebacks or dependency errors.
Reinstall dependencies if corrupted:
pip install --force-reinstall -r requirements.txtIdentify port conflicts:
sudo netstat -tlnp | grep 10086If another service occupies port 10086, either stop the conflicting service or change the dashboard port in wg-dashboard.ini.
WireGuard Interface Issues
Verify kernel module loading:
lsmod | grep wireguardAbsent output indicates the module isn’t loaded. Load manually:
sudo modprobe wireguardIf the command fails, kernel module installation may be incomplete. Reinstall WireGuard tools.
Validate configuration syntax:
sudo wg showconf wg0This command parses the configuration file and displays the current interface state. Syntax errors prevent interface activation.
Check file permissions:
ls -la /etc/wireguard/Configuration files require 600 permissions (read/write for owner only). Overly permissive permissions may prevent interface startup.
Review system logs:
sudo dmesg | grep wireguardKernel messages reveal low-level errors like cryptographic algorithm initialization failures or network device creation problems.
Peers Cannot Connect
Verify firewall rules permit UDP traffic on the WireGuard listen port:
sudo firewall-cmd --list-all | grep 51820Missing rules require adding with the commands in the firewall configuration section.
Confirm IP forwarding activation:
cat /proc/sys/net/ipv4/ip_forwardA 0 value indicates forwarding is disabled, preventing VPN traffic routing.
Check peer configuration parameters match server expectations. Common mismatches include incorrect endpoint addresses, mismatched allowed IPs, or transposed public keys.
Test basic connectivity with ping from server to peer internal IP:
ping 10.0.0.2Successful replies confirm routing works. Timeout indicates network layer issues.
Review allowed IPs configuration. Overly restrictive settings block legitimate traffic. Full tunnel configurations require 0.0.0.0/0.
Verify NAT/masquerade rules:
sudo firewall-cmd --query-masqueradeOutput of yes confirms masquerading is active. no indicates missing configuration.
Advanced Configuration Tips
Change default dashboard port for security through obscurity:
sudo nano /opt/WGDashboard/src/wg-dashboard.iniModify app_port to a non-standard value like 8443 or 9999. Restart the dashboard to apply.
Set up reverse proxy with Nginx for HTTPS encryption. Install Nginx:
sudo dnf install nginx -yCreate a server block configuration:
sudo nano /etc/nginx/conf.d/wgdashboard.confSample configuration:
server {
listen 443 ssl http2;
server_name vpn.example.com;
ssl_certificate /etc/ssl/certs/vpn.example.com.crt;
ssl_certificate_key /etc/ssl/private/vpn.example.com.key;
location / {
proxy_pass http://127.0.0.1:10086;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}This configuration terminates SSL encryption at Nginx and proxies requests to WGDashboard running locally.
Configure multiple WireGuard interfaces for network segregation. Create distinct configurations for different user groups, departments, or security zones. Each interface requires unique listen ports and IP ranges.
Manage existing command-line WireGuard setups with WGDashboard. The dashboard automatically detects configurations in /etc/wireguard/ without requiring migration or recreation.
Implement automatic peer cleanup procedures. Periodically audit peer lists removing inactive entries:
wg show wg0 latest-handshakesThis command displays last handshake timestamp for each peer. Peers without recent handshakes may indicate abandoned configurations.
Configure custom DNS servers for peers directing queries to specific resolvers. Privacy-focused options include Quad9 (9.9.9.9), DNS.Watch (84.200.69.80), or self-hosted resolvers.
Set up split-tunnel configurations allowing specific traffic through the VPN while routing other traffic direct. Use allowed IPs like 10.0.0.0/8, 192.168.0.0/16 for private network access only.
Maintenance and Updates
Check for WGDashboard updates regularly on the GitHub repository. The project maintains an active development cycle with frequent enhancements and security patches.
Update using the built-in mechanism:
cd /opt/WGDashboard/src
sudo ./wgd.sh updateThis script pulls the latest changes from GitHub and updates dependencies automatically.
Backup configurations before updating:
sudo cp -r /etc/wireguard /root/wireguard-backup-$(date +%Y%m%d)
sudo cp /opt/WGDashboard/src/wg-dashboard.ini /root/wg-dashboard-backup-$(date +%Y%m%d).iniThese backups enable quick rollback if updates introduce issues.
Monitor dashboard logs regularly for errors or warnings:
sudo tail -f /opt/WGDashboard/src/log/access.logAccess logs track user authentication, configuration changes, and peer modifications.
Conduct periodic security audits reviewing user accounts, peer configurations, firewall rules, and access logs. Remove unnecessary accounts and revoke unused peer access.
Remove inactive peers to maintain clean configurations. Use the dashboard interface to delete peers without recent activity.
Establish maintenance windows for system updates and reboots. Schedule during low-usage periods minimizing disruption to active VPN connections.
Update Fedora system packages monthly:
sudo dnf update -yRegular updates patch security vulnerabilities and improve system stability.
Keep WireGuard tools updated. Fedora’s repositories provide current versions through standard update mechanisms.
Document configuration changes in a change log. Record modification dates, changed parameters, and rationale for changes. Documentation aids troubleshooting and maintains institutional knowledge.
Congratulations! You have successfully installed WGDashboard. Thanks for using this tutorial for installing the WGDashboard on your Fedora 42 Linux system. For additional or useful information, we recommend you check the official WGDashboard website.
