| Name | wg-wizard JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | https://github.com/ianlini/wg-wizard |
| Summary | Control all the WireGuard server and client configs in a centralized way. |
| upload_time | 2023-12-03 10:31:34 |
| maintainer | |
| docs_url | None |
| author | Ian Lin |
| requires_python | >=3.10,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
wg-wizard
=========
.. image:: https://github.com/ianlini/wg-wizard/actions/workflows/main.yml/badge.svg
:target: https://github.com/ianlini/wg-wizard/actions/workflows/main.yml
.. image:: https://github.com/ianlini/wg-wizard/actions/workflows/release.yml/badge.svg
:target: https://github.com/ianlini/wg-wizard/actions/workflows/release.yml
.. image:: https://img.shields.io/pypi/v/wg-wizard.svg
:target: https://pypi.org/project/wg-wizard/
.. image:: https://img.shields.io/pypi/l/wg-wizard.svg
:target: https://github.com/ianlini/wg-wizard/blob/master/LICENSE
.. image:: https://img.shields.io/github/stars/ianlini/wg-wizard.svg?style=social
:target: https://github.com/ianlini/wg-wizard
wg-wizard can help you generate the configs for WireGuard interactively,
and control all the server and client configs in a centralized way.
.. contents::
Why Do We Need wg-wizard
------------------------
When I was trying to build my own VPN, although WireGuard is quite simple,
it was still hard to make everything right at the first trial.
The 2 most common issues are incorrect iptables and unmatched server/client
configs.
Therefore, I built this tool to make these steps less error-prone by
centralizing all the configs as one simple wizard config and generating the
configs required by WireGuard when needed.
Besides, the tool also provides some simple interactive CLI tools to help
you create the wizard config easily, and it can generate QR code for you
to set up your smart phone easily.
Network Architecture
--------------------
Our default network architecture is one
`relay server <https://docs.sweeting.me/s/wireguard#Bounce-Server>`_
with multiple clients connecting to the VPN via the relay server.
We assume that most people need a network architecture like this.
If you want another architecture, you can still achieve some of them
using the advance configuration.
Prerequisite
------------
1. A server with Ubuntu, Debian or Raspberry Pi OS.
You can still use other Linux distributions,
but the following instructions might not be applicable.
2. `Install Docker <https://docs.docker.com/engine/install/>`_ on your relay server.
3. `Install Wireguard <https://www.wireguard.com/install/>`_ on your relay server.
Run the Docker Container
------------------------
We use Docker to disable the network to make the whole process secure.
.. code-block:: sh
# go to the directory you want to put the configs
# assuming ~/wg-wizard here
export WG_WIZARD_CONFIG='~/wg-wizard'
cd "${WG_WIZARD_CONFIG}"
docker run -it --rm --network=none --volume="$PWD":/workdir ianlini/wg-wizard
Initialize the Configuration
----------------------------
.. code-block:: sh
# inside the Docker container
wg-wizard init
Follow the instruction to create the config. Example output:
.. code-block::
Interface name for WireGuard [wg0]:
Interface.ListenPort of the relay server [51820]:
Interface.Address of the relay server [192.168.10.1/24]:
The default endpoint in clients' Peer.Endpoint configs (e.g., example.com:51820): example.com
If you want to allow the clients to access the internet via the relay server, you must provide the interface name you want to forward the internet traffic to. It's usually eth0 or wlan0. You can check it by executing `ip addr`. If you provide an interface name {interface}, the following rules will be added:
- iptables -A FORWARD -i %i -o {interface} -j ACCEPT
- iptables -A FORWARD -i {interface} -o %i -j ACCEPT
- iptables -t nat -A POSTROUTING -s {network} -o {interface} -j MASQUERADE
Interface name for connecting to the internet []: eth0
Do you want to allow the clients to connect with each other? If yes, a rule will be added: `iptables -A FORWARD -i %i -o %i -j ACCEPT` [Y/n]:
Do you want to allow the clients to connect to any IPs on the relay server? If no, only the IP of the WireGuard interface can be connected, that is, the following rules will be added:
- iptables -A INPUT -d {wg_server_interface_ip} -i %i -j ACCEPT
- iptables -A INPUT -i %i -j DROP
[y/N]:
[2022-10-12 18:41:34,190][INFO] wg_wizard.core: Writing config to /home/pi/pi-gateway/wireguard/wg0.yml
[2022-10-12 18:41:38,868][INFO] wg_wizard.core: Writing secret to /home/pi/pi-gateway/wireguard/wg0_secret.json
Normally, you can use the default values for almost all of the options.
If you allow the internet access or allow the clients to connect with each other,
you also need to `enable IP forwarding <https://www.digitalocean.com/community/tutorials/how-to-set-up-wireguard-on-ubuntu-20-04#step-4-adjusting-the-wireguard-server-s-network-configuration>`_.
For convenience, in the following instructions,
we assume that your WireGuard interface name is ``wg0``:
.. code-block:: sh
export WG_INTERFACE=wg0
Add a Peer
----------
.. code-block:: sh
# inside the Docker container
wg-wizard add-peer
Follow the instruction to create the peer config. Example output:
.. code-block::
Interface name for WireGuard [wg0]:
Name of the client: phone1
Peer.PersistentKeepalive of the client [25]:
Interface.Address of the client [192.168.10.2/32]:
Peer.AllowedIPs of the client [0.0.0.0/0, ::/0]:
[2022-10-04 16:40:01,337][INFO] wg_wizard.core: Writing config to /workdir/wg0.yml
[2022-10-04 16:40:01,358][INFO] wg_wizard.core: Writing secret to /workdir/wg0_secret.json
[2022-10-04 16:40:01,362][INFO] wg_wizard.cli: Client's wg-quick config QR Code:
...
Normally, you can use the default values for almost all of the options.
In the end, there will be a QR Code generated.
You can now use your `WireGuard app <https://www.wireguard.com/install/>`_
on your phone to scan the QR Code to import the config.
If your client doesn't support QR Code, you can use another command to generate the text:
.. code-block:: sh
wg-wizard export-client-config --interface "${WG_INTERFACE}" --name phone1 --no-qrcode
Set Up the WireGuard Server
---------------------------
Preparing:
.. code-block:: sh
# on your relay server (outside the Docker container)
cd "${WG_WIZARD_CONFIG}"
export WG_INTERFACE=wg0 # replace wg0 with your interface name
(umask 077; sudo mkdir /etc/wireguard/)
Exporting server config:
.. code-block:: sh
docker run --rm --network=none --volume="$PWD":/workdir ianlini/wg-wizard \
wg-wizard export-server-config -i "${WG_INTERFACE}" \
| sudo cp --backup /dev/stdin "/etc/wireguard/${WG_INTERFACE}.conf"
If you haven't enabled the service:
.. code-block:: sh
# start the WireGuard server
sudo systemctl enable "wg-quick@${WG_INTERFACE}.service"
sudo systemctl start "wg-quick@${WG_INTERFACE}.service"
Now you can turn on the WireGuard tunnel on your client (phone1),
and it should work.
If the service is already running, you can check the config diff first:
.. code-block:: sh
sudo diff "/etc/wireguard/${WG_INTERFACE}.conf~" "/etc/wireguard/${WG_INTERFACE}.conf"
After confirming the changes, there are 2 ways to apply them.
1. If you are not changing the wg-quick specific interface configs
(e.g., Address, DNS, MTU, Table, PreUp, PostUp, PreDown,
PostDown and SaveConfig),
you can reload the config without stopping the server:
.. code-block:: sh
sudo systemctl reload "wg-quick@${WG_INTERFACE}.service"
2. Otherwise, you should restart the server:
.. code-block:: sh
sudo systemctl restart "wg-quick@${WG_INTERFACE}.service"
Troubleshooting
---------------
Read the service log:
.. code-block:: sh
journalctl -u "wg-quick@${WG_INTERFACE}.service" -f -n 1000
Enable the kernel log:
.. code-block:: sh
sudo modprobe wireguard
echo module wireguard +p | sudo tee /sys/kernel/debug/dynamic_debug/control
Read the kernel log:
.. code-block:: sh
journalctl -k -f -n 1000 | grep wireguard
Debug iptables:
.. code-block:: sh
# trace the ICMP packets from a WireGuard client
sudo iptables -t raw -A PREROUTING -i "${WG_INTERFACE}" -p icmp -j TRACE
# trace the incoming ICMP packets from the internet to a WireGuard client
sudo iptables -t mangle -A FORWARD -d 192.168.10.0/24 -p icmp -j TRACE
.. warning::
Debugging iptables requires much more knowledge,
or you might generate large logs,
or even break the network of the whole machine.
However, it is highly possible that the generated configs don't work out-of-the-box.
It is the hard part when developing this tool because people will have different existing rules.
If you have a bad luck, you might need to spend some time understanding
the relationship between iptables and WireGuard.
Build the Docker Image from Scratch
-----------------------------------
TODO
.. code-block:: sh
git clone ...
cd ...
docker build . -t ianlini/wg-wizard
References
----------
- `Some Unofficial WireGuard Documentation <https://docs.sweeting.me/s/wireguard>`_
- `How To Set Up WireGuard on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-set-up-wireguard-on-ubuntu-20-04>`_
- `How To Set Up WireGuard Firewall Rules in Linux <https://www.cyberciti.biz/faq/how-to-set-up-wireguard-firewall-rules-in-linux/>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/ianlini/wg-wizard",
"name": "wg-wizard",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Ian Lin",
"author_email": "you@example.com",
"download_url": "https://files.pythonhosted.org/packages/90/b5/1991ee531fc26acd2d58bd69ed8cd7932c77aca682527a8588b9faef94e3/wg_wizard-0.3.0.tar.gz",
"platform": null,
"description": "wg-wizard\n=========\n.. image:: https://github.com/ianlini/wg-wizard/actions/workflows/main.yml/badge.svg\n :target: https://github.com/ianlini/wg-wizard/actions/workflows/main.yml\n.. image:: https://github.com/ianlini/wg-wizard/actions/workflows/release.yml/badge.svg\n :target: https://github.com/ianlini/wg-wizard/actions/workflows/release.yml\n.. image:: https://img.shields.io/pypi/v/wg-wizard.svg\n :target: https://pypi.org/project/wg-wizard/\n.. image:: https://img.shields.io/pypi/l/wg-wizard.svg\n :target: https://github.com/ianlini/wg-wizard/blob/master/LICENSE\n.. image:: https://img.shields.io/github/stars/ianlini/wg-wizard.svg?style=social\n :target: https://github.com/ianlini/wg-wizard\n\nwg-wizard can help you generate the configs for WireGuard interactively,\nand control all the server and client configs in a centralized way.\n\n.. contents::\n\nWhy Do We Need wg-wizard\n------------------------\n\nWhen I was trying to build my own VPN, although WireGuard is quite simple,\nit was still hard to make everything right at the first trial.\nThe 2 most common issues are incorrect iptables and unmatched server/client\nconfigs.\nTherefore, I built this tool to make these steps less error-prone by\ncentralizing all the configs as one simple wizard config and generating the\nconfigs required by WireGuard when needed.\nBesides, the tool also provides some simple interactive CLI tools to help\nyou create the wizard config easily, and it can generate QR code for you\nto set up your smart phone easily.\n\nNetwork Architecture\n--------------------\n\nOur default network architecture is one\n`relay server <https://docs.sweeting.me/s/wireguard#Bounce-Server>`_\nwith multiple clients connecting to the VPN via the relay server.\n\nWe assume that most people need a network architecture like this.\nIf you want another architecture, you can still achieve some of them\nusing the advance configuration.\n\nPrerequisite\n------------\n\n1. A server with Ubuntu, Debian or Raspberry Pi OS.\n You can still use other Linux distributions,\n but the following instructions might not be applicable.\n2. `Install Docker <https://docs.docker.com/engine/install/>`_ on your relay server.\n3. `Install Wireguard <https://www.wireguard.com/install/>`_ on your relay server.\n\nRun the Docker Container\n------------------------\n\nWe use Docker to disable the network to make the whole process secure.\n\n.. code-block:: sh\n\n # go to the directory you want to put the configs\n # assuming ~/wg-wizard here\n export WG_WIZARD_CONFIG='~/wg-wizard'\n cd \"${WG_WIZARD_CONFIG}\"\n docker run -it --rm --network=none --volume=\"$PWD\":/workdir ianlini/wg-wizard\n\nInitialize the Configuration\n----------------------------\n\n.. code-block:: sh\n\n # inside the Docker container\n wg-wizard init\n\nFollow the instruction to create the config. Example output:\n\n.. code-block::\n\n Interface name for WireGuard [wg0]:\n Interface.ListenPort of the relay server [51820]:\n Interface.Address of the relay server [192.168.10.1/24]:\n The default endpoint in clients' Peer.Endpoint configs (e.g., example.com:51820): example.com\n If you want to allow the clients to access the internet via the relay server, you must provide the interface name you want to forward the internet traffic to. It's usually eth0 or wlan0. You can check it by executing `ip addr`. If you provide an interface name {interface}, the following rules will be added:\n - iptables -A FORWARD -i %i -o {interface} -j ACCEPT\n - iptables -A FORWARD -i {interface} -o %i -j ACCEPT\n - iptables -t nat -A POSTROUTING -s {network} -o {interface} -j MASQUERADE\n Interface name for connecting to the internet []: eth0\n Do you want to allow the clients to connect with each other? If yes, a rule will be added: `iptables -A FORWARD -i %i -o %i -j ACCEPT` [Y/n]:\n Do you want to allow the clients to connect to any IPs on the relay server? If no, only the IP of the WireGuard interface can be connected, that is, the following rules will be added:\n - iptables -A INPUT -d {wg_server_interface_ip} -i %i -j ACCEPT\n - iptables -A INPUT -i %i -j DROP\n [y/N]:\n [2022-10-12 18:41:34,190][INFO] wg_wizard.core: Writing config to /home/pi/pi-gateway/wireguard/wg0.yml\n [2022-10-12 18:41:38,868][INFO] wg_wizard.core: Writing secret to /home/pi/pi-gateway/wireguard/wg0_secret.json\n\nNormally, you can use the default values for almost all of the options.\n\nIf you allow the internet access or allow the clients to connect with each other,\nyou also need to `enable IP forwarding <https://www.digitalocean.com/community/tutorials/how-to-set-up-wireguard-on-ubuntu-20-04#step-4-adjusting-the-wireguard-server-s-network-configuration>`_.\n\nFor convenience, in the following instructions,\nwe assume that your WireGuard interface name is ``wg0``:\n\n.. code-block:: sh\n\n export WG_INTERFACE=wg0\n\nAdd a Peer\n----------\n\n.. code-block:: sh\n\n # inside the Docker container\n wg-wizard add-peer\n\nFollow the instruction to create the peer config. Example output:\n\n.. code-block::\n\n Interface name for WireGuard [wg0]:\n Name of the client: phone1\n Peer.PersistentKeepalive of the client [25]:\n Interface.Address of the client [192.168.10.2/32]:\n Peer.AllowedIPs of the client [0.0.0.0/0, ::/0]:\n [2022-10-04 16:40:01,337][INFO] wg_wizard.core: Writing config to /workdir/wg0.yml\n [2022-10-04 16:40:01,358][INFO] wg_wizard.core: Writing secret to /workdir/wg0_secret.json\n [2022-10-04 16:40:01,362][INFO] wg_wizard.cli: Client's wg-quick config QR Code:\n ...\n\nNormally, you can use the default values for almost all of the options.\nIn the end, there will be a QR Code generated.\nYou can now use your `WireGuard app <https://www.wireguard.com/install/>`_\non your phone to scan the QR Code to import the config.\nIf your client doesn't support QR Code, you can use another command to generate the text:\n\n.. code-block:: sh\n\n wg-wizard export-client-config --interface \"${WG_INTERFACE}\" --name phone1 --no-qrcode\n\nSet Up the WireGuard Server\n---------------------------\n\nPreparing:\n\n.. code-block:: sh\n\n # on your relay server (outside the Docker container)\n cd \"${WG_WIZARD_CONFIG}\"\n export WG_INTERFACE=wg0 # replace wg0 with your interface name\n (umask 077; sudo mkdir /etc/wireguard/)\n\nExporting server config:\n\n.. code-block:: sh\n\n docker run --rm --network=none --volume=\"$PWD\":/workdir ianlini/wg-wizard \\\n wg-wizard export-server-config -i \"${WG_INTERFACE}\" \\\n | sudo cp --backup /dev/stdin \"/etc/wireguard/${WG_INTERFACE}.conf\"\n\nIf you haven't enabled the service:\n\n.. code-block:: sh\n\n # start the WireGuard server\n sudo systemctl enable \"wg-quick@${WG_INTERFACE}.service\"\n sudo systemctl start \"wg-quick@${WG_INTERFACE}.service\"\n\nNow you can turn on the WireGuard tunnel on your client (phone1),\nand it should work.\n\nIf the service is already running, you can check the config diff first:\n\n.. code-block:: sh\n\n sudo diff \"/etc/wireguard/${WG_INTERFACE}.conf~\" \"/etc/wireguard/${WG_INTERFACE}.conf\"\n\nAfter confirming the changes, there are 2 ways to apply them.\n\n1. If you are not changing the wg-quick specific interface configs\n (e.g., Address, DNS, MTU, Table, PreUp, PostUp, PreDown,\n PostDown and SaveConfig),\n you can reload the config without stopping the server:\n\n .. code-block:: sh\n\n sudo systemctl reload \"wg-quick@${WG_INTERFACE}.service\"\n\n2. Otherwise, you should restart the server:\n\n .. code-block:: sh\n\n sudo systemctl restart \"wg-quick@${WG_INTERFACE}.service\"\n\n\nTroubleshooting\n---------------\n\nRead the service log:\n\n.. code-block:: sh\n\n journalctl -u \"wg-quick@${WG_INTERFACE}.service\" -f -n 1000\n\nEnable the kernel log:\n\n.. code-block:: sh\n\n sudo modprobe wireguard\n echo module wireguard +p | sudo tee /sys/kernel/debug/dynamic_debug/control\n\nRead the kernel log:\n\n.. code-block:: sh\n\n journalctl -k -f -n 1000 | grep wireguard\n\nDebug iptables:\n\n.. code-block:: sh\n\n # trace the ICMP packets from a WireGuard client\n sudo iptables -t raw -A PREROUTING -i \"${WG_INTERFACE}\" -p icmp -j TRACE\n # trace the incoming ICMP packets from the internet to a WireGuard client\n sudo iptables -t mangle -A FORWARD -d 192.168.10.0/24 -p icmp -j TRACE\n\n.. warning::\n Debugging iptables requires much more knowledge,\n or you might generate large logs,\n or even break the network of the whole machine.\n However, it is highly possible that the generated configs don't work out-of-the-box.\n It is the hard part when developing this tool because people will have different existing rules.\n If you have a bad luck, you might need to spend some time understanding\n the relationship between iptables and WireGuard.\n\nBuild the Docker Image from Scratch\n-----------------------------------\n\nTODO\n\n.. code-block:: sh\n\n git clone ...\n cd ...\n docker build . -t ianlini/wg-wizard\n\nReferences\n----------\n\n- `Some Unofficial WireGuard Documentation <https://docs.sweeting.me/s/wireguard>`_\n- `How To Set Up WireGuard on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-set-up-wireguard-on-ubuntu-20-04>`_\n- `How To Set Up WireGuard Firewall Rules in Linux <https://www.cyberciti.biz/faq/how-to-set-up-wireguard-firewall-rules-in-linux/>`_\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Control all the WireGuard server and client configs in a centralized way.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/ianlini/wg-wizard",
"Repository": "https://github.com/ianlini/wg-wizard"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "084d37cf15ce15f9078a99acc38f4011ee9d47d6e38a94d264e3393464bb0736",
"md5": "4e84821e2609025283d0edd28ab94597",
"sha256": "b0f6d7e72b93ff54f67e2b5d7b52d3ed2643b69f320d2d0805617c1f85c5e952"
},
"downloads": -1,
"filename": "wg_wizard-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e84821e2609025283d0edd28ab94597",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 14375,
"upload_time": "2023-12-03T10:31:32",
"upload_time_iso_8601": "2023-12-03T10:31:32.804390Z",
"url": "https://files.pythonhosted.org/packages/08/4d/37cf15ce15f9078a99acc38f4011ee9d47d6e38a94d264e3393464bb0736/wg_wizard-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "90b51991ee531fc26acd2d58bd69ed8cd7932c77aca682527a8588b9faef94e3",
"md5": "4ae7385711afa104d68bae6512cf671d",
"sha256": "912ecc180d74e82c021e4527c1f08885fb039da3995377f612b63cfe3adb5c04"
},
"downloads": -1,
"filename": "wg_wizard-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "4ae7385711afa104d68bae6512cf671d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 16024,
"upload_time": "2023-12-03T10:31:34",
"upload_time_iso_8601": "2023-12-03T10:31:34.394465Z",
"url": "https://files.pythonhosted.org/packages/90/b5/1991ee531fc26acd2d58bd69ed8cd7932c77aca682527a8588b9faef94e3/wg_wizard-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-03 10:31:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ianlini",
"github_project": "wg-wizard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "wg-wizard"
}
