Lernseite · Server und Kommandozeile
Server und Kommandozeile: das Handwerk unter TYPO3
Unter jeder TYPO3-Website liegt ein Server. Auf dieser Seite richtest du mit der Integratorin Mara einen Server ein. Danach bewegst du dich sicher in der Shell, legst Cronjobs an, liest und setzt Dateirechte und erkennst Fehler am Statuscode. Du weißt außerdem, wie TYPO3 Dateien und Bilder verwaltet, wie es IP-Adressen anonymisiert und wie Git dein Projekt verwaltet.
Das Beispiel: der Server der Musikschule Lindenau
Mara baut die Website der Musikschule Lindenau als Composer-Projekt mit TYPO3 14.3. Ihr Sitepackage heißt lindenau_site, das Composer-Paket dazu lindenau/site. Es liegt im Ordner packages des Projekts.
Jetzt zieht die Website auf einen Linux-Server um. Mara meldet sich per SSH an und landet auf der Kommandozeile, auch Shell genannt. Es gibt keine Maus und keinen Papierkorb, jeder Befehl wirkt sofort.
Erste Schritte auf der Kommandozeile
Du stehst immer in einem aktuellen Verzeichnis. Der Befehl pwd zeigt, wo das ist. Mit ls listest du den Inhalt eines Verzeichnisses auf. Mit der Option l wird die Liste ausführlich, samt Rechten und Besitzer. Mit cd wechselst du das Verzeichnis. Zwei Punkte als Ziel führen eine Ebene nach oben. Ohne Argument bringt dich cd ins Home-Verzeichnis. Der Befehl cat gibt den Inhalt einer Datei aus.
pwd
cd /var/www/lindenau
ls -l
cd ..
cat /var/www/lindenau/composer.jsonRelative Pfade beziehen sich auf das aktuelle Verzeichnis. Nur ein Pfad, der mit einem Schrägstrich beginnt, ist absolut. Derselbe Befehl kann also je nach Standort etwas anderes treffen.
Anlegen, kopieren, löschen:
mkdirlegt ein Verzeichnis an, mit der Option p auch mehrere Ebenen auf einmal. Vorhandenes löscht es nicht.touchlegt eine leere Datei an. Bei einer vorhandenen Datei aktualisiert es den Zeitstempel.cpkopiert Dateien. Ein Verzeichnis samt Inhalt kopiert es erst mit der Option r, also rekursiv.mvverschiebt eine Datei oder benennt sie um.rmlöscht Dateien, mit der Option r auch ein Verzeichnis samt Inhalt.rmdirlöscht nur leere Verzeichnisse.
mkdir -p backup/2026
touch notizen.txt
cp -r config backup/2026/
mv alt.txt neu.txt
rm -r tmp-testHilfe: Die Handbuchseite eines Befehls öffnest du mit man und dem Befehlsnamen. Viele Befehle zeigen außerdem mit der Option help, mit zwei Minuszeichen davor, eine Kurzhilfe. Ein Schrägstrich mit Fragezeichen ist eine Gewohnheit von Windows.
man ls
ls --helpEine leere Variable als Falle: In einem alten Skript löscht eine Zeile einen Ordner aus einer Variablen. Ist die Variable leer, bleibt nur der Schrägstrich übrig, und der Befehl trifft die Wurzel des Dateisystems. Die Option f unterdrückt jede Rückfrage.
rm -rf $ORDNER/Sichere Skripte prüfen deshalb vorher, ob die Variable gefüllt ist, und arbeiten mit absoluten, geprüften Pfaden.
Cron: Befehle nach Zeitplan
Der Cron-Daemon ist ein Dienst, der Befehle nach einem Zeitplan startet. Einen solchen zeitgesteuerten Befehl nennt man Cronjob. Die Liste der Cronjobs eines Benutzers heißt crontab. Mit crontab und der Option e bearbeitest du sie, mit der Option l zeigst du sie an.
crontab -e
crontab -lJede Zeile hat fünf Zeitfelder und danach den Befehl. Die Reihenfolge ist Minute, Stunde, Tag des Monats, Monat und Wochentag. Ein Stern bedeutet jeder Wert. Sekunden gibt es in der klassischen crontab nicht. Beim Wochentag steht 1 für Montag, 0 und 7 stehen für Sonntag.
Zwei Beispiele von Maras Server:
- Die Zeile mit null, drei und drei Sternen startet die Datensicherung täglich um 3 Uhr.
- Die Zeile mit 30, 2, zwei Sternen und einer 1 startet einen Bericht jeden Montag um 2 Uhr 30.
Cron und TYPO3: TYPO3 nutzt Cron, um den Scheduler regelmäßig anzustoßen. Dafür genügt ein einziger Eintrag, der alle paar Minuten scheduler run aufruft. Der Scheduler sucht dann selbst die fälligen Aufgaben.
*/5 * * * * /usr/bin/php8.4 /var/www/lindenau/vendor/bin/typo3 scheduler:runDateirechte unter Linux
Jede Datei hat einen Besitzer und eine Gruppe. Rechte gibt es getrennt für den Besitzer, die Gruppe und alle anderen:
- Das r steht für read, also lesen.
- Das w steht für write, also schreiben.
- Das x steht für execute, also ausführen. Bei einem Verzeichnis erlaubt x das Betreten.
Die Rechte zeigt die ausführliche Liste von ls. Das erste Zeichen nennt den Typ: ein Minus für eine Datei, ein d für ein Verzeichnis, ein l für einen symbolischen Link.
chmod ändert die Rechte, chown den Besitzer und chgrp die Gruppe. Als Zahl ist jede Ziffer die Summe aus 4 für lesen, 2 für schreiben und 1 für ausführen. Mit 755 darf der Besitzer eines Verzeichnisses alles. Alle anderen dürfen es lesen und betreten.
chmod 755 public
chown -R mara:www-data varWas TYPO3 setzt: Neue Dateien bekommen die Rechte aus der Einstellung fileCreateMask im Bereich SYS, Standard 0664. Neue Ordner bekommen sie aus folderCreateMask, Standard 2775. Die 2 vorne ist das setgid-Bit: Neue Dateien im Ordner erben dessen Gruppe. So arbeiten Mara und der Webserver in derselben Gruppe.
Wo der Webserver schreiben muss:
- Im Ordner
varlegt TYPO3 Caches, Logs und Sperren ab. - Im Ordner
public/fileadminliegen die Uploads der Redaktion. - Im Ordner
public/typo3templiegen öffentliche temporäre Dateien.
Den Ordner vendor verwaltet Composer, dort schreibt der Webserver nicht. Der Ordner config muss nur beschreibbar sein, wenn du im Backend Einstellungen oder Sites speicherst.
Ordner und Dateien von TYPO3
In einer Extension wie lindenau_site hat jeder Ordner eine feste Aufgabe:
- Im Ordner
Classesliegen die PHP-Klassen. Composer lädt sie nach PSR-4. - Im Ordner
Configurationsteht die Konfiguration, zum Beispiel Site Set und TCA. - Im Ordner
Resources/Privateliegen Templates und Sprachdateien. - Nur der Ordner
Resources/Publicwird öffentlich gemacht. Dort liegen CSS und JavaScript.
Im Projekt legt TYPO3 selbst Ordner an. Der Ordner var/cache enthält Caches, die sich neu erzeugen lassen. Der Ordner var/log enthält Protokolle. Bearbeitete Bilder legt TYPO3 in einen Ordner _processed_ im jeweiligen Dateispeicher. Den Ordner var löschst du nie komplett, sondern leerst nur gezielt. Den Ordner fileadmin rührt kein Cache-Leeren an, er gehört der Redaktion. Unter System, Maintenance gibt es die Karte „Remove Temporary Assets“. Sie entfernt unter anderem bearbeitete Bildvarianten.
Umlaute in Dateinamen: Eine Lehrerin lädt den Plan für „Flöte“ hoch, und der Dateiname kommt seltsam umbenannt an. Hier spielen zwei Einstellungen im Bereich SYS zusammen. Mit UTF8filesystem speichert TYPO3 Dateinamen in UTF-8. Das braucht eine UTF-8-fähige Locale, die du in systemLocale angibst. Sonst gibt es Probleme mit Sonderzeichen. Neue Installationen setzen UTF8filesystem auf true.
HTTP-Statuscodes
Der Server beantwortet jede Anfrage mit einem dreistelligen Statuscode. Die erste Ziffer nennt die Gruppe:
- Mit 2 beginnt Erfolg. 200 heißt OK.
- Mit 3 beginnen Weiterleitungen. Dazu zählt auch 304, Not Modified: Die gespeicherte Fassung des Browsers ist noch gültig.
- Mit 4 beginnen Fehler des Clients. 404 heißt nicht gefunden. 403 heißt verboten, etwa bei einer Seite nur für angemeldete Benutzer.
- Mit 5 beginnen Fehler des Servers. Du findest sie in den Log-Dateien.
Serverfehler im Log: 500 ist ein interner Fehler, etwa ein PHP-Fehler. 502 meldet eine fehlerhafte Antwort eines vorgeschalteten Servers. 503 heißt vorübergehend nicht verfügbar und passt für eine Wartung. 201 heißt angelegt und ist so wenig ein Fehler wie 304.
Weiterleitungen:
- 301 ist dauerhaft, 302 vorübergehend.
- 307 ist vorübergehend und verlangt dieselbe Methode. Ein POST bleibt ein POST.
- 308 ist das dauerhafte Gegenstück zu 307.
In der Site-Konfiguration hinterlegst du eigene Fehlerseiten für einzelne Codes, etwa für 404 und 403.
IP-Adressen anonymisieren
TYPO3 speichert an einigen Stellen IP-Adressen, zum Beispiel in der Tabelle sys_log. Eine IP-Adresse lässt sich einer Person zuordnen. Sie ist ein personenbezogenes Datum. Wer sie nach einer Frist unkenntlich macht, schützt die Besucher und senkt das Datenschutzrisiko alter Protokolle.
Die globale Einstellung ipAnonymization im Bereich SYS gilt für Adressen, die über die Schnittstelle von TYPO3 gespeichert werden:
- Der Wert 0 schaltet die Anonymisierung ab.
- Der Standardwert 1 ersetzt bei IPv4 das letzte Byte durch null, bei IPv6 die Interface-ID.
- Der Wert 2 maskiert bei IPv4 die letzten zwei Bytes, bei IPv6 zusätzlich die SLA-ID.
Für die Tabelle sys_log gilt diese Einstellung nicht. Dort speichert TYPO3 die volle Adresse. Für alte Einträge gibt es deshalb eine eigene Aufgabe.
Die Scheduler-Aufgabe „Anonymize IP addresses in database tables“ bearbeitet schon gespeicherte Adressen. Mara legt sie im Modul Scheduler an und gibt drei Dinge an:
- Die Tabelle, zum Beispiel sys_log.
- Die Zahl der Tage. Nur ältere Datensätze werden anonymisiert.
- Die Stufe der Maskierung, also ein oder zwei Bytes. Voreingestellt sind zwei Bytes.
Das Alter erkennt die Aufgabe an einem Zeitstempel-Feld der Tabelle.
Eigene Tabellen: Die Musikschule speichert bei Anmeldungen zur Probestunde die IP-Adresse in einer eigenen Tabelle. Seit TYPO3 14 meldet Mara sie per TCA-Override an. Die Datei gilt der Tabelle tx_scheduler_task, und zwar dem Typ der IP-Aufgabe. Unter taskOptions und tables nennt sie das Feld für die IP und das Zeitstempel-Feld.
$GLOBALS['TCA']['tx_scheduler_task']['types'][IpAnonymizationTask::class]['taskOptions']['tables']['tx_lindenausite_trial'] = [
'dateField' => 'crdate',
'ipField' => 'ip_address',
];Der frühere Weg über die globalen Einstellungen unter SC_OPTIONS ist veraltet und entfällt mit TYPO3 15.
Reguläre Ausdrücke
Ein regulärer Ausdruck beschreibt ein Muster, mit dem du Text findest, prüfst oder ersetzt. In TYPO3 begegnet er dir bei Redirects mit Regex und bei Validatoren. PHP nutzt die Variante PCRE, das Muster steht dort zwischen zwei Begrenzern, oft Rautenzeichen.
- Das Dach-Zeichen verankert das Muster am Anfang des Texts, das Dollarzeichen am Ende.
- Ohne Anker darf der Treffer irgendwo im Text liegen.
- Ein Punkt steht für ein beliebiges Zeichen. Einen echten Punkt schreibst du mit Backslash davor.
- Backslash d steht für eine Ziffer, Backslash w für ein Wortzeichen.
- Eckige Klammern mit a, b und c passen auf genau eines dieser Zeichen.
- Plus heißt ein- oder mehrmals, Stern null- oder mehrmals, Fragezeichen null- oder einmal.
- Runde Klammern bilden Gruppen, auf die du später verweisen kannst.
- Punkt und Stern zusammen sind gierig und greifen so viel wie möglich.
\d+
^index\.html$
[abc]
#^/news/\d+$#Testen kannst du Muster mit Werkzeugen wie regex101. Sie zeigen, welche Teile eines Texts passen.
Bilder auf dem Server bearbeiten
TYPO3 skaliert, beschneidet und wandelt Bilder auf dem Server um. Dafür ruft es GraphicsMagick oder ImageMagick auf. Die Systemanforderungen empfehlen GraphicsMagick, die Voreinstellung lautet ImageMagick. Programm und Pfad stehen im Bereich GFX in processor und processor_path. Für Bilder, die GIFBUILDER zeichnet, nutzt TYPO3 zusätzlich die PHP-Erweiterung gd.
Eine erzeugte Variante speichert TYPO3 im Ordner _processed_ und liefert sie beim nächsten Aufruf wieder aus. Das spart Rechenzeit.
Testen: Unter System, Environment erzeugt die Karte „Image Processing“ Testbilder und vergleicht sie mit Referenzbildern.
Dateien in TYPO3: FAL
FAL steht für File Abstraction Layer. Diese Schicht trennt die Dateiverwaltung von der physischen Ablage. Ein Speicher kann ein lokaler Ordner wie fileadmin sein. Über Treiber kann er auch bei einem Cloud-Dienst liegen. Dateien müssen also nicht in fileadmin liegen.
- Die Tabelle sys_file ist der Index. Sie beschreibt jede Datei genau einmal.
- Die Tabelle sys_file_metadata enthält Metadaten wie Titel und Alternativtext.
- Die Tabelle sys_file_reference hält jede Verwendung fest, etwa in einem Inhaltselement.
Ein Inhaltselement speichert also keinen Dateipfad als Text, sondern zeigt auf eine Referenz. Benennst du eine Datei im Backend um oder verschiebst sie, bleiben alle Inhalte gültig. In der Referenz kannst du Titel und Alternativtext je Verwendung überschreiben.
Am Backend vorbei: Mara ersetzt den Flyer für die Probestunde per FTP direkt in fileadmin. Im Backend stimmen danach Größe und Vorschaubilder nicht. Der FAL-Index ist veraltet, denn TYPO3 hat nichts mitbekommen. Die Scheduler-Aufgabe „File Abstraction Layer: Update storage index“ oder ein erneuter Upload bringt ihn wieder in Einklang. Dateien verschiebst du darum am besten im Modul Media.
Git: Versionen im Griff
Git ist ein System zur Versionskontrolle. Es speichert die Geschichte aller Dateien in einem Repository. So kannst du Änderungen nachvollziehen, zurücknehmen und zusammenführen.
git initlegt im aktuellen Verzeichnis ein neues Repository an.git clonekopiert ein bestehendes.git addmerkt Änderungen vor,git commitspeichert sie als neuen Stand.git pushschickt lokale Commits zum entfernten Repository, dem Remote.git pullholt Änderungen und führt sie zusammen.git fetchholt sie nur.
Branches: Ein Branch ist ein Entwicklungszweig, auf dem du getrennt vom Hauptzweig arbeitest. Mara baut das neue Kursprogramm auf einem eigenen Branch. Danach führt sie ihn per merge in den Hauptzweig zusammen.
Tags: Ein Tag markiert einen bestimmten Stand, etwa ein Release. Anders als ein Branch bewegt er sich nicht weiter.
git init -b main
git add .
git commit -m "Erste Fassung"
git remote add origin https://git.example.org/lindenau/site.git
git push -u origin main
git switch -c kursprogramm
git switch main
git merge kursprogramm
git tag v1.2.0Konflikte: Haben beide Branches dieselbe Stelle unterschiedlich geändert, meldet Git beim Merge einen Konflikt. Git kann nicht entscheiden, welche Änderung gilt. Mara löst ihn in den markierten Dateien, fügt sie mit git add hinzu und schließt den Merge mit einem Commit ab.
Was nicht ins Repository gehört: In die Datei .gitignore eines Composer-Projekts gehören typischerweise drei Ordner:
- Der Ordner
vendor, denn Composer erzeugt ihn aus der composer.lock. - Der Ordner
varmit Laufzeitdaten. - Der Ordner
public/fileadminmit den Dateien der Redaktion.
Ins Repository gehören dagegen composer.json, composer.lock, der Ordner config und das Sitepackage im Ordner packages. Zugangsdaten gehören nie hinein.
Das Wichtigste in Kürze
- Auf der Kommandozeile gibt es keinen Papierkorb. Verzeichnisse kopierst und löschst du rekursiv mit der Option r.
- Eine crontab-Zeile hat fünf Zeitfelder: Minute, Stunde, Tag, Monat, Wochentag. Für den Scheduler nennst du PHP mit vollem Pfad.
- Die Rechte r, w und x zählen 4, 2 und 1. TYPO3 setzt 0664 für Dateien und 2775 für Ordner.
- Der Webserver schreibt in var, fileadmin und typo3temp, nicht in vendor.
- Browser speichern 301, darum nutzt TYPO3 für automatische Redirects 307.
- Die Scheduler-Aufgabe anonymisiert IP-Adressen nach Tabelle, Frist und Stufe. Eigene Tabellen meldest du seit TYPO3 14 per TCA an.
- Bildvarianten liegen in _processed_ und werden wiederverwendet.
- FAL trennt Datei, Metadaten und Verwendung. Inhalte zeigen auf Referenzen, nicht auf Pfade.
- In die gitignore gehören vendor, var und fileadmin, nicht die composer.lock.
Begriffe
- Cronjob
- Befehl, den der Cron-Daemon nach einem Zeitplan startet.
- setgid-Bit
- Recht an einem Ordner, durch das neue Dateien die Gruppe des Ordners erben.
- Statuscode
- Dreistellige Zahl, mit der der Server das Ergebnis einer Anfrage meldet.
- IP-Anonymisierung
- Maskieren eines Teils der IP-Adresse, damit sie keiner Person mehr zuzuordnen ist.
- Regulärer Ausdruck
- Muster, das Text beschreibt und findet.
- FAL
- File Abstraction Layer, die Schicht zwischen TYPO3 und den Dateispeichern.
- Branch
- Entwicklungszweig in Git.
- Tag
- Feste Markierung eines Stands in Git.