DAW/furt
2
0
Fork 0
Code Issues 11 Pull requests Projects Releases 3 Packages 1 Wiki Activity Actions
Page: Konfiguration
Pages
API Documentation Health Endpoint Home Installation Scripte Installation automatisiert Installation Konfiguration Mail Service API create service sh health check sh setup directories sh setup user sh sync files sh validate config sh
2 Konfiguration
michael edited this page 2025-09-10 14:12:26 +02:00
Table of Contents

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.

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

[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:

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:

[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:

[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:

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:

[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:

[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:

[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:

[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:

[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:

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

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

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