**[Package] WireGuard Easy for pfSense — create and hand out peers from a single page**

marcelomayo74

[Package] WireGuard Easy for pfSense — create and hand out peers from a single page

Hi all,

Sharing a package I built because I got tired of generating client keys by hand, pasting the public key into a peer, and then writing the client .conf separately every time I needed to add a device. It's called wgeasy and it adds VPN → WireGuard Easy to pfSense.

What it does:

One form creates the peer and hands you the client file (.zip) with a QR code, a download button, and email delivery.
Auto-fills everything it can: next free IP in the tunnel subnet, your Dynamic DNS/RFC2136 hostnames as endpoint options, the tunnel's listen port, the subnets your DHCP server serves, DNS presets (Google, Cloudflare, Quad9, or the firewall's own).
A dashboard widget that, unlike the native one (which only counts active peers), shows who is connected, from where, and their traffic counters.
An "Easy Peers" list with per-row actions to re-download the client file, the QR code, or resend it by email at any time.

Important — how it works under the hood:
It doesn't edit config.xml by hand or touch any file belonging to the native package. It goes through the native pfSense-pkg-WireGuard's own functions (wg_do_peer_post, wg_gen_keypair, wg_tunnel_sync, etc.), so a peer created with this package is a completely normal peer — it can be edited or deleted from VPN → WireGuard → Peers without breaking anything, and it survives upgrades of the native package.

A trade-off I want to be upfront about: to be able to hand the client file out again later (re-download it, show the QR again, resend the email), the package stores the client's private key and the settings used to build the file inside a <wgeasy> element on the peer itself — which means it ends up in your config.xml backups and in AutoConfigBackup. That's a deliberate design choice (the alternative is that the file exists exactly once, on the screen that created it, and a user who loses it needs a brand new peer). It's documented in the README so everyone can decide for themselves whether that trade-off works for them.

Requires: pfSense-pkg-WireGuard installed. Tested on pfSense CE 2.8.1 with pfSense-pkg-WireGuard 0.2.9_6.

Install:

scp pfSense-pkg-wgeasy-<version>.pkg root@FIREWALL:/root/
ssh root@FIREWALL
pkg add /root/pfSense-pkg-wgeasy-<version>.pkg

pkg add will warn that the package doesn't come from a repository — that's expected, it isn't in the official repo or any unofficial one yet.

Repo with screenshots, releases, and full technical detail: https://github.com/MarceloMayo74/pfsense-wgeasy

It's Apache 2.0 licensed. Feedback, issues, and PRs are all welcome. Thanks for reading!

marcelomayo74

Update: 0.4.2 is out.

I went back over the form field by field looking for gaps.

The endpoint port is now mandatory. wg(8) parses Endpoint as
host:port and refuses a client file that has no port — the phone apps just
say the QR code is invalid. The field is pre-filled from the tunnel's listen
port, but if you cleared it the peer used to save anyway and produced a file
no client would accept. It's now rejected with a message. Peers already saved
without a port fall back to the tunnel listen port when their file is rebuilt,
so nothing that already works stops working.

A new client starts from the last one created on that tunnel. Endpoint,
port, DNS servers, MTU, keep alive and the routing preset are carried over, so
the second phone in a household doesn't mean typing the same six fields again.
The address and the key pair are always new, and split tunnel is recomputed
rather than replayed — if you changed the tunnel network or added a LAN, you
get the networks as they are now, never a stale list. Each tunnel remembers on
its own, and switching the tunnel dropdown applies that tunnel's settings in
place.

The MTU comes from the tunnel. If the tunnel doesn't run on the 1420 every
client already assumes — a PPPoE WAN, say — the client file now says so
instead of leaving the client to guess.

Firewall aliases can be used for Tunneled Networks. Pick a host or network
alias and its addresses are dropped into the field. They're resolved at that
moment, since WireGuard has no idea what an alias is, so editing the alias
later doesn't reach clients you already handed out.

Also fixed: opening an existing peer now always shows what that peer was saved
with, blank fields included, so the carry-over above can't leak another
client's MTU or DNS into it.

Tested on pfSense CE 2.8.1 with pfSense-pkg-WireGuard 0.2.9_6, and on 2.9.0-BETA
(amd64) with pfSense-pkg-WireGuard 0.2.13_4.

How to install it, step by step

You need the .pkg file from the release page:
https://github.com/MarceloMayo74/pfsense-wgeasy/releases/latest

Replace 192.168.1.1 below with your firewall's address, and admin with your
firewall's login user if it's a different one.

Option A — from a terminal (three commands)

SSH has to be enabled first: System → Advanced → Admin Access → Secure Shell →
Enable Secure Shell.

Windows 10/11 already ship scp and ssh; open PowerShell. On macOS or Linux,
open Terminal. Run these from the folder where you downloaded the file, or write
the full path to it.

Copy the package to the firewall:

scp pfSense-pkg-wgeasy-0.4.2.pkg admin@192.168.1.1:/root/

Install it:

ssh admin@192.168.1.1 "pkg add /root/pfSense-pkg-wgeasy-0.4.2.pkg"

If you already have an older version, delete it first — pkg add will not
upgrade in place:

ssh admin@192.168.1.1 "pkg delete -y pfSense-pkg-wgeasy && pkg add /root/pfSense-pkg-wgeasy-0.4.2.pkg"

Your peers survive that. They live in config.xml, not in the package.

Delete the copy you uploaded, so it doesn't pile up on the firewall:
```
ssh admin@192.168.1.1 "rm -f /root/pfSense-pkg-wgeasy-0.4.2.pkg"
```

Option B — from the web GUI, no terminal at all

Go to Diagnostics → Command Prompt.
In the Upload File box at the bottom, pick the .pkg and upload it. It
lands in /tmp/.

In the Execute Shell Command box at the top, run:

pkg add /tmp/pfSense-pkg-wgeasy-0.4.2.pkg

Upgrading from an older version instead:

pkg delete -y pfSense-pkg-wgeasy && pkg add /tmp/pfSense-pkg-wgeasy-0.4.2.pkg

Optional cleanup, in the same box:

rm -f /tmp/pfSense-pkg-wgeasy-0.4.2.pkg

What you should see

pkg add will warn that the package doesn't come from a repository. That's
expected — it isn't in the official repo or any unofficial one.

When it's done, the menu entry is at VPN → WireGuard Easy. If the menu
doesn't show up right away, reload the page.

To remove it later:

pkg delete -y pfSense-pkg-wgeasy

That leaves your peers alone: they were created through the native WireGuard
package and stay under VPN → WireGuard → Peers.

Your peers survive that — they live in config.xml, not in the package.

Release and changelog: https://github.com/MarceloMayo74/pfsense-wgeasy/releases/tag/v0.4.2

slu

@marcelomayo74 this looks really awesome!

Perhaps this could become an official package for pfSense, if you were to agree?

marcelomayo74

@slu Thanks for the kind words! Yes, I'd be very much in favor of that. The project is open source and I'd be glad to work with the Netgate team on any changes needed to meet their packaging standards, documentation requirements, or maintenance expectations. Feel free to point me to the right process/contact if there's one, or let me know if I should reach out directly.

slu

@stephenw10 can you pass this to the right person? This package would be awesome!

@marcelomayo74 thank you very much for working on open source software.