lancert — Use Your Own ACME Client

01

Register the target IP

The target is the private IPv4 address that Lancert will publish through DNS. Registration returns the hostname and scoped acme-dns credentials.

Terminal

curl --fail-with-body -X POST \
  https://lancert.dev/register/192.168.1.50

Response

{
  "hostname": "quiet-otter.lancert.dev",
  "username": "00000000-0000-0000-0000-000000000000",
  "password": "one-time-secret",
  "subdomain": "quiet-otter",
  "fulldomain": "_acme-challenge.quiet-otter.lancert.dev"
}

Save this response now. Lancert returns the password only once and provides no credential recovery or rotation endpoint. Replace the example values below with your response.

02

Obtain the certificate

Choose a client below. In every case the client sends DNS-01 values to Lancert through its acme-dns-compatible API. The examples use Let's Encrypt, but Lancert is independent of the CA: replace the ACME server option to use another RFC 8555-compatible CA.

Lego through acme-dns

Lego's acme-dns provider reads an account-storage file. Create ~/.config/lancert/acmedns.json with the values returned above:

Terminal

mkdir -p "$HOME/.config/lancert"
chmod 700 "$HOME/.config/lancert"

~/.config/lancert/acmedns.json

{
  "quiet-otter.lancert.dev": {
    "username": "00000000-0000-0000-0000-000000000000",
    "password": "one-time-secret",
    "subdomain": "quiet-otter",
    "fulldomain": "_acme-challenge.quiet-otter.lancert.dev"
  }
}

Terminal

chmod 600 "$HOME/.config/lancert/acmedns.json"

ACME_DNS_API_BASE=https://lancert.dev \
ACME_DNS_STORAGE_PATH="$HOME/.config/lancert/acmedns.json" \
lego --email you@example.com --accept-tos --dns acmedns \
  --domains quiet-otter.lancert.dev \
  --domains '*.quiet-otter.lancert.dev' run

Files: .lego/certificates/quiet-otter.lancert.dev.crt and .key.

Certbot through an acme-dns adapter

Certbot's manual DNS mode uses an authentication-hook file. Create ~/.config/lancert/certbot-auth.sh with the values returned above:

Terminal

mkdir -p "$HOME/.config/lancert"
chmod 700 "$HOME/.config/lancert"

~/.config/lancert/certbot-auth.sh

#!/bin/sh
set -eu
curl --fail-with-body --silent --show-error \
  -H 'X-Api-User: 00000000-0000-0000-0000-000000000000' \
  -H 'X-Api-Key: one-time-secret' \
  -H 'Content-Type: application/json' \
  --data "{\"subdomain\":\"quiet-otter\",\"txt\":\"$CERTBOT_VALIDATION\"}" \
  https://lancert.dev/update

# Give authoritative DNS a moment before Certbot starts validation.
sleep 2

Terminal

chmod 700 "$HOME/.config/lancert/certbot-auth.sh"

certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook "$HOME/.config/lancert/certbot-auth.sh" \
  --server https://acme-v02.api.letsencrypt.org/directory \
  --non-interactive --agree-tos --email you@example.com \
  -d quiet-otter.lancert.dev \
  -d '*.quiet-otter.lancert.dev'

Files: /etc/letsencrypt/live/quiet-otter.lancert.dev/fullchain.pem and privkey.pem.

acme.sh through its acme-dns provider

Pass the registration values directly to acme.sh's generic dns_acmedns provider:

Terminal

ACMEDNS_BASE_URL=https://lancert.dev \
ACMEDNS_USERNAME=00000000-0000-0000-0000-000000000000 \
ACMEDNS_PASSWORD=one-time-secret \
ACMEDNS_SUBDOMAIN=quiet-otter \
acme.sh --issue --dns dns_acmedns --server letsencrypt \
  -d quiet-otter.lancert.dev \
  -d '*.quiet-otter.lancert.dev'

Files: use acme.sh --install-cert to copy the certificate and key to the paths used by your web server. Do not serve files directly from acme.sh's internal directory.

03

Configure the web server

Point your web server at the certificate and private key produced by your client. Replace the example hostname and paths below.

Lego writes under .lego/certificates, Certbot under /etc/letsencrypt/live, and acme.sh installs to the paths selected with --install-cert. Ensure the web server can read the private key without making it publicly readable.

Caddyfile

quiet-otter.lancert.dev, *.quiet-otter.lancert.dev {
    tls /path/to/fullchain.pem /path/to/privkey.pem
    reverse_proxy 127.0.0.1:3000
}

Reload with caddy reload --force --config /path/to/Caddyfile.

nginx.conf

server {
    listen 443 ssl;
    server_name quiet-otter.lancert.dev *.quiet-otter.lancert.dev;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / { proxy_pass http://127.0.0.1:3000; }
}

Validate and reload with nginx -t && nginx -s reload.

dynamic/lancert.yml

tls:
  certificates:
    - certFile: /path/to/fullchain.pem
      keyFile: /path/to/privkey.pem

Enable providers.file.watch. After renewal, touch the watched dynamic configuration file to reload the certificate.

04

Renew the certificate

Run the native renewal command for your client. The examples reuse the account and client state created above.

Terminal

ACME_DNS_API_BASE=https://lancert.dev \
ACME_DNS_STORAGE_PATH="$HOME/.config/lancert/acmedns.json" \
lego \
  --email you@example.com --dns acmedns \
  --domains quiet-otter.lancert.dev \
  --domains '*.quiet-otter.lancert.dev' \
  renew --days 30

Terminal

certbot renew

Terminal

acme.sh --cron

When configured with --install-cert, acme.sh updates the selected files after successful renewal.

After renewal, reload Caddy or Nginx; for Traefik, touch the watched dynamic configuration file. Schedule the renewal command and reload with your preferred system timer.