Konfiguration hinzugefügt
parent
cfdf4aea4f
commit
39562e9e9e
1 changed files with 242 additions and 0 deletions
242
Konfiguration.md
Normal file
242
Konfiguration.md
Normal file
|
|
@ -0,0 +1,242 @@
|
|||
# Konfiguration
|
||||
|
||||
**furt für mehrere Websites einrichten**
|
||||
|
||||
## Getestet unter
|
||||
- OpenBSD 7.7
|
||||
- Debian 12
|
||||
- Arch Linux
|
||||
|
||||
## Konfigurationskonzept verstehen
|
||||
|
||||
furt wurde als Gateway für mehrere Websites entwickelt. Ein einzelner furt-Server kann Formulardaten von verschiedenen Websites entgegennehmen und an unterschiedliche E-Mail-Adressen weiterleiten. Jede Website erhält einen eigenen API-Key mit spezifischen Berechtigungen und Mail-Routing-Regeln.
|
||||
|
||||
Diese Architektur ermöglicht es einem Hosting-Provider mehrere Kunden über eine furt-Instanz zu bedienen, oder einem Unternehmen verschiedene Websites zentral zu verwalten. Jeder API-Key definiert wohin Mails weitergeleitet werden, welche SMTP-Server verwendet werden und von welchen IP-Adressen Anfragen akzeptiert werden.
|
||||
|
||||
## Konfigurationsdatei-Struktur
|
||||
|
||||
furt nutzt INI-Format mit mehreren Abschnitten. Die Konfigurationsdatei liegt je nach System unter:
|
||||
|
||||
- OpenBSD: `/usr/local/etc/furt/furt.conf`
|
||||
- Linux: `/etc/furt/furt.conf`
|
||||
|
||||
Das INI-Format macht die Konfiguration für Menschen lesbar und ermöglicht einfache Anpassungen ohne komplexe Parser oder spezielle Tools.
|
||||
|
||||
```ini
|
||||
# Server-Grundkonfiguration
|
||||
[server]
|
||||
host = 127.0.0.1
|
||||
port = 7811
|
||||
|
||||
# Standard-SMTP für alle Websites
|
||||
[smtp_default]
|
||||
host = mail.example.com
|
||||
user = noreply@example.com
|
||||
|
||||
# Website-spezifische API-Keys
|
||||
[api_key "website-name"]
|
||||
name = "Beschreibung"
|
||||
permissions = mail:send
|
||||
```
|
||||
|
||||
## Server-Grundkonfiguration
|
||||
|
||||
Der `[server]`-Abschnitt definiert auf welcher IP-Adresse und welchem Port furt lauscht:
|
||||
|
||||
```ini
|
||||
[server]
|
||||
host = 127.0.0.1
|
||||
port = 7811
|
||||
log_level = info
|
||||
log_requests = true
|
||||
client_timeout = 10
|
||||
```
|
||||
|
||||
Die Standard-Konfiguration bindet furt an localhost Port 7811. In Produktionsumgebungen läuft oft ein Reverse-Proxy wie nginx oder Apache vor furt, der SSL-Terminierung und Load-Balancing übernimmt. Die Logging-Optionen steuern wie detailliert furt Anfragen protokolliert.
|
||||
|
||||
Der `client_timeout` bestimmt nach wie vielen Sekunden eine HTTP-Verbindung geschlossen wird wenn der Client keine vollständige Anfrage sendet.
|
||||
|
||||
## CORS-Konfiguration für Frontend-Integration
|
||||
|
||||
Moderne Websites nutzen oft JavaScript für Formular-Submissions. Der CORS-Mechanismus kontrolliert von welchen Domains Browser API-Anfragen akzeptieren:
|
||||
|
||||
```ini
|
||||
cors_allowed_origins = http://localhost:1313,https://example.com,https://www.example.com
|
||||
```
|
||||
|
||||
Diese Liste enthält alle Domains von denen furt Cross-Origin-Requests akzeptiert. Entwicklungsserver laufen oft auf localhost mit verschiedenen Ports, während Produktions-Websites ihre eigenen Domains nutzen.
|
||||
|
||||
## Standard-SMTP-Konfiguration
|
||||
|
||||
Der `[smtp_default]`-Abschnitt definiert die Standard-SMTP-Einstellungen die alle API-Keys verwenden, außer sie überschreiben diese mit eigenen Werten:
|
||||
|
||||
```ini
|
||||
[smtp_default]
|
||||
host = mail.example.com
|
||||
port = 465
|
||||
user = noreply@example.com
|
||||
password = your-smtp-password-here
|
||||
use_ssl = true
|
||||
```
|
||||
|
||||
Port 465 ist der Standard für SMTP mit SSL-Verschlüsselung. Alternativ kann Port 587 mit STARTTLS verwendet werden. Die meisten modernen Mail-Provider erwarten verschlüsselte Verbindungen und verweigern unverschlüsselte Logins.
|
||||
|
||||
## API-Keys für verschiedene Websites
|
||||
|
||||
Jede Website die furt nutzen möchte benötigt einen eigenen API-Key-Abschnitt. Der Abschnittsname in Anführungszeichen wird als API-Key verwendet:
|
||||
|
||||
```ini
|
||||
[api_key "daw-frontend-key"]
|
||||
name = "Dragons@Work Website"
|
||||
permissions = mail:send
|
||||
allowed_ips = 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16
|
||||
mail_to = admin@dragons-at-work.de
|
||||
mail_from = noreply@dragons-at-work.de
|
||||
mail_subject_prefix = "[DAW Contact] "
|
||||
```
|
||||
|
||||
Das `name`-Feld dient der menschenlesbaren Beschreibung in Logs und Fehlermeldungen. Die `permissions` definieren welche API-Endpunkte dieser Key verwenden darf. Aktuell unterstützt furt `mail:send` für Mail-Weiterleitung und `health:check` für Monitoring.
|
||||
|
||||
Die `allowed_ips` Liste kontrolliert von welchen IP-Adressen Anfragen mit diesem API-Key akzeptiert werden. CIDR-Notation ermöglicht Netzwerk-Bereiche statt einzelner IPs.
|
||||
|
||||
## Mail-Routing pro Website
|
||||
|
||||
Jeder API-Key definiert wohin eingehende Mails weitergeleitet werden. Die `mail_to` Adresse ist das finale Ziel, `mail_from` erscheint als Absender der weitergeleiteten Mail:
|
||||
|
||||
```ini
|
||||
mail_to = admin@example.com
|
||||
mail_from = noreply@example.com
|
||||
mail_subject_prefix = "[Website] "
|
||||
```
|
||||
|
||||
Das `mail_subject_prefix` wird allen Betreffzeilen vorangestellt um Mails verschiedener Websites zu unterscheiden. So kann ein Postfach Mails von mehreren Websites empfangen ohne dass diese vermischt werden.
|
||||
|
||||
## Websites mit eigenen SMTP-Servern
|
||||
|
||||
Manche Kunden möchten ihre eigenen SMTP-Server verwenden statt den Standard-Server. API-Keys können die Standard-SMTP-Einstellungen überschreiben:
|
||||
|
||||
```ini
|
||||
[api_key "kunde-eigener-smtp"]
|
||||
name = "Kunde mit eigenem Mail-Server"
|
||||
permissions = mail:send
|
||||
allowed_ips = 198.51.100.0/24
|
||||
mail_to = support@kunde-server.com
|
||||
mail_from = noreply@kunde-server.com
|
||||
# Überschreibt smtp_default-Einstellungen
|
||||
mail_smtp_host = mail.kunde-server.com
|
||||
mail_smtp_port = 587
|
||||
mail_smtp_user = api@kunde-server.com
|
||||
mail_smtp_pass = kunde-smtp-passwort
|
||||
mail_smtp_ssl = true
|
||||
```
|
||||
|
||||
Die `mail_smtp_*` Parameter überschreiben selektiv die Standard-SMTP-Konfiguration. Andere API-Keys nutzen weiterhin den Standard-SMTP-Server. Diese Flexibilität ermöglicht es Unternehmen ihre eigene Mail-Infrastruktur zu nutzen während andere Kunden den Hosting-Provider-SMTP verwenden.
|
||||
|
||||
## Externe Mail-Provider integrieren
|
||||
|
||||
Auch kommerzielle Mail-Provider wie Gmail können als SMTP-Backend fungieren:
|
||||
|
||||
```ini
|
||||
[api_key "kunde-gmail"]
|
||||
name = "Kunde mit Gmail"
|
||||
permissions = mail:send
|
||||
allowed_ips = 9.10.11.12/32
|
||||
mail_to = support@kunde.com
|
||||
mail_from = website@kunde.com
|
||||
# Gmail SMTP Konfiguration
|
||||
mail_smtp_host = smtp.gmail.com
|
||||
mail_smtp_port = 587
|
||||
mail_smtp_user = website@kunde.com
|
||||
mail_smtp_pass = gmail-app-password
|
||||
mail_smtp_ssl = true
|
||||
```
|
||||
|
||||
Gmail erfordert App-Passwörter statt des normalen Account-Passworts für SMTP-Zugriff. Andere Provider haben ähnliche Authentifizierungs-Mechanismen.
|
||||
|
||||
## Administrative API-Keys
|
||||
|
||||
Neben Website-spezifischen API-Keys kannst du Administrative Keys für Monitoring und Verwaltung definieren:
|
||||
|
||||
```ini
|
||||
[api_key "admin-management-key"]
|
||||
name = "Admin Access"
|
||||
permissions = *, mail:send, auth:status
|
||||
allowed_ips = 127.0.0.1, 10.0.0.0/8
|
||||
```
|
||||
|
||||
Das `*` in permissions gewährt Zugriff auf alle API-Endpunkte. Administrative Keys sollten restriktive IP-Beschränkungen haben um unbefugten Zugriff zu verhindern.
|
||||
|
||||
Monitoring-Keys benötigen oft nur Health-Check-Zugriff:
|
||||
|
||||
```ini
|
||||
[api_key "monitoring-health-key"]
|
||||
name = "Monitoring Service"
|
||||
permissions = health:check
|
||||
allowed_ips = 127.0.0.1, 10.0.0.0/8, 172.16.0.0/12
|
||||
```
|
||||
|
||||
Diese Keys können von Monitoring-Systemen verwendet werden ohne Zugriff auf sensitive Mail-Funktionen zu gewähren.
|
||||
|
||||
## Sicherheitseinstellungen
|
||||
|
||||
Der `[security]`-Abschnitt definiert globale Sicherheitsparameter:
|
||||
|
||||
```ini
|
||||
[security]
|
||||
rate_limit_api_key_max = 60
|
||||
rate_limit_ip_max = 100
|
||||
rate_limit_window = 3600
|
||||
enable_test_endpoint = false
|
||||
```
|
||||
|
||||
Rate-Limiting verhindert Missbrauch durch zu viele Anfragen. Die Limits gelten pro API-Key und pro IP-Adresse innerhalb eines Zeitfensters. Der Test-Endpunkt sollte in Produktionsumgebungen deaktiviert bleiben da er interne Informationen preisgeben kann.
|
||||
|
||||
## Konfiguration validieren
|
||||
|
||||
Nach Änderungen an der Konfiguration solltest du die Syntax prüfen:
|
||||
|
||||
```bash
|
||||
# OpenBSD
|
||||
doas /usr/local/share/furt/scripts/validate-config.sh
|
||||
|
||||
# Linux
|
||||
sudo /usr/local/share/furt/scripts/validate-config.sh
|
||||
```
|
||||
|
||||
Das Validations-Script prüft die INI-Syntax und stellt sicher dass alle erforderlichen Abschnitte vorhanden sind. Bei Syntax-Fehlern gibt es spezifische Hinweise auf die problematischen Zeilen.
|
||||
|
||||
## Konfiguration neu laden
|
||||
|
||||
furt liest die Konfigurationsdatei beim Start. Nach Änderungen musst du den Service neu starten:
|
||||
|
||||
```bash
|
||||
# OpenBSD
|
||||
doas rcctl restart furt
|
||||
|
||||
# Linux
|
||||
sudo systemctl restart furt
|
||||
```
|
||||
|
||||
Ein Neustart ist notwendig da furt die komplette Konfiguration in den Speicher lädt und nicht kontinuierlich auf Datei-Änderungen überwacht.
|
||||
|
||||
## Konfiguration testen
|
||||
|
||||
Nach Konfigurationsänderungen solltest du die Funktionalität testen:
|
||||
|
||||
```bash
|
||||
# Health-Check für Service-Status
|
||||
curl http://127.0.0.1:7811/health
|
||||
|
||||
# API-Key-Authentifizierung testen
|
||||
curl -H "X-API-Key: daw-frontend-key" http://127.0.0.1:7811/v1/auth/status
|
||||
|
||||
# Mail-Weiterleitung testen
|
||||
curl -X POST http://127.0.0.1:7811/v1/mail/send \
|
||||
-H "X-API-Key: daw-frontend-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Test","email":"test@example.com","subject":"Config Test","message":"Konfiguration funktioniert"}'
|
||||
```
|
||||
|
||||
Der Auth-Status-Endpunkt zeigt welche Permissions der verwendete API-Key hat. Der Mail-Test sendet eine echte E-Mail an die konfigurierte Adresse und bestätigt dass SMTP-Routing funktioniert.
|
||||
|
||||
Diese flexible Konfigurationsarchitektur ermöglicht es furt als zentraler Mail-Gateway für komplexe Multi-Website-Umgebungen zu fungieren, während jede Website ihre spezifischen Routing- und Sicherheitsanforderungen erfüllen kann.
|
||||
Loading…
Add table
Add a link
Reference in a new issue