English Forums > Tutorials and FAQs

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

(1/5) > >>

Monviech:
Like this plugin? Consider donating to me. 8)



This plugin is part of OPNsense Plugins since Community Edition 24.1.4.

os-caddy plugin source code: https://github.com/opnsense/plugins/tree/master/www/caddy
os-caddy plugin docs: https://docs.opnsense.org/manual/how-tos/caddy.html
os-caddy DNS Provider issue tracker: https://github.com/opnsense/plugins/issues/3872

Caddy source code: https://github.com/caddyserver/caddy
Caddy docs: https://caddyserver.com/docs/
Caddy forum: https://caddy.community/


This plugin is simple to use and far easier to configure than most other reverse proxy plugins available.

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

1. How to install
2. Prepare OPNsense for Caddy after installation
3. Creating a simple reverse proxy

- For Dynamic DNS follow this additional step:

4. Using dynamic DNS


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:
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!

Navigation

[0] Message Index

[#] Next page