« Blog Index
March 27, 2018

Caddy 0.10.12 Released with ACMEv2 and Wildcard Certificates

By Matt Holt

Caddy 0.10.12 is big news for HTTPS lovers: Caddy now uses ACMEv2, so it can obtain and renew wildcard certificates for you. In addition, we've brought the distributed auto-HTTPS support full-circle so that it doesn't require the DNS challenge. We've also fixed some bugs and made other improvements. Read on, since there's some things you should know when upgrading!


ACME is the protocol Caddy uses to obtain and renew certificates for you automatically. Recently, Let's Encrypt's implementation of ACME and the IETF-backed specification of ACME finally converged, and now we have ACME "v2". This new version of the protocol has mostly internal improvements, but it's a significant release because with an actual standard, we can now hope for other CAs to add ACME support in the future.

Important note: Since ACMEv2 is a breaking change and runs on a different production endpoint, Caddy will create a new CA account associated with your email address and get all new certificates for you. It's just as if you were running Caddy for the first time. This happens automatically, and we expect the transition to be perfectly smooth for most users. After you are confident that you will not revert to an older version of Caddy that uses ACMEv1, you may safely delete the ~/.caddy/acme/acme-v01.api.letsencrypt.org folder (make sure it's the acme-v01 folder!).

As before, providing an email when asked (or using the -email flag) is strongly recommended so you can be notified in case of problems with your certificate or account. For example, if renewals keep failing, the CA may send you a message informing you of the expiring certificate. You can choose not to provide an email and leave it blank, but that will make things more difficult if something goes wrong.

Wildcard Certificates

This release introduces support for wildcard certificates, a new offering from Let's Encrypt. Getting a wildcard certificate requires enabling the DNS challenge. Fortunately, that is extremely simple with Caddy, and it works with over 20 different providers!

Caddy now supports automated wildcard certificates

Using Caddy to get wildcard certificates is as easy and intuitive as you would expect:

*.example.com tls { dns provider }

Just like any other site, Caddy will obtain and manage a certificate for this site. The fact that it's a wildcard doesn't even matter, except that you won't hit Let's Encrypt rate limits if you have a lot of subdomains! It "just works" when the site name matches the qualifying pattern. A qualifying name is one which has only one wildcard, and it is the left-most label of the domain. In other words, *.sub.example.com is valid, but *.*.example.com is not, nor are any of these: *bar.example.com, foo*.example.com, *, or foo.*.example.com.

Sometimes you can't group all your subdomains together in the same site definition like that. If you have many different sites defined in your Caddyfile which are all subdomains of the same base domain, you can still hit Let's Encrypt rate limits. This is unchanged from before. But now you can explicitly request a wildcard certificate to share across all of them with the wildcard subdirective of tls. For example:

(wildcard_cert) { tls { dns provider wildcard } } sub1.example.com { import wildcard_cert ... } . . . sub1000000.example.com { import wildcard_cert ... }

All these sites will use the same certificate: a single wildcard certificate for *.example.com.

Important note: We strongly discourage the use of wildcard certificates except when rate limits would be a hindrance. It is good practice to narrow the scope of your credentials. A compromised wildcard certificate will cause more fallout than a regular certificate. We do not recommend using wildcards just because you can. Remember: with Caddy, you don't have to manage them, so there is no added convenience for you. Wildcard certificates are a helpful utility to overcome rate limits and improve efficiency for extremely dynamic services/apps.

Improved Automatic HTTPS in a Cluster

In 0.10.11, we made it possible for Caddy to synchronize certificate maintenance in fleet configurations as long as they all mounted the same shared folder and configured the DNS challenge. Today, I'm pleased to announce that the DNS challenge is no longer required to obtain certificates behind a load balancer. Caddy's automatic HTTPS can "just work" behind a load balancer or in other cluster configurations as long as they simply share the same ~/.caddy/acme folder.

Caddy can now solve the HTTP challenge even if it was initiated by a different instance. Each instance can be on different machines—even separate networks, and behind firewalls and NAT (as long as the port 80 challenge request can get through to one instance). No extra configuration is required to make this work, except for mounting the shared ~/.caddy/acme folder locally.

Caddy obtaining its first certificate synchronized in a cluster Caddy's first certificate in a cluster. This screenshot captures the first time Caddy obtained a certificate in a cluster. The instance on the right was not externally reachable, and the instance on the left was being pointed to by the network's edge router and was actively serving a site. The instance on the right initiated a request to get a certificate, and the instance on the left completed the challenge successfully. The two instances can then share the same certificate. No extra configuration was required. (Amazingly, this worked successfully the first time I ran it!)

The HTTP challenge is a convenient, configuration-free way for Caddy to obtain certificates, and now it works no matter which instance your load balancer routes the request to. One instance can finish a challenge another one started. This means your load balancer doesn't have to terminate TLS, and you don't necessarily have to use Caddy as your load balancer either (but it's still awesome for that).

Yet again, Caddy is the first and only web server to do this. No other server can coordinate certificate management as a fleet, automatically.

{labelN} Placeholders

Have you ever wanted to rewrite a request to a folder based on a subdomain? Well, now you can! The {labelN} placeholders make this simple. {label1} corresponds to sub in sub.example.com, and {label2} corresponds to example.

Here's an example:

*.example.com rewrite { to /{label1}{uri} }

For a request like https://foo.example.com/bar.html, this will rewrite the request URI to /foo/bar.html. This is great if you dynmically create folders in your site root for subdomains you want to serve.

Minimum TLS Version is 1.2

We've upped the default minimum TLS version to 1.2, which is also the maximum version (for now). Older TLS versions 1.0 and 1.1 can still be enabled if needed, but we discourage this. Instead, please phase out older clients and upgrade to secure protocols.

Removed startup/shutdown Directives

Several versions ago, the startup and shutdown directives were deprecated in favor of the single on directive. We've removed them entirely now, cleaning up our code base a bit and making more event-driven hooks to be possible in the future.

Other Goodies

That's not all—a few other improvements come with this release!

You can now escape curly braces { } so they won't be treated as placeholders. For example, if you're defining a custom log format, you can have simple JSON-formatted logs by escaping the curly braces: \{"status": {status}, "remote": "{remote}"\}. (This works for simple log entries; we haven't yet implemented a way to safely escape the expanded placeholder values so they don't violate the JSON syntax. Pull requests welcome!)

The log directive also has a new except subdirective so you can exempt requests at certain base paths from being logged at all. (Use with care!)

There's also a new third-party plugin, geoip which geolocates client IP addresses with a database, and

We've also fixed a few bugs that you reported (including that one related to self-signed certificates). Thanks—keep up the helpful bug reports!

Thank You

I want to personally extend a huge thank-you to Sebastian Erhart, author of the xenolf/lego package, which makes Caddy's magical ACME integration possible. He is a busy person and has devoted some precious time to making it ACMEv2-compatible.

And thank you to everyone else who made this release happen, especially for your pull requests and code reviews!

Coming Up

We're already busy preparing the 0.11 release, scheduled for April sometime. Stay tuned!

« Blog Index