============================================================
pfSense WireGuard VPN setup (dev-vpn to kb-vpn)
============================================================

Overview
========

This guide walks through setting up a **site-to-site VPN** using **WireGuard** on a newly installed pfSense router (dev-vpn). 
The goal is to connect a local network (`xx.xx.x.x/24`) to a remote VPN server (`kb-vpn`, `10.10.2.1`) over a secure WireGuard tunnel.

All devices on the dev-vpn LAN should be able to access services in the `10.10.2.0/24` subnet.

Network Topology
================

.. code-block:: text

             +---------------------------------------------+
             |                 kb-vpn Server               |
             |                                             |
             |  Public IP:       143.110.xxx.xxx           |
             |  WireGuard IP:    10.10.2.1/24              |
             |                                             |
             |      [ WireGuard Host / Central VPN ]       |
             +----------------------▲----------------------+
                                    │
                    WireGuard VPN Tunnel (UDP 51820)
                                    │
             +----------------------▼----------------------+
             |             dev-vpn pfSense Router          |
             |                                             |
             |  LAN IP:           192.168.x.1/24           |
             |  WireGuard IP:     10.10.2.xxx/24           |
             |                                             |
             |     [ WireGuard Peer / Site Gateway ]       |
             +----------------------▲----------------------+
                                    │
                        +-----------+-----------+
                        |                       |
                +-------+--------+     +--------+-------+
                |   LAN Host     |     |   LAN Host     |
                | 192.168.x.10   |     | 192.168.x.11   |
                +----------------+     +----------------+


Requirements
============

- A pfSense router (latest version) at the local site
- Access to the remote WireGuard server (`kb-vpn`)
- LAN subnet: `192.168.x.x/24`
- Remote VPN subnet: `10.10.2.0/24`


Part 1: pfSense Initial Setup
=============================

Install pfSense via ISO or USB image. After reboot:

- Setup WAN/LAN interfaces
- Connect to: `http://xxx.xxx.xx.xx` (Address will be shown on console)
- Login: `admin / pfsense`
- Change password during initial setup


Part 2: Install and Configure WireGuard
=======================================

1. Install WireGuard Package
-----------------------------

Navigate to **System > Package Manager > Available Packages**:

- Install **`wireguard`** (by Netgate)

2. Generate WireGuard Keys
---------------------------

From a secure terminal:

.. code-block:: bash

   wg genkey | tee privatekey | wg pubkey > publickey

- Store these securely
- Only the public key will be used in remote config

3. Add WireGuard Tunnel (Local)
-------------------------------

Go to **VPN > WireGuard** → **Add Tunnel**:

- Name: `dev-vpn`
- Interface Keys:
  - Private Key: `<your_private_key_here>` (redacted)
- Listen Port: `51820`

Save and Enable.

4. Add Peer (Remote: kb-vpn)
----------------------------

Click **Add Peer** under your tunnel:

- Public Key: `<kb-vpn_public_key_here>` (redacted)
- Endpoint Address: `143.110.xxx.xxx:51820`
- Allowed IPs: `10.10.2.0/24`
- Persistent Keepalive: `25`

Save and Apply.

5. Assign WireGuard Interface
-----------------------------

Go to **Interfaces > Assignments**:

- Add interface: `tun_wg0`
- Rename to: `WG`
- Enable it with default settings
- Save and Apply

6. Configure Static IP for WG Interface
----------------------------------------------------

Now configure the assigned WG interface.

Go to **Interfaces > WG**:

- **Enable**: ✓
- **Static IP**: `10.10.2.xxx` (This will be the IP address we assigned in salt)
- **Subnet Mask**: `/24`
- Leave other settings as default

Save and Apply.


Part 3: Configure Firewall Rules and Routing
============================================

Go to **Firewall > Rules > WG**:

- Allow all traffic:

  .. code-block::

     Action: Pass
     Protocol: Any
     Source: Any
     Destination: Any

2. WAN to VPN Access
---------------------

Go to **Firewall > Rules > WAN**:

- Add rule:

  .. code-block::

     Action: Pass
     Protocol: UDP
     Source: Any
     Destination: (other) :51820


Part 4: Configure kb-vpn Server via salt
========================================

Example configuration:

.. code-block:: ini

  peers:
    dev-vpn:
       PublicKey = <dev-vpn_public_key_here> (redacted)
       AllowedIPs: 10.10.2.xx/32


Part 5: Connect and Test
========================

1. Connect a Client to LAN
---------------------------

Connect a device to dev-vpn’s LAN via Ethernet

Or you can use the pfSense console.

2. Test VPN Routing
--------------------

From the client, run:

.. code-block:: bash

   ping 10.10.2.xx

If the ping fails:
- Ensure both peers are configured correctly
- Check firewall rules and WireGuard interface status
- Verify AllowedIPs are correct on both ends

Check that it reaches a device on the network.

3. Verify Tunnel Status
------------------------

In pfSense:

- Go to **VPN > WireGuard > Status**
- Confirm handshakes and traffic flow

Appendix: Verifying Routes
==========================

Check pfSense routing table:

- Go to **Diagnostics > Routes**
- Ensure `10.10.2.0/24` routes through interface `tun_wg0`


Conclusion
==========

You now have a secure, routed site-to-site VPN using WireGuard between your pfSense router (dev-vpn) and the kb-vpn server.