Emergency server help: get in touch

Run a Script After Every DirectAdmin Certificate Renewal: domain_tls_cert_save_post.sh (Tested)

The DirectAdmin 1.712 certificate hook: the variables it receives, a tested script that copies the renewed certificate to another service, and what happens when it fails.

Published Updated 12 min read

Short answer: The DirectAdmin certificate renewal hook added in 1.712 is /usr/local/directadmin/scripts/custom/domain_tls_cert_save_post.sh. It runs as root each time DirectAdmin saves a domain certificate, once per certificate, and receives domain, cert_id, username, dns_names and the cert, key and chain file paths (relative to /usr/local/directadmin on our server). Use it to copy a renewed certificate to a service DirectAdmin does not manage. A non-zero exit is logged but does not stop the certificate being installed. (Reviewed October 2026.)

Before 1.712, copying a DirectAdmin certificate to another program meant a cron job that compared files. The new DirectAdmin certificate renewal hook does it at the right moment. We installed a logging version first to see exactly what DirectAdmin passes, then a working copy script, and tested what happens when the script fails.

What DirectAdmin passes to the hook

VariableExample from our server
usernameadmin
domainexample.com (the parent domain, also for a pointer’s certificate)
cert_idexample.com, or the pointer name for a pointer’s own certificate
dns_namesspace-separated: blog.example.com ftp.example.com mail.example.com … www.example.com
cert_file_pathdata/users/admin/domains/example.com.cert
key_file_pathdata/users/admin/domains/example.com.key
chain_file_pathdata/users/admin/domains/example.com.cacert

On our 1.712 server the three paths were relative to /usr/local/directadmin, so build the full path yourself; the script below accepts relative and absolute paths in case a later version changes this. The script ran as root (uid 0). The variable list matches DirectAdmin’s hook documentation.

When it ran

  • After a certificate request run by hand with da taskq --run "action=rewrite&value=letsencrypt&domain=example.com".
  • After the same task was queued and picked up by DirectAdmin’s background task runner (dataskq), which is the path normal renewals use.
  • Once per certificate: a domain with an alias pointer produced two runs, one with cert_id=example.com and one with cert_id=alias.example.

We did not wait for a scheduled renewal, and we could not test a manually pasted certificate: our attempt through the legacy CMD_API_SSL paste returned “Key is Invalid”, so that path remains untested.

A DirectAdmin certificate renewal hook script to adapt

This version copies one certificate to /etc/pki/myapp for a service DirectAdmin does not manage. Set the values at the top. Before it touches the destination it checks that the certificate and key are readable and belong together, and it refuses a destination file that is a link or a directory. It then saves a copy of the current pair (and stops if that copy cannot be made and checked), stages the new files in the destination folder and moves them into place with one rename each. If a rename or the reload fails, it puts the previous pair back, checks it and reloads again; if even that fails, it says whether the files left in place still match each other. A lock stops two saves from interleaving. Every failure is written to its own log and makes the script exit 1, which DirectAdmin records without blocking the certificate.

#!/bin/bash
# /usr/local/directadmin/scripts/custom/domain_tls_cert_save_post.sh
# Copies one DirectAdmin certificate to another service each time DirectAdmin saves it.
WANT="example.com"                  # cert_id to export
DEST="/etc/pki/myapp"               # folder the other service reads
OWNER="root:root"                   # owner of the copies, e.g. root:myapp
RELOAD="true"                       # e.g. "systemctl reload myapp" ("true" = nothing)
LOG="/var/log/directadmin/tls-hook.log"

[ "${cert_id:-}" = "$WANT" ] || exit 0
umask 077
log()  { echo "$(date -Is) $cert_id: $*" >> "$LOG"; }
fail() { log "FAILED: $*"; echo "tls-hook: $*"; exit 1; }
full() { case "$1" in "") ;; /*) echo "$1";; *) echo "/usr/local/directadmin/$1";; esac; }
match() { local a b; a=$(openssl x509 -noout -pubkey -in "$1" 2>/dev/null); b=$(openssl pkey -pubout -in "$2" 2>/dev/null); [ -n "$a" ] && [ "$a" = "$b" ]; }

exec 9>/run/lock/tls-hook.lock
flock -w 120 9 || fail "another run still holds the lock"

crt=$(full "${cert_file_path:-}"); key=$(full "${key_file_path:-}"); chn=$(full "${chain_file_path:-}")
[ -n "$crt" ] && openssl x509 -noout -in "$crt" 2>/dev/null || fail "certificate missing or unreadable: ${crt:-not passed}, nothing copied"
[ -n "$key" ] && openssl pkey -noout -in "$key" 2>/dev/null || fail "key missing or unreadable: ${key:-not passed}, nothing copied"
match "$crt" "$key" || fail "key does not match certificate, nothing copied"

install -d -m 750 "$DEST" || fail "cannot create $DEST"
for f in fullchain.pem privkey.pem; do
  if [ -L "$DEST/$f" ] || { [ -e "$DEST/$f" ] && [ ! -f "$DEST/$f" ]; }; then fail "$DEST/$f is a link or not a regular file, nothing copied"; fi
done
stage=$(mktemp -d "$DEST/.stage.XXXXXX") || fail "cannot create a staging folder in $DEST"
trap 'rm -rf "$stage"' EXIT
cat "$crt" > "$stage/fullchain.pem" || fail "cannot write the staged certificate"
# Append the chain unless the certificate file already carries it.
if [ -s "$chn" ] && [ "$(grep -c 'BEGIN CERTIFICATE' "$crt")" -eq 1 ]; then
  openssl x509 -noout -in "$chn" 2>/dev/null || fail "chain file unreadable: $chn, nothing copied"
  cat "$chn" >> "$stage/fullchain.pem" || fail "cannot write the staged chain"
fi
cp "$key" "$stage/privkey.pem" || fail "cannot write the staged key"
chmod 640 "$stage/fullchain.pem" && chmod 600 "$stage/privkey.pem" || fail "chmod failed, nothing copied"
chown "$OWNER" "$stage/fullchain.pem" "$stage/privkey.pem" || fail "chown $OWNER failed, nothing copied"
match "$stage/fullchain.pem" "$stage/privkey.pem" || fail "staged copy does not match, nothing copied"
new_end=$(openssl x509 -noout -enddate -in "$stage/fullchain.pem") || fail "cannot read the staged expiry date"

# Keep the current pair for rollback; stop if that copy cannot be made and checked.
had_prev=0
if [ -f "$DEST/fullchain.pem" ] && [ -f "$DEST/privkey.pem" ]; then
  { rm -rf "$DEST/.prev" && mkdir -m 700 "$DEST/.prev" &&
    cp -p "$DEST/fullchain.pem" "$DEST/.prev/fullchain.pem" && cp -p "$DEST/privkey.pem" "$DEST/.prev/privkey.pem" &&
    cmp -s "$DEST/fullchain.pem" "$DEST/.prev/fullchain.pem" && cmp -s "$DEST/privkey.pem" "$DEST/.prev/privkey.pem"; } ||
    fail "could not back up the current pair, nothing copied"
  had_prev=1
elif [ -e "$DEST/fullchain.pem" ] || [ -e "$DEST/privkey.pem" ]; then
  fail "only one of fullchain.pem and privkey.pem exists in $DEST, nothing copied"
fi

# Put the saved pair back: copy every file that changed into the staging folder first (nothing in DEST changes
# if a copy fails), then one rename per file, then check both files against the saved pair.
restore() {
  local f todo=""
  [ "$had_prev" = 1 ] || return 1
  for f in privkey.pem fullchain.pem; do
    cmp -s "$DEST/.prev/$f" "$DEST/$f" && continue
    cp -p "$DEST/.prev/$f" "$stage/$f" || return 1
    todo="$todo $f"
  done
  for f in $todo; do mv -fT "$stage/$f" "$DEST/$f" || return 1; done
  cmp -s "$DEST/.prev/privkey.pem" "$DEST/privkey.pem" && cmp -s "$DEST/.prev/fullchain.pem" "$DEST/fullchain.pem"
}
state() { match "$DEST/fullchain.pem" "$DEST/privkey.pem" && echo "the files in $DEST match each other" || echo "the files in $DEST DO NOT match, fix them now"; }

# Publish: one rename per file (same file system), then check what is in place.
if ! { mv -fT "$stage/privkey.pem" "$DEST/privkey.pem" && mv -fT "$stage/fullchain.pem" "$DEST/fullchain.pem" &&
       match "$DEST/fullchain.pem" "$DEST/privkey.pem"; }; then
  if restore; then
    $RELOAD >> "$LOG" 2>&1
    fail "could not publish the new pair; previous pair restored"
  elif [ "$had_prev" = 0 ]; then
    rm -f "$DEST/fullchain.pem" "$DEST/privkey.pem"
    fail "could not publish the new pair; the half-published files were removed (there was no previous pair)"
  fi
  fail "could not publish the new pair and could not restore the previous one; $(state)"
fi

if ! $RELOAD >> "$LOG" 2>&1; then
  if restore; then
    if $RELOAD >> "$LOG" 2>&1; then fail "reload failed with the new certificate; previous pair restored and reloaded"; fi
    fail "reload failed with the new certificate; previous pair restored, but the reload failed again"
  fi
  fail "reload failed with the new certificate and the previous pair could not be restored; $(state)"
fi
log "copied, $new_end"
exit 0
chmod 700 /usr/local/directadmin/scripts/custom/domain_tls_cert_save_post.sh
bash -n /usr/local/directadmin/scripts/custom/domain_tls_cert_save_post.sh && echo syntax ok

If the other service reads the key as its own user, set OWNER to root:thatgroup and change chmod 600 on the key to 640, rather than opening the file to everyone. The previous pair stays in DEST/.prev/ until the next successful run. To remove the hook, delete the script; DirectAdmin carries on as before and the copies already made stay where they are. Two renames are not one atomic step: a service that reads the files at the exact moment between them sees the new key with the old certificate. If that matters, point the service at a versioned folder through a single symlink and switch the symlink instead.

Test it without waiting for a renewal

The quickest test that does not involve the certificate authority is to save the domain’s current certificate again through the API. DirectAdmin ran the hook for this on our server, and the certificate, its expiry and auto-renewal stayed as they were. The JSON body holds the private key, so keep it in a root-only file and delete it afterwards:

umask 077; f=/usr/local/directadmin/data/users/USER/domains/example.com
python3 - "$f" > /root/put.json <<'P'
import sys, json, re
b = sys.argv[1]
chain = re.findall(r'-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----\n?', open(b + '.cacert').read(), re.S)
print(json.dumps({'cert': open(b + '.cert').read(), 'key': open(b + '.key').read(), 'chain': chain}))
P
curl -sk -o /dev/null -w '%{http_code}\n' -X PUT -H 'Content-Type: application/json' --data @/root/put.json \
  "$(da api-url --user=USER)/api/domain-tls/example.com/certs/example.com/files"
rm -f /root/put.json
tail -2 /var/log/directadmin/tls-hook.log

Or request the certificate again for the domain. This counts against the certificate authority’s limits (Let’s Encrypt allows 5 duplicate certificates per week for the same set of names), so do it once, not in a loop:

da taskq --run "action=rewrite&value=letsencrypt&domain=example.com"
tail -2 /var/log/directadmin/tls-hook.log
a=$(openssl x509 -noout -pubkey -in /etc/pki/myapp/fullchain.pem)
b=$(openssl pkey -pubout -in /etc/pki/myapp/privkey.pem)
[ -n "$a" ] && [ "$a" = "$b" ] && echo "key matches" || echo "KEY MISMATCH or unreadable file"
grep -c 'BEGIN CERTIFICATE' /etc/pki/myapp/fullchain.pem    # leaf plus intermediates

On our server the log showed the copy with the new expiry date, the chain file had the leaf plus the intermediates, and the key matched. If da taskq reports that no names were requested, the certificate is still valid and DirectAdmin only orders missing names; see DirectAdmin certificate not renewing for how renewals are triggered.

If the script fails

We made the hook print a message and exit 1. DirectAdmin still saved and served the new certificate, and logged the failure: on a manual run it appeared in the da taskq output as error running post hook … exit code 1: hook-says-failed; on a queued run it went to the system journal under dataskq. Find it with:

journalctl -t dataskq --since today | grep "post hook"

Nothing in the panel shows these errors, which is why the example writes its own log as well as exiting 1. Exim and Dovecot are managed by DirectAdmin and do not need this hook; if they keep serving an old certificate, see Exim or Dovecot still serving the old certificate.

How we tested

  • Server: DirectAdmin 1.712 on AlmaLinux 9.8 with Apache 2.4 (CustomBuild), Let’s Encrypt staging certificates, 19–20 October 2026.
  • A logging hook to record the variables (key contents were never logged, only the path), then the copy script above with RELOAD="true", then a failing hook; triggered by manual and queued certificate requests on a domain with one pointer and two subdomains.
  • The script on this page, 21 October 2026, with fixture certificates: relative and absolute paths, a missing key, a key that does not match, another cert_id, a certificate file that already holds its chain, no chain, and two runs at once (the second waited for the lock). Failure paths, forced with stand-ins for mv and cp: the second rename failing once or every time (previous pair restored and checked), the backup copy failing (nothing changed), the reload failing (previous pair restored), the reload and the restore both failing (reported, with whether the files still match), fullchain.pem being a directory and privkey.pem a symlink (refused), and a failed first run with no previous pair (half-published files removed). Then one real run: the domain’s current Let’s Encrypt certificate saved again through PUT /api/domain-tls/DOMAIN/certs/ID/files, which ran the hook and copied a matching pair; the certificate, its expiry and auto-renewal stayed as they were.
  • Not tested: scheduled renewals, pasting a different certificate in the panel, the server hostname certificate, wildcard (DNS-01) certificates and DirectAdmin versions before 1.712.

FAQ

Which DirectAdmin version added domain_tls_cert_save_post.sh?

Version 1.712. On older versions the file is ignored, so check da version before relying on it.

Does the hook run for every certificate or once per renewal?

Once per saved certificate. A domain with a pointer that has its own certificate ran the hook twice, with a different cert_id each time.

Are the certificate paths absolute?

Not on our 1.712 server: they were relative to /usr/local/directadmin, for example data/users/USER/domains/example.com.cert. The script on this page handles both forms.

What happens if my hook script returns an error?

The certificate is still installed. DirectAdmin logs the exit code and output, in the task output for a manual run or in the journal under dataskq for a queued one.

At a glance

Run a Script After Every DirectAdmin Certificate Renewal: domain_tls_cert_save_post.sh (Tested) summary card: The DirectAdmin certificate renewal hook added in 1.712 is /usr/local/directadmin/scripts/custom/domain_tls_cert_save_po…
In short: The DirectAdmin certificate renewal hook added in 1.712 is /usr/local/directadmin/scripts/custom/domain_tls_cert_save_post.sh. It runs as root each time DirectAdmin saves a domain certificat…

Share this guide

Free website test

Is your website set up right?

Check SSL, security headers, redirects, robots.txt, sitemap, llms.txt and security.txt in one test. It takes about 30 seconds.