adam/jarl
1
0 Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 34 Wiki Activity

TLS certificates: Jarl obtains and renews them over ACME

Browse Source 
Jarl is now an ACME client (lego's core, no DNS providers). It answers
DNS-01 challenges in a zone it serves, or through Porkbun's DNS API while
Porkbun serves the domain; "auto" decides from the domain's public name
servers at every renewal, and a CNAME on _acme-challenge is followed.
Certificates are used for jarld's HTTPS (served without a restart; each
port speaks HTTPS and plain HTTP, plain HTTP from loopback and trusted
proxies still served) and/or written for named's DNS over TLS/HTTPS, with
rndc reconfig on renewal. Renewal follows the CA's ARI window or two
thirds of the lifetime, with back-off. Certificates you renew yourself
can be used too. Certificates page and dashboard card, jarl cert,
/api/v1/certificates, Prometheus gauges, docs/certificates.md, and an
e2e section against Pebble.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
adamandClaude Opus 5.5 committed 2026-10-12 14:35:53 +01:00
1 parent 88965096bb
commit 88f63ffb0a
43 files changed
+4584 -45
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/config/config.go
+138 -13
View File
@@ -40,6 +40,17 @@ type Config struct {
Porkbun Porkbun `yaml:"porkbun"`
Blocking Blocking `yaml:"blocking"`
Metrics Metrics `yaml:"metrics"`
// Certificates configures TLS certificates Jarl manages
// (docs/certificates.md); the ACME account is under acme.
Certificates Certificates `yaml:"certificates"`
}
// Certificates configures the certificates Jarl manages.
type Certificates struct {
// Dir is where certificates are written for named (DNS over TLS and
// HTTPS): one directory per certificate, readable by bind.file_group.
// "" is <bind.config_dir>/tls.
Dir string `yaml:"dir"`
}
// Metrics configures the Prometheus endpoint /metrics (docs/metrics.md).
@@ -183,9 +194,85 @@ type Backup struct {
WarnAfter Duration `yaml:"warn_after"`
}
// ACME configures the ACME helpers.
// ACME configures the ACME helpers and the account Jarl uses to obtain
// certificates itself.
type ACME struct {
HTTPReq HTTPReq `yaml:"httpreq"`
HTTPReq HTTPReq `yaml:"httpreq"`
Account ACMEAccount `yaml:"account"`
// Resolvers are the recursive resolvers used to see a domain as the
// CA does: its zone, its public name servers and any CNAME on
// _acme-challenge. Public resolvers by default, because this server's
// own answers may come from an internal view.
Resolvers []string `yaml:"resolvers"`
// CABundle is a PEM file of extra CA certificates to trust when
// talking to the ACME server (a private CA such as step-ca).
CABundle string `yaml:"ca_bundle"`
// CheckPropagation waits until every name server of the zone serves
// a challenge before telling the CA to look.
CheckPropagation bool `yaml:"check_propagation"`
}
// ACMEAccount is the ACME account certificates are obtained with.
type ACMEAccount struct {
// Directory is letsencrypt, letsencrypt-staging or an ACME directory URL.
Directory string `yaml:"directory"`
Email string `yaml:"email"`
// AgreeTOS says you accept the CA's terms of service. Jarl doesn't
// register an account without it.
AgreeTOS bool `yaml:"agree_tos"`
// EABKeyID and EABHMAC are External Account Binding credentials, for
// CAs that need them (ZeroSSL, Google).
EABKeyID string `yaml:"eab_kid"`
EABHMAC string `yaml:"eab_hmac"`
}
// Directory URLs for the names acme.account.directory accepts.
const (
LetsEncrypt = "https://acme-v02.api.letsencrypt.org/directory"
LetsEncryptStaging = "https://acme-staging-v02.api.letsencrypt.org/directory"
)
// DirectoryURL is the account's ACME directory URL.
func (a ACMEAccount) DirectoryURL() string {
switch a.Directory {
case "", "letsencrypt":
return LetsEncrypt
case "letsencrypt-staging":
return LetsEncryptStaging
}
return a.Directory
}
func (a *ACME) check() error {
if d := a.Account.Directory; d != "" && d != "letsencrypt" && d != "letsencrypt-staging" {
u, err := url.Parse(d)
if err != nil || u.Scheme != "https" || u.Host == "" {
return fmt.Errorf("account.directory must be letsencrypt, letsencrypt-staging or an https:// URL")
}
}
if a.Account.Email != "" && !strings.Contains(a.Account.Email, "@") {
return fmt.Errorf("account.email %q isn't an email address", a.Account.Email)
}
if (a.Account.EABKeyID == "") != (a.Account.EABHMAC == "") {
return fmt.Errorf("account: set both eab_kid and eab_hmac, or neither")
}
for _, r := range a.Resolvers {
if _, _, err := net.SplitHostPort(r); err != nil {
return fmt.Errorf("resolvers: %q must be address:port, e.g. 1.1.1.1:53 or [2606:4700:4700::1111]:53", r)
}
}
if a.CABundle != "" && !filepath.IsAbs(a.CABundle) {
return fmt.Errorf("ca_bundle must be an absolute path")
}
return nil
}
// CertDir is certificates.dir, or <bind.config_dir>/tls.
func (c *Config) CertDir() string {
if c.Certificates.Dir != "" {
return c.Certificates.Dir
}
return filepath.Join(c.BIND.ConfigDir, "tls")
}
// HTTPReq configures the endpoint for lego's httpreq DNS provider
@@ -372,7 +459,8 @@ func Default() *Config {
Retention: StatsRetention{Minute: Duration(7 * 24 * time.Hour), Hour: Duration(90 * 24 * time.Hour), Day: Duration(730 * 24 * time.Hour)},
TopN: 100,
},
ACME: ACME{HTTPReq: HTTPReq{RequireHTTPS: true}},
ACME: ACME{HTTPReq: HTTPReq{RequireHTTPS: true}, Account: ACMEAccount{Directory: "letsencrypt"},
Resolvers: []string{"1.1.1.1:53", "9.9.9.9:53", "8.8.8.8:53"}, CheckPropagation: true},
Blocking: Blocking{Refresh: Duration(24 * time.Hour), MaxDownloadMB: 64, MaxEntries: 1_000_000},
Metrics: Metrics{Allow: []string{"127.0.0.1", "::1"}},
Backup: Backup{Dir: "/var/backups/jarl", Retention: Duration(30 * 24 * time.Hour), KeepAtLeast: 7, WarnAfter: Duration(2 * 24 * time.Hour)},
@@ -449,6 +537,12 @@ func (c *Config) check() error {
if err := c.Metrics.check(); err != nil {
return fmt.Errorf("metrics: %w", err)
}
if err := c.ACME.check(); err != nil {
return fmt.Errorf("acme: %w", err)
}
if d := c.Certificates.Dir; d != "" && !filepath.IsAbs(d) {
return fmt.Errorf("certificates.dir must be an absolute path")
}
switch c.Log.Format {
case "text", "json":
default:
@@ -552,8 +646,10 @@ const Example = `# Jarl daemon configuration (/etc/jarl/jarl.yaml).
listen:
- "127.0.0.1:8053"
# HTTPS. The certificate is reread when the file changes (or on SIGHUP),
# so renewed Let's Encrypt certificates are picked up automatically.
# HTTPS from a certificate file you renew yourself. The certificate is
# reread when the file changes (or on SIGHUP). Easier: let Jarl obtain one
# ('jarl cert create ... --use web', docs/certificates.md), which then
# takes over from this.
tls:
cert_file: ""
key_file: ""
@@ -667,15 +763,44 @@ acme:
# this server. Leave false if a reverse proxy runs on this server but
# isn't in trusted_proxies: its requests would look local.
allow_loopback_http: false
# The account Jarl obtains certificates with (docs/certificates.md).
# Nothing is registered until you create a certificate. Read the CA's
# terms (https://letsencrypt.org/repository/) and set agree_tos: true.
# Try letsencrypt-staging first: its certificates aren't trusted, but
# its rate limits are generous.
account:
directory: letsencrypt # letsencrypt, letsencrypt-staging or a directory URL
email: "" # optional
agree_tos: false
eab_kid: "" # External Account Binding, only for CAs that need it
eab_hmac: ""
# Resolvers to see your domains as the CA does (their public name
# servers, a CNAME on _acme-challenge). Not this server: it may answer
# from an internal view.
resolvers: ["1.1.1.1:53", "9.9.9.9:53", "8.8.8.8:53"]
ca_bundle: "" # extra CA certificates for a private ACME server
# Wait until every name server of the zone serves a challenge before
# telling the CA to look (they are asked directly, on port 53).
check_propagation: true
# The registrar Porkbun (docs/dnssec.md#porkbun): with an API key, Jarl can
# show and set a domain's name servers, glue records and DNSSEC DS records
# there, after checking that the change won't break the domain. Off without
# a key. Create the key at porkbun.com (Account -> API Access), switch on
# "API Access" for the domain, and limit the key to that domain if you can.
# The key can move your domain elsewhere: it lives only in this file (keep
# it readable by root and jarld only: chown root:jarl, chmod 640), never in
# Jarl's database or backups.
# Where certificates with the "dns" use are written for named, one
# directory per certificate (fullchain.pem, privkey.pem), readable by
# bind.file_group. Default: <bind.config_dir>/tls.
certificates:
dir: ""
# Porkbun, as registrar and as DNS host. With an API key, Jarl can:
# - show and set a domain's name servers, glue records and DNSSEC DS
# records there, after checking that the change won't break the domain
# (docs/dnssec.md#porkbun);
# - publish the DNS-01 challenges of certificates Jarl obtains while
# Porkbun still serves the domain's DNS (docs/certificates.md): it adds
# and removes TXT records at _acme-challenge names only.
# Off without a key. Create the key at porkbun.com (Account -> API Access),
# switch on "API Access" for the domain, and limit the key to that domain
# if you can. The key can move your domain elsewhere: it lives only in this
# file (keep it readable by root and jarld only: chown root:jarl, chmod
# 640), never in Jarl's database or backups.
porkbun:
api_key: "" # pk1_...
secret_api_key: "" # sk1_...
internal/config/config_test.go
+2 -1
View File
@@ -3,6 +3,7 @@ package config
import (
"os"
"path/filepath"
"reflect"
"testing"
"time"
)
@@ -18,7 +19,7 @@ func TestExampleParses(t *testing.T) {
if c.BIND.ZoneDir != d.BIND.ZoneDir || time.Duration(c.Session.IdleTimeout) != 2*time.Hour || c.Listen[0] != "127.0.0.1:8053" {
t.Errorf("example differs from defaults: %+v", c)
}
if c.ACME != d.ACME || c.ACME.HTTPReq.Enabled || !c.ACME.HTTPReq.RequireHTTPS {
if !reflect.DeepEqual(c.ACME, d.ACME) || !reflect.DeepEqual(c.Certificates, d.Certificates) || c.ACME.HTTPReq.Enabled || !c.ACME.HTTPReq.RequireHTTPS {
t.Errorf("acme = %+v, want the defaults %+v", c.ACME, d.ACME)
}
}