occ – die Kommandozeile #

occ ist das Verwaltungswerkzeug von owncloud.online auf der Kommandozeile. Es liegt als Datei occ im Wurzelverzeichnis der Installation, startet dieselbe Umgebung wie die Weboberfläche und lädt zusätzlich die Befehle der aktivierten Apps. Der Befehlsvorrat ist deshalb nicht fest: Er hängt davon ab, ob die Instanz installiert ist, ob sie im Wartungsmodus steht und welche Apps aktiviert sind.

Aufruf #

# alle verfügbaren Befehle auflisten
sudo -u www-data php8.4 /var/www/owncloud.online/occ list

# Hilfe zu einem einzelnen Befehl mit allen Optionen
sudo -u www-data php8.4 /var/www/owncloud.online/occ user:add --help

Der Aufruf funktioniert aus jedem Arbeitsverzeichnis, solange der vollständige Pfad angegeben wird — console.php wechselt selbst in das Installationsverzeichnis. Auf dieser Seite ist der Pfad in den Beispielen der Kürze halber weggelassen.

Vorausgesetzt werden die PHP-Erweiterungen posix (harte Bedingung, ohne sie bricht occ sofort ab) und pcntl (weiche Bedingung, ohne sie lassen sich lang laufende Befehle nicht sauber unterbrechen; es erscheint eine Warnung).

Rechte: immer als Webserver-Benutzer #

occ prüft vor jeder Ausführung, ob der aufrufende Benutzer identisch mit dem Eigentümer von config/config.php ist. Ist er es nicht, bricht der Aufruf ab:

Console has to be executed with the user that owns the file config/config.php

In der Standardinstallation ist das www-data. Deshalb gilt ausnahmslos:

sudo -u www-data php8.4 /var/www/owncloud.online/occ status

Ein Aufruf als root ist auch dann falsch, wenn er durchläuft: Dateien und Verzeichnisse, die dabei entstehen — Logdatei, Vorschaubilder, Dateien im Datenverzeichnis — gehören danach root und sind für den Webserver nicht mehr beschreibbar. Dasselbe gilt für den Cron-Eintrag, siehe Hintergrund-Jobs.

Globale Optionen #

sudo -u www-data php8.4 occ status --output=json_pretty

Wartungsmodus #

Der Wartungsmodus wird über occ gesetzt und schreibt den Systemwert maintenance nach config/config.php:

sudo -u www-data php8.4 occ maintenance:mode --on
sudo -u www-data php8.4 occ maintenance:mode --off

# ohne Option: aktuellen Zustand anzeigen
sudo -u www-data php8.4 occ maintenance:mode

Entscheidend für die Praxis: Im Wartungsmodus lädt occ keine Apps. Damit verschwinden auch deren Befehle aus der Liste. occ weist beim Start darauf hin:

owncloud.online is in maintenance mode - no app have been loaded

Zwei weitere Zustände schränken den Befehlsvorrat ebenso ein:

• Nicht installiert: Es steht nur maintenance:install zur Verfügung, dazu die wenigen Befehle, die keine Installation brauchen (status, check, integrity:*, app:check-code, l10n:createjs).
• Update ausstehend: Meldet die Instanz „owncloud.online or one of the apps require upgrade", werden die Apps nicht geladen — der Befehlsvorrat entspricht dem im Wartungsmodus, die Core-Befehle bleiben also vorhanden. Der Weg heraus ist occ upgrade.

Der Einzelbenutzermodus (maintenance:singleuser, Systemwert singleuser) ist davon zu unterscheiden: Er lässt die Apps geladen. occ system:cron bricht darin mit „We are in admin only mode, skipping cron" ab, die Weboberfläche antwortet Konten außerhalb der Gruppe admin mit HTTP 503, und der WebDAV-Endpunkt verweigert jede Anfrage mit „System in single user mode." — auch die von Administratoren.

Wartung und Update #

Ein Update spielt zuerst den Code ein und lässt danach occ upgrade laufen:

sudo -u www-data php8.4 occ maintenance:mode --on
sudo -u www-data php8.4 occ upgrade
sudo -u www-data php8.4 occ maintenance:mode --off

integrity:check-core liefert auf dem ausgelieferten Kanal keine belastbare Aussage — die Einzelheiten stehen unter Sicherheit und Setup-Warnungen.

Steckengebliebene Dateisperren nach einem Absturz löst dieser Befehl:

# gefahrlos im laufenden Betrieb: nur abgelaufene Sperren
sudo -u www-data php8.4 occ maintenance:file-locks --cleanup-expired

# alle Sperren — verlangt aktiven Wartungsmodus
sudo -u www-data php8.4 occ maintenance:file-locks --all

Mit --dry-run zeigt der Befehl nur an, was er löschen würde.

Konten und Gruppen #

user:sync ist der Befehl für angebundene Verzeichnisdienste. Er kennt die Kurzformen ldap, samba und shibboleth anstelle des vollen Klassennamens und listet mit --list die aktiven Backends auf:

sudo -u www-data php8.4 occ user:sync --list
sudo -u www-data php8.4 occ user:sync ldap --missing-account-action=disable

--missing-account-action nimmt disable oder remove. remove löscht mit dem Konto auch dessen Daten und Dateien — im Regelbetrieb gehört dort disable hin.

Dateien und Dateisystem #

files:scan ist der Befehl, den man nach jedem Eingriff direkt im Datenverzeichnis braucht — der Dateicache kennt sonst die neuen Dateien nicht:

# ein Konto
sudo -u www-data php8.4 occ files:scan alice

# nur ein Unterpfad
sudo -u www-data php8.4 occ files:scan --path="/alice/files/Musik"

# alle Konten
sudo -u www-data php8.4 occ files:scan --all

Zusätzlich gibt es --group, --unscanned (nur unvollständig erfasste Dateien) und --repair für abgehängte Cache-Einträge. --repair ist deutlich langsamer und gehört in ein Wartungsfenster.

Freigaben #

Beim Übertragen eines Kontos wandern die Freigaben mit — dafür ist files:transfer-ownership zuständig, siehe voriger Abschnitt.

Konfiguration #

sudo -u www-data php8.4 occ config:list system
sudo -u www-data php8.4 occ config:system:set loglevel --value 2 --type integer

config:list ersetzt einen fest hinterlegten Satz vertraulicher Systemwerte durch ***REMOVED SENSITIVE VALUE*** — darunter dbpassword, passwordsalt, secret, mail_smtppassword, ldap_agent_password, license-key und die Zugangsdaten unter redis und objectstore. Erst --private gibt sie im Klartext aus. Die App-Werte aus der Datenbank filtert der Befehl nicht — sie stehen bei config:list all und config:list <app> auch ohne --private unverändert in der Ausgabe. Die Ausgabe gehört deshalb in keinem Fall ungeprüft in ein Ticket oder ein Repository. Die einzelnen Schlüssel beschreibt Konfiguration (config.php).

Hintergrundaufträge #

Die drei background:-Befehle schreiben denselben App-Wert core / backgroundjobs_mode; abfragen lässt er sich mit config:app:get core backgroundjobs_mode. Empfohlen ist cron, Einrichtung und Prüfung stehen unter Hintergrund-Jobs.

system:cron bricht ab, wenn ein Update aussteht, der Wartungsmodus oder der Einzelbenutzermodus aktiv ist oder die Ausführungsart auf none steht. Mit --progress zeigt es einen Fortschrittsbalken — diese Option gehört ausdrücklich nicht in einen Crontab-Eintrag.

Datenbank #

Vor jedem dieser Eingriffe gehört ein Datenbank-Backup angelegt, siehe Backups und Updates. Im Regelbetrieb ruft man migrations:* nicht direkt auf — occ upgrade erledigt das.

Protokoll #

# Stufe auf Warnungen, Ausgabe in eine Datei
sudo -u www-data php8.4 occ log:manage --level warning
sudo -u www-data php8.4 occ log:owncloud --enable --rotate-size 100M

log:manage schreibt die Systemwerte log_type (owncloud, syslog oder errorlog), loglevel (debug, info, warning, error, fatal) und logtimezone. log:owncloud schreibt logfile und log_rotate_size (0 schaltet die Rotation ab). Zum Lesen und Auswerten siehe Serverprotokoll und Fehlermeldungen.

Apps #

Die vier market:-Befehle stammen aus der Markt-App und stehen nur zur Verfügung, wenn diese aktiviert ist; Katalog und Konfiguration beschreibt Apps und Marketplace.

Das gilt allgemein: Eine App bringt ihre Befehle nur mit, solange sie aktiviert ist. Nach app:disable files_external verschwinden alle files_external:*-Befehle aus occ list.

Weitere registrierte Befehlsgruppen #

Die Einzelheiten zur Verschlüsselung stehen unter Verschlüsselung.

Fehlersuche #