167 lines
8.7 KiB
Markdown
167 lines
8.7 KiB
Markdown
|
# README: ICS-Importer für mailbox.org unter Linux
|
||
|
|
|
||
|
|
Dieses Projekt durchsucht ein mailbox.org-Postfach per IMAP nach `.ics`-Anhängen und importiert enthaltene Termine anschließend per CalDAV in einen mailbox.org-Kalender. mailbox.org dokumentiert Thunderbird/IMAP für E-Mail und CalDAV für Kalender; die CalDAV-URL des Zielkalenders wird in mailbox.org im Kalender über **Eigenschaften** angezeigt. [kb.mailbox](https://kb.mailbox.org/de/privat/e-mail/e-mail-einrichtung-mit-mozilla-thunderbird/)
|
||
|
|
|
||
|
|
## Voraussetzungen
|
||
|
|
|
||
|
|
Benötigt werden ein Linux-System, Python 3, `pipenv`, ein mailbox.org-Konto sowie Zugangsdaten für IMAP und CalDAV. Wenn bei mailbox.org die Zwei-Faktor-Authentifizierung aktiv ist, sollen für externe Anwendungen App-Passwörter beziehungsweise Applikationspasswörter verwendet werden. [kb.mailbox](https://kb.mailbox.org/de/business/adressbuch-und-kalender/caldav-bei-thunderbird/)
|
||
|
|
|
||
|
|
## Projektinhalt
|
||
|
|
|
||
|
|
Die typische Struktur des Projekts sieht so aus:
|
||
|
|
|
||
|
|
```text
|
||
|
|
ics-importer/
|
||
|
|
├── ics_mail_importer.py
|
||
|
|
├── config.ini.example
|
||
|
|
├── config.ini
|
||
|
|
├── imported_uids.txt
|
||
|
|
├── ics_importer.log
|
||
|
|
└── cron.log
|
||
|
|
```
|
||
|
|
|
||
|
|
`ics_mail_importer.py` ist das Hauptskript, `config.ini` enthält die Zugangsdaten, `imported_uids.txt` dient als Duplikat-Schutz, und `cron.log` kann die Ausgabe des Cron-Jobs aufnehmen. Der Duplikat-Schutz ist sinnvoll, weil bei wiederkehrender IMAP-Prüfung sonst identische ICS-Anhänge mehrfach verarbeitet würden. [github](https://github.com/Vilhjalmr26/import_ics)
|
||
|
|
|
||
|
|
## Installation mit pipenv
|
||
|
|
|
||
|
|
In das Projektverzeichnis wechseln und die Python-Abhängigkeiten installieren:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd ~/ics-importer
|
||
|
|
pipenv install caldav icalendar
|
||
|
|
```
|
||
|
|
|
||
|
|
`caldav` wird für den Zugriff auf den CalDAV-Kalender benötigt, während `icalendar` ICS-Dateien parst; für das Mail-Lesen werden Standardbibliotheken wie `imaplib` und `email` verwendet. [github](https://github.com/python-caldav/caldav)
|
||
|
|
|
||
|
|
Den Interpreter-Pfad des Pipenv-Umfelds kann man mit folgendem Befehl prüfen:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd ~/ics-importer
|
||
|
|
pipenv --py
|
||
|
|
```
|
||
|
|
|
||
|
|
Pipenv dokumentiert virtuelle Umgebungen und deren Interpreter-Pfade explizit; dieser Pfad ist später für Cron praktisch. [pipenv.pypa](https://pipenv.pypa.io/en/latest/virtualenv.html)
|
||
|
|
|
||
|
|
## Konfiguration
|
||
|
|
|
||
|
|
Die Vorlage kopieren und bearbeiten:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cp config.ini.example config.ini
|
||
|
|
nano config.ini
|
||
|
|
```
|
||
|
|
|
||
|
|
Beispielinhalt:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
[imap]
|
||
|
|
host = imap.mailbox.org
|
||
|
|
port = 993
|
||
|
|
username = ihr-name@mailbox.org
|
||
|
|
password = IHR_PASSWORT_ODER_APP_PASSWORT
|
||
|
|
folder = INBOX
|
||
|
|
unseen_only = true
|
||
|
|
mark_as_read = false
|
||
|
|
|
||
|
|
[caldav]
|
||
|
|
url = https://dav.mailbox.org/caldav/IHR_KALENDER_ID
|
||
|
|
username = ihr-name@mailbox.org
|
||
|
|
password = IHR_PASSWORT_ODER_APP_PASSWORT
|
||
|
|
```
|
||
|
|
|
||
|
|
Die IMAP-Einstellungen orientieren sich an mailbox.org für Thunderbird, und die CalDAV-URL des gewünschten Kalenders wird laut mailbox.org im Kalenderbereich über die Eigenschaften des Kalenders ermittelt. [kb.mailbox](https://kb.mailbox.org/de/privat/e-mail/e-mail-einrichtung-mit-mozilla-thunderbird/)
|
||
|
|
|
||
|
|
### Bedeutung der wichtigsten Optionen
|
||
|
|
|
||
|
|
| Schlüssel | Bedeutung |
|
||
|
|
|---|---|
|
||
|
|
| `imap.host` | IMAP-Server von mailbox.org: `imap.mailbox.org`. [kb.mailbox](https://kb.mailbox.org/de/privat/e-mail/e-mail-einrichtung-mit-mozilla-thunderbird/) |
|
||
|
|
| `imap.port` | Standardport für IMAP über SSL: `993`. [kb.mailbox](https://kb.mailbox.org/de/privat/e-mail/e-mail-einrichtung-mit-mozilla-thunderbird/) |
|
||
|
|
| `imap.folder` | Zu prüfender Ordner, meist `INBOX`. |
|
||
|
|
| `imap.unseen_only` | Wenn `true`, werden nur ungelesene Nachrichten gesucht; das reduziert unnötige Prüfungen. |
|
||
|
|
| `imap.mark_as_read` | Wenn `true`, markiert das Skript verarbeitete Nachrichten als gelesen. |
|
||
|
|
| `caldav.url` | Vollständige CalDAV-URL des Zielkalenders aus mailbox.org. [kb.mailbox](https://kb.mailbox.org/de/business/adressbuch-und-kalender/caldav-bei-thunderbird/) |
|
||
|
|
| `caldav.username` | Meist die mailbox.org-E-Mail-Adresse. [kb.mailbox](https://kb.mailbox.org/de/business/adressbuch-und-kalender/caldav-bei-thunderbird/) |
|
||
|
|
| `caldav.password` | Passwort oder App-/Applikationspasswort bei aktiver 2FA. [kb.mailbox](https://kb.mailbox.org/de/business/adressbuch-und-kalender/caldav-bei-thunderbird/) |
|
||
|
|
|
||
|
|
## Erster Testlauf
|
||
|
|
|
||
|
|
Das Skript kann manuell getestet werden mit:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd ~/ics-importer
|
||
|
|
pipenv run python3 ics_mail_importer.py
|
||
|
|
```
|
||
|
|
|
||
|
|
Dabei werden neue `.ics`-Anhänge gesucht, importiert und im Log protokolliert. Python-Lösungen für IMAP-Anhangsextraktion und ICS-zu-CalDAV-Import folgen genau diesem Muster aus Mail-Abruf, Parsing und Import. [stackoverflow](https://stackoverflow.com/questions/6225763/downloading-multiple-attachments-using-imaplib)
|
||
|
|
|
||
|
|
## Stündliche Ausführung mit Cron
|
||
|
|
|
||
|
|
Die eigene User-Crontab wird mit `crontab -e` bearbeitet; User-Crontabs liegen auf Debian-/Raspberry-Pi-ähnlichen Systemen typischerweise unter `/var/spool/cron/crontabs/`, sollen aber nicht direkt bearbeitet werden. [cronitor](https://cronitor.io/guides/five-places-for-cron-jobs)
|
||
|
|
|
||
|
|
Für eine Ausführung **stündlich zur vollen Stunde** sieht der Eintrag so aus:
|
||
|
|
|
||
|
|
```cron
|
||
|
|
0 * * * * /home/hans/.local/share/virtualenvs/ics-importer-wOz4rK-o/bin/python /home/hans/ics-importer/ics_mail_importer.py >> /home/hans/ics-importer/cron.log 2>&1
|
||
|
|
```
|
||
|
|
|
||
|
|
Alternativ ist auch `@hourly` möglich; beide Varianten entsprechen einer stündlichen Ausführung, wobei die klassische Cron-Syntax mit `0 * * * *` die Ausführung zur Minute 0 jeder Stunde beschreibt. [wiki.ubuntuusers](https://wiki.ubuntuusers.de/Cron/)
|
||
|
|
|
||
|
|
### Cron-Eintrag ohne eigenes Umleitungslog
|
||
|
|
|
||
|
|
Wenn die zusätzliche Datei `cron.log` nicht gewünscht ist, kann die Umleitung weggelassen werden:
|
||
|
|
|
||
|
|
```cron
|
||
|
|
0 * * * * /home/hans/.local/share/virtualenvs/ics-importer-wOz4rK-o/bin/python /home/hans/ics-importer/ics_mail_importer.py
|
||
|
|
```
|
||
|
|
|
||
|
|
## Logrotation für `cron.log`
|
||
|
|
|
||
|
|
Für benutzerdefinierte Logs ist `logrotate` der übliche Weg unter Linux. Eine eigene Datei unter `/etc/logrotate.d/` ist dafür die gängige Methode. [dash0](https://www.dash0.com/guides/log-rotation-linux-logrotate)
|
||
|
|
|
||
|
|
Beispiel:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
sudo nano /etc/logrotate.d/ics-importer
|
||
|
|
```
|
||
|
|
|
||
|
|
Inhalt:
|
||
|
|
|
||
|
|
```conf
|
||
|
|
/home/hans/ics-importer/cron.log {
|
||
|
|
weekly
|
||
|
|
rotate 4
|
||
|
|
compress
|
||
|
|
delaycompress
|
||
|
|
missingok
|
||
|
|
notifempty
|
||
|
|
create 0644 hans hans
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Diese Konfiguration rotiert wöchentlich, behält vier alte Versionen, komprimiert alte Logs und legt nach der Rotation eine neue Datei mit passenden Rechten an. [putorius](https://www.putorius.net/rotating-custom-logs-with-logrotate-on.html)
|
||
|
|
|
||
|
|
Zum Testen der Konfiguration:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
sudo logrotate -d /etc/logrotate.d/ics-importer
|
||
|
|
sudo logrotate -f /etc/logrotate.d/ics-importer
|
||
|
|
```
|
||
|
|
|
||
|
|
## Einfügen in vim-nox
|
||
|
|
|
||
|
|
Wenn `crontab -e` mit Vim geöffnet wird, kann im Insert-Modus oft direkt mit `Strg+Shift+V` aus dem Terminal-Zwischenspeicher eingefügt werden. Wenn Vim mit Clipboard-Unterstützung gebaut wurde, ist im Normal-Modus auch `"+p` zum Einfügen aus der System-Zwischenablage möglich. [reddit](https://www.reddit.com/r/vim/comments/q0fsw4/how_do_i_paste_clipboard_contents_into_vim/)
|
||
|
|
|
||
|
|
## Sicherheitshinweise
|
||
|
|
|
||
|
|
`config.ini` enthält Zugangsdaten und sollte nicht weitergegeben oder in öffentliche Repositories eingecheckt werden. Bei aktivierter Zwei-Faktor-Authentifizierung empfiehlt mailbox.org für externe Anwendungen App-Passwörter beziehungsweise Applikationspasswörter anstelle des normalen Passworts. [kb.mailbox](https://kb.mailbox.org/de/business/adressbuch-und-kalender/caldav-bei-thunderbird/)
|
||
|
|
|
||
|
|
## Fehlersuche
|
||
|
|
|
||
|
|
Wenn der Cron-Job nicht läuft, sind die häufigsten Ursachen ein falscher Python-Pfad, fehlende Rechte auf Dateien oder abweichende Umgebungsvariablen unter Cron. Cron-Jobs sollten deshalb mit absoluten Pfaden arbeiten, und ein separates Log wie `cron.log` macht Fehler schnell sichtbar. [betterstack](https://betterstack.com/community/guides/logging/how-to-manage-log-files-with-logrotate-on-ubuntu-20-04/)
|
||
|
|
|
||
|
|
Wenn Termine nicht importiert werden, sollte zuerst geprüft werden, ob die IMAP-Anmeldung funktioniert, ob tatsächlich `.ics`-Anhänge im ausgewählten Ordner vorhanden sind und ob die CalDAV-URL exakt zum Zielkalender gehört. mailbox.org beschreibt, dass die Kalenderadresse direkt aus den Kalendereigenschaften des jeweiligen Kalenders übernommen werden soll. [kb.mailbox](https://kb.mailbox.org/de/privat/e-mail/e-mail-einrichtung-mit-mozilla-thunderbird/)
|
||
|
|
|
||
|
|
## Empfohlener Betriebsmodus
|
||
|
|
|
||
|
|
Für dieses Setup ist ein stündlicher Cron-Job mit aktiviertem Duplikat-Schutz und `unseen_only = true` ein pragmatischer Standard. Das reduziert unnötige IMAP-Abfragen und passt gut zu einem Postfach, in dem Termine typischerweise per Mail-Anhang eingehen. [naschenweng](https://www.naschenweng.eu/2025/03/29/%F0%9F%93%85-sync-ics-feeds-to-your-caldav-calendar-with-emojis-deduplication-and-docker/)
|