Grundkonfiguration

Erste Schritte

Jede Site in smoxy stellt einen isolierten Konfigurationsbereich für eine oder mehrere Hostnamen dar. Die Site Grundkonfiguration ist der Ort, an dem du das Kernverhalten der Site definierst – einschließlich der Weiterleitung zum Zielserver, Aktivierung von CDN- und Optimierungsfunktionen sowie Verwaltung von Caching-Verhalten und Fallback-Seiten.

Bevor du mit Regeln, Antwort-Headern, SSL-Einstellungen oder Analytics weitermachst, solltest du sicherstellen, dass deine Seite hier korrekt konfiguriert ist. Diese Konfiguration ist die Grundlage für alle weiteren Funktionen in smoxy.

---

smoxy Aktivierung

Schalter: smoxy aktivieren Dieser Schalter aktiviert die Optimierungsfunktionen von smoxy. Wenn aktiviert, übernimmt smoxy:

• Bildoptimierung

• HTML-Caching und -Beschleunigung

• Sicherheitsfunktionen wie Bot Protection

Wenn deaktiviert, fungiert smoxy lediglich als Reverse Proxy und umgeht alle Caching-, Optimierungs- und Schutzlogiken.

Hinweis: Bei Deaktivierung werden CDN, HTML-Caching und Optimierung gestoppt. DNS und Routing bleiben funktionsfähig.

---

Hostnamen Verwalten

Hostname hinzufügen

Jede Seite kann einen oder mehrere Hostnamen bedienen. Das Hinzufügen eines Hostnamens verknüpft ihn mit der Seitenkonfiguration.

Beim Hinzufügen eines Hostnamens:

1. Einen gültigen Domainnamen eingeben

2. Formular absenden

smoxy überprüft DNS- und SSL-Status asynchron im Hintergrund.

Stelle sicher dass:

• Der DNS Eintrag auf den bereitgestellten CNAME-Zielwert gesetzt ist (einzigartig pro Hostname)

• Das SSL-Zertifikat am besten durch smoxy verwalten wird

So funktioniert SSL in smoxy: Wenn du einen Hostname hinzufügst, wird die Root-Domain dieses Hostnamens automatisch im Domain-Management von smoxy hinterlegt. Dort kannst du smoxy ein SSL-Zertifikat generieren lassen. Für jeden SAN (Subject Alternative Name) wird ein eigener _acme_challenge-DNS-Eintrag verlangt.

Bei neuen Domains legt smoxy automatisch SAN-Einträge für deinedomain.de und *.deinedomain.de an – ein idealer Ausgangspunkt für Wildcard-Zertifikate.

Tipp: Du kannst auch eigene SSL-Zertifikate hochladen. Beachte aber, dass smoxy diese nicht automatisch erneuern kann – du musst sie vor Ablauf manuell ersetzen.

Verknüpfte Hostnamen

Für jeden verknüpften Hostnamen kannst du:

• Die Website aufrufen

• Konfigurationsprobleme anzeigen (z. B. fehlendes CNAME)

• Hostnamen verschieben

• Hostnamen löschen

• DNS- & SSL-Einstellungen aufrufen

---

Origin oder Loadbalancer

Wähle das Zielsystem, an das smoxy Anfragen weiterleiten soll:

• Origin: Ein einzelner Server

• Loadbalancer: Eine Gruppe von Servern, zwischen denen smoxy automatisch Lastverteilung betreibt

Du kannst jederzeit zwischen Origin und Loadbalancer wechseln.

Ein Wechsel des Ziels leert nicht automatisch den Cache. Nutze entweder die Invalidation-API oder den Zonenschlüssel. Alternativ stehen dir im Dashboard einer Seite folgende Schnellaktionen zur Verfügung:

• Gesamten Cache leeren

• Cache per URL leeren

• Cache per Tag leeren

---

Seitentoken

Jede Seite hat ein eindeutiges Invalidierungs-Token, das verwendet wird für:

• Cache-Bypass über speziellen Header

• Authentifizierung für die Invalidation-API

Eine Änderung dieses Tokens betrifft alle verknüpften Hostnamen der Seite.

---

Debug-Header

Zeigt HTTP-Header mit internen smoxy-Debug-Informationen an.

Wenn aktiviert, liefert smoxy unter anderem folgende Header:

• s-cache: Cache-Status (HIT, MISS, BYPASS)

• s-cache-key-page-str: Zusammensetzung des Cache-Schlüssels (z. B. host, uri)

• s-debug-message: Immer 1, wenn aktiv

• s-env: Umgebung (z. B. prod, dev)

• s-node: smoxy-Knoten, der die Anfrage verarbeitet hat

• s-upstream: Zielserver der Anfrage

• s-zone-id: Kombination aus Organisations- und Seiten-ID (z. B. 5_38)

Zusätzlich wird in den Headern angezeigt, welche Regeln geprüft und angewendet wurden.

---

SSI & ESI

SSI (Server Side Includes)

Erlaubt die Verarbeitung von <!--#include -->-Anweisungen. Damit kann smoxy serverseitige Fragment-Includes rendern.

ESI (Edge Side Includes)

smoxy erkennt <esi:include> Tags in HTML-Antworten und wandelt sie automatisch in SSI-Direktiven (<!--#include-->) um. So können Anwendungen, die ursprünglich für ESI entwickelt wurden, ohne Anpassungen weiterhin verwendet werden.

Folgende ESI-Strukturen werden automatisch umgeschrieben:

• <esi:include src="..."/> → <!--#include virtual="..." -->

• <esi:remove>...</esi:remove> → wird komplett entfernt

• <esi:choose> → <!--#if expr="" -->

• <esi:when test="..."> → <!--#if expr="%1" -->

  • </esi:when> → <!--#endif -->

• <esi:otherwise> → <!--#else -->

  • </esi:otherwise> → ""

• <esi:choose> → <!--#if expr=""

  • </esi:choose> → <!--#endif -->

Die Umschreibung erfolgt automatisch während der Response-Verarbeitung und ermöglicht eine Kompatibilität mit gängigen ESI-Implementierungen (z. B. von Varnish oder Akamai), solange deren Logik in SSI übertragbar ist.

---

Läuft ab in (Cache-Lebensdauer)

Bestimmt, wie lange Ressourcen im Cache verbleiben:

• Wert 0 = Standardwert von smoxy (7 Tage)

• Minimal: 300 Sekunden

• Maximal: 604800 Sekunden (7 Tage)

---

Cache-Control Header beachten

Wenn aktiviert, berücksichtigt smoxy den Cache-Control-Header der Ursprungsantwort.

• Werte wie no-store, private, max-age=0, no-cache führen zu einem Cache-Bypass

---

Cache Key

Konfiguriere, welche Parameter in die Cache-Key-Berechnung einfließen.

Optionen:

• Anfrage Hostname: Caching basiert auf dem Hostname

• Cookie: Caching basiert zusätzlich auf bestimmten Cookie-Werten. Liste der Cookie-Namen erforderlich.

Jede Kombination führt zu einem separaten Cache-Objekt.

---

Ausgeschlossene URL-Parameter

Definiere eine Liste von GET-Parametern, die bei der Cache-Key-Berechnung ignoriert werden sollen.

Typische Anwendung: Bei vielen Marketing-Kampagnen kommen unterschiedliche Tracking-Parameter wie utm_*, gclid, ref, etc. zum Einsatz. Ohne Ausschluss wird jede URL als individuelle Seite behandelt – mit schlechter Cache-Hitrate.

Durch den Ausschluss:

• Steigt die Cache-Hitrate deutlich

• Wird die Antwort direkt von smoxy ausgeliefert

• Kommt ggf. keine Anfrage beim Backend an (Server-seitiges Tracking fällt aus)

---

Ignorierte Cache-Tags

Manche Anwendungen liefern sehr viele, wiederholte Cache-Tags in jeder Antwort. Ein Purge auf Basis eines dieser Tags kann dann viel mehr löschen als beabsichtigt.

Mit dieser Funktion kannst du solche Tags ignorieren lassen. Sie werden beim Cache-Aufbau nicht gespeichert und können somit nicht versehentlich zu einem großen Purge führen.

---

Benutzerdefinierte Cache-Tag-Header

Standardmäßig erwartet smoxy den Header x-cache-tags, um Cache-Tags aus der Antwort zu extrahieren.

Wenn deine Anwendung andere Header oder Trennzeichen (z. B. xkey, Leerzeichen) verwendet, kannst du diese hier definieren. smoxy wird sich entsprechend anpassen.

Bis zu 4 Header mit jeweils eigenem Trennzeichen sind möglich.

---

Stale Cache (nur mit CDN)

Zwei Optionen zum temporären Ausliefern abgelaufener Cache-Daten:

• While Offline: Wenn das Zielsystem nicht erreichbar ist

• While Updating: Während eine neue Version im Hintergrund geladen wird

Verbessert Verfügbarkeit und Antwortzeiten.

---

Cache Error Response (nur mit CDN)

Wenn aktiviert, werden Fehlermeldungen (HTTP 5xx) für 5 Sekunden im Cache gehalten. Dies schützt dein Ursprungssystem bei hoher Last oder DDoS.

---

HTTP-Header

Request Header

Wird beim Weiterleiten an das Zielsystem mitgeschickt:

x-app-env = staging
x-feature-flag = true

Response Header

Wird an den Client mitgeschickt, nachdem die Antwort generiert wurde.

---

Eigene Seiten

Fehlerseite (502/504)

HTML-Datei hochladen, die bei Fehlercodes 502 oder 504 angezeigt wird.

• Maximalgröße: 4 KB

• Unterstützte Platzhalter:

  • ::SX_STATUS::

  • ::SX_REMOTE_IP::

  • ::SX_HOST::

  • ::SX_STATUS_TEXT::

Sicherheitsseite

Wird angezeigt, wenn smoxy eine Anfrage aufgrund von Sicherheitsregeln blockiert hat. Unterstützt dieselben Platzhalter wie die Fehlerseite.

Wartungsseite

Wird angezeigt, wenn der Wartungsmodus aktiviert ist. Du kannst auch IP-basierte Ausnahmen definieren (über Regeln).