A pfSense package providing a full GUI for DNSCrypt Proxy, an encrypted DNS client supporting DNSCrypt v2, DNS-over-HTTPS (DoH), Oblivious DoH (ODoH), and Anonymized DNS protocols.
Note: This is a community-maintained package and is not affiliated with or supported by Netgate.
- Full GUI Configuration - 8 configuration tabs accessible from the pfSense web interface
- Multiple Protocols - Supports DNSCrypt v2, DNS-over-HTTPS (DoH), Oblivious DoH (ODoH), and Anonymized DNS with relay routing
- Popular Providers - Pre-configured servers from Cloudflare, Quad9, Google, AdGuard, NextDNS, Mullvad, OpenDNS, CleanBrowsing, and more
- Custom Resolvers - Add custom servers via DNS stamps
- Custom TOML Options - Add any dnscrypt-proxy option not exposed in the UI, including TOML section blocks, with validation via
dnscrypt-proxy -checkbefore saving - Domain Filtering - Block and allow lists, forwarding rules, and cloaking rules
- Query Logging - Built-in query log viewer with filtering by domain, type, and client IP
- Config Management - View, copy, download, import (paste or upload), and reset the TOML configuration
- Advanced Tuning - Load balancing strategies, HTTP/3 (QUIC) support, ephemeral keys, cache size/TTL controls, and log rotation
- Multi-Architecture - Supports both amd64 and arm64 (auto-detected)
- Service Integration - Managed via Status > Services like native pfSense services
View screenshots
Run this command in the pfSense shell (via SSH or Console):
pkg-static add -A https://github.com/nopoz/pfsense-dnscrypt-proxy/releases/latest/download/pfSense-pkg-dnscrypt-proxy.pkgpkg-static -C /dev/null add -A https://github.com/nopoz/pfsense-dnscrypt-proxy/releases/latest/download/pfSense-pkg-dnscrypt-proxy.pkgReplace latest/download/pfSense-pkg-dnscrypt-proxy.pkg with download/vX.X.X/pfSense-pkg-dnscrypt-proxy-X.X.X.pkg:
pkg-static add -A https://github.com/nopoz/pfsense-dnscrypt-proxy/releases/download/v1.0.0/pfSense-pkg-dnscrypt-proxy-1.0.0.pkgSee all available versions on the Releases page.
After installation, navigate to Services > DNSCrypt Proxy in the pfSense web interface.
Note: This package won't appear under "Installed Packages" since it's installed manually, not from the pfSense repository. It will appear under Services > DNSCrypt Proxy, on the Dashboard under Services Status, and under Status > Services.
Why
-A? It marks the package automatically installed, which is not cosmetic here. pfSense's bulk package operations, Factory Defaults reset and "Reinstall all packages", loop over manually installed packages only and stop at the first one they cannot find in the pfSense repository. A package installed from a file is never in that repository, so without-Athose operations abort partway and silently leave every package sorting after this one untouched. With-Athey skip this package and finish normally. It does not risk the package being auto-removed, because the package also marks itself vital. If you installed without-A, runpkg set -A 1 pfSense-pkg-dnscrypt-proxyonce.
To upgrade to a newer version, use the -f (force) flag:
pkg-static add -f -A https://github.com/nopoz/pfsense-dnscrypt-proxy/releases/latest/download/pfSense-pkg-dnscrypt-proxy.pkgOr delete the existing package first, then install the new version:
pkg delete -f pfSense-pkg-dnscrypt-proxy
pkg-static add -A https://github.com/nopoz/pfsense-dnscrypt-proxy/releases/latest/download/pfSense-pkg-dnscrypt-proxy.pkgYour configuration settings are preserved during upgrades.
A Factory Defaults reset will not remove this package. pfSense removes
add-on packages by looping over manually installed ones, and this package marks
itself automatic (see -A above) precisely so that loop skips it rather than
stopping on it.
The package is left installed with its settings gone from config.xml, so it
disappears from Services. The daemon will not start in that state, so
nothing is left running, but the package files remain. Remove it explicitly if
you want a clean box:
pkg delete -f pfSense-pkg-dnscrypt-proxyUpgrading pfSense (2.8.1 to 2.9.0, for example) deletes every package that is
not in the official pfSense repository. This is deliberate behaviour in
Netgate's upgrade script and has been since 2017: any pfSense-pkg-* it cannot
find in the remote repo is flagged automatic and collected by pkg autoremove.
From 1.2.10 the package marks itself vital, which makes pkg autoremove skip
it, so it now survives. Reinstall the current release afterwards anyway. A
major pfSense upgrade can change the FreeBSD base and the PHP version
underneath the package (2.9.0 moves to FreeBSD 16 and PHP 8.5), and the flag
only guarantees the files are still there, not that they still run.
If you are coming from a version before 1.2.10, or you restore a config backup
onto a fresh install, the package will be gone and the symptom is that
the firewall loses all DNS. The forward-addr: 127.0.0.1@5300 line in the
DNS Resolver custom options belongs to Unbound, so it survives the upgrade and
now points at a port with nothing listening. Unbound forwards every query into
the void, including the firewall's own attempts to reach the package
repository. To recover: remove the forward-zone block from Services > DNS
Resolver > Custom options, apply, reinstall the package, then put the block
back.
- Install the package using the command above
- Navigate to Services > DNSCrypt Proxy
- Check Enable DNSCrypt Proxy
- Select your preferred DNS servers from the Server Selection tab
- Click Save
Forward Unbound queries through DNSCrypt Proxy:
- Go to Services > DNS Resolver > General Settings
- Add the following to Custom options:
server:
do-not-query-localhost: no
forward-zone:
name: "."
forward-addr: 127.0.0.1@5300
- Click Save and Apply Changes
These lines belong to Unbound, not to this package, so they stay behind if the package is ever removed and will take the firewall's DNS down with them. See Upgrading pfSense itself.
To use DNSCrypt Proxy directly via System > General Setup:
- Disable DNS Resolver: Go to Services > DNS Resolver, uncheck Enable, and click Save
- Configure DNSCrypt Proxy to listen on port 53
- Go to System > General Setup > DNS Server Settings and set DNS Server to
127.0.0.1
Note: The pfSense DNS Server Settings only accepts IP addresses and assumes port 53.
pkg delete -f pfSense-pkg-dnscrypt-proxyThe -f is required because the package marks itself vital so that a pfSense
OS upgrade cannot delete it (see Upgrading pfSense
itself). It only bypasses that check, so the
uninstall is otherwise normal and still runs the package's own cleanup.
Use -f rather than clearing the vital flag by hand. pkg set -v 0 leaves the
package marked automatic but no longer protected, and the next pkg autoremove
will then delete it without warning.
If normal uninstall doesn't fully clean up, or you need a fresh start:
# From your local machine (requires SSH access to pfSense)
./uninstall.sh pfsense.localThis removes all package files, runtime artifacts, and pfSense registrations while preserving your settings in config.xml.
Requirements: FreeBSD with pkg tools, or a pfSense instance for remote builds.
# Clone the repository
git clone https://github.com/nopoz/pfsense-dnscrypt-proxy.git
cd pfsense-dnscrypt-proxy
# Build the package (requires FreeBSD)
./build.sh build
# Or build and deploy directly to pfSense via SSH
./build.sh deploy pfsense.local
# Clean build artifacts
./build.sh clean| Script | Purpose |
|---|---|
build.sh build |
Build .pkg file (requires FreeBSD) |
build.sh deploy [host] |
Build on pfSense via SSH and install |
build.sh clean |
Remove local build artifacts |
uninstall.sh [host] |
Completely remove package from pfSense |
| Variable | Default | Description |
|---|---|---|
DEPLOY_HOST |
pf |
SSH hostname for pfSense |
PORTVERSION |
1.2.3 |
Package version to build |
- DNSCrypt Proxy - The upstream project
- pfSense FreeBSD-ports PR #1434 - Submission to the official pfSense package repository
- pfSense Redmine #9315 - Original feature request
- Netgate Forum Discussion - Community discussion and support
This package vendors a third-party binary, so the release pipeline is built to keep that supply chain auditable:
- Upstream binaries are signature-verified (minisign, against the official DNSCrypt key) in CI before they are committed, and proposed via pull request rather than auto-merged.
- Releases carry SLSA build provenance plus a
SHA256SUMSfile. Verify a download withgh attestation verify <pkg> --repo nopoz/pfsense-dnscrypt-proxy. - Workflows are hardened: Actions pinned to commit SHAs (kept current by
Dependabot), least-privilege tokens, and CI static analysis with ShellCheck,
php -l, actionlint, and zizmor.
See SECURITY.md for the full policy and how to report a vulnerability.
- Open a GitHub issue for bug reports, feature requests, or questions
- Add a star on GitHub to support the project!
Other open-source tools I maintain that you might find useful:
- Hosaka - Docker image update monitor with notifications and one-click updates.
- Portrieve - back up, restore, and migrate Portainer stacks as plain Docker Compose files.
ISC License - See LICENSE for details.