How SSL Works in smoxy
SSL/TLS certificates are essential for securing traffic between your visitors and smoxy, as well as between smoxy and your origin servers. smoxy provides a fully integrated certificate lifecycle - from automatic generation via Let's Encrypt to manual certificate uploads.
This guide explains how SSL works in smoxy, the different certificate types available, and how smoxy manages certificates on your behalf.
SSL Certificate Types
smoxy supports two types of SSL certificates:
| Type | Generated by | Renewed by | Best for |
|---|---|---|---|
| Auto-managed (Recommended) | smoxy via Let's Encrypt | smoxy (automatic) | Most users - zero maintenance |
| Self-managed | You | You (manual) | Enterprise certs, EV certificates, specific compliance needs |
Auto-managed Certificates (Recommended)
When you add a domain to smoxy, a wildcard SSL certificate is automatically created. This certificate covers:
yourdomain.com*.yourdomain.com(all subdomains)
The certificate is issued via Let's Encrypt using DNS-based validation (ACME protocol). smoxy handles the entire lifecycle:
- Certificate request
- DNS challenge verification
- Certificate issuance
- Automatic renewal (timed by the CA's recommended renewal window)
Self-managed Certificates
If you need to use your own certificate (e.g., Extended Validation, organization-specific requirements), you can upload it manually.
Requirements:
- Certificate file in PEM format
- Private key file in PEM format
- The private key must match the certificate
- The certificate must not be expired
- The certificate must cover the domain(s) you intend to use
INFO
Important: smoxy cannot automatically renew manually uploaded certificates. You are responsible for uploading a new certificate before the current one expires.
How Certificate Generation Works
Step 1: DNS Verification
For each Subject Alternative Name (SAN) on the certificate, smoxy requires a CNAME record pointing to smoxy's ACME verification infrastructure:
_acme-challenge.yourdomain.com → yourdomain.com.acme.smoxy.eu.This CNAME record allows smoxy to complete the ACME DNS-01 challenge required by Let's Encrypt. The target is the SAN's own domain followed by .acme.smoxy.eu. (including the trailing dot). The exact value for each SAN is shown in the certificate's SANs tab - copy it from there.
INFO
Important: If you use Cloudflare, the Cloudflare proxy must be disabled for the _acme-challenge CNAME record. See Cloudflare Setup for details.
Step 2: Certificate Issuance
Once all DNS records are verified, smoxy automatically:
- Requests a certificate from Let's Encrypt
- Completes the ACME challenge
- Downloads and installs the certificate
- Activates the certificate for your hostnames
Step 3: Automatic Renewal
smoxy monitors certificate expiration and renews automatically. Renewal timing follows the CA's recommended renewal window (ACME Renewal Information, ARI); if no window is available, smoxy falls back to renewing roughly two weeks before expiry. The renewal follows the same verification flow - if the DNS records are still in place, it happens completely automatically.
Subject Alternative Names (SANs)
A Subject Alternative Name (SAN) is an individual domain name covered by an SSL certificate. When you create a new domain in smoxy, two default SANs are added:
yourdomain.com- the root domain*.yourdomain.com- wildcard for all subdomains
Adding Additional SANs
If you need to cover additional specific subdomains (e.g., specific.sub.yourdomain.com that isn't covered by the wildcard), smoxy can add additional SANs to your certificate. Each SAN requires its own _acme-challenge CNAME record for DNS verification.
When you add such a hostname to a zone and the domain's DNS is managed by smoxy, this can happen automatically: smoxy offers to add the missing SAN, create its validation record, and trigger the certificate renewal in one step. See Automatic DNS Setup.
SAN Status
Each SAN has two independent statuses:
| Status | Values | Meaning |
|---|---|---|
| DNS Status | Unknown / Valid / Missing | Whether the _acme-challenge CNAME record is correctly configured. Unknown means it hasn't been checked yet; Missing covers every case where the expected record isn't found - including a CNAME pointing at the wrong target or a conflicting TXT record |
| SSL Status | Covered / Not covered | Whether the current certificate actually includes this domain |
smoxy regularly re-checks DNS records:
- Every 24 hours for valid records (to detect removal)
- Every 1 hour for missing records (to detect when you've added them)
You can also trigger a manual Recheck DNS on the SANs tab. After a manual recheck, smoxy schedules the next automatic check in 24 hours for a still-valid record, or in 5 minutes for a still-missing one.
When new SANs are added and their DNS is verified, smoxy automatically triggers a certificate regeneration to include the new domains.
Certificate Statuses
Your SSL certificate in smoxy can be in one of the following states:
| Status | Meaning | Action Required |
|---|---|---|
| Pending | Certificate generation has been initiated but not yet completed | Wait for generation to complete |
| Active | Certificate is valid and working | None |
| Renewing | A renewal is in progress | None - smoxy handles this automatically |
| Expired | The certificate has passed its expiry date | Auto-managed: check the _acme-challenge records so renewal can complete. Self-managed: upload a new certificate |
| Failed | Certificate generation or renewal failed | Check each SAN's DNS status and the latest attempt for the specific error |
INFO
Note: DNS problems don't appear as certificate statuses. They surface per SAN as a DNS Status of Missing on the SANs tab. Common causes are a missing _acme-challenge CNAME record, a CNAME pointing at the wrong target, or a conflicting TXT record for _acme-challenge. See SSL Troubleshooting for how to fix each.
Certificate Generation Workflow
Behind the scenes, smoxy tracks certificate generation through a detailed workflow:
Each generation or renewal is tracked as an attempt, which is Processing, Succeeded, or Failed. An attempt runs through the following steps in order:
| Step | What happens |
|---|---|
| Initialize | The attempt is set up |
| Verify CNAME Record | Checks the _acme-challenge CNAME records for all SANs |
| Create ACME Order | Requests a certificate order from Let's Encrypt |
| Provision DNS Record | Creates the DNS-01 challenge record |
| Await DNS Propagation | Waits until the challenge record resolves |
| Authorize | Lets the CA validate the challenge |
| Poll Order Status | Waits for the order to become ready |
| Download Certificate | Downloads the issued certificate |
| Save Certificate | Stores and activates the certificate |
If a transient error occurs during generation, smoxy automatically retries with exponential backoff. The errors you may see fall into two groups - problems with the ACME/DNS flow for auto-managed certificates, and validation failures when uploading a custom certificate:
| Error | Cause | Resolution |
|---|---|---|
| Rate limit | Too many certificate requests to Let's Encrypt | Automatic - smoxy waits and retries later |
| CNAME record missing | The _acme-challenge CNAME record is missing for one or more SANs | Add the missing CNAME record(s). On Cloudflare, disable the proxy for the challenge record (see Cloudflare Setup) |
| CNAME record invalid | The CNAME record exists but points to the wrong target | Update the CNAME to the exact target shown on the SANs tab |
| DNS provisioning failed | smoxy could not create the DNS-01 challenge record | Temporary - smoxy retries automatically |
| ACME error | The certificate authority reported an error | Check DNS propagation; smoxy retries automatically |
| Invalid PEM | An uploaded certificate or key is not valid PEM data | Re-export the file in PEM format and upload again |
| Key mismatch | The uploaded private key does not match the certificate | Upload the private key that belongs to the certificate |
| Certificate expired | The uploaded certificate has already expired | Obtain and upload a current certificate |
| SAN mismatch | The uploaded certificate does not cover all configured SANs | Use a certificate that covers your domains |
| Invalid chain | The uploaded chain / intermediate certificate is not valid PEM data | Provide a valid intermediate chain in the Chain PEM field |
| Internal error | An unexpected error occurred | Retry; contact support if it persists |
Uploading a Self-managed Certificate
To upload your own SSL certificate:
- Open SSL Certificates in the smoxy sidebar
- Click New Certificate to open the New SSL Certificate dialog
- Set Type to Custom
- Provide:
- Certificate PEM: Your server certificate in PEM format
- Private Key PEM: The matching private key
- Chain PEM (optional): Any intermediate certificates, in this separate field
Validation
When uploading, smoxy validates:
- The certificate is parseable and in valid PEM format
- The private key matches the certificate
- The certificate has not expired
- The SANs in the certificate cover your domain
If the SANs in the new certificate differ from the current ones, smoxy will show you the differences and ask for confirmation before proceeding.
After Upload
- The previous certificate is archived for audit purposes
- The new certificate is immediately activated
- Since self-managed certificates are not auto-renewed, you must upload a replacement before expiration
Wildcard Certificates
smoxy creates wildcard certificates by default. A wildcard certificate for *.yourdomain.com covers:
www.yourdomain.comshop.yourdomain.comapi.yourdomain.com- Any other single-level subdomain
What wildcards do NOT cover:
- The root domain itself (
yourdomain.com) - this is added as a separate SAN - Multi-level subdomains (
sub.sub.yourdomain.com) - these need additional SANs
When you add a hostname like shop.yourdomain.com to a smoxy Zone (the delivery and security configuration for a hostname - distinct from a DNS zone), smoxy checks if the existing wildcard certificate already covers it. If yes, no additional certificate work is needed.
Downloading Certificates
You can download your SSL certificate and private key for use in external tools:
- Open SSL Certificates in the smoxy sidebar and select the certificate
- Use the Download buttons for the certificate, chain, or private key
Required role: Owner or Manager
Subdomain Reuse
When you create the main domain (e.g., yourdomain.com) and a wildcard certificate is generated, all subdomains can reuse this certificate. When adding subdomains as hostnames to zones:
- No additional DNS verification is needed for the subdomain
- The existing wildcard certificate automatically covers the subdomain
- This significantly speeds up the setup of additional hostnames
INFO
Recommendation: Always create your main domain first, then add subdomains. This ensures the wildcard certificate is in place and subdomains can be configured without additional SSL steps.
Troubleshooting
Certificate stuck in "Pending"
- Check that all required
_acme-challengeCNAME records are set at your DNS provider - DNS propagation can take up to 48 hours (though usually much faster)
- If using Cloudflare, ensure the proxy is disabled for challenge records
DNS Status shows "Missing": record not found
The _acme-challenge CNAME record is not found. Verify:
- The record exists at your DNS provider
- It points to the correct target (shown on the certificate's SANs tab)
- DNS has had time to propagate
DNS Status shows "Missing": CNAME points to the wrong target
The CNAME record exists but points to an incorrect target, so it still counts as Missing. Update the record to the exact target shown on the certificate's SANs tab.
DNS Status shows "Missing": conflicting TXT record
A TXT record for _acme-challenge exists alongside or instead of the required CNAME, which also results in a Missing status. Remove the TXT record and ensure only the CNAME record exists.
Certificate not renewing
- Auto-managed certificates renew automatically within the CA's recommended renewal window (roughly two weeks before expiry as a fallback)
- Ensure the
_acme-challengeCNAME records are still in place - Self-managed certificates are never auto-renewed - you must upload a replacement
SAN changes not reflected
After adding new SANs, smoxy needs to regenerate the certificate. This happens automatically once the DNS verification for the new SAN passes. Check the SAN's DNS status on the certificate's SANs tab.