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:

1. Certificate request

2. DNS challenge verification

3. Certificate issuance

4. 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

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.eu

This CNAME record allows smoxy to complete the ACME DNS-01 challenge required by Let's Encrypt.

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:

1. Requests a certificate from Let's Encrypt

2. Completes the ACME challenge

3. Downloads and installs the certificate

4. 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

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:

1. Navigate to Domains & DNS and select your domain

2. Go to the SSL tab

3. Click Upload Custom SSL Certificate

4. 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.com

• shop.yourdomain.com

• api.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:

1. Navigate to Domains & DNS and select your domain

2. Go to the SSL tab

3. 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

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-challenge CNAME 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-challenge CNAME 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.