;
};
`Synology` · `acme.sh` · `Let's Encrypt` · `Cloudflare` · `TLS` · `Shell`
## Overview
DSM 7's built-in Let's Encrypt support only covers HTTP-01 validation, which requires port 80 open to the internet and cannot issue wildcard certificates. This project uses acme.sh with Cloudflare DNS-01 validation to issue a `*.example.com` wildcard certificate without opening any inbound ports, then deploys it to DSM automatically via the `synology_dsm` deploy hook. It also covers a dual-certificate strategy: Cloudflare Origin Certificate for orange-cloud (proxied) traffic, and the Let's Encrypt wildcard for direct-access services such as VPN, Mail, and WebDAV.
## Core features
* DNS-01 validation via Cloudflare API: writes a TXT record to fulfil the ACME challenge with no ports opened
* Single wildcard issuance (`example.com` + `*.example.com`) covers all subdomains
* `synology_dsm` deploy hook pushes and reloads the certificate through the DSM Web API after each issuance or renewal
* DSM Task Scheduler triggers acme.sh renew daily; acme.sh only acts when the certificate is within 60 days of expiry
* Dual certificates: DSM lets you assign Origin Certificate or Let's Encrypt per service independently
## Deployment architecture
## Certificate strategy
```
Browser / client
|- HTTPS -> Cloudflare Edge (Universal SSL, automatic)
| -> orange-cloud proxy -> NAS: Cloudflare Origin Certificate (15-year validity)
-> Direct (grey-cloud / VPN / Mail / WebDAV)
-> NAS: Let's Encrypt Wildcard (acme.sh auto-renewed)
```
## Quick start
Cloudflare Dashboard → My Profile → API Tokens → Create Token → Custom Token.
Set permissions: Zone → DNS → **Edit**, zone resource scoped to the target zone. Copy the token (shown only once) and the Zone ID (right-hand panel on the Dashboard overview page).
```bash theme={null}
sudo -i
rm -rf /usr/local/share/acme.sh /root/.acme.sh
cd /tmp && wget https://github.com/acmesh-official/acme.sh/archive/master.tar.gz
tar xvf master.tar.gz && cd acme.sh-master/
./acme.sh --install --nocron \
--home /usr/local/share/acme.sh \
--accountemail "your-email@example.com"
chown -R your_username /usr/local/share/acme.sh/
```
`--nocron` is required because DSM upgrades wipe non-native crontab entries. `--home` is required because Synology's `/root` directory structure is non-standard and causes errors without it.
```bash theme={null}
/usr/local/share/acme.sh/acme.sh --register-account \
-m "your-email@example.com" \
--home /usr/local/share/acme.sh \
--server letsencrypt
```
`--server letsencrypt` is required. Recent acme.sh versions default to ZeroSSL.
```bash theme={null}
export CF_Token="your_cloudflare_api_token"
export CF_Zone_ID="your_zone_id"
# Validate config against the staging environment first
/usr/local/share/acme.sh/acme.sh --issue --dns dns_cf \
-d "example.com" -d "*.example.com" \
--home /usr/local/share/acme.sh \
--server letsencrypt --test
# Issue for real once staging passes
/usr/local/share/acme.sh/acme.sh --issue --dns dns_cf \
-d "example.com" -d "*.example.com" \
--home /usr/local/share/acme.sh \
--server letsencrypt --force
```
```bash theme={null}
export SYNO_Hostname="localhost"
export SYNO_Port="5000"
export SYNO_Username="your_username"
export SYNO_Password='your_password'
export SYNO_Certificate="Let's Encrypt Wildcard"
export SYNO_Create=1
/usr/local/share/acme.sh/acme.sh --deploy \
-d "example.com" -d "*.example.com" \
--deploy-hook synology_dsm \
--home /usr/local/share/acme.sh
```
Confirm in DSM Control Panel → Security → Certificate that "Let's Encrypt Wildcard" appears.
Control Panel → Task Scheduler → Create → Scheduled Task → User-defined script, scheduled daily at 03:00:
```bash theme={null}
/usr/local/share/acme.sh/acme.sh --renew \
-d "example.com" -d "*.example.com" \
--deploy-hook synology_dsm \
--home /usr/local/share/acme.sh
```
Or use `scripts/renew-cert.sh` from the repo. acme.sh skips renewal internally unless the certificate is within 60 days of expiry, so running daily is safe.
## Notes
Let's Encrypt production enforces a rate limit of 5 certificates per domain per week. Always run `--test` against the staging environment before the production issuance; staging has no rate limits. Use a Custom API Token with Zone DNS Edit scope only, never the Global API Key. If `SYNO_CERTIFICATE` contains a single quote (as in `Let's Encrypt Wildcard`), wrap the value in double quotes in `account.conf` to avoid shell quoting errors.
## In practice
The lab NAS runs VPN, Mail, WebDAV, and Synology Drive simultaneously, all of which need a publicly trusted certificate. A single wildcard covers all subdomains with one renewal cycle. Orange-cloud services get the Origin Certificate assigned separately in DSM, leaving the Let's Encrypt wildcard for direct-access services.
## Links
* GitHub: [felimet/synology-letsencrypt-cloudflare](https://github.com/felimet/synology-letsencrypt-cloudflare)
* acme.sh: [acmesh-official/acme.sh](https://github.com/acmesh-official/acme.sh)
* acme.sh Cloudflare DNS API guide: [acme.sh/wiki/dnsapi#dns\_cf](https://github.com/acmesh-official/acme.sh/wiki/dnsapi#dns_cf)
* acme.sh Synology DSM deploy hook: [acme.sh/wiki/deployhooks#synology\_dsm](https://github.com/acmesh-official/acme.sh/wiki/deployhooks#synology_dsm)