Tuxipedia - Benutzerbeiträge [de]

Belegversand

2026-08-19T14:53:58Z

Admin: /* 2. Repository klonen */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt potentiell fahrlässig!

== Aktuelle Softwareversion (August 2026) ==

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 4.x, Apple Mail
; Lizenz: MIT-License
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 4.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand

cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)

; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)

; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")

; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)

; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")

; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")

; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)

; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)

; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")

; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")

; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:
<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

* 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

* 1.3: Dry-Run Verbesserungen, Markdown-Logs

* 1.2: Mail-Templates in DEVONthink, interne README

* 1.1: Konfigurationssystem

* 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T17:25:41Z

Admin:

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt potentiell fahrlässig!

== Aktuelle Softwareversion (August 2026) ==

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 4.x, Apple Mail
; Lizenz: MIT-License
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 4.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)

; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)

; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")

; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)

; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")

; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")

; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)

; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)

; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")

; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")

; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:
<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

* 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

* 1.3: Dry-Run Verbesserungen, Markdown-Logs

* 1.2: Mail-Templates in DEVONthink, interne README

* 1.1: Konfigurationssystem

* 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T17:21:36Z

Admin: /* Sicherheitstechnischer Hinweis! */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt potentiell fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)

; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)

; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")

; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)

; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")

; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")

; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)

; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)

; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")

; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")

; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:
<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

* 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

* 1.3: Dry-Run Verbesserungen, Markdown-Logs

* 1.2: Mail-Templates in DEVONthink, interne README

* 1.1: Konfigurationssystem

* 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:47:22Z

Admin: /* Booking-Jahr Enforcement */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)

; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)

; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")

; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)

; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")

; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")

; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)

; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)

; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")

; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")

; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:
<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

* 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

* 1.3: Dry-Run Verbesserungen, Markdown-Logs

* 1.2: Mail-Templates in DEVONthink, interne README

* 1.1: Konfigurationssystem

* 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:45:49Z

Admin: /* Wichtigste Parameter */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)

; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)

; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")

; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)

; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")

; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")

; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)

; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)

; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")

; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")

; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

* 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

* 1.3: Dry-Run Verbesserungen, Markdown-Logs

* 1.2: Mail-Templates in DEVONthink, interne README

* 1.1: Konfigurationssystem

* 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:44:38Z

Admin: /* Versionshistorie */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

* 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

* 1.3: Dry-Run Verbesserungen, Markdown-Logs

* 1.2: Mail-Templates in DEVONthink, interne README

* 1.1: Konfigurationssystem

* 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:44:12Z

Admin: /* Externe Links */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

- 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

- 1.3: Dry-Run Verbesserungen, Markdown-Logs

- 1.2: Mail-Templates in DEVONthink, interne README

- 1.1: Konfigurationssystem

- 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository]
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:43:46Z

Admin: /* "Mixed-Year-Selection"-Fehler */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

- Lösung 1: Nur Belege aus einem Buchungsjahr auswählen

- Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

- 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

- 1.3: Dry-Run Verbesserungen, Markdown-Logs

- 1.2: Mail-Templates in DEVONthink, interne README

- 1.1: Konfigurationssystem

- 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:43:14Z

Admin: /* Versionshistorie */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

- 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration

- 1.3: Dry-Run Verbesserungen, Markdown-Logs

- 1.2: Mail-Templates in DEVONthink, interne README

- 1.1: Konfigurationssystem

- 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:42:50Z

Admin: /* Versionshistorie */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

- 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
- 1.3: Dry-Run Verbesserungen, Markdown-Logs
- 1.2: Mail-Templates in DEVONthink, interne README
- 1.1: Konfigurationssystem
- 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:42:24Z

Admin: /* Protokollierung */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt ''Booking-Jahr Enforcement'').

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:41:26Z

Admin: /* Booking-Jahr Enforcement */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
├── 02_Februar/
├── .../
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind.
Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:40:06Z

Admin: /* Protokollierung */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind.
Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:37:15Z

Admin:

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<code>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</code>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

- Die Versandvorgänge werden jeweils doppelt protokolliert. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.
- Zum anderen im menschlich lesbaren Mark-Down-Textformatm mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres, wenn innerhalb dieses Jahres Dokumente versendet wurden.
Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:30:42Z

Admin: /* Markdown-Logs */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:25:37Z

Admin: /* Markdown-Logs */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<code>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</code>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:24:40Z

Admin: /* 2. Repository klonen */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<code lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</code>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:23:07Z

Admin: /* 1. Verzeichnisstruktur anlegen */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<code lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</code>

==== 2. Repository klonen ====

<source lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</source>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:19:15Z

Admin: /* Automatische Initialisierung */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<source lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</source>

==== 2. Repository klonen ====

<source lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</source>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<pre>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</pre>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T16:18:45Z

Admin: /* Booking-Jahr Enforcement */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<source lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</source>

==== 2. Repository klonen ====

<source lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</source>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<source>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</source>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<pre>
Belege/
├── 2026/
│ ├── 01_Januar/
│ └── Versendet/ [← Logs]
├── 2027/
│ └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</pre>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T15:44:14Z

Admin: /* Sicherheitstechnischer Hinweis! */

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<source lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</source>

==== 2. Repository klonen ====

<source lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</source>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<source>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</source>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<source>
Belege/
├── 2026/
│ ├── 01_Januar/
│ ├── [weitere Monate]
│ └── Versendet/ [← Logs für 2026-Versand]
├── 2027/
│ ├── 01_Januar/
│ ├── [weitere Monate]
│ └── Versendet/ [← Logs für 2027-Versand]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</source>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T15:43:17Z

Admin:

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

== Sicherheitstechnischer Hinweis! ==

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.
Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich: Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin gilt aber ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<source lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</source>

==== 2. Repository klonen ====

<source lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</source>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<source>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</source>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<source>
Belege/
├── 2026/
│ ├── 01_Januar/
│ ├── [weitere Monate]
│ └── Versendet/ [← Logs für 2026-Versand]
├── 2027/
│ ├── 01_Januar/
│ ├── [weitere Monate]
│ └── Versendet/ [← Logs für 2027-Versand]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</source>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Belegversand

2026-08-18T12:55:39Z

Admin: Ausfühlriche Doku: Appleskript-Paket für die Datenbanksoftware DEVONthink, das beliebige Dokumente aus der Datenbank per Mail automatisuert versendet, diese Dokumente innerhalb von DEVONthink taggt und die Vorgänge protokolliert.

= Belegversand =

== Übersicht ==

'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

; Version: 1.4
; Plattform: macOS 10.13+
; Abhängigkeiten: DEVONthink 3.x, Apple Mail
; Lizenz: Privatgebrauch
; Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

== Installation ==

=== Voraussetzungen ===

* macOS 10.13 oder neuer
* DEVONthink 3.x
* Apple Mail
* AppleScript-Zugriff in Systemeinstellungen aktiviert
* Git (zum Klonen des Repositories)

=== Schritt-für-Schritt Anleitung ===

==== 1. Verzeichnisstruktur anlegen ====

<source lang="bash">
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
</source>

==== 2. Repository klonen ====

<source lang="bash">
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
</source>

==== 3. Scripts kompilieren ====

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden!

<source lang="bash">
chmod +x compile.sh
./compile.sh
</source>

Erwartete Ausgabe:
<source>
Compiliere Belegversand AppleScripts...
✓ Fertig!
</source>

==== 4. Erste Ausführung ====

# DEVONthink öffnen
# Ein Objekt in der gewünschten Datenbank auswählen
# Scripts → START aufrufen
# Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

== Wichtig: .applescript vs. .scpt Dateien ==

Im Repository gibt es zwei Arten von AppleScript-Dateien:

; .applescript: Quelldateien (lesbar, nur für Entwicklung)
; .scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die `.applescript`-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Das `compile.sh`-Script:
# Kompiliert alle `.applescript` zu `.scpt`
# Löscht anschließend die `.applescript`-Dateien
# Hinterlässt nur funktionsfähige `.scpt`-Dateien

Falls nach dem Clone noch `.applescript`-Dateien vorhanden sind, war `compile.sh` nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

== Konfiguration ==

=== Automatische Initialisierung ===

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

<source>
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Standard-Template
├── README-Belegversand # Interne Hilfe
└── [weitere Dateien nach Versand]
</source>

=== Konfigurationsdatei ===

Die Datei `belegversand.conf` befindet sich in DEVONthink unter `_config → belegversand.conf`.

==== Wichtigste Parameter ====

; MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
; MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
; MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
; ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
; LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
; SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
; WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
; SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
; MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
; MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
; PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

==== Multiple Empfänger (CSV-Format) ====

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

<source>
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
</source>

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

== Verwendung ==

=== Grundablauf ===

# Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
# Scripts → START aufrufen
# Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
# Dry-Run Vorschau anschauen (optional)
# Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

=== Menü-Befehle ===

; START: Haupteinstiegspunkt — startet Setup oder Versand
; About...: About-Dialog mit Versionsinformation und Links

=== Booking-Jahr Enforcement ===

Das System verhindert Versandvermischung über mehrere Jahre:

; Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
; Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
; Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Beispiel-Struktur:

<source>
Belege/
├── 2026/
│ ├── 01_Januar/
│ ├── [weitere Monate]
│ └── Versendet/ [← Logs für 2026-Versand]
├── 2027/
│ ├── 01_Januar/
│ ├── [weitere Monate]
│ └── Versendet/ [← Logs für 2027-Versand]
└── Provisionsabrechnungen/
└── [← Separate Outsider-Logs]
</source>

=== Dry-Run Modus ===

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

# Simuliert den kompletten Versandprozess
# Erstellt Vorschau-Datei mit allen Details
# Zeigt Dialog mit Zusammenfassung
# User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

=== Mail-Drafts ===

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

# ZIP-Archive werden erzeugt
# Apple Mail öffnet mit neuem Draft (nicht gesendet!)
# User kann Template prüfen, weitere Empfänger hinzufügen
# Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

=== Mail-Templates ===

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Beispiel-Template:

<source>
Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen
</source>

== Protokollierung ==

=== NDJSON-Logs ===

Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:

<source lang="json">
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
</source>

=== Markdown-Logs ===

Menschlich lesbar mit Übersichten nach Versandlauf:

<source>
# Belegversand Logs — 2026

## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
**Status:** Erfolgreich

### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
</source>

== Troubleshooting ==

=== Scripts funktionieren nicht ===

==== Problem: "Script nicht gefunden" ====

Häufigste Ursache: `compile.sh` wurde nicht ausgeführt.

Lösung:
# Prüfen ob `.scpt`-Dateien vorhanden sind: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> erneut ausführen
# Auf Fehlermeldungen achten

==== Problem: Script-Zugriff verweigert ====

Lösung:
# System Settings → Privacy & Security → Automation
# DEVONthink sollte mit entsprechenden Rechten gelistet sein
# Script Editor öffnen und START.scpt öffnen
# Compile (⌘K) — sollte ohne Fehler durchlaufen

=== ZIP wird nicht erstellt ===

* ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
* Ausreichend Festplatte vorhanden?
* Staging-Ordner in DEVONthink beschreibbar?

=== Mail-Draft öffnet sich nicht ===

* Apple Mail ist geöffnet?
* Script-Zugriff für Mail aktiviert?
* Mail-Templates-Ordner vorhanden?

=== "Mixed-Year-Selection"-Fehler ===

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

; Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
; Lösung 2: Belege in mehreren Versänden verteilen

=== Debug-Informationen aktivieren ===

In `belegversand.conf`:

<source>
WRITE_DEBUG_LOG=true
</source>

Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log`.

== Versionshistorie ==

; 1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
; 1.3: Dry-Run Verbesserungen, Markdown-Logs
; 1.2: Mail-Templates in DEVONthink, interne README
; 1.1: Konfigurationssystem
; 1.0: Erste funktionale Version

== Entwicklung ==

Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:
# Quelldateien (`.applescript`) editieren
# `./compile.sh` ausführen
# In DEVONthink testen
# Bei Änderungen: `./compile.sh` erneut ausführen

== Support ==

Für technische Fragen oder Probleme:
* Wiki-Dokumentation durchlesen (diese Seite)
* Debug-Log aktivieren und analysieren
* Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

== Externe Links ==

* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
* [https://www.devontechnologies.com DEVONthink Homepage]
* [https://support.apple.com/mail Apple Mail Documentation]

Projekte

2026-08-18T12:52:53Z

Admin: /* Software */

== Software ==
- AI und Anverwandte -
* [[ChatGPT-Client - Wiki]]
- Linux-Tools -
* [[Git-Spickzettel]]
* [[Mutt - ein textbasierter Mail-Client ]]
- DEVONthink-Automation
* [[Belegversand ]]

== Server-Administration ==

=== Sicherheit ===
* [[SSH]]

=== Webserver ===
* [[:Kategorie:Webserver|Webserver – Übersicht]]

=== Infrastruktur ===
* [[Homeserver-Sicherheitsarchitektur]]
* [[Powertop (Linux-Daemon)]]

== Romanprojekt: Der verborgene Bach ==
* [[Basis: Die "Kunst der Fuge", BWV 1080]]
* [[Plot]]

[[Kategorie:Projekte]]

Projekte

2026-08-18T12:32:00Z

Admin: /* Software */

== Software ==
* [[ChatGPT-Client - Wiki]]
* [[Git-Spickzettel]]
* [[Mutt - ein textbasierter Mail-Client ]]
test

== Server-Administration ==

=== Sicherheit ===
* [[SSH]]

=== Webserver ===
* [[:Kategorie:Webserver|Webserver – Übersicht]]

=== Infrastruktur ===
* [[Homeserver-Sicherheitsarchitektur]]
* [[Powertop (Linux-Daemon)]]

== Romanprojekt: Der verborgene Bach ==
* [[Basis: Die "Kunst der Fuge", BWV 1080]]
* [[Plot]]

[[Kategorie:Projekte]]

Robert Franz (1815-1892), deutscher Komponist

2026-05-31T13:49:57Z

Admin: /* Die Lieder */

{{DISPLAYTITLE:Robert Franz}}
[[Kategorie:Musik]]
[[Kategorie:Musik/Persönlichkeiten]]
Robert Franz (eigentlich Robert Franz Julius Knauth; * 28. Juni 1815 in Halle an der Saale; † 24. Oktober 1892 ebenda) war ein deutscher Komponist, Organist und Dirigent. Zu Lebzeiten von Zeitgenossen wie Robert Schumann, Franz Liszt und Felix Mendelssohn geschätzt, gehört er heute zu den weitgehend vergessenen Komponisten der deutschen Romantik.

[[Datei:Robert Franz.jpg|thumb|right|250px|Robert Franz (1815–1892)]]

== Leben ==

=== Herkunft und Ausbildung ===

Robert Franz stammte aus einer alteingesessenen Hallorer-Familie. (Siehe auch: [[Halloren]]).
Er wuchs in Halle auf, wo er ab 1828 die Latina der Franckeschen Stiftungen besuchte. Früh fiel er durch musikalische Begabung auf; der dortige Kantor Carl Gottlob Abela ließ ihn die Proben des Schulchors am Klavier begleiten. Von 1835 bis 1837 studierte er Komposition bei Friedrich Schneider in Dessau und kehrte danach nach Halle zurück – in eine Stadt, die er zeit seines Lebens kaum verlassen sollte.

=== Berufliche Laufbahn in Halle ===

Nach schwierigen wirtschaftlichen Anfangsjahren übernahm Franz 1841 das Organistenamt an der Ulrichskirche. Im folgenden Jahr wurde er Dirigent der Singakademie Halle, die später seinen Namen annahm. 1848 heiratete er Marie Hinrichs, Tochter eines Professors und selbst Komponistin; das Paar hatte drei Kinder. 1859 wurde Franz schließlich zum Universitätsmusikdirektor ernannt – der Höhepunkt seiner öffentlichen Laufbahn.

=== Krankheit und Rückzug ===

Seit 1843 litt Franz an einem Nerven- und Ohrenleiden, das sich über Jahrzehnte progressiv verschlimmerte und schließlich zur vollständigen Taubheit führte. 1867 wurde er beurlaubt,
1868 musste er alle Ämter endgültig aufgeben. Die daraus folgende finanzielle Not war erheblich: Ein 1867 zuerkannter Ehrensold wurde ihm 1877 auf Betreiben von Widersachern wieder entzogen. Seinen Lebensunterhalt sicherte schließlich ein 1873 von Freunden und Kollegen – allen voran Franz Liszt – gestifteter Ehrenfonds in Höhe von 30.000 Talern.

Die letzten rund 25 Jahre seines Lebens verbrachte Franz in nahezu vollständiger Taubheit und sozialem Rückzug. Er starb am 24. Oktober 1892 in Halle.

1885 wurde ihm zu seinem 70. Geburtstag – anlässlich der Feier des 200. Geburtstags Georg Friedrich Händels – das Ehrenbürgerrecht der Stadt Halle verliehen.

=== Familie ===

1848 heiratete Robert Franz in Halle Marie Hinrichs (1828–1891),
Tochter des Hallenser Philosophieprofessors Hermann Friedrich
Wilhelm Hinrichs. Marie Franz war selbst Komponistin und hatte bereits 1846 – also
zwei Jahre vor der Heirat – bei Breitkopf & Härtel in Leipzig einen
Band mit neun Gesängen für Singstimme und Klavier veröffentlicht.

Dem Paar wurden drei Kinder geboren. Bekannt sind: ein Sohn, der
1900 als praktischer Arzt in Heidelberg starb, sowie eine Tochter,
die den Superintendenten Bethge in Giebichenstein heiratete.

Marie Franz starb 1891. Robert Franz,
taub und weitgehend isoliert, überlebte sie um ein Jahr.
Beide sind auf dem Stadtgottesacker in Halle begraben.

[[Datei:Robert-franz-im-alter.png |thumb|right|250px|Robert Franz, späte Aufnahme]]

== Das Werk ==

=== Die Lieder ===

Robert Franz schrieb über 350 Kunstlieder für Singstimme und Klavier – und fast ausschließlich das. Keine Symphonien, keine Opern, kein Streichquartett. Diese bewusste Konzentration auf eine einzige Gattung war seine Stärke und zugleich der Grund für sein späteres Vergessen.

Etwa ein Viertel seiner Lieder vertont Texte von Heinrich Heine. Daneben war Karl Wilhelm Osterwald ein bevorzugter Dichter. Franz' Vertonungsweise gilt als außerordentlich textgetreu und harmonisch differenziert – ohne Effekthascherei, in großer Zurückhaltung und mit feinem Klangsinn. Robert Schumann, dem Franz 1843 sein erstes gedrucktes Heft (op. 1, ''Zwölf Gesänge'') zuschickte, antwortete, die Lieder hätten ihm gefallen „wie seit langer Zeit keine mehr". Auch Mendelssohn, Liszt und Wagner äußerten sich anerkennend.

Zu den heute noch gelegentlich aufgeführten Liedern gehören:
* ''Aus meinen großen Schmerzen'', op. 5 Nr. 1 (Text: Heinrich Heine)
* ''Auf dem Meere'', op. 5 Nr. 3 (Text: Heinrich Heine)
* ''Sterne mit den goldnen Füßchen'', op. 30 Nr. 1 (Text: Heinrich Heine)
* ''Schilflieder'', op. 2 (Text: Nikolaus Lenau)

=== Bearbeitungen von Bach und Händel ===

Neben seinen Liedern hat Franz einen – heute kaum noch bekannten,
aber musikhistorisch aufschlussreichen – Teil seiner Energie in die
Bearbeitung älterer Musik investiert. Als Leiter der Singakademie
musste er Werke von Bach und Händel aufführbar machen – und das
bedeutete im 19. Jahrhundert: eingreifen.

Konkret tat er dreierlei:

* '''Generalbassaussetzung:''' Die in Barockpartituren nur als bezifferter oder unbezifferter Bass notierten Begleitstimmen schrieb er vollständig aus – für Klavier oder Orchester.

* '''Uminstrumentierung:''' Barockbesetzungen ersetzte er durch das romantische Orchester. Cembalo, Gambe, Oboe d'amore – all das wurde durch zeitgenössische Instrumente ersetzt.

* '''Ergänzung fehlender Stimmen:''' Wo Partituren lückenhaft überliefert waren, schrieb er fehlende Stimmen hinzu.

Das Ergebnis war kein historisches Bach oder Händel, sondern Bach
und Händel im romantischen Gewand – aufführungspraktisch für das
19. Jahrhundert gedacht, ästhetisch aber von Anfang an umstritten.

Genau hier lag der Kern des späteren Streits mit Friedrich
Chrysander und Philipp Spitta (siehe [[#Der Bearbeitungsstreit|
Der Bearbeitungsstreit]]): nicht ob man den Generalbass aussetzen
darf, sondern ''wie'' – und ob dabei die Klangsprache des
19. Jahrhunderts legitim ist.

== Der Bearbeitungsstreit ==

Franz' Ergänzungen des barocken Generalbasssatzes – also seine Ausführung der in Barockpartituren nur skizzenhaft notierten Begleitung – stießen auf scharfen Widerspruch der aufkommenden philologisch-historischen Schule. Besonders Friedrich Chrysander, Herausgeber der Händel-Gesamtausgabe, und Philipp Spitta, der maßgebliche Bach-Forscher der Zeit, kritisierten Franz' Herangehensweise als zu romantisierend und zu wenig historisch korrekt.

Franz seinerseits ließ sich das nicht gefallen. In einem [[Brief vom 1. Februar 1871 | Brief]] an seinen Freund Julius Schäffer schrieb er über Chrysander:

: ''„Das ist ja ein ganz unverschämter Schlingel, der sich ernsthaft einzubilden scheint, Händel, weil er sich sonst einiges Verdienst um ihn erworben hat, ausschließlich als Domäne gepachtet zu haben."''

Der Streit wurde auch öffentlich geführt. Schäffer verfasste zwischen 1875 und 1880 eine Reihe von Streitschriften zur Verteidigung der Franz'schen Bearbeitungen, darunter ''Entgegnung auf Ph. Spitta's Artikel: Über das Accompagnement in den Kompositionen Seb. Bachs'' und ''Friedr. Chrysander in seinen Klavierauszügen zur deutschen Händel-Ausgabe''. Franz selbst meldete sich mit einem ''Offenen Brief an Eduard Hanslick'' und den ''Mitteilungen über J. S. Bachs Magnificat'' zu Wort.

Auf Seiten der Franz'schen Bearbeitungen standen namhafte Praktiker wie Liszt, Felix Mottl, Hans Richter und Arthur Nikisch. Die philologische Schule – Chrysander, Spitta – pochte auf Texttreue.

Dieser Streit ist im Kern derselbe, der bis heute nicht wirklich entschieden ist: Wie viel interpretatorische Freiheit darf – oder muss – eine lebendige Aufführung alter Musik haben? Franz stand auf der Seite der musikalischen Praxis; die Gegenseite bereitete den Boden für das vor, was später als Historisch Informierte Aufführungspraxis bekannt werden sollte.

== Warum ist Robert Franz vergessen? ==

Das ist eine berechtigte Frage – und die Antwort ist vielschichtig:

* '''Das Gattungsproblem:''' Franz schrieb fast ausschließlich Lieder. Im 20. Jahrhundert rückte das Kunstlied zunehmend an den Rand des Konzertlebens. Komponisten, die auch Symphonien, Kammermusik oder größere Vokalwerke hinterlassen haben – Brahms, Schumann, Schubert –, blieben im Repertoire präsent. Franz nicht.

* '''Kein zyklisches Hauptwerk:''' Anders als Schubert mit der ''Winterreise'' oder der ''Schönen Müllerin'' hinterließ Franz keinen Liederzyklus, der als geschlossenes Abendprogramm funktioniert und vermarktbar ist.

* '''Kein überregionales Netzwerk:''' Franz lebte und arbeitete sein Leben lang in Halle. Er hatte keine Schüler, die seine Tradition weitergetragen hätten, und keine Präsenz in den großen Musikzentren Wien, Leipzig oder Berlin.

* '''Die Taubheit:''' 25 Jahre Isolation am Ende seines Lebens bedeuteten: kein Spätwerk, keine Weiterentwicklung, keine späten Meisterwerke wie bei Beethoven oder Schubert.

Schumann hatte Franz übrigens bereits früh ermahnt, sich nicht auf das Lied zu beschränken. Franz blieb trotzdem bei seiner Wahl – konsequent und ohne Kompromisse.

== Zeitgenössische Wertschätzung ==

Dass Franz zu Lebzeiten keineswegs unbekannt war, zeigt eine Episode aus dem Jahr 1873: Als seine finanzielle Lage nach dem Verlust seiner Ämter und Bezüge prekär wurde, organisierten Franz Liszt und andere namhafte Musikerpersönlichkeiten einen Ehrenfonds, der Franz den Lebensunterhalt sicherte. Liszt hatte zudem bereits 1872 eine Monographie über Franz verfasst.

== Weblinks und Quellen ==

* [https://www.deutsche-biographie.de/sfz16975.html Deutsche Biographie – Robert Franz] (Allgemeine Deutsche Biographie, Band 48, 1904)
* [https://de.wikipedia.org/wiki/Robert_Franz Wikipedia – Robert Franz]
* [https://www.musikland-sachsenanhalt.de/beitraege/franz-robert-1815-1892/ Musikland Sachsen-Anhalt – Robert Franz]
* [https://halle.de/kultur-tourismus/stadtgeschichte/bekannte-persoenlichkeiten/beruehmte-hallenser/details/franz-robert Berühmte Hallenser – Stadt Halle]
* [https://st.museum-digital.de/object/1102 Brief von Robert Franz an Julius Schäffer, 1. Februar 1871] – Stiftung Händel-Haus Halle (museum-digital Sachsen-Anhalt)
* [https://www.klassik-heute.com/4daction/www_komponist?id=43036&bio= Klassik Heute – Biographie Robert Franz]

----
''Seite erstellt im Kontext eines Konzertprogramms mit Liedern von Robert Franz, Mai 2026.''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:54:01Z

Admin: /* Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt hier verschiedene Anbieter, oft auch kostenlose.

'''Beispiel:''' Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird. Bei mir war damals die Freude darüber groß.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Eine öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...wäre hochgradig fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer schon einmal aufgrund "zu..." vieler unbeabsichtigter Fehlversuche während der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus teilen!)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Sollte das keine Option sein: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen).
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine(!) externen Freigaben!'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts.
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren.

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:51:30Z

Admin: /* Sicherheitshinweise */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Eine öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...wäre hochgradig fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer schon einmal aufgrund "zu..." vieler unbeabsichtigter Fehlversuche während der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus teilen!)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Sollte das keine Option sein: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen).
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine(!) externen Freigaben!'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts.
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren.

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:50:55Z

Admin: /* Sicherheitshinweise */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Eine öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...wäre hochgradig fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer schon einmal aufgrund "zu..." vieler unbeabsichtigter Fehlversuche während der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus teilen!)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Sollte das keine Option sein: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine(!) externen Freigaben!'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:50:10Z

Admin: /* Sicherheitshinweise */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Eine öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...wäre hochgradig fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer schon einmal aufgrund "zu..." vieler unbeabsichtigter Fehlversuche während der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus teilen!)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Sollte das keine Option sein: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:47:33Z

Admin: /* Annahmen / Szenario */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Eine öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...wäre hochgradig fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer schon einmal aufgrund "zu..." vieler unbeabsichtigter Fehlversuche während der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus teilen!)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:44:52Z

Admin: /* Motivation für einen Server mit OPNsense, Managed Switch und Docker */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Eine öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...wäre hochgradig fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:43:44Z

Admin: /* Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Kurz: Die öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...

* http://myhomeserver.dyndns.de

...ist fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:43:04Z

Admin: /* Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Motivation für einen Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.
Die öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...
* http://myhomeserver.dyndns.de
...ist fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:41:44Z

Admin: /* Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

Beispiel: Der eigenen, von außen sichtbaren IP 78.123.234.45 wird vom DynDDS-Dienst die Domain <myhomeserver.dyndns.de> zugewiesen.
Einmal eingerichtet, wird der eigene Rechner antworten, wenn die Domain http://myhomeserver.dyndns.de in die Browser-Adressleiste einkopiert wird.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar.
Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.
Die öffentliche Erreichbarkeit des eigenen Servers über die ungesicherte Adresse...
* http://myhomeserver.dyndns.de
...ist fahrlässig.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:33:14Z

Admin: /* Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.
Einmal eingerichtet,

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:31:54Z

Admin: /* Sicherheitshinweise */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regel, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:28:03Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:27:33Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen, und, abgesehen von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:26:53Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man darüber nachdenken, einen VPN-Tunnel einzurichten. Sicherer jedoch - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen, und, jenseits von 80 und 443, auf jeden nach außen exponierten Port zu verzichten.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:23:03Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wird man sicherlich darüber nachdenken, einen VPN-Tunnel einzurichten. Noch sicherer - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:19:58Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wäre das am sichersten über ein VPN zu realisieren. Sicherer - und einfacher - ist es dennoch, die Administration ausschließlich über einen zertifikats-geschützten SSH-Zugang im inneren 192.168.-er-Netz zuzulassen.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:18:44Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS auf Port 443 umgeleitet werden.

Die Idee, ausschließlich HTTPS zuzulassen, läge nahe. Damit bräuchte sich der Webserver nicht um die Weiterleitung auf Port 443 zu befassen.
Bedauerlicherweise wird in diesem Fall der Umgang mit dem TLS-Zertifikat, das den HTTPS-Datenstrom verschlüsselt, scheitern. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung seiner Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wäre das am sichersten über ein VPN mit SSH/Zertifikat zu realisieren. Sicherer - und einfacher - ist es dennoch, die Administration ausschließlich über einen SSH-Zugang im inneren 192.168.-er-Netz zuzulassen.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:10:07Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports '''80/TCP''' und '''443/TCP''' nach außen frei gibt. Der Webserver wird dabei so konfiguriert, dass HTTP-Daten über Port 80 nach HTTPS, 443 umgeleitet werden.

Die Idee, Port 80 ebenfalls dicht zu machen und ausschließlich HTTPS zuzulassen, liegt nahe, scheitert aber spätestens beim TLS-Zertifikat. [https://letsencrypt.org/ LetsEncrypt] benötigt bei Einrichtung und Verlängerung der Zertifikate einen offenen 80-er Port.

Sollte es nötig sein, den Server von außen zu administrieren, wäre das vermutlich am sichersten über ein VPN mit SSH/Zertifikat zu realisieren.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:05:01Z

Admin: /* Sicherheitshinweise */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports 80/TCP und 443/TCP nach außen frei gibt. Sollte es nötig sein, den Server von außen zu administrieren, wäre das vermutlich am sichersten über ein VPN mit SSH/Zertifikat zu realisieren.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur die Ports 80 + 443 öffnen)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die auf einem Rechner '''NICHT''' existieren, werden niemals angegriffen! Wenig ist hier mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T23:02:23Z

Admin: /* Sicherheitshinweise */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports 80/TCP und 443/TCP nach außen frei gibt. Sollte es nötig sein, den Server von außen zu administrieren, wäre das vermutlich am sichersten über ein VPN mit SSH/Zertifikat zu realisieren.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen! Wenn das nicht geht: VPN-Tunnel!
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur 80 + 443)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse oder statische IP-Adressen verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

Abschließend eine absolute Regeln, die immer und durch die Ewigkeiten gilt:
* Dienste, die '''NICHT''' existieren, werden nicht angegriffen! Wenig ist hier immer mehr!
----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T22:58:09Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

Am Ende dieses Beitrages gibt es Sicherheitshinweise. Bitte dringend beachten, dass der Router ausschließlich die Ports 80/TCP und 443/TCP nach außen frei gibt. Sollte es nötig sein, den Server von außen zu administrieren, wäre das vermutlich am sichersten über ein VPN mit SSH/Zertifikat zu realisieren.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur 80 + 443)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T22:50:18Z

Admin: /* Die Kette von außen nach innen */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 (und nur! diese!!) → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

Damit ist der Server auf der IP-Ebene (Layer 3 des OSI-Modells) von außen hin "unsichtbar": Die Firewall (OPNsense) lebt, mit dem Gateway, im 192.168.2-er Netz. Von dort routet sie alle Anfragen über die Ports 80 und 443 an das Interface 192.168.10.100. Dahinter, also im 192.168.10-er-Subnetz, residiert der Heimserver.

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur 80 + 443)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T22:43:38Z

Admin: /* Annahmen / Szenario */

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ funktionieren [https://nginx.org/ nginx], [https://httpd.apache.org/ Apache], oder (ggf. kostenpflichtige) proprietäre Lösungen. Caddy allerdings hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur 80 + 443)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''

Homeserver-Sicherheitsarchitektur

2026-05-27T22:39:21Z

Admin: Die Seite wurde neu angelegt: „== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose == Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein. Es gibt verschiedene Anbieter, oft auch kostenlose. === Ein Leitfaden…“

== Homeserver-Sicherheitsarchitektur: Aufbau, Funktionsweise und Diagnose ==

Einen eigenen Server an's Internet zu bekommen, ist nicht allzu schwierig. Ein Dienst, der die eigene, vom Internet-Provider zugewiesene IP-Adresse in einen festen Domain-Namen umwandelt (siehe: [https://de.wikipedia.org/wiki/Dynamisches_DNS Dynamisches DNS]), wird im privaten Bereich die Voraussetzung sein.
Es gibt verschiedene Anbieter, oft auch kostenlose.

=== Ein Leitfaden für selbst gehostete Server mit OPNsense, Managed Switch und Docker ===

Die Kehrseite: Sowie der Server über's Internet erreichbar ist, ist er angreifbar. Das ist kein theoretisches Szenario. Meiner Erfahrung nach ist es eine Frage von Stunden, bis die ersten Bots "anklopfen", nach laufenden Diensten suchen, nach offenen Ports, nach Schwachstellen.

Aufgrund einer mangelhaften Konfiguration (offener Samba-Port) hatte ich die sehr reale Erfahrung einer russischen Hackerbande, die einige Hundert Textdateien mit Zahlungsaufforderungen und einen Verschlüsselungstrojaner auf meinem Rechner hinterlassen hatte. Gerettet hatten mich damals die Dateirechte von Linux. Das fehlende E(x)ecutional-Flag und die eingeschränkten Benutzerrechte hatten den Trojaner ausgebremst.

Trotzdem: Nie wieder!
Ein wenig von dem, was ich gelernt habe, gebe ich ich hier weiter.

----

== Einleitung ==

Dieser Artikel beschreibt den Aufbau einer '''sicheren''' Netzwerkarchitektur für einen Homeserver, der über das öffentliche Internet erreichbar ist. Der Beitrag richtet sich an alle, die ihre Daten selbst kontrollieren wollen — und dabei nicht unfreiwillig Teil einer globalen Angriffs-Infrastruktur werden möchten. Er will zum Verständnis beitragen, wie die einzelnen Komponenten zusammenspielen — und wie man systematisch vorgeht, wenn etwas nicht funktioniert.

Der Fokus liegt nicht auf einer spezifischen Hardware-Konfiguration, sondern auf dem allgemeinen Prinzip: Wie kommt ein Request von außen sicher zu einem Docker-Container?

----

== Annahmen / Szenario ==

Folgende Komponenten werden in diesem Artikel vorausgesetzt:

* '''Homeserver''' (Raspberry Pi, Intel NUC, oder beliebiger Linux-Server)
** Betriebssystem: Debian/Ubuntu oder vergleichbar
** Docker mit mehreren Diensten (z.B. WordPress, Nextcloud, MediaWiki)
** Caddy als Reverse Proxy (alternativ: nginx, Apache, aber Caddy hat das für mich charmante Feature, sich eigenständig um die TSL-Zertifikate und ihre Verlängerung bei LetsEncrypt zu kümmern. Wer aufgrund "zu vieler" Fehlversuche bei der Zertifikats-Einrichtung von LetsEncrypt auf Tage gesperrt wurde, wird mein Faible über diesen Automatismus nachvollziehen oder teilen können.)
** fail2ban als Brute-Force-Schutz

* '''DynDNS-Dienst''' der dem Homeserver eine feste Domain zuweist
** Beispiel: <code>myhomeserver.dyndns.de</code>

* '''Router / Heimnetz-Gateway'''
** Beispiel-IP: <code>192.168.2.1</code>
** Aufgabe: Portweiterleitung, WLAN, DynDNS-Aktualisierung
** Typisch: FritzBox, aber jeder Router mit Portweiterleitung funktioniert

* '''OPNsense Firewall''' (dedizierte Hardware-Firewall)
** WAN-Interface: <code>192.168.2.2</code> (im Router-Netz)
** LAN-Interface / Server-VLAN: <code>192.168.10.1</code>
** Aufgabe: Firewall, NAT, DHCP, IDS/IPS

* '''Managed Switch''' (optional, für VLAN-Segmentierung)
** Trennt Server-VLAN vom Rest des Netzes

* '''Homeserver-IP''': <code>192.168.10.100</code> (per DHCP-Reservation oder besser: Per statischer IP-Adresse fest)

----

== Abschnitt 1: Wie funktionieren die Weiterleitungen? Wer macht was? ==

=== Die Kette von außen nach innen ===

Ein Request von außen (z.B. Browser ruft <code>https://myhomeserver.dyndns.de</code> auf) durchläuft folgende Stationen:

<pre>
Internet
↓ DNS-Auflösung: dyndns.de → öffentliche IP des Heimnetzes
Router / Gateway (192.168.2.1)
↓ Portweiterleitung: :80 + :443 → 192.168.2.2
OPNsense WAN-Interface (192.168.2.2)
↓ Destination NAT: :80/:443 → 192.168.10.100
Homeserver eno1/eth0 (192.168.10.100)
↓ Docker-Port-Binding: 0.0.0.0:80 + 0.0.0.0:443
Caddy / Reverse Proxy (Docker-intern)
↓ Reverse Proxy anhand des Host-Headers
Ziel-Container (z.B. wordpress, nextcloud, ...)
</pre>

=== Wer macht was? ===

{| class="wikitable"
|-
! Komponente !! Aufgabe !! Konfigurationsort
|-
| '''Router / Gateway''' || DynDNS-Aktualisierung, erste NAT-Stufe, WLAN || Router Web-UI → Portfreigaben
|-
| '''OPNsense Firewall''' || Firewall-Regeln, zweite NAT-Stufe (Destination NAT), DHCP für Server-VLAN || OPNsense Web-UI (Standard: https://<wan-ip>:443 oder :8443)
|-
| '''Caddy / Reverse Proxy''' || TLS-Terminierung, Let's Encrypt, Weiterleitung an Container || Caddyfile auf dem Homeserver
|-
| '''Docker''' || Container-Isolation, internes Netz (Standard: 172.18.0.0/16) || docker-compose.yml pro Dienst
|-
| '''fail2ban''' || Brute-Force-Schutz auf Applikationsebene || Jail-Configs im fail2ban-Container
|}

=== Wichtig: OPNsense hat ZWEI Firewall-Engines ===

OPNsense 26.x hat zwei parallele Regelwerke:
* '''Rules [new]''' — neue API-basierte Engine
* '''Rules''' — alte Engine (Legacy)

Neue Regeln '''immer in beiden''' anlegen! Bei Problemen immer beide prüfen.

----

== Abschnitt 2: Wo steht was? ==

=== IP-Adressen (Beispiel-Setup) ===

{| class="wikitable"
|-
! Gerät !! Interface !! IP !! Bemerkung
|-
| Router / Gateway || — || 192.168.2.1 || Gateway, WLAN, DynDNS
|-
| OPNsense WAN || wan-interface || 192.168.2.2 || Statisch konfiguriert
|-
| OPNsense LAN / Server-VLAN || lan-interface || 192.168.10.1 || Gateway für Server-Netz
|-
| Homeserver || eno1 / eth0 || 192.168.10.100 || Fest per DHCP-Reservation (MAC-Adresse)
|-
| Client-Geräte || WLAN || 192.168.2.x || Im Router-Netz, nicht im Server-VLAN
|}

=== Homeserver: Netzwerk-Interface-Konfiguration ===

Der Homeserver bezieht seine IP per DHCP vom OPNsense-DHCP-Server. Bei Debian/Ubuntu mit systemd-networkd:

<pre>
/etc/systemd/network/10-eth0.network
</pre>

'''Korrekter Inhalt (DHCP):'''

<pre>
[Match]
Name=eno1

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=100
</pre>

⚠️ '''Niemals''' eine statische IP oder einen Gateway manuell eintragen!
Der Default-Gateway kommt immer vom DHCP-Server der OPNsense-Firewall (<code>192.168.10.1</code>).

=== Kea DHCP Lease-Datei (OPNsense) ===

<pre>
/var/db/kea/kea-leases4.csv
</pre>

Hier verwaltet Kea die aktiven Leases. Bei Problemen mit doppelten IPs kann diese Datei (nach <code>configctl kea stop</code>) auf den Header reduziert werden:

<pre>
address,hwaddr,client_id,valid_lifetime,expire,subnet_id,fqdn_fwd,fqdn_rev,hostname,state,user_context,pool_id
</pre>

----

== Abschnitt 3: Systematische Diagnose — Schritt für Schritt ==

=== Grundprinzip: Von außen nach innen ===

Immer von außen nach innen vorgehen — nie raten, immer messen. Jede Schicht einzeln prüfen.

==== Schritt 1: Ist OPNsense überhaupt erreichbar? ====

<pre>
# Vom Client-Rechner:
ping 192.168.2.2
</pre>

⚠️ OPNsense antwortet standardmäßig '''nicht''' auf ICMP/Ping von außen — das ist korrekt!

Stattdessen prüfen:
<pre>
# Web-UI erreichbar?
https://192.168.2.2:8443

# Router zeigt OPNsense als verbundenes Gerät?
http://192.168.2.1
</pre>

==== Schritt 2: OPNsense intern prüfen ====

Per SSH oder serieller Konsole auf OPNsense:

<pre>
# WAN-Interface OK?
ifconfig <wan-interface>
# Erwartete Ausgabe: inet 192.168.2.2, status: active

# LAN-Interface OK?
ifconfig <lan-interface>
# Erwartete Ausgabe: inet 192.168.10.1, status: active

# Router erreichbar?
ping -c 3 192.168.2.1

# Homeserver erreichbar?
ping -c 3 192.168.10.100
</pre>

==== Schritt 3: Homeserver direkt prüfen ====

<pre>
# SSH auf Homeserver:
ssh root@192.168.10.100

# Alle Container laufen?
docker ps

# Internet vom Homeserver aus erreichbar?
ping -c 3 9.9.9.9

# Routing-Tabelle korrekt?
ip route show
# Erwartete Default-Route: default via 192.168.10.1 dev eno1
# NICHT: default via 192.168.178.x — das wäre falsch!

# Welche IP hat das Interface?
ip addr show eno1
# Erwartete IP: 192.168.10.100
</pre>

==== Schritt 4: Caddy / Reverse Proxy prüfen ====

<pre>
# Läuft Caddy und antwortet er lokal?
curl -v http://localhost
# Erwartete Antwort: HTTP 308 Redirect → https://localhost/

# Caddy-Logs auf Fehler prüfen:
docker logs caddy --tail 50
</pre>

Typische Fehler in den Caddy-Logs:

{| class="wikitable"
|-
! Fehlermeldung !! Bedeutung !! Lösung
|-
| <code>dial tcp ...:443: connect: no route to host</code> || Caddy kommt nicht ins Internet (Let's Encrypt nicht erreichbar) || Routing auf Homeserver prüfen (Schritt 3)
|-
| <code>no route to host</code> bei Ping auf 9.9.9.9 || Falscher Default-Gateway || <code>ip route show</code> prüfen, falsche Route entfernen
|}

==== Schritt 5: NAT und Firewall-Regeln prüfen (OPNsense Shell) ====

<pre>
# NAT-Regeln anzeigen:
pfctl -s nat | grep <PORT>

# Firewall-Regeln anzeigen:
pfctl -s rules | grep <PORT>

# Traffic auf WAN-Interface beobachten (kommt der Request an?):
tcpdump -i <wan-interface> port <PORT>

# Traffic auf LAN-Interface beobachten (wird er weitergeleitet?):
tcpdump -i <lan-interface> port <PORT>
</pre>

'''Diagnose-Logik:'''
<pre>
tcpdump WAN sieht Traffic, LAN nicht → NAT-Regel prüfen!
tcpdump WAN sieht keinen Traffic → Portweiterleitung im Router prüfen!
</pre>

==== Schritt 6: Bekannte Fallstricke ====

{| class="wikitable"
|-
! Problem !! Symptom !! Ursache !! Fix
|-
| Falsche statische Route || <code>ping 9.9.9.9</code> schlägt fehl || Netzwerk-Config hat statischen Gateway eingetragen || Auf DHCP umstellen, <code>systemctl restart systemd-networkd</code>
|-
| Homeserver hat falsche IP || NAT-Regeln greifen nicht || DHCP hat beim Neustart temporär andere IP vergeben || DHCP-Reservation per MAC-Adresse einrichten
|-
| DHCP-Leases durcheinander || Server taucht mit zwei IPs auf || Neustart hat neuen Lease vor Ablauf des alten erzeugt || <code>configctl kea stop</code>, Lease-CSV bereinigen, <code>configctl kea start</code>
|-
| OPNsense Firewall-Regel fehlt || Dienste von außen nicht erreichbar, intern OK || Regel nur in einer der beiden Engines angelegt || Regel in '''beiden''' Engines anlegen (Rules [new] + Rules)
|-
| NAT-Regel ohne Subnetz-Maske || Traffic kommt nicht an || <code>192.168.178.0</code> statt <code>192.168.178.0/24</code> eingetragen || Subnetz-Maske ergänzen — ohne /24 gilt nur die Netzadresse selbst!
|-
| Source/Destination Port vertauscht || Verbindungen werden blockiert || Bei Firewall-Regel Port unter "Source" statt "Destination" eingetragen || Source Port: any / Destination Port: gewünschter Port
|}

----

== Notfall-Cheatsheet ==

<pre>
# OPNsense: Firewall temporär deaktivieren (Notfall!)
pfctl -d

# OPNsense: Firewall wieder aktivieren
pfctl -e

# OPNsense: Kea DHCP stoppen/starten
configctl kea stop
configctl kea start

# Homeserver: Falsche Default-Route entfernen
ip route del default via <falsche-gateway-ip> dev eno1

# Homeserver: IP manuell setzen (Sofortlösung bei DHCP-Problemen)
ip addr add 192.168.10.100/24 dev eno1

# Homeserver: Netzwerk-Dienst neu starten (Verbindung kurz weg!)
systemctl restart systemd-networkd

# Homeserver: Docker-Logs prüfen
docker logs caddy --tail 50
docker ps

# OPNsense: Alias-Tabellen prüfen (Blocklisten)
pfctl -t <tabellenname> -T show | wc -l
pfctl -t <tabellenname> -T show | grep <IP>
</pre>

----

== Sicherheitshinweise ==

* SSH-Ports '''nicht''' über das Internet freigeben — nur intern erreichbar lassen
* Portweiterleitung im Router auf das '''Minimum''' beschränken (nur 80 + 443)
* Für interne Admin-Interfaces (OPNsense Web-UI, Monitoring) '''keine externen Freigaben'''
* DHCP-Reservations per MAC-Adresse verhindern IP-Wechsel nach Neustarts
* Bei Firewall-Regeln: Block-Regeln '''immer''' vor Pass-Regeln platzieren

----

''Dieser Artikel basiert auf praktischen Erfahrungen aus dem Betrieb eines selbst gehosteten Servers mit OPNsense, Cisco-Switch und Docker-Stack.''
''Erstellt: Mai 2026''