Tutorial: Caddy (Reverse Proxy) + Let's Encrypt Certificates + Dynamic DNS

[Monviech (Cedrik)]

Like this plugin? Consider donating to me.



This plugin is simple to use and very easy to configure. Yet, it also offers plenty of advanced options for more complicated usecases at the same time.

- For Reverse Proxy + automatic Let’s Encrypt Certificates follow these steps:

1. Installation
2. Prepare OPNsense for Caddy after installation
3. Creating a simple reverse proxy
(Please note that the docs have been updated for 24.7, so there might be different terminology at a few steps.)

- For Dynamic DNS follow this additional step:

4. Dynamic DNS

Layer 4 module:

https://docs.opnsense.org/manual/how-tos/caddy.html#caddy-layer4-proxy


If you have questions or find an issue, please ask here or post on Github, I will answer them and fix problems as soon as possible.

[gspannu]

Thankyou. A very well written piece of software, a great plugin that makes Caddy a breeze to use.

Great work done… hope to see this integrated into the official OPNsense library someday.

[jemkewl]

Appreciate the work you've done and the help on github.

I have several handlers working now for my domain.  Only one is accessible externally (Internet) and the rest are all available internally only on my LAN or VPN via the Access lists functions.  This was far easier than HAProxy or nginx for my needs.  I've actually disabled the configs I had there and migrated them to Caddy since my use cases are straightforward.

In an effort to try and give something back, I've front-ended my Unifi console with this Caddy plugin and wish to share a quick tutorial here.  There are many ways to do this (e.g. update the cert for Unifi itself to a Trusted Cert).  However, this method is potentially an easier way where we will just trust the Unifi cert.  Every 2 years or so, this cert will need to be updated.

Step 1 - Get the Unifi CA cert:  Many ways to do this, but opted for lazy way.  Navigate to your Unifi console in any browser.  Click the cert icon in the address bar (most likely will say "Not secure").  Then click the "cert is not valid" link or the link your browser has to show the cert.  Go to the details tab and find "Export".  Export the cert and save it to a location with a name you'll recognize (e.g. Unifi.crt).

Step 2 - Get the cert text: Right click on the "Unifi.crt" or whatever you named it and open it with notepad or notepad++ or vi or nano or your text editor of choice.  Copy the details to your clipboard:
At time of this writing for my version of the Unifi console the text for the Unifi.crt is/was:
-----BEGIN CERTIFICATE-----
MIIDfTCCAmWgAwIBAgIEZVl1bjANBgkqhkiG9w0BAQsFADBrMQswCQYDVQQGEwJV
UzERMA8GA1UECAwITmV3IFlvcmsxETAPBgNVBAcMCE5ldyBZb3JrMRYwFAYDVQQK
DA1VYmlxdWl0aSBJbmMuMQ4wDAYDVQQLDAVVbmlGaTEOMAwGA1UEAwwFVW5pRmkw
HhcNMjMxMTE5MDIzOTQyWhcNMjYwMjIxMDIzOTQyWjBrMQswCQYDVQQGEwJVUzER
MA8GA1UECAwITmV3IFlvcmsxETAPBgNVBAcMCE5ldyBZb3JrMRYwFAYDVQQKDA1V
YmlxdWl0aSBJbmMuMQ4wDAYDVQQLDAVVbmlGaTEOMAwGA1UEAwwFVW5pRmkwggEi
MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCaxheTfuaMfIltQuageZS7T55k
cs9xGlvgP3QGGpqeEpk43lHJBZaJmhUtI91dFkfBxyMUBe5AcSWoazRpLYmIuDqI
6T1GDzwe38Hjsy+sCl/CLtjBqga4FCVhqDwMppqqgyBAU6eSLdHr3mTNQk21X5VS
rgU5/zNx9Yon9ChhIxxukqCqMneVXDr8gSGWB3n9AxwTeVm8xVEWWxd+1ho0KP+T
6mxy3UhygoKbgJgxGH8rXgoAwxV8J7YG/soJ5SrJBHm3mZEquUZkFnjmd7Vd0Sl0
6y+44mkxOa0f0evh9LYpvCfXT7Q/705Ucqn9u0lSK86yZN2hjf3GUU5koiOJAgMB
AAGjKTAnMBMGA1UdJQQMMAoGCCsGAQUFBwMBMBAGA1UdEQQJMAeCBVVuaUZpMA0G
CSqGSIb3DQEBCwUAA4IBAQCS9KXCOjT7tqplCrMR3CyeYQAOJsyr1fAGK6AF9jHO
KD7CidfR7ZJi/ocZABr7i+F2zSaPXw9PwHrbRF44uiTxHt5jlXLDhYNI/MqI2Yx/
yx1ddT1UiJF3MM4v8xx7CBpvBKYl6Wr8D561wT7ywb/PcGZ/N7TZbT3yqEr/W3CB
5LhDitlf+DZ0F/SmDFvmFdf0Y9vQuqrylYnTwTr4di7UUoPYbBFf3w4Uu4DAfROX
MoB9Jr0jBi7+nH+MtUHFtn1vcrRU8Q8O4TCq0S+WLGhbrILzBbrX6hCbsrzxEYzW
tzDGic7FQrRpqGfwfeCHsEU42LpBPpaIGKZXt3EhzYo9
-----END CERTIFICATE-----

Step 3 - Add cert to OPNsense trusted store:  Login to OPNsense console and go to System-> Trust -> Authorities.  Click the + to add a Trust Authority.
Descriptive name : Unifi's Self-Signed Console CA
Method: Import an existing Certificate Authority
Certificate data: paste the full text from Step 2
Click Save
(We will need to edit this trusted cert once it expires and replace it with the newly issued one.  with my current Unifi console version, that will be February 20th, 2026.  If upgrading the console version, the cert may change and need to be updated as well - depends on what Ubiquiti does with the Unifi Console)


Step 3 - Create the Unifi handler: Assuming domains, subdomains, etc. are all configured via other tutorials.
 Create a "handler" in Caddy "Handlers" as normal like you would for any other http site with the backend server domain and port for the Unifi console in your infrastructure.  Unifi's console requires https, so to avoid the 502 and similar errors, we need to configure Caddy to "handle" the https.  This is completed by supplying the Subject Alternative Name (SAN) value from the Unifi.crt which is DNS Name=Unifi, the CA we added to the trusted authorities for OPNsense, and utilizing TLS between caddy and the Unifi console.

Handle type: handle
handle path: (blank).
backend server domain: your unifi's IP / hostname
backend server port: your unifi's port (usually 8443)
TLS: "checked"
TLS Trust CA Certificate: select the item named from Step 2 (e.g. Unifi's Self-Signed Console CA).
TLS Server Name: Unifi

Add a description, save and apply.  Navigate to the handler for Unifi's console and your connection should now be encrypted and trusted: https -> Caddy -> https to Unifi server.

[Monviech (Cedrik)]

Thank you a lot I have added your post to the main post as additional tutorial. ^^

[MeroP]

My utmost respect. This is a very successful plugin. Simple, direct and, above all, easy to use for inexperienced users.
The alternative HAProxy/Nginx are really not characterized by their user-friendliness and simplicity.

WHERE CAN I BUY YOU A BEER OR COFFEE? would like to support your work!

Perhaps it would be possible to add a few more aspects, pitfalls and tips to the above tutorial.

- Specific syntax of the API key for the DNS challenge
- Where to find Subject Alternative Name (SAN)
- Instructions for e.g. Nextcloud etc.

What I have not yet managed to get right.

That the OPNsense internal calls are forwarded directly to the backend server and certificates are still issued by Caddy. All connections only succeed via HTTP without certificates. Could you help with an example or give me a hint? I have now tried it with Vaultwarden and Sterling PDF (both in a docker container), resolution to external works without problems even with wildcard, but to internal only as described above.

Many thanks for the great work and good luck with the integration in OPNsense!

[Monviech (Cedrik)]

Hey, thanks for the praise. Right now I don't have any donations set up, I'm doing this mostly because I use this plugin myself excessively everywhere.

Regarding TLS Certificates, it's a good idea to follow this tutorial for a successful backend TLS connection. When you get this to work you can also get all other TLS examples to work: https://github.com/Monviech/os-caddy-plugin#how-to-create-a-handle-with-tls-and-a-trusted-self-signed-certificate

In the coming version the API Key stuff is documented a bit better, also with a reference to the repository where Caddy stores all DNS Providers: https://github.com/caddy-dns (Here you can find the docs for each dns provider module).

I don't have instructions for Nextcloud, but you can always check the /usr/local/etc/caddy/Caddyfile and also browse the https://caddy.community where there are a lot of Caddyfile examples for specific setups like Nextcloud.

[MeroP]

Many thanks for your advice. I followed your tutorials - it works perfectly.
(Self-signed) certificates from OPNsense, Unifi, Proxmox TLS works between proxy and backend.

However, it is unclear to me how this should work for virtual machines, containers - which do not yet have a certificate.
Was under the assumption that the certificate that Caddy issues externally can also be used for the connection between ReversProxy and the backend.

Or should I simply create an override in Unbound?

Like:
host.example.com ---- unbound----opnsense 127.0.0.1-----caddy----TLS----backend

Somehow I can't see the way right now.

[Monviech (Cedrik)]

TLS is not a requirement to create a connection between Caddy and your Backend Servers. The standard is to use HTTP without encryption (which is also the Caddy default).

That is called TLS Termination https://en.m.wikipedia.org/wiki/TLS_termination_proxy in Reverse Proxy Jargon. Just leave the port in the Handler empty, and it will use Port 80 and HTTP. Or use any other port (other than 443) and leave TLS unchecked to use an unencrypted connection per default.

Encrypting the connection in a trusted network (aka not internet) is unneeded most of the time.

You also use Caddy internally if you want to access these VMs with a TLS connection. Since you have made an A-Record in your authorative nameserver that points to the external IP of the OPNsense, all internal requests to this A-Record will reach the OPNsense per default (with HTTPS), and Caddy will reverse proxy them back to your backend servers (with HTTP). You dont need any special NAT rules or any unbound overrides or anything.

[jemkewl]

Hello - I recently upgraded and am wondering if something isn't quite working as expected.

Short version -

1) upgraded OPNsense to 24.1.3_1

2) I had two new subdomains I wanted to add (in addition to the ones I've already created).  However, I am unable to get these to work.  Other/previous subdomains are still working without issue.

3) To troubleshoot, I enabled "http access log" for my domain and also enabled Log HTTP Access in JSON Format.

4) Have hit apply, save, and even restarted the Caddy service a few times.

No logs in
:/var/log/caddy/access # ls
:/var/log/caddy/access #

nothing is showing in the caddy.log either for access

The Caddyfile looks correct with the new host and handle
The autosave.json in /usr/local/etc/caddy/.config/caddy does not have the new host and handle (don't think that  is an issue, but just mentioning it).

Any ideas to tell me what I am doing wrong?


edit: To troubleshoot further, I modified an existing working "Handle" via the Caddy UI.  I changed the IP and port to be of the settings for one of the new domains.  After saving and applying, I am still presented the original configuration in the browser when I access that Handler subdomain.  Seems like something isn't being persisted properly based on this test; at worst, I should receive an error, but instead things still work, albeit for the original subdomain configuration.

edit2:  Since the plugin is close to being or is already available natively, do I need to do some cleanup steps with the repo since I installed the plugin prior to the native access?

[Monviech (Cedrik)]

I would suggest you remove the plugin one time, restart the firewall, and then reinstall it. Your config won't be lost. There has been a big cleanup due to the code review and a lot of things changed. The .config folder isnt used anymore now either.

The autoconf.json is somewhere in "/var/db/caddy/config/caddy" now cause the standard rc.d file of freebsd is used now "/usr/local/etc/rc.d/caddy". It should define that autosave path as ${caddy_directory:="/var/db/${name}"}.

The plugin has been merged but it will be available natively in a future version, probably during the next OPNsense update. After that you can remove my repo. So far my repo serves the plugin, and the actual caddy binary already comes from the OPNsense Repo now.
"caddy-custom-2.7.6.3.0.3.5.3_XX.pkg" (Check here: https://pkg.opnsense.org/FreeBSD:13:amd64/snapshots/latest/All/)

(I had to remove and reinstall the plugin too, I'm using it on a few firewalls myself)

Sorry that you're having trouble, an integration like this and changing a lot of things is pretty hard without having some weird things happen.

[jemkewl]

Disregard - uninstall, reboot, reinstall worked.

Thank you!

This is a great plug-in and I appreciate your efforts.  Weird things always happen - appreciate the help

The new handlers are working as expected - one with TLS and the other clear.  Straightforward and works well.

[Monviech (Cedrik)]

Awesome. Good to know. ^^

[Walki]

I have problems with "Timeout during connect (likely firewall problem)". Which rules have to be set on Port 80 and 443 to "ThisFirewall"? Is it correct to setup a IN-Rule for the LAN to "ThisFirewall" or should "ThisFirewall" the Source?

I do not receive a certificate and wonder what to do. In your FAQ is no need for additional rules.

Great plugin. Thank you very much for your efforts. It should make a Reverse proxy setup much easier.

[Monviech (Cedrik)]

Hello.

The rule on WAN/LAN/ other interfaces should be:

Direction: In
TCP/IP Version: IPv4/IPv6
Protocol: TCP
Source: Any
Destination: This Firewall
Destination Port Range: HTTP

A second rule with HTTPS should be made too.

The WAN rule makes sure external clients can connect to your domains, and that Let's Encrypt can issue the certificate.

The same rules on LAN allows your internal clients to connect to the same domains.

If you want to restrict access afterwards while retaining the Lets Encrypt functionality you can use basic auth or access lists (build into the plugin). Dont use Firewall rules for that.

If you dont get a certificate then, check that your FQDN resolves to the external IP Adress of your Firewall (A-Record).

Also, make sure you have the GUI redirect rule disabled, and have the WEB UI listen on an alternate port.

[bucky2780]

nice plugin... super simple !

Is it possible to defer certs to the opnsense trust store ? 
I already have LE generating certs there... and would like to use those, rather than have caddy own the process of creating/renewing the cert ?

------------ answer ------
I can see now, that you can select other cert if you use advanced option for the domain.