Bash script to backup calendars and addressbooks from a local ownCloud/Nextcloud installation
https://codeberg.org/BernieO/calcardbackup
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 

23 KiB

calcardbackup

­čçČ­čçž read this in english...

Dieses Bash-Skript exportiert Kalender und Adressb├╝cher aus ownCloud/Nextcloud als .ics- und .vcf-Dateien und speichert sie in einem komprimierten Archiv. Weitere Optionen stehen zur Verf├╝gung.

Inhalt

Voraussetzungen

  • lokale Installation von ownCloud/Nextcloud >= 5.0 mit MySQL/MariaDB, PostgreSQL oder SQLite3
  • der zur Datenbank geh├Ârende command line client
  • der das Skript startende User muss Leserechte f├╝r den gesamten Pfad zu ownClouds/Nextclouds config.php, zum Skript selbst und zu allen benutzten Konfigurationsdateien haben
  • GNU Bash >= 4.2 (pr├╝fen mit bash --version)
  • optional: das Paket gnupg, um Backups zu verschl├╝sseln
  • optional: das Paket zip, um Backups als zip-Datei zu komprimieren (anstelle tar.gz)
  • optional: das Paket curl, um zus├Ątzliche Pr├╝fungen auszuf├╝hren

Schnellinstallation

  1. das Repository auf Ihren Server klonen (nicht ins webroot!) und ins Verzeichnis wechseln:
    git clone https://codeberg.org/BernieO/calcardbackup.git
    cd calcardbackup

  2. die Besitzrechte des Repository dem Webserver-User zuweisen (hier www-data):
    sudo chown -R www-data:www-data .

  3. das Skript als Webserver-User (hier www-data) aufrufen und als Argument den Pfad zu ownCloud/Nextcloud ├╝bergeben (hier /var/www/nextcloud):
    sudo -u www-data ./calcardbackup "/var/www/nextcloud"

  4. die Ausgabe des Skripts beobachten. Falls weitere Optionen ben├Âtigt werden, wird dies ausgegeben.

  5. Das Backup befindet sich im Verzeichnis backups/.

Es gibt viele weitere Optionen, die dem Skript ├╝bergeben werden k├Ânnen (siehe Optionen und Beispiele).

optional: automatische, t├Ągliche Ausf├╝hrung durch Erstellen eines Cronjobs

Wenn das Skript fehlerfrei l├Ąuft, empfiehlt es sich, die Ausf├╝hrung zu automatisieren.
F├╝r den t├Ąglichen Aufruf kann folgenderma├čen ein Cronjob erstellt werden:

  1. zun├Ąchst eine Logdatei erstellen und die Besitzrechte dem Webserver-User (hier www-data) zuweisen:
    sudo touch /var/log/calcardbackup.log
    sudo chown www-data:www-data /var/log/calcardbackup.log

  2. die Cron-Tabelle des Webserver-Users (hier www-data) zum Bearbeiten ├Âffnen mit:
    sudo crontab -u www-data -e
    und am Ende der Datei die folgende Zeile hinzuf├╝gen (Pfade anpassen!):

    0 2 * * * /pfad/zu/calcardbackup/calcardbackup "/var/www/nextcloud" > /var/log/calcardbackup.log 2>&1
    

Nun wird Cron calcardbackup jeden Tag um 02:00 Uhr morgens aufrufen.
Die Skriptausgabe der jeweils letzten Ausf├╝hrung befindet sich in der Logdatei /var/log/calcardbackup.log.

Es sollte beachtet werden, dass Prozent-Zeichen (%) in einer crontab-Datei in Zeilenumbr├╝che umgewandelt werden, sofern sie nicht maskiert sind.

calcardbackup aktualisieren

Wenn calcardbackup nach der Schnellinstallation eingerichtet wurde, gen├╝gt ein git pull im Installationsordner, um das Skript zu aktualisieren:

cd /path/to/calcardbackup
sudo -u www-data git pull

Migration von GitHub nach Codeberg

Um von GitHub nach Codeberg zu migrieren, ist es am einfachsten, den Ordner mit dem GitHub-Repository umzubenennen und die Schnellinstallation erneut durchzuf├╝hren. Falls Konfigurationsdateien und/oder der Ordner mit den Backups im Verzeichnis des Github-Repositories liegen, m├╝ssen diese in den neuen Ordner verschoben werden.

Optionen

Alle Optionen k├Ânnen als Konfigurationsdatei oder ├╝ber die Kommandozeile ├╝bergeben werden. Ohne Optionen, oder nur mit Option -b|--batch aufgerufen, benutzt das Skript die Datei calcardbackup.conf im Skriptverzeichnis als Konfigurationsdatei, sofern vorhanden.
Falls keine Konfigurationsdatei ├╝ber die Option -c|--configfile an das Skript ├╝bergeben wird, muss der Pfad zur ownCloud/Nextcloud Instanz als erstes Argument ├╝bergeben werden.
Im Folgenden werden die verf├╝gbaren Optionen ausf├╝hrlich beschrieben:

Aufruf: ./calcardbackup [VERZEICHNIS] [Option [Argument]] [Option [Argument]] [Option [Argument]] ...

Argumente in Gro├čbuchstaben sind f├╝r die jeweiligen Optionen notwendig.
Pfade (DATEI / VERZEICHNIS) sind absolute Pfade oder relative Pfade zum Arbeitsverzeichnis.
Falls ein Pfad mit einer Tilde-Slash Kombination ~/ beginnt, wird die Tilde durch ${HOME} ersetzt.

-a | --address URL
       Optional: ├╝bergibt die URL der ownCloud/Nextcloud Installation an das Skript.
-b | --batch
       Batchmodus: au├čer des Pfades zum Backup erfolgt keine Ausgabe.
       Abh├Ąngig von der Konfiguration ist das:
          - absoluter Pfad zum komprimierten Backup-Archiv
       oder, falls mit Option '-x|--uncompressed' aufgerufen,
          - absoluter Pfad zum Verzeichnis mit den unkomprimierten Backupdateien
-c | --configfile DATEI
       Benutze DATEI als Konfigurationsdatei. Siehe 'examples/calcardbackup.conf.example'
       Weitere angegebene Optionen mit Ausnahme von '-b|--batch' werden ignoriert!
-d | --date FORMAT
       Benutze FORMAT als Dateinamenserweiterung f├╝r die komprimierte Backupdatei oder das
       Backupverzeichnis. FORMAT muss eine g├╝ltige Formatbeschreibung des Befehls date() sein.
       Als Standard wird -%Y-%m-%d benutzt, was zu folgender Datei- oder Verzeichnisbenennung f├╝hrt:
       'calcardbackup-2017-03-23.tar.gz' oder 'calcardbackup-2017-03-23'
       Informationen ├╝ber verschiedene Formate und die Syntax finden sich unter 'man date'
-e | --encrypt DATEI
       Verschl├╝ssele das komprimierte Backup mit AES256 (gnupg).
       Die erste Zeile von DATEI wird als Passphrase benutzt werden.
-h | --help
       Gib Versionsnummer und einen kurzen Hilfetext aus
-i | --include-shares
       Sichere auch geteilte Adressb├╝cher und Kalender, aber nur einmal: z.B. ein geteilter
       Kalender wird nicht erneut gesichert, wenn derselbe Kalender schon f├╝r einen anderen
       Nutzer gesichert wurde.
       ACHTUNG: diese Option wird ignoriert, wenn nicht in Kombination mit '-u|--usersfile' benutzt.
-ltm | --like-time-machine N
       Behalte alle Sicherungen der letzten N Tage, f├╝r die Zeit davor aber nur solche, die Montags
       erstellt wurden.
-na | --no-addressbooks
       Sichere keine Adressb├╝cher
-nc | --no-calendars
       Sichere keine Kalender
-o | --output VERZEICHNIS
       Benutze VERZEICHNIS, um die Backups zu speichern.
       Fehlt diese Option, wird das Verzeichnis 'backups/' im Skriptverzeichnis erstellt und benutzt.
-one | --one-file-per-component
       Speichere jede Kalender-Komponente (z.B. Event) und jede Addressbuch-Komponente in eine einzelne
       Datei mit Namen USERNAME-(CALENDARNAME|ADDRESSBOOKNAME)_UID.(ics|vcf).
       In diesem Modus nimmt calcardbackup keine Änderungen an den von der Datenbank erhaltenen Daten
       vor, au├čer die Zeilenenden mit CR+LF zu gestalten (wie in RFC5545/RFC6350 vorgeschrieben).
       Mit Hilfe dieser Option k├Ânnen fehlerhafte Datenbankeintr├Ąge untersucht oder
       Kalender/Addressb├╝cher zu einem Radicale caldav/carddav Server oder zu vdirsyncer migriert
       werden.
-p | --snap
       Diese Option ist verpflichtend bei nextcloud-snap (https://github.com/nextcloud/nextcloud-snap).
       calcardbackup muss in diesem Fall mit sudo gestartet werden (ausgef├╝hrt als root ohne sudo wird
       auch scheitern!).
-r | --remove N
       L├Âsche Backups ├Ąlter als N Tage vom Backupverzeichnis (N muss eine positive Ganzzahl sein).
-s | --selfsigned
       Ignoriere ein nicht vertrauensw├╝rdiges (z.B. selbstsigniertes) Zertifikat. cURL wird
       benutzt, um status.php abzurufen und damit zus├Ątzliche Pr├╝fungen durchzuf├╝hren. Falls
       cURL die URL aufgrund eines nicht vertrauensw├╝rdigen Zertifikates nicht erreichen kann,
       wird calcardbackup diese zus├Ątzlichen Pr├╝fungen ├╝berspringen. Dasselbe gilt, falls cURL
       nicht installiert ist.
-u | ÔÇöusersfile DATEI
       Benutze DATEI, die die Nutzernamen der Nutzer enth├Ąlt, deren Daten gesichert werden sollen.
       Ein Nutzer pro Zeile. Siehe 'examples/users.txt.example'
-x | --uncompressed
       komprimiere das Backup nicht
-z | --zip
       Benutze zip, um das Backup zu komprimieren, an Stelle eines gzip-tar-Archivs (tar.gz)

ACHTUNG: - die Option '-f|--fetch-from-database' (eingef├╝hrt mit calcardbackup 0.6.0) ist
           der Standard f├╝r calcardbackup >= 0.8.0 und hat daher keine Funktion mehr.
         - die Option '-g|--get-via-http' wurde mit v2.0.0 entfernt (veraltet seit v0.8.0, 30.10.2018).

Dateinamenkonvention

Die Dateinamen der exportierten Kalender und Adressb├╝cher werden zusammengesetzt aus dem Nutzernamen, dem Namen des Kalenders/Adressbuchs und einer Dateierweiterung (.ics f├╝r Kalender, .webcal f├╝r Kalenderabonnements, .vcf f├╝r Adressb├╝cher):

Tom_Konferenzen.ics
Tom_Bundesliga.webcal
Tom_Kontakte.vcf

In folgenden F├Ąllen wird dem Dateinamen eine zus├Ątzliche Bezeichnung hinzugef├╝gt (Kombinationen sind m├Âglich):

  • vorhandene Dateien werden niemals ├╝berschrieben. Stattdessen wird dem Dateinamen eine Zahl direkt vor der Dateinamenserweiterung hinzugef├╝gt:
    Tom_Konferenzen_01.ics
    
  • beim Benutzen der Option -i|--include-shares wird _shared-by-USERNAME zum Dateinamen von geteilten Kalendern/Adressb├╝chern hinzugef├╝gt (Tom teilt seinen Kalender Konferenzen mit Emma):
    Emma_Konferenzen_shared-by-Tom.ics
    
  • beim Benutzen der Option -one|--one-file-per-component wird die UID des betreffenden Elementes dem Dateinamen hinzugef├╝gt:
    Tom_Konferenzen_1234-5678.ics
    
  • nur Nextcloud >= 22: dem Dateinamen eines gel├Âschten Kalenders wird _DEL-CLNDR hinzugef├╝gt:
    Tom_Konferenzen_DEL-CLNDR.ics
    
  • nur Nextcloud >= 22: falls ein Kalender gel├Âschte Elemente enth├Ąlt, werden diese gel├Âschten Elemente in einem separaten Kalender gesichert. Dem Dateinamen wird _DEL-CMPNTS hinzugef├╝gt:
    Tom_Konferenzen_DEL-CMPNTS.ics
    

Beispiele

  1. ./calcardbackup /var/www/nextcloud -nc -x
    Sichere keine Kalender (-nc) und speichere das Backup unkomprimiert (-x) im Verzeichnis calcardbackup-YYYY-MM-DD (Standard) in ./backups/ (Standard).

  2. ./calcardbackup /var/www/nextcloud --no-calendars --uncompressed
    Dies ist genau dasselbe Kommando wie im ersten Beispiel, allerdings mit langen Optionsnamen statt der kurzen.

  3. ./calcardbackup -c /etc/calcardbackup.conf
    Benutze die Konfigurationsdatei /etc/calcardbackup.conf (-c /etc/calcardbackup.conf). Alle Parameter f├╝r das gew├╝nschte Verhalten m├╝ssen in dieser Datei angegeben werden (siehe examples/calcardbackup.conf.example).
    Die Angabe weiterer Optionen entf├Ąllt, da sie ignoriert werden (mit Ausnahme von -b|--batch).

  4. ./calcardbackup
    Benutze die Datei calcardbackup.conf im Verzeichnis des Skripts als Konfigurationsdatei.
    Dies ist im Grunde dasselbe wie Beispiel Nr. 3, nur mit dem Standardpfad der Konfigurationsdatei.

  5. ./calcardbackup /var/www/nextcloud -b -d .%d.%H -z -e /home/tom/key -o /media/data/backupfolder/ -u /etc/calcardbackupusers -i -r 15
    Unterdr├╝cke alle Ausgaben au├čer dem Pfad zum Backup (-b), benutze die Dateinamenserweiterung .DD.HH (-d .%d.%H), benutze zip, um das Backup zu komprimieren (-z), verschl├╝ssele das komprimierte Backup und benutze als Schl├╝ssel die erste Zeile der Datei /home/tom/key (-e /home/tom/key), speichere das Backup im Verzeichnis /media/data/backupfolder/ (-o /media/data/backupfolder/), sichere nur Elemente von in der Datei /etc/calcardbackupusers angegebenen Nutzern (-u /etc/calcardbackupusers), schlie├če mit Nutzern geteilte Adressb├╝cher/Kalender mit ein (-i) und l├Âsche alle Sicherungen ├Ąlter als 15 Tage (-r 15).

  6. sudo ./calcardbackup /var/snap/nextcloud/current/nextcloud -p
    Dieses Beispiel ist f├╝r Nutzer von nextcloud-snap. calcardbackup wird die Dienstprogramme von nextcloud-snap benutzen (-p), um alle in der Datenbank vorhandenen Kalender und Adressb├╝cher zu sichern.

  7. ./calcardbackup /var/www/nextcloud -ltm 30 -r 180
    Behalte alle Sicherungen der letzten 30 Tage, f├╝r die Zeit davor aber nur solche, die Montags erstellt wurden (-ltm 30) und l├Âsche alle Backups, die ├Ąlter als 180 Tage sind (-r 180).
    ÔÜá´ŞĆ Es muss sichergestellt werden, dass Backups auch Montags erstellt werden, wenn die Option -ltm benutzt wird.

Nextcloud-Snap Benutzer

Falls Nextcloud-Snap benutzt wird, muss das Skript mit Option -p|--snap aufgerufen werden. calcardbackup wird dann das im Snap-Paket enthaltene Dienstprogramm nextcloud.mysql-client benutzen, um auf die Datenbank zuzugreifen.
Damit dies funktioniert, muss calcardbackup mit sudo aufgerufen werden (als root ohne sudo aufgerufen wird auch fehlschlagen).
Als Pfad zu Nextcloud muss der Pfad zu den Konfigurationsdateien des Snap Paketes angegeben werden. Bei einer Standardinstallation ist dies /var/snap/nextcloud/current/nextcloud. Siehe Beispiel Nr. 6.

Syncloud Benutzer

Unter syncloud muss das Skript als User nextcloud mit der Option -p aufgerufen werden. Zus├Ątzlich muss beim Aufruf von calcardbackup der Pfad zu den snap-binaries der Pfad-Variablen hinzugef├╝gt werden:

sudo -u nextcloud PATH="${PATH}:/snap/bin" ./calcardbackup "/var/snap/nextcloud/current/nextcloud" -p

Es gibt auch ein kleines Code-Beispiel ├╝ber die Benutzung von calcardbackup im Wiki der Syncloud-Plattform.

Synology Benutzer

Beim Synology DiskStation Manager (DSM) muss vor Aufruf von calcardbackup der Pfad zu mysql der PATH Variablen hinzugef├╝gt werden. Beispiel:

sudo -u http PATH="${PATH}:/usr/local/mariadb10/bin" ./calcardbackup "/volume1/web/nextcloud"

Funktioniert das auch mit einer kaputten ownCloud/Nextcloud Installation?

Ja, das geht! ­čśâ

calcardbackup ben├Âtigt lediglich die Datenbank (und Zugang zu ihr) einer ownCloud/Nextcloud Installation, um Kalender/Adressb├╝cher von der Datenbank auszulesen und sie als .ics und .vcf Datein zu sichern (ein Datenbank-dump muss zuerst in eine Datenbank importiert werden).
So kann vorgegangen werden:

  1. eine Nextcloud Verzeichnis Attrappe anlegen (inklusive Unterverzeichnis config):
    mkdir -p /usr/local/bin/nextcloud_dummy/config

  2. eine Datei config.php anlegen und mit folgenden Werten f├╝llen:
    nano /usr/local/bin/nextcloud_dummy/config/config.php

    • den Typ der Datenbank wie in config.sample.php

    • f├╝r MySQL/MariaDB/PostgreSQL:

    • f├╝r SQLite3:

      • den Pfad des in Schritt 1 angelegten nextcloud_dummy Verzeichnisses als 'datadirectory' wie in config.sample.php
      • die SQLite3 Datenbank in die Verzeichnisattrappe kopieren (der Dateiname der SQLite3 Datenbank muss owncloud.db lauten):
        cp /path/to/owncloud.db /usr/local/bin/nextcloud_dummy/owncloud.db
    • falls die Datenbank zu einer Installation von ownCloud <= 8.2 geh├Ârt, muss folgende Zeile hinzugef├╝gt werden:
      'version' => '8.0.0',

  3. calcardbackup ausf├╝hren und als erstes Argument den Pfad zu der in Schritt 1 angelegten Nextcloud Verzeichnisattrappe angeben:
    ./calcardbackup /usr/local/bin/nextcloud_dummy

Kann ich das auch ohne Shell Zugang zu meinem Server benutzen?

Abh├Ąngig von der Konfiguration des Webhosters kann calcardbackup eventuell auch ohne Shell-Zugang benutzt werden: Zus├Ątzlich zu den Voraussetzungen des Skriptes muss der Hoster zulassen, dass eine PHP-Funktion Shell-Skripte ausf├╝hren darf (entweder passthru(), system(), exec() oder shell_exec()). Nur dann kann calcardbackup ausgef├╝hrt werden, indem es vom im Repo enthaltenen calcardbackup_wrapper.php calcardbackup aufgerufen wird.
Es wird folgenderma├čen genutzt:

  1. calcardbackup und calcardbackup_wrapper.php in ein Verzeichnis auf dem Webserver hochladen

  2. die Pfade des Kommandos im Konfigurationsbereich von calcardbackup_wrapper.php entsprechend der Umgebung anpassen und nach Bedarf weitere Optionen hinzuf├╝gen.

  3. mit dem Browser die gerade hochgeladene Datei calcardbackup_wrapper.php aufrufen und die Ausgabe ├╝berpr├╝fen.

Da es sehr viele unterschiedliche Konfigurationen bei den Webhostern gibt, kann es vorkommen, dass calcardbackup nicht ausgef├╝hrt werden kann oder nicht alle Optionen funktionieren werden (manche Hoster deaktivieren aus Sicherheitsgr├╝nden die ben├Âtigten PHP-Funktionen, andere m├Âgen sie aktiviert haben, sperren aber den Aufruf von externen Befehlen). Das Kommando, um calcardbackup aufzurufen, muss also eventuell angepasst oder um verschiedene Optionen erg├Ąnzt werden.

Bei einer sehr gro├čen zu sichernden Datenmenge k├Ânnen PHP-Timeouts auftreten. Diese k├Ânnen umgangen werden, indem das Skript zweimal ausgef├╝hrt wird (einmal mit der Option -na, um nur die Kalender zu sichern, ein zweites Mal mit der Option -nc um nur Adressb├╝cher zu sichern). Eine andere M├Âglichkeit ist, bei jedem Skriptdurchlauf nur einen Teil der Nutzerdaten zu sichern (├╝ber die Option -u).

ÔÜá´ŞĆ Um ein unberechtiges Herunterladen der gesicherten Daten zu verhindern, sollte der Zugang zum Backup-Ordner mit einem Passwort gesch├╝tzt werden (z.B. ├╝ber eine .htaccess-Datei).

Ich freue mich ├╝ber Feedback, mit welchen Hostern das funktioniert oder nicht funktioniert.

Erw├Ąhnenswertes zur Verschl├╝sselungsoption

Falls die Verschl├╝sselungsoption des Skripts benutzt wird (Option -e), sollte man sich folgender Dinge bewusst sein:

  • die Dateien werden von GnuPG (AES256) mit einem Passwort verschl├╝sselt, das in einer separaten Datei angegeben wird
  • das Passwort ist in einer Datei gespeichert. Andere Nutzer mit Zugang zum Server k├Ânnten das Passwort einsehen.
  • calcardbackup soll ohne Benutzerinteraktion funktionieren. Daher kann es keine bombensichere Verschl├╝sselung anbieten. Ich betrachte die angebotene Verschl├╝sselungsm├Âglichkeit allerdings f├╝r die meisten Anwendungsf├Ąlle als ausreichend
  • falls bombensichere Verschl├╝sselung ben├Âtigt wird, lassen Sie nicht calcardbackup die Sicherung verschl├╝sseln. Verschl├╝sseln Sie das Archiv stattdessen selbst.
  • das Kommando zum Entschl├╝sseln lautet (nach Eingabe des Befehls wird das Passwort angefordert):
    gpg -o AUSGABE_DATEI -d VERSCHL├ťSSELTE_DATEI.GPG

Zugeh├Ârige Forenthreads

Blogartikel ├╝ber calcardbackup

calcardbackup in der Presse:

Linux Pakete

Docker Abbild f├╝r calcardbackup

ICS und VCF Standard

  • RFC 5545 - Internet Calendaring and Scheduling Core Object Specification (iCalendar)
  • RFC 6350 - vCard Format Specification

Exporter Plugins von SabreDAV

Kontakt

Er├Âffne ein Issue, kommentiere meinen Blogbeitrag ├╝ber calcardbackup oder schreibe mir eine E-Mail.

Spenden

calcardbackup ist und bleibt freie Open Source Software.
Falls dir calcardbackup gef├Ąllt und du das Skript n├╝tzlich findest, k├Ânntest du den Entwickler unterst├╝tzen und eine Spende t├Ątigen. Jeder Betrag ist willkommen!

IBAN: DE58 1203 0000 1032 8146 40
BIC: BYLADEM1001

Lizenz

Copyright (C) 2017 Bernhard Ostertag bernieo.code@gmx.de

Dieses Programm ist freie Software. Sie k├Ânnen es unter den Bedingungen der
GNU Affero General Public License, wie von der Free Software Foundation ver├Âffentlicht,
weitergeben und/oder modifizieren, entweder gem├Ą├č Version 3 der Lizenz oder (nach
Ihrer Option) jeder sp├Ąteren Version.

Die Ver├Âffentlichung dieses Programms erfolgt in der Hoffnung, da├č es Ihnen von Nutzen
sein wird, aber OHNE IRGENDEINE GARANTIE, sogar ohne die implizite Garantie der MARKTREIFE
oder der VERWENDBARKEIT F├ťR EINEN BESTIMMTEN ZWECK. Details finden Sie in der
GNU Affero General Public License.

Sie sollten ein Exemplar der GNU Affero General Public License zusammen mit diesem
Programm erhalten haben. Falls nicht, siehe <http://www.gnu.org/licenses/>.