diff --git a/Konfiguration.md b/Konfiguration.md new file mode 100644 index 0000000..0477b7b --- /dev/null +++ b/Konfiguration.md @@ -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. \ No newline at end of file