# Dolphin FTP Share Tab

Ein KDE Dolphin Properties-Dialog Plugin zum Erstellen und Verwalten von FTP-Freigaben — direkt über die GUI.

![Share Tab](screenshot.png)

## Features

- **FTP-Tab** in Dolphins Ordner-Eigenschaften (Rechtsklick → Eigenschaften)
- Freigabe per Checkbox aktivieren/deaktivieren
- Freigabename konfigurierbar (Standard = Ordnername)
- **Per-User Berechtigungen**: Read Only / Read-Write pro Benutzer
- Jeder Benutzer sieht **nur seine freigegebenen Ordner** per FTP
- Read-Only wird direkt am Dateisystem durchgesetzt (read-only Bind-Mount)
- Automatische Einrichtung mit `dolphin-ftp-share setup`

## Voraussetzungen

- Pure-FTPd als FTP-Server
- Das Helper-Script `dolphin-ftp-share` im PATH
- Build-Dependencies (siehe unten)

## Einrichtung

### 1. Pure-FTPd installieren

```bash
sudo apt install pure-ftpd
```

### 2. Helper-Script installieren

```bash
sudo cp scripts/dolphin-ftp-share /usr/local/bin/
sudo chmod +x /usr/local/bin/dolphin-ftp-share
```

### 3. Automatisches Setup

Das Setup konfiguriert Pure-FTPd komplett und erstellt die sudoers-Regel:

```bash
sudo dolphin-ftp-share setup
```

Das macht automatisch:
- Aktiviert PureDB-Authentifizierung (virtuelle FTP-Benutzer)
- Deaktiviert System-Login und anonymen Zugang
- Aktiviert Chroot (jeder sieht nur seine Ordner)
- Erstellt sudoers-Regel für mount/umount/pure-pw
- Aktiviert Logging
- Startet Pure-FTPd neu

### 4. FTP-Passwörter

FTP-Benutzer werden beim ersten Freigeben automatisch erstellt — das Plugin fragt dabei nach einem Passwort.

Passwort später ändern:
- **Im Plugin**: FTP-Tab → "FTP Password" → Benutzer auswählen → "Change Password..."
- **Per Kommandozeile**: `dolphin-ftp-share passwd <benutzername> <neues-passwort>`

### Logging

Pure-FTPd loggt über syslog:

```bash
# Logs live verfolgen:
sudo tail -f /var/log/syslog | grep pure-ftpd
```

## Versionen

| Verzeichnis | Zielplattform | KDE Frameworks | Qt |
|---|---|---|---|
| `kf5/` | Debian 12 Bookworm | KF5 | Qt5 |
| `kf6/` | Debian 13 Trixie | KF6 | Qt6 |

Der C++ Quellcode ist identisch — nur die CMake-Konfiguration unterscheidet sich.

## Build & Installation

### Debian 12 (KF5)

**Build-Dependencies:**

```bash
sudo apt install build-essential cmake extra-cmake-modules \
    libkf5kio-dev libkf5coreaddons-dev libkf5i18n-dev \
    qtbase5-dev
```

**Bauen:**

```bash
cd kf5
bash build.sh
```

**Installieren:**

```bash
sudo cp build/bin/ftpshareplugin.so \
    /usr/lib/x86_64-linux-gnu/qt5/plugins/kf5/propertiesdialog/
```

**Dolphin neustarten:**

```bash
killall dolphin; dolphin &
```

### Debian 13 Trixie (KF6)

**Build-Dependencies:**

```bash
sudo apt install build-essential cmake extra-cmake-modules \
    libkf6kio-dev libkf6coreaddons-dev libkf6i18n-dev \
    qt6-base-dev
```

**Bauen:**

```bash
cd kf6
bash build.sh
```

**Installieren:**

```bash
sudo cp build/bin/ftpshareplugin.so \
    /usr/lib/x86_64-linux-gnu/qt6/plugins/kf6/propertiesdialog/
```

**Dolphin neustarten:**

```bash
killall dolphin; dolphin &
```

## Deinstallation

```bash
# KF5
sudo rm /usr/lib/x86_64-linux-gnu/qt5/plugins/kf5/propertiesdialog/ftpshareplugin.so

# KF6
sudo rm /usr/lib/x86_64-linux-gnu/qt6/plugins/kf6/propertiesdialog/ftpshareplugin.so

# Helper-Script & sudoers
sudo rm /usr/local/bin/dolphin-ftp-share
sudo rm /etc/sudoers.d/dolphin-ftp-share

# Pure-FTPd (optional)
sudo apt remove pure-ftpd
```

## Projektstruktur

```
kde-dolphin-ftp-sharing-tab/
├── README.md
├── scripts/
│   └── dolphin-ftp-share            # Helper-Script für Share-Verwaltung
├── kf5/                              # Debian 12 (KDE Plasma 5)
│   ├── CMakeLists.txt
│   ├── build.sh
│   └── src/
│       ├── CMakeLists.txt
│       ├── ftpshareplugin.json
│       ├── ftpshareplugin.h
│       └── ftpshareplugin.cpp
└── kf6/                              # Debian 13 (KDE Plasma 6)
    ├── CMakeLists.txt
    ├── build.sh
    └── src/
        ├── CMakeLists.txt
        ├── ftpshareplugin.json
        ├── ftpshareplugin.h
        └── ftpshareplugin.cpp
```

## Wie es funktioniert

1. **Rechtsklick auf Ordner → Eigenschaften → FTP-Tab**
2. Freigabe aktivieren, Berechtigungen pro Benutzer setzen (Read Only / Read-Write)
3. Beim Anwenden ruft das Plugin `dolphin-ftp-share add` auf
4. Das Helper-Script:
   - Erstellt für jeden Benutzer ein persönliches FTP-Root (`~/.local/share/dolphin-ftp-root/users/<name>/`)
   - Bind-mounted den freigegebenen Ordner dorthin
   - Read-Only Freigaben werden als read-only Bind-Mount gemountet
   - Erstellt automatisch virtuelle Pure-FTPd-Benutzer (PureDB)
5. **Jeder FTP-Benutzer sieht nur seine freigegebenen Ordner** — durch Chroot auf sein persönliches FTP-Root

### Kommandos

| Kommando | Beschreibung |
|---|---|
| `dolphin-ftp-share setup` | Einmalige Pure-FTPd Einrichtung |
| `dolphin-ftp-share add <name> <path> <acl>` | Freigabe erstellen |
| `dolphin-ftp-share delete <name>` | Freigabe löschen |
| `dolphin-ftp-share info` | Bestehende Freigaben auflisten |
| `dolphin-ftp-share passwd <user> <pass>` | FTP-Passwort ändern |

### Berechtigungen

| Level | Beschreibung |
|---|---|
| `---` | Kein Zugriff — Ordner ist für diesen Benutzer nicht sichtbar |
| `ro` | Read Only — nur Download |
| `rw` | Read-Write — Upload und Download |

## Tipps: Port-Forwarding für FTP

### Szenario

Ein Gerät (z.B. ein Dokumentenscanner) soll per FTP auf den Server scannen, hat aber **keinen direkten Zugang** zum Server-Netzwerk (z.B. VPN). Ein Windows- oder Linux-Rechner, der in **beiden Netzen** hängt, leitet die FTP-Ports weiter.

```
Scanner ──► Windows/Linux (Port-Forwarding) ──► VPN ──► FTP-Server
```

### Wichtig: Warum Passiver Modus bei NAT/Port-Forwarding?

**Aktiver Modus funktioniert NICHT durch NAT hindurch!** Im aktiven Modus versucht der Server eine Verbindung *zurück* zum Client (Scanner) aufzubauen — aber der Scanner sitzt hinter NAT, und der Server erreicht ihn nicht.

**Passiver Modus ist Pflicht** wenn der Client (Scanner) über NAT/Port-Forwarding angebunden ist:
- Der Client verbindet sich zum Server (nicht umgekehrt) → funktioniert durch NAT
- Dafür muss neben Port 21 auch die **passive Port-Range** weitergeleitet werden

### Aktiver Modus

Funktioniert nur bei **direkter Verbindung** ohne NAT. Nur 2 Ports nötig: **20** (Daten) und **21** (Steuerung).

### Passiver Modus (empfohlen bei NAT/Port-Forwarding)

Port **21** (Steuerung) + die **gesamte Port-Range** (z.B. 30000-31000) müssen weitergeleitet werden. Mehr Ports, aber die einzige Option die durch NAT funktioniert.

### Windows: Port-Forwarding mit netsh

Als Administrator in der Eingabeaufforderung (cmd):

```batch
:: Aktiver Modus — Port 21 (Steuerung) und Port 20 (Daten) weiterleiten
netsh interface portproxy add v4tov4 listenport=21 listenaddress=0.0.0.0 connectport=21 connectaddress=<SERVER-VPN-IP>
netsh interface portproxy add v4tov4 listenport=20 listenaddress=0.0.0.0 connectport=20 connectaddress=<SERVER-VPN-IP>

:: Passiver Modus — zusätzlich die Port-Range weiterleiten
:: (PowerShell, da netsh keine Ranges unterstützt)
for ($p=30000; $p -le 31000; $p++) { netsh interface portproxy add v4tov4 listenport=$p listenaddress=0.0.0.0 connectport=$p connectaddress=<SERVER-VPN-IP> }
```

**Windows-Firewall öffnen:**

```batch
netsh advfirewall firewall add rule name="FTP Active" dir=in action=allow protocol=TCP localport=20,21
:: Für passiven Modus zusätzlich:
netsh advfirewall firewall add rule name="FTP Passive" dir=in action=allow protocol=TCP localport=30000-31000
```

**Port-Forwarding anzeigen / entfernen:**

```batch
:: Alle Weiterleitungen anzeigen
netsh interface portproxy show all

:: Einzelne Weiterleitung entfernen
netsh interface portproxy delete v4tov4 listenport=21 listenaddress=0.0.0.0

:: Alle Weiterleitungen entfernen
netsh interface portproxy reset
```

### Linux: Port-Forwarding mit iptables oder socat

**Variante 1: socat (einfach, gut zum Testen)**

```bash
# Aktiver Modus
sudo socat TCP-LISTEN:21,fork,reuseaddr TCP:<SERVER-VPN-IP>:21 &
sudo socat TCP-LISTEN:20,fork,reuseaddr TCP:<SERVER-VPN-IP>:20 &

# Passiver Modus — zusätzlich Port-Range
for p in $(seq 30000 31000); do
    sudo socat TCP-LISTEN:$p,fork,reuseaddr TCP:<SERVER-VPN-IP>:$p &
done
```

**Variante 2: iptables (performanter, dauerhaft)**

```bash
# IP-Forwarding aktivieren
sudo sysctl -w net.ipv4.ip_forward=1

# Aktiver Modus
sudo iptables -t nat -A PREROUTING -p tcp --dport 21 -j DNAT --to-destination <SERVER-VPN-IP>:21
sudo iptables -t nat -A PREROUTING -p tcp --dport 20 -j DNAT --to-destination <SERVER-VPN-IP>:20
sudo iptables -t nat -A POSTROUTING -j MASQUERADE

# Passiver Modus — zusätzlich Port-Range
sudo iptables -t nat -A PREROUTING -p tcp --dport 30000:31000 -j DNAT --to-destination <SERVER-VPN-IP>
```

**Dauerhaft speichern:**

```bash
sudo apt install iptables-persistent
sudo netfilter-persistent save
```

## Lizenz

GPLv2+