From 8c77fb834be2763765d5cd3ddb071d7a98b0ef00 Mon Sep 17 00:00:00 2001 From: Khue Doan Date: Mon, 25 Nov 2024 01:25:46 +0700 Subject: [PATCH] docs(wireguard): update setup instruction --- docs/getting-started/vpn-setup.md | 172 +++++++++++++++++++++++++----- 1 file changed, 146 insertions(+), 26 deletions(-) diff --git a/docs/getting-started/vpn-setup.md b/docs/getting-started/vpn-setup.md index 4ab57300..3ac07c9f 100644 --- a/docs/getting-started/vpn-setup.md +++ b/docs/getting-started/vpn-setup.md @@ -1,6 +1,8 @@ # VPN setup -You can choose between [Tailscale](https://tailscale.com), [Wireguard](https://www.wireguard.com), or use both like me. +You can choose between [Tailscale](https://tailscale.com), +[Wireguard](https://www.wireguard.com), or use both like me. I primarily use +WireGuard but keep Tailscale as a backup for when the WireGuard server is down. ## Tailscale (requires third-party account) @@ -17,6 +19,8 @@ extra_secrets = { } ``` +You may want to back up the `external/terraform.tfvars` file to a secure location. + Apply the secret: ```sh @@ -30,32 +34,148 @@ You can now connect to your homelab via Tailscale and [invite user to your Tails ## Wireguard (requires port-forwarding) -Update the peer list in `apps/wireguard/values.yaml`: +### Prerequisites -```yaml -PEERS: | - UserDevice - FooPhone - FooLaptop - BarDesktop -``` - -Go to your router settings and forward the Wireguard service. -Each router is different, here's mine for reference: - -- Protocol: `UDP` -- Start Port: `51820` -- End Port: `51820` -- Local IP Address: `192.168.1.226` (find it with `kubectl get service -n wireguard wireguard`) -- Start Port Local: `51820` -- End Port Local: `51820` - -To get the QR code (for mobile) and config (for desktop), run: - -!!! warning - - This command will print sensitive secrets to the terminal. +Find your public IP address using: ```sh -./scripts/get-wireguard-config FooPhone +curl -4 ifconfig.me ``` + +If you don’t have a static IP address, use dynamic DNS and replace the IP with +your domain name. + +Next, configure port forwarding in your router for the WireGuard service. + +!!! example + + Each router is different, here's mine for reference: + + - Protocol: `UDP` + - Start Port: `51820` + - End Port: `51820` + - Local IP Address: `192.168.1.226` (find it with `kubectl get service -n wireguard wireguard`) + - Start Port Local: `51820` + - End Port Local: `51820` + +Generate a key pair for the server: + +```sh +wg genkey | tee /dev/tty | wg pubkey +``` + +This will generate a private key and a public key, in that order. Add the +private key to `external/terraform.tfvars` as an extra secret: + +```hcl +extra_secrets = { + wireguard-private-key = "privatekeyhere" +} +``` + +You may want to back up the `external/terraform.tfvars` file to a secure location. + +Apply the secret: + +```sh +make external +``` + +I use `172.16.0.0/12` as the private IP range for WireGuard, but you can choose +any private IP address range you prefer in `./apps/wireguard/values.yaml`. I +also recommend removing my peers and adding your own. + +### Add a new device to the server + +!!! info + + Each device requires its own configuration. + +Generate a new key pair for the device. You can generate it for the user, or +they can generate it themselves if they prefer to keep the private key +confidential: + +```sh +wg genkey | tee /dev/tty | wg pubkey +``` + +This will generate a private key and a public key, in that order. The private +key must be saved in a secure password manager, and save the public key for the +next step. + +Update the list of peers in `./apps/wireguard/values.yaml`, make sure you +replace all of my peers with yours. + +!!! example + + Example configuration for my phone: + + ```ini + [Peer] + PublicKey = nITHFdgTkNZOTWeSWqnGXjgwlCJMKRCnnUsjMx2yp2U= + AllowedIPs = 172.16.0.12/32 + ``` + + - The public key is the one generated in the previous step. + - `172.16.0.12/32` is the device's private IP address, manually selected from + the `172.16.0.0/12` range mentioned above. + +### Add the Wireguard config to the device + +Create a new configuration file for the device: + +```ini +[Interface] +Address = /32 +PrivateKey = + +[Peer] +PublicKey = +Endpoint = :51820 +AllowedIPs = /32, +``` + +Replace placeholders with actual values and save as `wg0.conf`. + +!!! example + + Example configuration for my phone: + + ```ini + [Interface] + Address = 172.16.0.12/32 + PrivateKey = + + [Peer] + PublicKey = sSAZS1Z3vB7Wx8e2yVqXfeHjgWTa80wnSYoma3mZkiU + Endpoint = :51820 + AllowedIPs = 172.16.0.1/32, 192.168.1.224/27 + ``` + +The client can now import this configuration and connect to your WireGuard +mesh. Make sure you clean up the `wg0.conf` file after importing it to the +client. + +=== "Mobile" + + Generate a QR code from the configuration file: + + ```sh + qrencode -t ansiutf8 -r wg0.conf + ``` + + Then scan the QR code using the official WireGuard app. + +=== "Linux" + + Import the WireGuard configuration using NetworkManager: + + ```sh + nmcli connection import type wireguard file wg0.conf + ``` + + Activate the connection: + + ```sh + nmcli connection up wg0 + ```