Sync SSL certificates from Linux to a Synology NAS

zac

Preamble

I have a wildcard SSL certificate issued by Let’s Encrypt on a Debian Linux-based webserver, which also covers hostnames I reverse proxy with a Synology NAS. Up until recently, I have been manually copying the SSL certificate across after renewal. With the upcoming reduction in permitted validity for SSL certificates, it’s time to automate!

Synology DiskStation Manager (DSM) doesn’t make this easy.

The DSM API to add certificates isn’t documented in any useful way. This has resulted in some (IMHO) pretty messy scripts that mostly seem to overwrite files in various directories, restart services and hope for the best. If you also need to routinely copy an SSL certificate to a Synology NAS, here’s an approach that uses the DSM API instead:

How it works

There are two scripts:

  1. A script on the Linux server that publishes the issued certificate into a specific directory
  2. A script on the Synology NAS that uses SCP to retrieve the certificates and install them

The user on the NAS needs to be able to SSH into the server using an unencrypted key, with group access to the directory containing the certificates.

Checklist

There are quite a few things to check before the scripts will work:

Linux server

  • Internet-facing, or at least accessible to the NAS via SSH
  • SSH configuration that permits key authentication
  • Group on the server called certsync – this helps keep the certificate files secure
  • Directory on the server called /var/lib/certsync – root is the owner, certsync is the group, 750 for the directory permissions (i.e., no global permissions)
  • Non-root user account – needs to be a member of the certsync group, and must be able to SSH in

This also assumes you’re using certbot to issue Let’s Encrypt certificates. If you are using a different tool or a different CA, you will need to make a bunch of changes to how the script works.

Synology NAS

  • Running some flavour of DSM 7.x (I’ve tested this with DSM 7.1.1, but it should work with others)
  • SSH service enabled (Control Panel > Terminal & SNMP > Terminal)
  • User account that is a member of the administrators group
  • User home service enabled (Control Panel > User & Group > Advanced)
  • Optional: email notifications enabled (Control Panel > Notification > Email)

After confirming that the NAS user account can SSH in successfully: you need to create an RSA-based SSH key with no password, and transfer the public key to the user account on the Linux server. The easiest way to do this is using the ssh-keygen and ssh-copy-id commands.

This guide doesn’t cover how to do this, but you ultimately need to check that you can log into the Linux server via SSH from the Synology NAS without being prompted for a password.

Scripts

Linux server

This script runs as a deploy hook after any certificate has been renewed, and if the renewed certificate is in the list of certificates to copy – copies all of the relevant files atomically to a specified folder.

There are three configuration parameters – you probably only need to adjust LINEAGE_SUFFIXES (an array of certificate suffixes – check the directory structure in /etc/letsencrypt/live for what to use here).

#!/usr/bin/bash
# /etc/letsencrypt/renewal-hooks/deploy/synology-sync.sh
# Certbot deploy hook to sync PEM files for Synology DSM pull

set -euo pipefail

# === Configuration parameters  - edit these ===
STAGE_GROUP="certsync"
STAGE_DIR="/var/lib/certsync"
LINEAGE_SUFFIXES=("example.com-wildcard" "example.com.au-wildcard")

# === Stop editing ===

# Determine whether renewed lineage needs to be copied to the staging dir
lineage_allowed() {
  # Allow all if no filters specified
  if [[ ${#LINEAGE_SUFFIXES[@]} -eq 0 ]]; then
    return 0
  fi
  local lineage_path="$1"
  local base; base="$(basename -- "$lineage_path")"
  local sfx
  for sfx in "${LINEAGE_SUFFIXES[@]}"; do
    # Match either by full last component, or by path suffix
    if [[ "$base" == "$sfx" ]] || [[ "$lineage_path" == */"$sfx" ]]; then
      return 0
    fi
  done
  return 1
}

err() { echo "ERROR: $*" >&2; }

LINEAGE="${RENEWED_LINEAGE:-}"
if [[ -z "$LINEAGE" ]]; then
  err "RENEWED_LINEAGE is not set (this script is meant to run as a certbot deploy hook)."
  exit 1
fi

if ! lineage_allowed "$LINEAGE"; then
  echo "Skipping lineage not in LINEAGE_SUFFIXES: $LINEAGE"
  exit 0
fi

SRC_PRIVKEY="${LINEAGE}/privkey.pem"
SRC_CERT="${LINEAGE}/cert.pem"
SRC_CHAIN="${LINEAGE}/chain.pem"

[[ -f "$SRC_PRIVKEY" && -f "$SRC_CERT" && -f "$SRC_CHAIN" ]] || {
  err "Missing certificate files in $LINEAGE"
  exit 1
}

# Create staging dir if needed
install -d -o root -g "${STAGE_GROUP}" -m 0750 "${STAGE_DIR}"

# Create subdirectory for this specific lineage
LINEAGE_NAME="$(basename -- "$LINEAGE")"
LINEAGE_STAGE_DIR="${STAGE_DIR}/${LINEAGE_NAME}"
install -d -o root -g "${STAGE_GROUP}" -m 0750 "${LINEAGE_STAGE_DIR}"

# Stage atomically: copy into a temp dir, then move into place
TMP="$(mktemp -d "${STAGE_DIR}.tmp.XXXXXX")"
trap 'rm -rf "$TMP"' EXIT

# Copy with correct permissions (group-read for sync group; no world access to private key)
install -m 0640 "$SRC_PRIVKEY" "${TMP}/privkey.pem"
install -m 0644 "$SRC_CERT" "${TMP}/cert.pem"
install -m 0644 "$SRC_CHAIN" "${TMP}/chain.pem"

# Version marker: Subject + NotAfter + SHA256 fingerprint
CERTLOG="$(openssl x509 -in "$SRC_CERT" -noout -subject -enddate -fingerprint -sha256)"
printf '%s\n\n' "$CERTLOG" > "${TMP}/version.txt"
chmod 0644 "${TMP}/version.txt"

# Finalize atomically (keep stable file names expected by the NAS)
mv -f "${TMP}/privkey.pem"  "${LINEAGE_STAGE_DIR}/privkey.pem"
mv -f "${TMP}/cert.pem"     "${LINEAGE_STAGE_DIR}/cert.pem"
mv -f "${TMP}/chain.pem"    "${LINEAGE_STAGE_DIR}/chain.pem"
mv -f "${TMP}/version.txt"  "${LINEAGE_STAGE_DIR}/version.txt"

# Ensure ownership/perms
chown root:"${STAGE_GROUP}" "${LINEAGE_STAGE_DIR}/privkey.pem"
chmod 0640                  "${LINEAGE_STAGE_DIR}/privkey.pem"
chown root:"${STAGE_GROUP}" "${LINEAGE_STAGE_DIR}/cert.pem" "${LINEAGE_STAGE_DIR}/chain.pem" "${LINEAGE_STAGE_DIR}/version.txt"
chmod 0644                  "${LINEAGE_STAGE_DIR}/cert.pem" "${LINEAGE_STAGE_DIR}/chain.pem" "${LINEAGE_STAGE_DIR}/version.txt"

echo "Staged cert for $(basename -- "$LINEAGE") at ${LINEAGE_STAGE_DIR}"

Once edited, the script needs to be placed in /etc/letsencrypt/renewal-hooks/deploy – call it synology-sync.sh, and give it execute permissions (chmod a+x synology-sync.sh).

Synology NAS

This script is designed to run via Task Scheduler in the Control Panel, and handles one certificate per Task Scheduler entry. If you have multiple certificates, you need to customise and create multiple Task Scheduler entries!

The script logs into the Linux server on a schedule (I recommend daily to start, then move to weekly if everything is working), pulls the certificate files down, checks to see if they’re different to the installed version and if so – installs them.

There are several configuration parameters that you’ll need to customise to taste. You definitely need to adjust the following, but review all options down to where it says stop editing:

  • CERT_NAME – the name of the certificate in the DSM UI
  • LINUX_HOST – the FQDN of the Linux server
  • LINUX_USER – the user on the Linux server you’re SSH’ing in as
  • LINUX_LINEAGE_SUFFIX – the suffix used in the Let’s Encrypt directory structure
  • LOCAL_USER – the NAS user account that you’re SSH’ing from
#!/bin/sh
# synology-import-cert.sh — DSM 7.1.1: pull PEMs from a Linux server, validate, import, and reload nginx

set -eu
umask 077
export PATH="/usr/syno/bin:/usr/syno/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:$PATH"

# === Configuration parameters - edit these (one cert per Task Scheduler entry) ===

# Name / description of the certificate entry in the DSM to import
CERT_NAME="*.example.com"

# Set this certificate as the default certificate for DSM (true/false)
SET_AS_DEFAULT="true"

# Linux server details and user account
LINUX_HOST="linux.server.host.name"
LINUX_USER="linuxuser"
LINUX_BASE_PATH="/var/lib/certsync"
LINUX_LINEAGE_SUFFIX="example.com-wildcard" # lineage directory name (e.g., from /etc/letsencrypt/live/...)
LINUX_PATH="${LINUX_BASE_PATH}/${LINUX_LINEAGE_SUFFIX}" # contains privkey.pem, cert.pem, chain.pem, version.txt

# (Optional but recommended) Strict host key checking — populate /root/.ssh/known_hosts first.
SSH_OPTS="-o BatchMode=yes -o StrictHostKeyChecking=yes"

# Local DSM user that owns the SSH key used for scp
LOCAL_USER="synouser"
LOCAL_HOME="/var/services/homes/${LOCAL_USER}"
LOCAL_SSH_KEY="${LOCAL_HOME}/.ssh/id_rsa"

# === Stop editing ===

# Working/state locations on DSM
WORKDIR="/tmp/certsync/${LINUX_LINEAGE_SUFFIX}" #transient
STATEDIR="/var/packages/CertSync/var/${LINUX_LINEAGE_SUFFIX}" # persistent
LOGFILE="${STATEDIR}/run.log"

# Find command paths
JQ="/bin/jq"
SCP="/bin/scp"
OPENSSL="/bin/openssl"
SYNOWEBAPI="/usr/syno/bin/synowebapi"

# Set up directories
install -d -m 0755 "$STATEDIR"
install -d -o "${LOCAL_USER}" -g users -m 0700 "$WORKDIR"

# Logging
touch "$LOGFILE"
log() { printf '%s %s\n' "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" "$*" | tee -a "$LOGFILE" ; }

# Pull into a temp dir then install atomically
TMPDIR="$(mktemp -d "${WORKDIR}/.pull.XXXXXX")"
cleanup() { rm -rf "$TMPDIR" ; }
trap cleanup EXIT

# Let LOCAL_USER write into TMPDIR (scp runs as that user)
chown "${LOCAL_USER}:users" "$TMPDIR"
chmod 0700 "$TMPDIR"

log "Pulling certs from ${LINUX_USER}@${LINUX_HOST}:${LINUX_PATH}"

pull_file() {
  _remote="$1"
  _dest="$2"
  _error="$(/bin/su -s /bin/sh "${LOCAL_USER}" -c \
    "$SCP -i '${LOCAL_SSH_KEY}' ${SSH_OPTS} '${LINUX_USER}@${LINUX_HOST}:${LINUX_PATH}/${_remote}' '${_dest}'" 2>&1)" || {
    log "ERROR: scp failed for ${_remote}"
    log "SCP error output: ${_error}"
    return 1
  }
  log "Successfully pulled: ${_remote}"
}

pull_file "privkey.pem"  "${TMPDIR}/privkey.pem"
pull_file "cert.pem"     "${TMPDIR}/cert.pem"
pull_file "chain.pem"    "${TMPDIR}/chain.pem"
pull_file "version.txt"  "${TMPDIR}/version.txt"

for f in privkey.pem cert.pem chain.pem version.txt; do
  [ -f "${TMPDIR}/${f}" ] || { log "ERROR: failed to pull ${f}"; exit 1; }
done

# Sanity checks
$OPENSSL pkey -in "${TMPDIR}/privkey.pem" -noout >/dev/null 2>&1 || { log 'ERROR: invalid privkey.pem'; exit 1; }
$OPENSSL x509 -in "${TMPDIR}/cert.pem" -noout >/dev/null 2>&1 || { log 'ERROR: invalid cert.pem'; exit 1; }
$OPENSSL x509 -in "${TMPDIR}/chain.pem" -noout >/dev/null 2>&1 || { log 'ERROR: invalid chain.pem'; exit 1; }

# cert ↔ key match (key-type agnostic: SPKI hash)
CERT_SPKI="$(
  $OPENSSL x509 -in "${TMPDIR}/cert.pem" -noout -pubkey |
  $OPENSSL pkey -pubin -outform der 2>/dev/null |
  $OPENSSL dgst -sha256 | awk '{print $2}'
)"
KEY_SPKI="$(
  $OPENSSL pkey -in "${TMPDIR}/privkey.pem" -pubout -outform der 2>/dev/null |
  $OPENSSL dgst -sha256 | awk '{print $2}'
)"
[ "$CERT_SPKI" = "$KEY_SPKI" ] || { log "ERROR: public key mismatch (SPKI)"; exit 1; }

# Skip if unchanged
if [ -f "${STATEDIR}/version.txt" ] && cmp -s "${STATEDIR}/version.txt" "${TMPDIR}/version.txt"; then
  log "No new certificate (version unchanged)."
  exit 0
fi

# Install with correct permissions
install -m 0600 "${TMPDIR}/privkey.pem"  "${WORKDIR}/privkey.pem"
install -m 0644 "${TMPDIR}/cert.pem"     "${WORKDIR}/cert.pem"
install -m 0644 "${TMPDIR}/chain.pem"    "${WORKDIR}/chain.pem"
install -m 0644 "${TMPDIR}/version.txt"  "${WORKDIR}/version.txt"

# Find certificate ID using CERT_NAME
CERT_LIST="$("$SYNOWEBAPI" --exec api=SYNO.Core.Certificate.CRT method=list version=1)"
CERT_ID="$(echo "$CERT_LIST" | $JQ -r --arg desc "$CERT_NAME" '.data.certificates[] | select(.desc == $desc) | .id')"

if [ -z "$CERT_ID" ]; then
  log "ERROR: Certificate '${CERT_NAME}' not found in DSM"
  exit 1
fi

log "Certificate ID: ${CERT_ID}"

# Set whether certificate is configured as default
if [ "$SET_AS_DEFAULT" = "true" ]; then
  AS_DEFAULT_PARAM='as_default="\"true\""'
  IMPORT_ACTION="Certificate updated and set as default."
else
  AS_DEFAULT_PARAM='as_default="\"false\""'
  IMPORT_ACTION="Certificate updated."
fi

# Install certificate and restart nginx
"$SYNOWEBAPI" --exec api=SYNO.Core.Certificate method=import version=1 \
  key_tmp="\"${WORKDIR}/privkey.pem\"" \
  cert_tmp="\"${WORKDIR}/cert.pem\"" \
  inter_cert_tmp="\"${WORKDIR}/chain.pem\"" \
  id="\"${CERT_ID}\"" \
  desc="\"${CERT_NAME}\"" \
  $AS_DEFAULT_PARAM || { log "ERROR: import for certificate name: ${CERT_NAME} failed"; exit 1; }

# Persist version marker
cp -f "${WORKDIR}/version.txt" "${STATEDIR}/version.txt"
log "${IMPORT_ACTION}"
exit 0

Once edited, you need to create a Task Scheduler entry in the DSM (Control Panel > Task Scheduler > Create > Scheduled Task > User-defined script).

On the General tab, give the task a descriptive name and select the root user.

On the Schedule tab, set it to run daily. Once working, I recommend backing this off to weekly.

On the Task Settings tab, configure Notifications to your taste (if you have email notifications running), then paste the script in the User-defined script box.

Click OK, then click OK on the warning window.

Related Posts

Leave a Reply

Your email address will not be published. Required fields are marked *

78 − = 73

This site uses Akismet to reduce spam. Learn how your comment data is processed.