donaldzou/WGDashboard
1
1
Fork 0
mirror of https://github.com/donaldzou/WGDashboard.git synced 2024-09-20 07:16:25 +08:00
Code Issues Packages Projects Releases Wiki Activity
WGDashboard/README.md
Donald Zou 47efb644b7 Working on some updates
2024-08-14 22:45:36 -04:00

30 KiB
Raw Blame History

WGDashboard

WGDashboard

wakatime

Monitoring WireGuard is not convenient, need to login into server and type wg show. That's why this project is being created, to view all configurations and manage them in a easy way.

This project is not affiliate to the official WireGuard Project

📣 What's New: v4.0

  • 🎉 New Features

    • Updated dashboard design: Re-designed some of the section with more modern style and layout, the UI is faster and more responsive, it also uses less memory. But overall is still the same dashboard you're familiarized.
    • Docker Solution: We now have 2 docker solutions! Thanks to @DaanSelen & @shuricksumy for providing them. For more information, please see the Docker section below.
    • Peer Job Scheduler: Now you can schedule jobs for each peer to either restrict or delete the peer if the peer's total / upload / download data usage exceeded a limit, or you can set a specific datetime to restrict or delete the peer.
    • Share Peer's QR Code with Public Link: You can share a peer's QR code and .conf file without the need to loging in.
    • API Key for WGDashboard's REST API: You can now request all the api endpoint used in the dashboard. For more details please review the API Documentation below.
    • Logging: Dashboard will now log all activity on the dashboard and API requests.
    • Time-Based One-Time Password (TOTP): You can enable this function to add one more layer of security, and generate the TOTP with your choice of authenticator.
    • Designs
      • Real-time Graphs: You can view real-time data changes with graphs in each configuration.
      • Night mode: You know what that means, it avoids bugs ;)
    • Enforce Python Virtual Environment: I noticed newer Python version (3.12) does not allow to install packages globally, and plus I think is a good idea to use venv.

  • 🧐 Other Changes

    • Deprecated jQuery from the project, and migrated and rewrote the whole front-end with Vue.js. This allow the dashboard is future proofed, and potential cross server access with a desktop app.
    • Rewrote the backend into a REST API structure
    • Improved SQL query efficient
    • Removed all templates, except for index.html where it will load the Vue.js app.

  • 🥘 New Experimental Features

    • Cross-Server Access: Now you can access other servers that installed v4 of WGDashboard through API key.
    • Desktop App: Thanks to Cross-Server Access, you can now download an ElectronJS based desktop app of WGDashboard, and use that to access WGDashboard on different servers.

    • For more information, please scroll down to 🥘 Experimental Functions

I can't thank enough for all of you who wait for this release, and for those who are new to this project, welcome :) Also, huge thanks to who contributed to this major release: @bolgovrussia, @eduardorosabales, @Profik, @airgapper, @tokon2000, @bkeenke, @kontorskiy777, @bugsse, @Johnnykson, @DaanSelen, @shuricksumy and many others!

Table of Content

💡 Features

  • Automatically look for existing WireGuard configuration under /etc/wireguard
  • Easy to use interface, provided credential and TOTP protection to the dashboard
  • Manage peers and configuration
    • Add Peers or by bulk with auto-generated information
    • Edit peer information
    • Delete peers with ease
    • Restrict peers
    • Generate QR Code and .conf file for peers, share it through a public link
    • Schedule jobs to delete / restrict peer when conditions are met
  • View real time peer status
  • Testing tool: Ping and Traceroute to your peer

📝 Requirement

  • Recommend the following OS, tested by our beloved users:

    • Ubuntu 18.04.1 LTS, 20.04.1 LTS, 22.04.4 LTS, 24.02 LTS, Fedora 38 [@Me]
    • Debian GNU/Linux 10 (buster) [❤️ @robchez]
    • AlmaLinux 8.4 (Electric Cheetah) [❤️ @barry-smithjr]
    • CentOS 7 [❤️ @PrzemekSkw]

    If you have tested on other OS and it works perfectly please provide it to me in #31. Thank you!

  • WireGuard and WireGuard-Tools (wg-quick) are installed.

    Don't know how? Check this official documentation

  • Configuration files under /etc/wireguard, but please note the following sample

    [Interface]
...
SaveConfig = true
# Need to include this line to allow WireGuard Tool to save your configuration, 
# or if you just want it to monitor your WireGuard Interface and don't need to
# make any changes with the dashboard, you can set it to false.

[Peer]
PublicKey = abcd1234
AllowedIPs = 1.2.3.4/32
# Must have for each peer

  • Python 3.10 for v4.0+, Python 3.7 - 3.9 for v2.0 - v3.0.6.2

🛠 Install

  1. Download WGDashboard

    git clone -b v4.0 https://github.com/donaldzou/WGDashboard.git wgdashboard

  2. Open the WGDashboard folder

    cd wgdashboard/src

  3. Install WGDashboard

    sudo chmod u+x wgd.sh
sudo ./wgd.sh install

  4. Give read and execute permission to root of the WireGuard configuration folder, you can change the path if your configuration files are not stored in /etc/wireguard

    sudo chmod -R 755 /etc/wireguard

  5. Run WGDashboard

    sudo ./wgd.sh start

    Note:

    For pivpn user, please use sudo ./wgd.sh start to run if your current account does not have the permission to run wg show and wg-quick.

  6. Access dashboard

    Access your server with port 10086 (e.g. http://your_server_ip:10086), using username admin and password admin. See below how to change port and ip that the dashboard is running with.

🪜 Usage

Start/Stop/Restart WGDashboard

cd wgdashboard/src
-----------------------------
./wgd.sh start    # Start the dashboard in background
-----------------------------
./wgd.sh debug    # Start the dashboard in foreground (debug mode)
-----------------------------
./wgd.sh stop     # Stop the dashboard
-----------------------------
./wgd.sh restart  # Restart the dasboard

Autostart WGDashboard on boot (>= v2.2)

In the src folder, it contained a file called wg-dashboard.service, we can use this file to let our system to autostart the dashboard after reboot. The following guide has tested on Ubuntu, most Debian based OS might be the same, but some might not. Please don't hesitate to provide your system if you have tested the autostart on another system.

  1. Changing the directory to the dashboard's directory

    cd wgdashboard/src

  2. Get the full path of the dashboard's directory

    pwd
#Output: /root/wgdashboard/src

    For this example, the output is /root/wireguard-dashboard/src, your path might be different since it depends on where you downloaded the dashboard in the first place. Copy the the output to somewhere, we will need this in the next step.

  3. Edit the service file, the service file is located in wireguard-dashboard/src, you can use other editor you like, here will be using nano

    nano wg-dashboard.service

    You will see something like this:

    [Unit]
After=syslog.target network-online.target
Wants=wg-quick.target
ConditionPathIsDirectory=/etc/wireguard

[Service]
Type=forking
PIDFile=<absolute_path_of_wgdashboard_src>/gunicorn.pid
WorkingDirectory=<absolute_path_of_wgdashboard_src>
ExecStart=<absolute_path_of_wgdashboard_src>/wgd.sh start
ExecStop=<absolute_path_of_wgdashboard_src>/wgd.sh stop
ExecReload=<absolute_path_of_wgdashboard_src>/wgd.sh restart
TimeoutSec=120
PrivateTmp=yes
Restart=always

[Install]
WantedBy=multi-user.target

    Now, we need to replace all <absolute_path_of_wgdashboard_src> to the one you just copied from step 2. After doing this, the file will become something like this, your file might be different:

    Be aware that after the value of WorkingDirectory, it does not have a / (slash). And then save the file after you edited it

  4. Copy the service file to systemd folder

    $ sudo cp wg-dashboard.service /etc/systemd/system/wg-dashboard.service

    To make sure you copy the file successfully, you can use this command cat /etc/systemd/system/wg-dashboard.service to see if it will output the file you just edited.

  5. Enable the service

    $ sudo chmod 664 /etc/systemd/system/wg-dashboard.service
$ sudo systemctl daemon-reload
$ sudo systemctl enable wg-dashboard.service
$ sudo systemctl start wg-dashboard.service  # <-- To start the service

  6. Check if the service run correctly

    $ sudo systemctl status wg-dashboard.service

    And you should see something like this

     ● wg-dashboard.service
 Loaded: loaded (/etc/systemd/system/wg-dashboard.service; enabled; vendor preset: enabled)
 Active: active (running) since Wed 2024-08-14 22:21:47 EDT; 55s ago
 Process: 494968 ExecStart=/home/donaldzou/Wireguard-Dashboard/src/wgd.sh start (code=exited, status=0/SUCCESS)
 Main PID: 495005 (gunicorn)
 Tasks: 5 (limit: 4523)
 Memory: 36.8M
 CPU: 789ms
 CGroup: /system.slice/wg-dashboard.service
 ├─495005 /home/donaldzou/Wireguard-Dashboard/src/venv/bin/python3 ./venv/bin/gunicorn --config ./gunicorn.conf.py
 └─495007 /home/donaldzou/Wireguard-Dashboard/src/venv/bin/python3 ./venv/bin/gunicorn --config ./gunicorn.conf.py

 Aug 14 22:21:40 wg sudo[494978]:     root : PWD=/home/donaldzou/Wireguard-Dashboard/src ; USER=root ; COMMAND=./venv/bin/gunicorn --config ./gunicorn.conf.py
 Aug 14 22:21:40 wg sudo[494978]: pam_unix(sudo:session): session opened for user root(uid=0) by (uid=0)
 Aug 14 22:21:40 wg wgd.sh[494979]: [WGDashboard] WGDashboard w/ Gunicorn will be running on 0.0.0.0:10086
 Aug 14 22:21:40 wg wgd.sh[494979]: [WGDashboard] Access log file is at ./log/access_2024_08_14_22_21_40.log
 Aug 14 22:21:40 wg wgd.sh[494979]: [WGDashboard] Error log file is at ./log/error_2024_08_14_22_21_40.log
 Aug 14 22:21:40 wg sudo[494978]: pam_unix(sudo:session): session closed for user root
 Aug 14 22:21:45 wg wgd.sh[494968]: [WGDashboard] Checking if WGDashboard w/ Gunicorn started successfully
 Aug 14 22:21:47 wg wgd.sh[494968]: [WGDashboard] WGDashboard w/ Gunicorn started successfully
 Aug 14 22:21:47 wg wgd.sh[494968]: ------------------------------------------------------------
 Aug 14 22:21:47 wg systemd[1]: Started wg-dashboard.service.

    If you see Active: followed by active (running) since... then it means it run correctly.

  7. Stop/Start/Restart the service

    sudo systemctl stop wg-dashboard.service      # <-- To stop the service
sudo systemctl start wg-dashboard.service     # <-- To start the service
sudo systemctl restart wg-dashboard.service   # <-- To restart the service

  8. And now you can reboot your system, and use the command at step 6 to see if it will auto start after the reboot, or just simply access the dashboard through your browser. If you have any questions or problem, please report it in the issue page.

✂️ Dashboard Configuration

Dashboard Configuration file

Since version 2.0, WGDashboard will be using a configuration file called wg-dashboard.ini, (It will generate automatically after first time running the dashboard). More options will include in future versions, and for now it included the following configurations:

Description Default Edit Available
[Account] Configuration on account
username Dashboard login username admin Yes
password Password, will be hash with SHA256 admin hashed in SHA256 Yes
[Server] Configuration on dashboard
wg_conf_path The path of all the Wireguard configurations /etc/wireguard Yes
app_ip IP address the dashboard will run with 0.0.0.0 Yes
app_port Port the the dashboard will run with 10086 Yes
auth_req Does the dashboard need authentication to access, if auth_req = false , user will not be access the Setting tab due to security consideration. User can only edit the file directly in system. true No
version Dashboard Version v3.0.5 No
dashboard_refresh_interval How frequent the dashboard will refresh on the configuration page 60000ms Yes
dashboard_sort How configuration is sorting status Yes
[Peers] Default Settings on a new peer
peer_global_dns DNS Server 1.1.1.1 Yes
peer_endpoint_allowed_ip Endpoint Allowed IP 0.0.0.0/0 Yes
peer_display_mode How peer will display grid Yes
remote_endpoint Remote Endpoint (i.e where your peers will connect to) depends on your server's default network interface Yes
peer_mtu Maximum Transmit Unit 1420
peer_keep_alive Keep Alive 21 Yes

Generating QR code and peer configuration file (.conf)

Starting version 2.2, dashboard can now generate QR code and configuration file for each peer. Here is a template of what each QR code encoded with and the same content will be inside the file:

[Interface]
PrivateKey = QWERTYUIOPO234567890YUSDAKFH10E1B12JE129U21=
Address = 0.0.0.0/32
DNS = 1.1.1.1

[Peer]
PublicKey = QWERTYUIOPO234567890YUSDAKFH10E1B12JE129U21=
AllowedIPs = 0.0.0.0/0
Endpoint = 0.0.0.0:51820
Description Default Value Available in Peer setting
[Interface]
PrivateKey The private key of this peer Private key generated by WireGuard (wg genkey) or provided by user Yes
Address The allowed_ips of your peer N/A Yes
DNS The DNS server your peer will use 1.1.1.1 - Cloud flare DNS, you can change it when you adding the peer or in the peer setting. Yes
[Peer]
PublicKey The public key of your server N/A No
AllowedIPs IP ranges for which a peer will route traffic 0.0.0.0/0 - Indicated a default route to send all internet and VPN traffic through that peer. Yes
Endpoint Your wireguard server ip and port, the dashboard will search for your server's default interface's ip. <your server default interface ip>:<listen port> Yes

❓ How to update the dashboard?

Please note for users who are using v3 - v3.0.6 want to update to v4.0

  • Although theoretically updating through wgd.sh should work, but I still suggest you to update the dashboard manually.

Please note for users who are using v2.3.1 or below

  • For user who is using v2.3.1 or below, please notice that all data that stored in the current database will not transfer to the new database. This is hard decision to move from TinyDB to SQLite. But SQLite does provide a thread-safe access and TinyDB doesn't. I couldn't find a safe way to transfer the data, so you need to do them manually... Sorry about that 😔。 But I guess this would be a great start for future development 😎.

  1. Change your directory to wgdashboard

    cd wgdashboard/src

  2. Update the dashboard

    git pull https://github.com/donaldzou/WGDashboard.git v4.0 --force

  3. Install

    sudo ./wgd.sh install

Starting with v3.0, you can simply do sudo ./wgd.sh update !! (I hope)

🥘 Experimental Functions

Cross-Server Access

Starting with v4.0, you can access WGDashboards on other server through one WGDashboard with API Keys

🔍 Screenshot

Sign In Page

Index Image

Configuration

Add Peer

Edit Peer

Delete Peer

Dashboard Setting

Ping

Traceroute

⏰ Changelog

v3.0.0 - v3.0.6.2 - Jan 18, 2022

  • 🎉 New Features

    • Moved from TinyDB to SQLite: SQLite provide a better performance and loading speed when getting peers! Also avoided crashing the database due to race condition.
    • Added Gunicorn WSGI Server: This could provide more stable on handling HTTP request, and more flexibility in the future (such as HTTPS support). BIG THANKS to @pgalonza ❤️
    • Add Peers by Bulk: User can add peers by bulk, just simply set the amount and click add.
    • Delete Peers by Bulk: User can delete peers by bulk, without deleting peers one by one.
    • Download Peers in Zip: User can download all downloadable peers in a zip.
    • Added Pre-shared Key to peers: Now each peer can add with a pre-shared key to enhance security. Previously added peers can add the pre-shared key through the peer setting button.
    • Redirect Back to Previous Page: The dashboard will now redirect you back to your previous page if the current session got timed out and you need to sign in again.
    • Added Some 🥘 Experimental Functions

  • 🪚 Bug Fixed

  • 🧐 Other Changes

    • Key generating moved to front-end: No longer need to use the server's WireGuard to generate keys, thanks to the wireguard.js from the official repository!
    • Peer transfer calculation: each peer will now show all transfer amount (previously was only showing transfer amount from the last configuration start-up).
    • UI adjustment on running peers: peers will have a new style indicating that it is running.
    • wgd.sh finally can update itself: So now user could update the whole dashboard from wgd.sh, with the update command.
    • Minified JS and CSS files: Although only a small changes on the file size, but I think is still a good practice to save a bit of bandwidth ;)

And many other small changes for performance and bug fixes! 😆

v2.3.1 - Sep 8, 2021

  • Updated dashboard's name to WGDashboard!!

v2.3 - Sep 8, 2021

v2.2.1 - Aug 16, 2021

Bug Fixed:

  • Added support for full subnet on Allowed IP
  • Peer setting Save button

v2.2 - Aug 14, 2021

  • 🎉 New Features
    • Add new peers: Now you can add peers directly on dashboard, it will generate a pair of private key and public key. You can also set its DNS, endpoint allowed IPs. Both can set a default value in the setting page. [❤️ in #44]
    • QR Code: You can add the private key in peer setting of your existed peer to create a QR code. Or just create a new one, dashboard will now be able to auto generate a private key and public key ;) Don't worry, all keys will be generated on your machine, and will delete all key files after they got generated. [❤️ in #29]
    • Peer configuration file download: Same as QR code, you now can download the peer configuration file, so you don't need to manually input all the details on the peer machine! [❤️ in #40]
    • Search peers: You can now search peers by their name.
    • Autostart on boot: Added a tutorial on how to start the dashboard to on boot! Please read the tutorial below. [❤️ in #29]
    • Click to copy: You can now click and copy all peer's public key and configuration's public key.
    • ....
  • 🪚 Bug Fixed
    • When there are comments in the wireguard config file, will cause the dashboard to crash.
    • Used regex to search for config files.
  • 🧐 Other Changes
    • Moved all external CSS and JavaScript file to local hosting (Except Bootstrap Icon, due to large amount of SVG files).
    • Updated Python dependencies
      • Flask: v1.1.2 => v2.0.1
      • Jinja: v2.10.1 => v3.0.1
      • icmplib: v2.1.1 => v3.0.1
    • Updated CSS/JS dependencies
      • Bootstrap: v4.5.3 => v4.6.0
    • UI adjustment
      • Adjusted how peers will display in larger screens, used to be 1 row per peer, now is 3 peers in 1 row.

v2.1 - Jul 2, 2021

  • Added Ping and Traceroute tools!
  • Adjusted the calculation of data usage on each peers
  • Added refresh interval of the dashboard
  • Bug fixed when no configuration on fresh install (#23)
  • Fixed crash when too many peers (#22)

v2.0 - May 5, 2021

  • Added login function to dashboard
    • I'm not using the most ideal way to store the username and password, feel free to provide a better way to do this if you any good idea!
  • Added a config file to the dashboard
  • Dashboard config can be change within the Setting tab on the side bar
  • Adjusted UI
  • And much more!

v1.1.2 - Apr 3, 2021

  • Resolved issue #3.

v1.1.1 - Apr 2, 2021

  • Able to add a friendly name to each peer. Thanks #2 !

v1.0 - Dec 27, 2020

  • Added the function to remove peers

🛒 Dependencies

✨ Contributors

All Contributors

Thanks goes to these wonderful people (emoji key):


antonioag95
⚠️ 💻
tonjo
💻
Richard Newton
💻
David Long
💻
Markus Neubauer
💻

This project follows the all-contributors specification. Contributions of any kind welcome!