Metadata-Version: 2.4
Name: certbot-dns-galaxyweb
Version: 1.0.0
Summary: Certbot DNS-01 authenticator plugin for the Galaxyweb DNS Manager
Home-page: https://github.com/sis-GMBH/certbot-dns-galaxyweb
Author: Steiner IT Solutions GmbH
Author-email: info@steineritsolutions.ch
License: Apache-2.0
Project-URL: Homepage, https://docs.galaxyweb.ch/dns-manager/acme
Project-URL: Repository, https://github.com/galaxyweb/certbot-dns-galaxyweb
Keywords: certbot,letsencrypt,acme,dns,galaxyweb
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: certbot>=2.0.0
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: author-email
Dynamic: home-page

# certbot-dns-galaxyweb

Certbot DNS-01 authenticator plugin für den **Galaxyweb DNS Manager**.  
Setzt und entfernt `_acme-challenge`-TXT-Records automatisch über die REST-API –
kein Shell-Hook, keine manuellen curl-Aufrufe.

## Voraussetzungen

| Komponente | Version |
|------------|---------|
| Python     | ≥ 3.8   |
| certbot    | ≥ 2.0   |

---

## Installation

```bash
# Im selben Python-Environment wie certbot:
pip install certbot-dns-galaxyweb
```

Certbot erkennt das Plugin automatisch über den Entry-Point –  
kein zusätzliches `--configurator`-Flag nötig.

---

## API-Token erstellen

**Empfohlen – Wizard:**  
Portal → `/api-keys` → **Let's Encrypt Wizard** → Scope wird automatisch auf
`acme_only` eingeschränkt, Zone-Lockdown wird gesetzt.

**Manuell** (mehrere Zonen mit einem Token):  
Portal → `/api-keys` → Neuer API-Key → Scope `ACME_ONLY`, Rate-Limit 10/min,
IP-Allowlist auf den Certbot-Host einschränken.

---

## Credentials-Datei

Kopiere die Beispiel-Datei und trage deine Werte ein:

```bash
cp galaxyweb.ini.example /etc/letsencrypt/galaxyweb.ini
chmod 0600 /etc/letsencrypt/galaxyweb.ini   # nur root darf lesen
```

Inhalt:

```ini
# /etc/letsencrypt/galaxyweb.ini
certbot_dns_galaxyweb_api_url   = https://dns.example.ch
certbot_dns_galaxyweb_api_token = gw_xxxxxxxxxxxx_…
```

---

## Zertifikat ausstellen

```bash
certbot certonly \
  --authenticator dns-galaxyweb \
  --dns-galaxyweb-credentials /etc/letsencrypt/galaxyweb.ini \
  --dns-galaxyweb-propagation-seconds 30 \
  -d example.ch \
  -d '*.example.ch'
```

| Flag | Bedeutung |
|------|-----------|
| `--authenticator dns-galaxyweb` | Aktiviert dieses Plugin |
| `--dns-galaxyweb-credentials`   | Pfad zur INI-Datei |
| `--dns-galaxyweb-propagation-seconds` | Wartezeit nach dem Setzen des TXT-Records (Default: 30 s) |

### Wildcard + Apex gleichzeitig

```bash
certbot certonly \
  --authenticator dns-galaxyweb \
  --dns-galaxyweb-credentials /etc/letsencrypt/galaxyweb.ini \
  -d '*.example.ch' -d example.ch
```

Beide Domains verwenden denselben Record-Namen `_acme-challenge.example.ch`.
Das Plugin ruft für jede Domain separat `set_challenge` auf – der Manager
überschreibt den Record mit dem jeweils aktuellen Token, was dem ACME-Protokoll
entspricht (nur der letzte Challenge-Token zählt).

---

## Automatisches Renewal

certbot renew läuft idempotent – das Plugin wird automatisch erneut aufgerufen:

```bash
# /etc/cron.d/certbot  (Debian/Ubuntu liefert das mit)
0 */12 * * *  root  certbot renew --quiet --post-hook 'systemctl reload nginx'
```

Kein weiterer Konfigurationsaufwand.

---

## Troubleshooting

| Symptom | Ursache | Lösung |
|---------|---------|--------|
| `HTTP 401` | Token falsch oder abgelaufen | Portal → `/api-keys` → Status prüfen / regenerieren |
| `HTTP 403` (scope) | Token hat `read_only` statt `acme_only` | Scope im Portal hochstufen |
| `HTTP 403` (IP) | Quell-IP nicht in der Allowlist | IP in der Key-Konfiguration ergänzen |
| `HTTP 403` (read-only zone) | Zone ist Upstream-Sync oder Slave | Master direkt verwenden |
| `HTTP 429` | Rate-Limit überschritten | Rate-Limit im Portal anheben |
| CA meldet "no TXT record" | DNS-Propagation noch nicht abgeschlossen | `--dns-galaxyweb-propagation-seconds` auf 60 oder 120 erhöhen |
| Renewal schlägt fehl, manuell klappt | Env-Variablen im Cron-Kontext fehlen | Credentials stets aus INI-Datei lesen, nie als Env-Variable |

---

## Entwicklung & Tests

```bash
pip install -e ".[dev]"
pytest tests/
```

---

## Lizenz

Apache 2.0 – siehe [LICENSE](LICENSE).
