ACME Clients#

This guide covers installation and system-level configuration of ACME clients for use with acme-proxy. It is intended for system administrators deploying certificate automation on behalf of end users.

For certificate issuance commands and per-scenario usage, see user.md.

Table of Contents#

Installing ACME Clients
Account Registration
Configuring Auto-Renewal via Systemd
Log Management

Installing ACME Clients#

Certbot

Note: Certbot’s actively maintained distribution is via Snap. The .deb packages available in apt repositories are no longer maintained by the Certbot project and ship outdated versions.

Install via Snap:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot

The Snap package installs certbot.timer and certbot.service systemd units automatically.

For the NGINX plugin:

sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-nginx

For the Apache plugin:

sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-apache

acme.sh

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y acme.sh socat

RHEL / Rocky / AlmaLinux — requires EPEL:

sudo dnf install -y epel-release
sudo dnf install -y acme.sh socat

The package installs the binary to /usr/bin/acme.sh. Use /etc/acme.sh as the configuration home for system-wide installations (passed via --home in all commands).

socat is required for standalone mode. acme.sh uses socat to bind port 80 for HTTP-01 challenges in standalone mode. It is installed above alongside acme.sh. This is not required if you use NGINX or Apache plugin mode.

Lego

Lego has no official packages in major Linux distribution repositories. Install the release binary directly:

LEGO_VERSION=4.33.0
curl -fsSL "https://github.com/go-acme/lego/releases/download/v${LEGO_VERSION}/lego_v${LEGO_VERSION}_linux_amd64.tar.gz" \
  | tar xz lego
sudo install -o root -g root -m 0755 lego /usr/local/bin/lego
rm lego
lego --version

Verify the checksum from the GitHub releases page before deploying to production. Pin LEGO_VERSION in your configuration management tool and treat upgrades as a deliberate change.

Account Registration#

Each ACME client must register an account with acme-proxy before any certificates can be issued. This is a one-time step per host.

Certbot

Certbot registers automatically on first use. No separate registration step is required.

acme.sh

sudo acme.sh --register-account \
  --server https://acme-proxy.example.com/acme/acme/directory \
  --email admin@example.com \
  --home /etc/acme.sh

Lego

Lego registers automatically on the first run invocation. No separate registration step is required.

Configuring Auto-Renewal via Systemd#

Replacing cron-based renewal with systemd timers provides:

Missed-run recovery via Persistent=true — if the system was off at the scheduled time, the timer fires on next boot.
Structured log output to the systemd journal, queryable and forwardable to syslog.
Visibility via systemctl list-timers.

All service units below set SyslogIdentifier so logs can be filtered by tag regardless of which syslog daemon is in use.

Certbot

The Snap-installed certbot ships certbot.timer and certbot.service units automatically. Enable the timer and confirm it is active:

sudo systemctl enable --now certbot.timer
systemctl status certbot.timer

Configure the SyslogIdentifier so certbot’s renewal logs are tagged consistently alongside other ACME clients:

sudo mkdir -p /etc/systemd/system/certbot.service.d
sudo tee /etc/systemd/system/certbot.service.d/logging.conf <<'EOF'
[Service]
StandardOutput=journal
StandardError=journal
SyslogIdentifier=certbot-renewal
EOF
sudo systemctl daemon-reload

Test renewal without issuing:

sudo certbot renew --dry-run

acme.sh

acme.sh’s --cron flag iterates over all configured certificates and renews those expiring within 30 days. A single service and timer unit covers all certificates on the host.

Create the service unit:

sudo tee /etc/systemd/system/acme-renewal.service <<'EOF'
[Unit]
Description=Renew ACME certificates (acme.sh)
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=root
ExecStart=/usr/bin/acme.sh --cron --home /etc/acme.sh
StandardOutput=journal
StandardError=journal
SyslogIdentifier=acme-renewal
EOF

Create the timer unit:

sudo tee /etc/systemd/system/acme-renewal.timer <<'EOF'
[Unit]
Description=Daily ACME certificate renewal check (acme.sh)

[Timer]
OnCalendar=daily
RandomizedDelaySec=1h
Persistent=true

[Install]
WantedBy=timers.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now acme-renewal.timer

Verify:

systemctl status acme-renewal.timer
systemctl list-timers acme-renewal.timer

Lego

Lego has no built-in renewal scheduling. Create service and timer units manually.

Unlike acme.sh and certbot, lego’s renew command targets one domain at a time. If you manage multiple certificates, use a wrapper script.

Wrapper script for multiple certificates:

sudo tee /usr/local/sbin/lego-renew-all.sh <<'EOF'
#!/bin/bash
set -euo pipefail

LEGO=/usr/local/bin/lego
SERVER=https://acme-proxy.example.com/acme/acme/directory
EMAIL=admin@example.com

# Add each managed domain below
domains=(
  myserver.example.com
  anotherserver.example.com
)

for domain in "${domains[@]}"; do
  "$LEGO" \
    --server "$SERVER" \
    --accept-tos \
    --email "$EMAIL" \
    --http \
    -d "$domain" \
    renew
done
EOF
sudo chmod 0700 /usr/local/sbin/lego-renew-all.sh

Create the service unit:

sudo tee /etc/systemd/system/lego-renewal.service <<'EOF'
[Unit]
Description=Renew ACME certificates (lego)
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=root
ExecStart=/usr/local/sbin/lego-renew-all.sh
StandardOutput=journal
StandardError=journal
SyslogIdentifier=lego-renewal
EOF

Create the timer unit:

sudo tee /etc/systemd/system/lego-renewal.timer <<'EOF'
[Unit]
Description=Daily ACME certificate renewal check (lego)

[Timer]
OnCalendar=daily
RandomizedDelaySec=1h
Persistent=true

[Install]
WantedBy=timers.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now lego-renewal.timer

Verify:

systemctl status lego-renewal.timer
systemctl list-timers lego-renewal.timer

Log Management#

All service units above write to the systemd journal with a unique SyslogIdentifier. Logs are accessible via journalctl and forwarded to syslog if your system runs rsyslog or syslog-ng with journal forwarding enabled.

Filter renewal logs by client:

Client	Command
Certbot	`journalctl -t certbot-renewal`
acme.sh	`journalctl -t acme-renewal`
Lego	`journalctl -t lego-renewal`

Follow logs in real time:

journalctl -t acme-renewal -f

Forward to syslog — rsyslog:

Ensure the journal input module is loaded in /etc/rsyslog.conf or a drop-in under /etc/rsyslog.d/:

module(load="imjournal" StateFile="imjournal.state")

Forward to syslog — syslog-ng:

Ensure the systemd-journal source is present in your syslog-ng configuration:

source s_systemd { systemd-journal(); };

Log retention:

Journal retention is controlled by /etc/systemd/journald.conf. Set MaxRetentionSec and SystemMaxUse appropriate to your environment:

[Journal]
SystemMaxUse=500M
MaxRetentionSec=90day

Apply changes with:

sudo systemctl restart systemd-journald