kazeyukiro
bcee7502ff
Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes. docs: align panel SSL with DNS-01 wildcards Add panel-ssl.md; update README, installation, batch-certificate, and OpenAPI /system/ssl for challenge, Cloudflare token, and recovery notes.
62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# Panel SSL (HTTPS / ACME)
|
||
|
||
Panel TLS is configured under **Settings → Certificates / SSL** (API: `GET/PUT /api/v1/system/ssl`). Changes apply after **restarting the panel** (`systemctl restart 3m-ui` or the in-panel restart action).
|
||
|
||
## Modes
|
||
|
||
| Mode | When | Notes |
|
||
|------|------|--------|
|
||
| **HTTP-01** (default) | Single hostname, port **80** reachable from the internet | `golang.org/x/crypto/acme/autocert` |
|
||
| **DNS-01** | Wildcard `*.example.com`, or no usable port 80 | Cloudflare API token; via `acmez` |
|
||
| **IP certificate** | Domain field is a public IP | Short-lived Let’s Encrypt profile; HTTP-01 / TLS-ALPN-01 |
|
||
| **Manual** | `cert_file` + `key_file` set | Paths must be under allowlisted dirs (e.g. `/etc/letsencrypt/`, `/var/lib/3m-ui/`) |
|
||
|
||
## Wildcard (`*.example.com`)
|
||
|
||
1. Set **Domain** to `*.example.com` (or a normal hostname with **Challenge = DNS-01**).
|
||
2. Set **ACME challenge** to **DNS-01**.
|
||
3. **DNS provider**: Cloudflare (currently the only built-in provider).
|
||
4. **DNS API token**: Cloudflare token with **Zone → DNS → Edit** on that zone. Leave the field blank on later saves to keep the stored token.
|
||
5. **DNS zone** (optional): e.g. `example.com` if auto-detect fails.
|
||
6. Save and **restart** the panel. Issuance runs at startup (may take tens of seconds).
|
||
|
||
The certificate includes both `*.example.com` and the apex `example.com`.
|
||
|
||
**Not supported as automatic ACME without DNS-01:** filling only `*.example.com` with HTTP-01.
|
||
|
||
### Cloudflare token
|
||
|
||
- Permission: `Zone` → `DNS` → **Edit**
|
||
- Resource: the zone that hosts the domain
|
||
|
||
## API fields (`PUT /system/ssl`)
|
||
|
||
| Field | Description |
|
||
|-------|-------------|
|
||
| `enabled` | Enable panel HTTPS |
|
||
| `domain` | Hostname, `*.example.com`, or public IP |
|
||
| `email` | ACME account contact |
|
||
| `challenge` | empty / `http-01` (default) or `dns-01` |
|
||
| `dns_provider` | `cloudflare` |
|
||
| `dns_token` | Provider API token (not returned on `GET`; empty on PUT keeps previous) |
|
||
| `dns_zone` | Optional zone name |
|
||
| `cache_dir` | ACME cache (default under data dir, e.g. `/var/lib/3m-ui/acme`) |
|
||
| `cert_file` / `key_file` | Manual PEM paths |
|
||
| `listen_http` / `listen_tls` | e.g. `:80` / `:443` |
|
||
|
||
`GET /system/ssl/status` includes `mode` (`letsencrypt`, `letsencrypt-dns01`, `letsencrypt-ip`, `manual`, …), `is_wildcard`, `has_dns_token`, etc.
|
||
|
||
## Misconfiguration / recovery
|
||
|
||
```bash
|
||
3m-ui reset-config --panel --yes # or use the SSH menu reset option
|
||
systemctl restart 3m-ui
|
||
```
|
||
|
||
You do **not** need a full reinstall to undo a bad SSL setting.
|
||
|
||
## Related
|
||
|
||
- [Batch apply certificate to nodes](./batch-certificate.md)
|
||
- Nodes can reuse panel manual cert paths via **Apply cert** → `from_panel_ssl` when panel SSL uses file paths (ACME cache formats differ; prefer manual PEMs or Let’s Encrypt live paths for listeners).
|