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 (30 days before expiration)
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 → your-org.acme.smoxy.euThis CNAME record allows smoxy to complete the ACME DNS-01 challenge required by Let's Encrypt.
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 begins the renewal process 30 days before expiry. The renewal follows the same verification flow. If the DNS records are still in place, renewal 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.
SAN Status
Each SAN has two independent statuses:
| Status | Values | Meaning |
|---|---|---|
| DNS Status | Valid / Missing | Whether the _acme-challenge CNAME record is correctly configured |
| SSL Status | Covered / Not covered | Whether the current certificate actually includes this domain |
smoxy regularly re-checks DNS records:
- Every 12 hours for valid records (to detect removal)
- Every 1 hour for missing records (to detect when you've added them)
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 |
|---|---|---|
| Active | Certificate is valid and working | None |
| Pending | Certificate generation has been initiated but not yet completed | Wait for generation to complete |
| DNS Missing | The _acme-challenge CNAME record does not exist | Add the required CNAME record at your DNS provider |
| DNS Wrong | The CNAME record exists but points to the wrong target | Update the CNAME to point to the correct smoxy target |
| DNS Duplicate | A TXT record exists for _acme-challenge instead of the required CNAME | Remove the TXT record and create a CNAME record instead |
INFO
Note: Multiple DNS issues can exist simultaneously (e.g., some SANs may have missing records while others have wrong targets).
Certificate Generation Workflow
Behind the scenes, smoxy tracks certificate generation through a detailed workflow:
| Phase | What happens |
|---|---|
| Pending | Generation request is queued |
| Starting | Worker picks up the request |
| CNAME Check | Verifying DNS records for all SANs |
| Ordering | Requesting certificate from Let's Encrypt |
| Validating | ACME challenge validation in progress |
| Completed | Certificate successfully issued and installed |
If an error occurs during generation, smoxy automatically retries with exponential backoff. Common errors include:
| Error | Cause | Resolution |
|---|---|---|
| CNAME not found | DNS record missing for one or more SANs | Add the missing CNAME record(s) |
| TXT record exists | A TXT record for _acme-challenge conflicts with the CNAME | Remove the TXT record, keep only the CNAME |
| Rate limit | Too many certificate requests to Let's Encrypt | Automatic — smoxy waits and retries after 1 hour |
| Validation failed | ACME challenge could not be verified | Check DNS propagation; smoxy will retry automatically |
| Cloudflare error | Cloudflare proxy is interfering with DNS verification | Disable Cloudflare proxy for the _acme-challenge record |
Uploading a Self-managed Certificate
To upload your own SSL certificate:
- Navigate to Domains & DNS and select your domain
- Go to the SSL tab
- Click Upload Custom SSL Certificate
- Provide:
- Certificate (PEM format): The full certificate chain, including intermediate certificates
- Private Key (PEM format): The matching private key
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 site, 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:
- Navigate to Domains & DNS and select your domain
- Go to the SSL tab
- Click the Download button for the certificate or key
Required role: Owner or Maintainer
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 sites:
- 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 Missing" status
The _acme-challenge CNAME record is not found. Verify:
- The record exists at your DNS provider
- It points to the correct target (shown in smoxy)
- DNS has had time to propagate
"DNS Wrong" status
The CNAME record exists but points to an incorrect target. Update the record to point to the target shown in smoxy.
"DNS Duplicate" status
A TXT record for _acme-challenge exists alongside or instead of the required CNAME. Remove the TXT record and ensure only the CNAME record exists.
Certificate not renewing
- Auto-managed certificates renew automatically 30 days before expiration
- 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 in the SSL tab.