Skip to content

SSL Certificates

PegaProx checks for SSL certificates in the following priority order:

  1. Persisted config directory - config/ssl/cert.pem + config/ssl/key.pem (a top-level ssl/cert.pem from older installs is auto-migrated here on first start).
  2. Self-signed - auto-generated certificate, created on first start.

Using Custom Certificates (Let's Encrypt, etc.)

To use your own SSL certificates (e.g. from Let's Encrypt), upload them via the PegaProx Web UI:

  1. Go to Settings → Server → SSL Certificates

  2. Upload your certificate file (cert.pem / fullchain.pem)

  3. Upload your private key file (key.pem / privkey.pem)

  4. PegaProx will restart automatically with the new certificate

Alternatively, place certificates manually in the config/ssl/ directory as cert.pem and key.pem, then restart PegaProx.

ACME / Let's Encrypt (Automatic)

PegaProx has built-in ACME support for automatic certificate issuance and renewal via Let's Encrypt:

  1. Go to Settings → Server → SSL Certificates → ACME

  2. Enter your domain name (must point to this server via DNS)

  3. Accept the Let's Encrypt Terms of Service and provide a contact email

  4. Click Request Certificate - PegaProx handles the HTTP-01 challenge automatically

ACME requires port 80 to be reachable from the internet for the HTTP-01 challenge. If you're behind a reverse proxy, forward /.well-known/acme-challenge/ to PegaProx. Certificates are renewed automatically before expiry.

Self-Signed Certificate (Default)

If no custom certificate is provided, PegaProx automatically generates a self-signed certificate on first start. You can also generate one manually:

mkdir -p ssl
openssl req -x509 -newkey rsa:4096 -keyout ssl/key.pem -out ssl/cert.pem \
  -days 365 -nodes -subj "/CN=PegaProx"

Certificate Details

Auto-generated self-signed certificates use RSA 2048-bit keys with 365-day validity. Key file permissions are set to 0600 (owner read/write only).

ACME / Let's Encrypt Details

Setting Detail
ACME Endpoint acme-v02.api.letsencrypt.org (v2 API)
Challenge Types HTTP-01 (default) or DNS-01 via RFC 2136 dynamic update v0.9.12
Challenge Validation 30 attempts × 2s = 60s max
Certificate Polling 15 attempts × 2s = 30s max
Auto-Renewal Daily thread, renews 30 days before expiry

Staging endpoint available under Settings → SSL → Use Staging for testing without hitting rate limits.

HTTP-01 challenge path served at /.well-known/acme-challenge/<token> on port 80.

Warning: If using a reverse proxy with HTTP-01, ensure /.well-known/acme-challenge/ requests are forwarded to PegaProx on port 80. HTTPS-only proxies will break HTTP-01 validation. DNS-01 sidesteps this entirely - recommended for any setup behind CGNAT, with no port-80 reachability, or when issuing wildcard certificates.

ACME DNS-01 Challenge (RFC 2136) v0.9.12

For sites that aren't reachable on port 80 from the public internet - datacenter networks, CGNAT'd home labs, behind-VPN management planes - PegaProx can use the DNS-01 challenge instead. PegaProx publishes a temporary _acme-challenge.<domain> TXT record via RFC 2136 dynamic update (the protocol used by ISC BIND, PowerDNS, Knot DNS, and most managed DNS providers). Wildcard certificates (e.g. *.internal.example.com) are also supported via DNS-01.

Configure TSIG on your DNS server

Generate a TSIG key and grant it update permission for the zone you want PegaProx to manage. Example for BIND:

named.conf

key "pegaprox-acme" {
    algorithm hmac-sha512;
    secret "<base64-encoded-secret>";
};

zone "internal.example.com" {
    type master;
    file "internal.example.com.db";
    update-policy {
        grant pegaprox-acme name _acme-challenge.internal.example.com. TXT;
        grant pegaprox-acme name _acme-challenge.*.internal.example.com. TXT;
    };
};

Pick DNS-01 in the PegaProx UI

Settings → Server → SSL Certificates → ACME. Switch Challenge Type to DNS-01 (RFC 2136).

Enter your DNS server credentials

Fill in the server address (IP or hostname of your authoritative DNS server), TSIG key name, TSIG algorithm (default hmac-sha512), and the base64-encoded secret. The full algorithm matrix is available: hmac-sha512, hmac-sha384, hmac-sha256, hmac-sha224, hmac-sha1, hmac-md5.

Request the certificate

PegaProx submits the order, publishes the _acme-challenge.<domain> TXT record via RFC 2136, waits for Let's Encrypt to validate, then deletes the record. Renewal uses the same flow automatically.

Tip: TSIG keys are stored encrypted at rest in the SQLCipher DB and never logged. The DNS server only needs to accept dynamic updates for the _acme-challenge subdomain - you can scope the key as tightly as your DNS server's update-policy grammar allows.

Field Description
dns_server IP or hostname of the authoritative DNS server accepting dynamic updates
dns_port UDP/TCP port (default 53)
tsig_key_name Name of the TSIG key as configured on the DNS server
tsig_algorithm One of hmac-sha512 (default), hmac-sha384, hmac-sha256, hmac-sha224, hmac-sha1, hmac-md5
tsig_secret Base64-encoded shared secret - stored encrypted at rest