# SSL Troubleshooting

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

***

### Understanding SSL Status

Your domain's SSL status is visible on the **SSL tab** under **Domains & DNS**. The following statuses indicate an issue:

#### 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 SSL tab
* Look for SANs with "Missing" DNS status and fix those records
* smoxy retries automatically with increasing intervals

#### DNS Missing

**Meaning:** The required `_acme-challenge` CNAME record was not found for one or more SANs.

**Resolution:**

1. Check the expected CNAME record shown in smoxy
2. Add the record at your DNS provider:

   ```
   Type:   CNAME
   Name:   _acme-challenge
   Target: your-org.acme.smoxy.eu  (as shown in smoxy)
   ```
3. Wait for DNS propagation
4. smoxy checks missing records every **1 hour** and will detect the change automatically

#### DNS Wrong

**Meaning:** A CNAME record for `_acme-challenge` exists, but it points to the wrong target.

**Resolution:**

1. Go to your DNS provider
2. Update the `_acme-challenge` CNAME to point to the target shown in smoxy
3. smoxy will verify the updated record on the next check

#### DNS Duplicate

**Meaning:** A TXT record for `_acme-challenge` exists, which conflicts with the required CNAME record.

**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 30 days before expiration. If renewal isn't happening:

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

{% hint style="info" %}
**Note:** Self-managed certificates are **never** auto-renewed. You must upload a replacement yourself.
{% endhint %}

#### 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 not found           | DNS record missing                      | Add the required CNAME record                          |
| TXT ACME challenge exists | Conflicting TXT record                  | Remove the TXT record, keep CNAME only                 |
| Rate limit                | Too many Let's Encrypt requests         | Automatic — smoxy retries after 1 hour                 |
| Validation failed         | DNS propagation incomplete              | Wait for propagation, smoxy retries automatically      |
| Fetch DNS error           | DNS provider unreachable                | Temporary — smoxy retries automatically                |
| No SAN error              | No Subject Alternative Names configured | Contact support — SANs should be created automatically |

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

***

### 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

```bash
# 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