Post

Automating Let's Encrypt SSL Certificates on Synology DSM with acme.sh and Cloudflare DNS

How to automate Let's Encrypt SSL certificate issuance and renewal on Synology DSM using acme.sh with Cloudflare DNS.

Posted
By Corey Callaway
9 min read
Automating Let's Encrypt SSL Certificates on Synology DSM with acme.sh and Cloudflare DNS

Managing SSL certificates can be tedious, especially when dealing with resources that aren’t publicly accessible. Synology currently provides the ability to automate certificate management through its interface, but it has limitations. If you want to use a certificate from Let’s Encrypt, you have to rely on HTTP challenges, which require your Synology to be accessible over the internet. This can be a security concern and isn’t always feasible for home labs or internal services.

However, by SSHing into your Synology and using the acme.sh script with Cloudflare DNS validation, you can fully automate the issuance and renewal of Let’s Encrypt certificates without exposing your Synology to the internet. In this guide, I’ll walk you through setting up the certificate generation and automation using acme.sh and Cloudflare’s to perform DNS-01 challenges for your domain.

Why DNS Challenge?

The DNS-01 challenge method offers several advantages over traditional HTTP-01 challenges:

  • No port forwarding required - Your Synology doesn’t need to be publicly accessible
  • Wildcard certificate support - Secure multiple subdomains with a single certificate
  • Works behind firewalls - Perfect for internal or VPN-only accessible systems
  • Cleaner and more secure - No temporary files exposed on your web server

Prerequisites

Before starting, ensure you have:

  • A Synology NAS running DSM 7.x
  • SSH access enabled (Control Panel → Terminal & SNMP → Enable SSH service)
  • A domain managed by Cloudflare (free tier works)
  • Cloudflare API credentials
  • Basic command line familiarity

Step 1: Create a Dedicated Certificate Management User

For better security and organization, create a dedicated user for managing certificates. This user will own the acme.sh installation and handle certificate renewals.

Creating the User in DSM

  1. Log into your Synology DSM web interface as an administrator
  2. Navigate to Control Panel → User & Group
  3. Click Create to add a new user
  4. Configure the user with these settings:
    • Name: certadmin
    • Description: Certificate Management Account
    • Email: (optional)
    • Password: Set a strong password (you’ll need this for deployment)
    • Disallow user to change password: (your preference)
  5. On the Permissions tab, you can leave most services unchecked
  6. On the Applications tab, no special permissions are needed
  7. Click Apply to create the user

Grant Administrator Privileges

The certadmin user needs administrator privileges to deploy certificates to DSM:

  1. Still in Control Panel → User & Group
  2. Select the Group tab
  3. Click on the administrators group
  4. Click Edit
  5. Check the box next to certadmin to add them to the administrators group
  6. Click OK to save

Enable SSH Access

Now SSH into your Synology as an administrator user to prepare the environment:

1

ssh certadmin@your-synology-ip

The certadmin user is now ready to manage certificates.

Step 2: Obtain Cloudflare API Credentials

You’ll need Cloudflare API credentials to allow acme.sh to create DNS validation records.

  1. Log into your Cloudflare dashboard
  2. Navigate to My Profile → API Tokens
  3. Create a token with Zone:DNS:Edit permissions for your domain
  4. Save the token securely - you’ll need it shortly

Alternatively, you can use your Global API Key (less secure):

  • Find it under My Profile → API Tokens → Global API Key

Step 3: Download and Install acme.sh

Download the latest acme.sh release from GitHub:

1

wget -O /tmp/acme.sh.zip https://github.com/acmesh-official/acme.sh/archive/master.zip

Extract it to a permanent location:

1

sudo 7z x -o/usr/local/share /tmp/acme.sh.zip

Rename the extracted directory:

1

sudo mv /usr/local/share/acme.sh-master/ /usr/local/share/acme.sh

Set appropriate ownership (if using the certadmin user):

1

sudo chown -R certadmin /usr/local/share/acme.sh/

Step 4: Configure Cloudflare DNS API

Set your Cloudflare credentials as environment variables. For API Token (recommended):

1
2
3

export CF_Token="your_cloudflare_api_token_here"
export CF_Account_ID="your_cloudflare_account_id"
export CF_Zone_ID="your_zone_id"

Or for Global API Key:

1
2

export CF_Key="your_cloudflare_global_api_key"
export CF_Email="[email protected]"

These credentials will be saved by acme.sh for future renewals.

Step 5: Issue Your Certificate

Navigate to the acme.sh directory:

1

cd /usr/local/share/acme.sh

Request a certificate using the DNS challenge method:

1

./acme.sh --server letsencrypt --issue -d "exampledomain.com" --dns dns_cf --home $PWD

For a wildcard certificate, add the wildcard domain:

1

./acme.sh --server letsencrypt --issue -d "exampledomain.com" -d "*.exampledomain.com" --dns dns_cf --home $PWD

The script will:

  1. Generate a certificate signing request
  2. Create a TXT record in your Cloudflare DNS
  3. Wait for DNS propagation
  4. Complete the ACME challenge
  5. Retrieve your certificate

Step 6: Deploy to Synology DSM

Once the certificate is issued, deploy it to your Synology system:

1

./acme.sh -d "exampledomain.com" --deploy --deploy-hook synology_dsm --home $PWD

Before running this command, you may need to set Synology-specific environment variables:

1
2
3
4

export SYNO_Username="your_admin_username"
export SYNO_Password="your_admin_password"
export SYNO_Certificate="your_certificate_description"
export SYNO_Create=1

The deploy hook will:

  • Connect to the Synology API
  • Upload the certificate and private key
  • Create or update the certificate in DSM
  • Optionally restart services using the certificate

Step 7: Verify Installation

Log into your Synology DSM web interface:

  1. Go to Control Panel → Security → Certificate
  2. You should see your new Let’s Encrypt certificate listed
  3. Click Configure to assign it to specific services
  4. Select which services should use this certificate

Step 8: Configure Automatic Renewal with Synology Task Scheduler

While acme.sh can install its own cron job, using Synology’s Task Scheduler provides better integration and easier management through the DSM interface.

Create a Scheduled Task

  1. Log into DSM and navigate to Control Panel → Task Scheduler
  2. Click Create → Scheduled Task → User-defined script
  3. Configure the General settings:
    • Task: Renew Let's Encrypt Certificate
    • User: Select certadmin (this is critical - it must run as the certadmin user)
    • Enabled: Check this box
  4. Configure the Schedule tab:
    • Run on the following days: Select Daily
    • First run time: Set to a time when your NAS is reliably on (e.g., 3:00 AM)
    • Frequency: Select Once
    • Last run time: Leave blank
  5. Configure the Task Settings tab:
    • Send run details by email: (optional, recommended for monitoring)
    • User-defined script: Enter the renewal command:
1

/usr/local/share/acme.sh/acme.sh --renew -d "*.exampledomain.com" --home /usr/local/share/acme.sh --server letsencrypt

For a non-wildcard certificate, use:

1

/usr/local/share/acme.sh/acme.sh --renew -d "exampledomain.com" --home /usr/local/share/acme.sh --server letsencrypt
  1. Click OK to save the task

Testing the Scheduled Task

Before waiting for the scheduled run, test the task manually:

  1. In Task Scheduler, select your renewal task
  2. Click Run at the top
  3. Check the results by clicking Action → View Result

The task will check if renewal is needed (certificates are renewed when they’re within 60 days of expiration). During the initial test, you should see output indicating the certificate is still valid and renewal isn’t needed yet.

Force a Renewal Test

To verify everything works correctly, you can force a renewal via SSH:

1

sudo -u certadmin /usr/local/share/acme.sh/acme.sh --renew -d "*.exampledomain.com" --home /usr/local/share/acme.sh --server letsencrypt --force

This will renew the certificate immediately, allowing you to verify the entire process works before the certificate actually needs renewal.

Monitoring Renewals

Enable email notifications in the Task Scheduler to receive alerts about renewal status:

  1. Edit your scheduled task
  2. Check Send run details by email
  3. Send run details only when the script terminates abnormally: (your preference)

This ensures you’re notified if renewals fail for any reason.

Troubleshooting

DNS Propagation Issues

If the challenge fails due to DNS propagation, you can increase the wait time:

1

./acme.sh --issue -d "exampledomain.com" --dns dns_cf --dnssleep 120 --home $PWD

Permission Errors

If you encounter permission issues, ensure the acme.sh directory has correct ownership:

1

sudo chown -R $(whoami) /usr/local/share/acme.sh/

Certificate Not Appearing in DSM

Verify your Synology credentials are correct and the certadmin user has admin privileges (is in the administrators group). You can also manually import the certificate through the DSM interface:

  • Certificate: /usr/local/share/acme.sh/exampledomain.com/exampledomain.com.cer
  • Private Key: /usr/local/share/acme.sh/exampledomain.com/exampledomain.com.key
  • Intermediate Certificate: /usr/local/share/acme.sh/exampledomain.com/ca.cer

Scheduled Task Not Running

If your Task Scheduler task fails, check these common issues:

  • Verify the task is running as the certadmin user (not root or another user)
  • Ensure certadmin has ownership of /usr/local/share/acme.sh/
  • Check the task result logs in Task Scheduler for specific error messages
  • Verify the domain name in your renewal command matches exactly what you issued

Checking Certificate Status

View information about your certificates:

1

./acme.sh --list --home $PWD

View detailed information for a specific certificate:

1

./acme.sh --info -d "exampledomain.com" --home $PWD

Security Considerations

  • Protect your credentials: The acme.sh configuration stores your Cloudflare API credentials. Ensure proper file permissions.
  • Use API Tokens over Global API Keys: Tokens can be scoped to specific permissions and revoked independently.
  • Limit SSH access: Consider disabling SSH when not needed or restricting it to specific IP addresses.
  • Regular backups: Include your acme.sh directory in your backup routine to preserve certificate history and configurations.

Rotating Cloudflare API Credentials

Cloudflare API tokens have expiration dates and should be rotated periodically for security. When your token expires or you need to rotate credentials, follow these steps:

Generate a New API Token

  1. Log into your Cloudflare dashboard
  2. Navigate to My Profile → API Tokens
  3. Create a new token with the same permissions (or click Edit on your existing token to extend/regenerate it)
  4. Copy the new token immediately - Cloudflare only shows it once

Update acme.sh Configuration

The API credentials are stored in acme.sh’s configuration file. To update them:

1
2

# SSH into your Synology as certadmin or use sudo
ssh certadmin@your-synology-ip

Edit the account configuration file:

1
2

cd /usr/local/share/acme.sh
nano account.conf

Look for these lines and update with your new credentials:

For API Token:

1
2
3

CF_Token='your_new_cloudflare_api_token_here'
CF_Account_ID='your_cloudflare_account_id'
CF_Zone_ID='your_zone_id'

Or for Global API Key:

1
2

CF_Key='your_new_cloudflare_global_api_key'
CF_Email='[email protected]'

Save the file (Ctrl+O, Enter, Ctrl+X in nano).

Verify the New Credentials

Test that the new credentials work by forcing a renewal:

1

./acme.sh --renew -d "exampledomain.com" --home /usr/local/share/acme.sh --server letsencrypt --force

If successful, your new API credentials are working correctly. The scheduled task will now use these updated credentials automatically.

Set a Reminder

Since API tokens expire, set a calendar reminder to rotate your token before expiration:

  • Check your token’s expiration date in the Cloudflare dashboard
  • Set a reminder 1-2 weeks before expiration
  • Follow this rotation process when the reminder triggers

Updating acme.sh

Keep acme.sh updated to benefit from bug fixes and new features:

1
2

cd /usr/local/share/acme.sh
./acme.sh --upgrade --home $PWD

To enable automatic updates:

1

./acme.sh --upgrade --auto-upgrade --home $PWD

Conclusion

With acme.sh and Cloudflare DNS validation, you now have a fully automated SSL certificate solution for your Synology NAS. Certificates will renew automatically, and you don’t need to expose your system to the internet. This setup is particularly valuable for home labs, internal services, or any Synology deployment that prioritizes security and convenience.

The combination of Let’s Encrypt’s free certificates, acme.sh’s automation capabilities, and Cloudflare’s DNS API creates a robust, maintenance-free certificate management system that just works.

Additional Resources

Tutorial, Synology
Synology lets-encrypt SSL acme.sh Cloudflare dns-challenge Automation
This post is licensed under CC BY 4.0 by the author.