SSL Troubleshooting

This guide covers common SSL issues in smoxy and how to resolve them.

---

Understanding SSL Status

Your certificate's status and each SAN's DNS status are visible on the SSL Certificates page - open a certificate to see its SANs tab. The following conditions indicate an issue:

The SANs table on a certificate's detail view: each name's DNS and SSL status, plus the required CNAME record.

Pending

Meaning: Certificate generation has been initiated but is not yet complete.

What to do:

• Verify that all _acme-challenge CNAME records are configured at your DNS provider
• Allow time for DNS propagation (typically a few minutes, but can take up to 48 hours)
• smoxy will automatically pick up the generation once DNS is verified

If stuck for more than 1 hour:

• Check each SAN's DNS status on the certificate's SANs tab
• Look for SANs with "Missing" DNS status and fix those records
• smoxy retries automatically with increasing intervals

DNS Status: Missing

Meaning: The required _acme-challenge CNAME record was not found for one or more SANs. A record that points to the wrong target, or a conflicting TXT record, both also result in a Missing status - see the causes below.

Resolution:

1. Check the expected CNAME record shown on the certificate's SANs tab

2. Add the record at your DNS provider:

   Type:   CNAME
   Name:   _acme-challenge
   Target: yourdomain.com.acme.smoxy.eu.  (use the exact value shown on the SANs tab)

3. Wait for DNS propagation

4. smoxy checks missing records every 1 hour and will detect the change automatically

Cause: CNAME points to the wrong target

Meaning: A CNAME record for _acme-challenge exists, but it points to the wrong target, so the SAN stays in the Missing DNS status.

Resolution:

1. Go to your DNS provider
2. Update the _acme-challenge CNAME to the exact target shown on the certificate's SANs tab
3. smoxy will verify the updated record on the next check

Cause: conflicting TXT record

Meaning: A TXT record for _acme-challenge exists, which conflicts with the required CNAME record and keeps the SAN in the Missing DNS status.

Why this happens: Some DNS providers or previous setups may have created a TXT record for ACME challenges. smoxy requires a CNAME record instead.

Resolution:

1. Remove the TXT record for _acme-challenge at your DNS provider
2. Ensure only the CNAME record exists
3. smoxy will detect the change on the next check

---

Common Scenarios

Cloudflare Users

If you use Cloudflare as your DNS provider:

1. Disable the Cloudflare proxy (orange cloud) for the _acme-challenge CNAME record
2. The record must be DNS Only (grey cloud) for ACME verification to work
3. Your regular traffic records can still use the Cloudflare proxy

See Cloudflare Setup for detailed instructions.

Certificate Not Renewing Automatically

Auto-generated certificates renew within the CA's recommended renewal window (roughly two weeks before expiry as a fallback). If renewal isn't happening:

1. Check DNS records - The _acme-challenge CNAME records must still be in place
2. Check SAN DNS status - Open the certificate's SANs tab and verify all SANs show Valid DNS status
3. Rate limits - If smoxy hit Let's Encrypt rate limits, it waits before retrying

INFO

Note: Self-managed certificates are never auto-renewed. You must upload a replacement yourself.

Multiple Subdomains Not Covered

The default wildcard (*.yourdomain.com) covers single-level subdomains. It does not cover:

• Multi-level subdomains like sub.shop.yourdomain.com
• Different top-level domains

For these cases, smoxy can add additional SANs. Each additional SAN requires its own _acme-challenge CNAME record.

Certificate Shows as Expired

If your certificate has expired:

• Auto-managed: Check if the _acme-challenge DNS records are still in place. If they are, smoxy will attempt to renew. If they were removed, add them back.
• Self-managed: Upload a new certificate. smoxy cannot renew certificates it didn't generate.

SSL Generation Fails Repeatedly

If you see repeated failures in the SSL generation process:

Error	Cause	Resolution
CNAME record missing	The _acme-challenge CNAME record is missing for one or more SANs	Add the required CNAME record(s)
CNAME record invalid	The CNAME record exists but points to the wrong target	Update it 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
Rate limit	Too many certificate requests to Let's Encrypt	Automatic - smoxy waits and retries later
Internal error	An unexpected error occurred	smoxy retries; contact support if it persists

smoxy uses exponential backoff when retrying, increasing the wait time between attempts to avoid overwhelming external services.

The Attempts tab: each certificate generation and renewal attempt, expandable into its individual steps and any error.

---

Certificate Verification

To independently verify your SSL certificate is working:

Using a Browser

1. Visit your domain with https://
2. Click the padlock icon in the address bar
3. View certificate details to confirm:
   • Issued to the correct domain
   • Valid date range
   • Issued by the expected CA (Let's Encrypt for auto-managed)

Using Command Line

# Check certificate details
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com < /dev/null 2>/dev/null | openssl x509 -text -noout

# Check certificate expiration
echo | openssl s_client -connect yourdomain.com:443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -dates

---

Getting Help

If you've followed the troubleshooting steps and your SSL issue persists:

1. Note the exact status messages shown in smoxy
2. Check the Activity Log (under Team settings) for SSL-related events
3. Contact smoxy support with your domain name and the error details