Skip to main content

Let's Encrypt Setup for FileWave Server (Debian)

What

This Knowledge Base (KB) article covers a Debian-focused shell script that automates Let's Encrypt SSL certificate setup for a FileWave server on Debian 12/13.

The script supports two challenge methods:

  • HTTP-01 (standalone certbot)
  • DNS-01 (Cloudflare)

Both paths handle certificate request, FileWave certificate injection, and renewal automation.

When/Why

FileWave administrators use this when they need a trusted SSL certificate for secure communication.

  • Use HTTP-01 when port 80 can be reached from the internet.
  • Use DNS-01 (Cloudflare) when port 80 is blocked/unavailable or you prefer DNS validation.

This documented process is for Debian 12/13. If you are a Hosted customer, FileWave can handle certificate management for you: SSL Certificate Management for Custom Domains (FileWave-Hosted Servers).

How

Prerequisites

  • FileWave server on Debian 12 or 13
  • Root/sudo access
  • Public DNS name (FQDN) for the FileWave server
  • If using DNS validation: Cloudflare API token with DNS edit permissions for the zone

Challenge method guidance

  • HTTP-01: requires inbound TCP/80 reachability for Let's Encrypt validation.
  • DNS-01 (Cloudflare): does not require inbound TCP/80.

If TCP/80 is not available, select DNS-01 (Cloudflare) during install.

Install steps

  1. Download the script with wget:

    wget -O filewave-letsencrypt-debian.sh https://kb.filewave.com/attachments/413

  2. Make it executable:

    chmod +x filewave-letsencrypt-debian.sh

  3. Run install:

    sudo ./filewave-letsencrypt-debian.sh --install

  4. Follow prompts for:

    • Hostname (FQDN)
    • Email
    • Validation method:
      • 1 = HTTP-01
      • 2 = DNS-01 (Cloudflare)
    • If DNS-01 is selected: Cloudflare API token

  5. Confirm values when prompted.

  6. Verify output for success messages and final summary.

What the script does

  • Validates Debian and root execution
  • Validates that FileWave server paths exist (/usr/local/bin/fwcontrol, /usr/local/filewave/certs)
  • Validates hostname and email
  • Validates DNS resolution (tries 8.8.8.8, then system resolver fallback)
  • Backs up existing certs under /usr/local/filewave/certs/backup-<timestamp>/
  • Installs/validates certbot
  • Requests a new certificate using selected challenge method
  • For DNS-01 (Cloudflare): creates /etc/letsencrypt/secrets/cloudflare.ini automatically (no manual pre-creation required)
  • Updates FileWave mdm_cert_trusted DB flag
  • Creates renewal deploy hook:
    • /etc/letsencrypt/renewal-hooks/deploy/filewave-server-cert.sh
  • Preserves existing cert file owner/group when replacing certificates
  • Creates daily renewal cron:
    • /etc/cron.daily/letsencrypt-filewave
  • Immediately injects cert into FileWave and restarts server services

Uninstall

To remove integration files created by the script:

sudo ./filewave-letsencrypt-debian.sh --uninstall

This removes FileWave renewal hook + cron job and (if present) Cloudflare credentials file. The script intentionally leaves certbot installed.

Troubleshooting

1) FileWave server prerequisites failed

If script reports missing FileWave binaries/paths:

  • Verify /usr/local/bin/fwcontrol exists.
  • Verify /usr/local/filewave/certs exists.
  • Re-run on the FileWave server host.

2) Certificate request failed (HTTP-01)

Ensure inbound TCP/80 is reachable, then retry:

sudo certbot -n --agree-tos --standalone certonly -d "<FQDN>" -m "<EMAIL>"
sudo certbot renew --force-renewal

3) Certificate request failed (DNS-01 Cloudflare)

Ensure token permissions and retry:

sudo certbot -n --agree-tos --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/secrets/cloudflare.ini certonly -d "<FQDN>" -m "<EMAIL>"
sudo certbot renew --force-renewal

4) FileWave UI shows old certificate behavior

If older behavior persists, verify mdm_cert_trusted is set in PostgreSQL:

image.png

/usr/local/filewave/postgresql/bin/psql -d mdm -U django

insert into ios_preferences values('mdm_cert_trusted', TRUE) on conflict (key) do nothing;

update ios_preferences set value='true' where key='mdm_cert_trusted';

\q
Nicolas Schwarz
Nicolas Schwarz  commented 2 weeks ago
#1

Thanks for this guide, but we encountered an issue with the HTTP-01 challenge. I don't know if this is standard on newer installs as well, but on our server we had to open port 80/tcp in firewalld. By default this was dropped and the challenge could not be completed. Maybe the install script could check if firewalld is enabled and if port 80 is allowed? Or you could add this as an extra step before running the installation?
The installation worked fine after allowing port 80

Josh Levitsky
Josh Levitsky  commented 2 weeks ago
#2

In reply to #1

That's a good point. At the very least I should mention this but you are right it would be good to programatically check. Thanks for this feedback.

No comments to display

Back to top