.. -*- fill-column: 78; -*- .. include:: general.txt ##################################### Duden Korrekturserver: Administration ##################################### Lizenzierung ============= Der |DKS| verlangt zum Betrieb einen Lizenzschlüssel, der auf dem Server installiert werden muss. Lizenzschlüssel für den |DKS| können permanent oder temporär sein und haben im letzteren Fall ein Ablaufdatum, nach dem der Schlüssel nicht mehr akzeptiert wird. Um den Lizenzstatus des |DKSs| zu überprüfen, klicken Sie auf :menuselection:`Einstellungen --> Lizenz`, um die Lizenzinformationen anzuzeigen. Wenn kein gültiger Lizenzschlüssel installiert oder der Lizenzschlüssel abgelaufen ist, wird auf der Startseite des Servers eine entsprechende Nachricht eingeblendet: .. image:: images/static_DKS_LicenseMessage.png Durch einen Klick auf den Link in der Nachricht oder durch die Auswahl von :menuselection:`Einstellungen --> Lizenz` gelangen Sie zur Lizenzübersicht. Auf dieser Seite erhalten Sie einen Überblick über den aktuellen Lizenzstatus und haben die Möglichkeit, einen neuen Lizenzschlüssel zu installieren. .. image:: images/DKS_License.png :class: with-border .. note:: Die folgenden Abschnitte beziehen sich auf Installationen des |DKSs|, die **nicht** in einer Docker-Umgebung betrieben werden. In einer Docker- Umgebung empfehlen wir, die Datei mit dem Lizenzschlüssel außerhalb des Docker Containers zu speichern und sie dem Container über ein Docker-Volume zur Verfügung zu stellen. Einzelheiten hierzu finden sie im plattformspezifischen Installationshandbuch des |DKSs|. Zur Installation eines neuen Lizenzschlüssels speichern Sie diesen zunächst auf Ihrem Arbeitsplatz und betätigen dann die Schaltfläche zur Dateiauswahl. Navigieren Sie im Dateiauswahldialog zur Datei mit dem neuen Lizenzschlüssel und wählen Sie diese aus. Klicken Sie danach auf die Schaltfläche :guilabel:`Lizenz installieren`, um die Lizenzdatei auf den Server hochzuladen und zu installieren. Wenn dieser Vorgang erfolgreich war, erscheint die Startseite des Servers, wo eine entsprechende Nachricht eingeblendet wird. .. image:: images/static_DKS_LicenseInstalledMessage.png Falls der neue Lizenzschlüssel ungültig oder beschädigt sein sollte, wird der Schlüssel nicht installiert, und es erscheint nach dem Hochladen der Datei ein entsprechender Hinweis. .. image:: images/static_DKS_LicenseFailed.png Sie können in diesem Fall den Vorgang wiederholen. Bitte kontaktieren Sie EPC unter dpf-support@epc.de, falls die Schwierigkeiten bei der Installation eines Lizenzschlüssels andauern sollten. .. _usermgt: Benutzerverwaltung und Rechte ============================= Der |DKS| unterstützt seit Version 1.4 eine integrierte Benutzerverwaltung, die mit den Berechtigungen für einzelne Funktionen gekoppelt ist. Hierbei werden fünf Rollen mit unterschiedlichen Rechten unterschieden: * `api` erlaubt das Nutzen der API-Funktionen, ermöglicht aber keinen Zugriff auf die Web-Oberfläche des |DKSs|. * `Wörterbuch-Editor` erlaubt das Editieren bestehender Wörterbücher. * `Wörterbuch-Administrator` kann Wörterbücher und Korrektureinstellungen (Korrekturprofile) anlegen, modifizieren und löschen. * `Administrator` kann darüber hinaus weitere Benutzer anlegen oder löschen und Lizenzdateien installieren * `Super-Administrator` entspricht der Administrator-Rolle, kann aber weder neu angelegt noch gelöscht werden. .. note:: In der aktuellen Version gelten die Benutzerrechte lediglich für den Zugriff auf die Web-Oberfläche des |DKSs|. Der API-Zugriff wird zur Zeit global freigegeben oder auf Benutzer mit API-Rechten beschränkt, innerhalb der API-Funktionen aber nicht weiter differenziert! Im Auslieferungszustand ist ein Benutzer "duden" mit dem Passwort "duden" und der Rolle `Super-Administrator` angelegt. Es wird empfohlen, den Namen und das Passwort für diesen Benutzer unmittelbar nach der Installation zu ändern. ====== === ========= ======== ===== ======================================= anonym api WB-Editor WB-Adm. Adm. Berechtigung ====== === ========= ======== ===== ======================================= j j j j j Vorschläge anlegen n j j j j REST API nutzen n n j j j Testmöglichkeit für Korrektur nutzen n n j j j Wörterbucheinträge bearbeiten (erstellen, modifizieren,löschen) n n n j j Wörterbücher erstellen oder löschen, Wörterbuchinformationen bearbeiten n n n j j Korrekturprofile erstellen, bearbeiten oder löschen. n n n n j Benutzer hinzufügen, bearbeiten oder löschen ====== === ========= ======== ===== ======================================= Der Nutzer mit der Rolle `Super-Administrator` hat die gleichen Rechte wie Benutzer mit der Rolle `Administrator`, kann aber nicht gelöscht werden. Die Rolle `Super-Administrator` kann weder entzogen noch an einen anderen Benutzer vergeben werden. .. _internalroles: Interne Rollenhierarchie ------------------------ ============================= =========================================== Interner Rollenname DKS-Rolle und Anmerkung ============================= =========================================== IS_AUTHENTICATED_ANONYMOUSLY `anonym` (verbunden ohne Login) ROLE_USER keine (Login ohne weitere Rechte) ROLE_API `api` ROLE_WB_EDITOR `Wörterbuch-Editor` ROLE_WB_ADMIN `Wörterbuch-Administrator` ROLE_ADMIN `Administrator` ROLE_SUPER_ADMIN `Super-Administrator` ============================= =========================================== Bitte kontaktieren Sie EPC unter dpf-support@epc-de, wenn Sie weitergehende Anforderungen an die Benutzerverwaltung haben oder an einer Anbindung an ein bestehendes System interessiert sind. Sichern des API-Zugriffs ------------------------ Ab Version 1.5 des |DKSs| ist es möglich, den Zugriff auf das API des Servers auf Benutzer mit den Rechten `api` zu beschränken. Durch die Auswahl von :menuselection:`Einstellungen --> DKS-Einstellungen` gelangen Sie zu den Einstellungen des |DKSs|. .. image:: images/DKS_SecureApi.png :class: with-border Hier können Sie mit der Checkbox `API-Anfragen schützen` festlegen, ob der Zugriff auf das API die Authentisierung mit einem Benutzernamen und einem Passwort erfordert. .. note Diese Einstellung hat auch Einfluss auf die eingebaute Testmöglichkeit mit dem TinyMCE Plug-in. Wenn Sie nach der Sicherung des API-Zugriffs diese Testmöglichkeit weiterhin verwenden möchten, sind folgende Schritte notwendig: * Legen Sie einen Benutzer mit einem passenden Namen (z. B. `apiuser`) mit `api` Rechten und einem geeigneten Passwort (z. B. `yu9phuN4`) an. * Editieren Sie auf dem System mit dem |DKS| die Datei :file:`duden-correction-server-connector.php` im Verzeichnis :file:`/opt/epc/dks/public/js/tinymce-plugin/duden/php/`. Entfernen Sie dort die Kommentare vor den beiden Zeilen mit `DCS_USERNAME` und `DCS_PASSWORD` und ändern Sie die Werte auf den zuvor angelegten Benutzer und das zugeordnete Passwort:: $DCS_USERNAME = "apiuser"; $DCS_PASSWORD = "yu9phuN4"; .. todo Diese Ausführungen beziehen sich auf das Plug-in in Version 1.x. Ab DKS 1.8.0 wird die Version 2.x des Plug-ins verwendet. Dokumentation muss entsprechend angepasst werden! Vorschläge durch anonyme Benutzer --------------------------------- In der Standardeinstellung des |DKSs| ist es möglich, auf der Startseite ohne vorheriges Login Vorschläge für richtig geschriebene Wörter im Wörterbuch "Proposals" zu hinterlegen. Falls dieses Verhalten unerwünscht ist lässt es sich durch das Setzen der Umgebungsvariablen :envvar:`REQUIRED_ROLE_FOR_PROPOSALS` ändern. In der Standareinstellung wird für die Eingabe von Vorschläge die interne Rolle `IS_AUTHENTICATED_ANONYMOUSLY` vorausgesetzt, d. h. jeder Benutzer (vgl. :ref:`internalroles`), der die Startseite des |DKSs| aufrufen kann, kann einen Vorschlag hinterlegen. Damit nur authentifizierte Benutzer ab einer bestimmten Berechtigungsebene diese Funktion nutzen können, muss vor der Start des |DKSs| die Umgebungsvariable `REQUIRED_ROLE_FOR_PROPOSALS` auf den Namen der korrespondierenden internen Rolle gesezt werden, hier am Beispiel eines Docker-Containers mit `docker-compose`:: # file docker-compose.yml ... dks: ... environment: ... REQUIRED_ROLE_FOR_PROPOSALS: ROLE_USER Dieses Beispiel würde jedem Benutzer, der sich mit Benutzernamen und Passwort angemeldet hat, erlauben, neue Vorschläge einzugeben - ohne, dass dieser Benutzer über weitergehende Rechte verfügen muss. Analog lassen sich auch alle anderen internen Rollen verwenden, um die Möglichkeit des Hinterlegens von Korrekturvorschlägen weiter einzuschränken. Für das genaue Vorgehen in einer konkreten Installationsumgebung beachten Sie bitte die Informationen im systemspezifischen Installationshandbuch. Anzeige von Versions- und Statusinformationen --------------------------------------------- In der Standardeinstellung des |DKSs| werden auf der Startseite folgende Informationen angezeigt: * Versionummer des |DKSs| * Anzahl der angerabeiteten Check-Anfragen * Die Version der linguistischen Basis * Einen Link zum Plug-in Download Um zu erreichen, dass diese Informationen erst dann angezeigt werden, wenn sich ein Benutzer erfolgreich angemeldet hat, kann die Umgebungsvariable :envvar:`SHOW_VERSION_INFO_FOR_ANONYMOUS_USERS` auf den Wert `false` gesetzt werden. Hat diese Variable den Wert `true` oder ist sie nicht gesetzt, werden diese Informationen immer angezeigt. Beispiel eines Docker-Containers mit `docker-compose`:: # file docker-compose.yml ... dks: ... environment: ... SHOW_VERSION_INFO_FOR_ANONYMOUS_USERS: 'false' Dieses Beispiel würde sicherstellen, dass Informationen zur Serverversion, zur Anzahl der abgearbeiteten Anfragen, etc. erst nach dem Login angezeigt werden. Für das genaue Vorgehen in einer konkreten Installationsumgebung beachten Sie bitte die Informationen im systemspezifischen Installationshandbuch. Konfigurationsdateien ================================== Die Konfiguration der Dienste (Web Server apache2 , PHP Fast Process manager php-fpm, etc.) ist im systemspezifischen Installationshandbuch beschrieben. Logfiles ================================== .. note:: Die folgenden Abschnitte beziehen sich auf Installationen des |DKSs|, die **nicht** als Docker-Container betrieben werden. Für Docker-Container gilt, dass Log-Ausgaben auf die Standardausgabe des Containers erfolgen und dass mit den Standardmitteln (z. B. dem Kommando `docker logs`) darauf zugegriffen werden kann. Bedingt durch den modularen Aufbau des Duden Korrekturservers werden Log-Informationen an unterschiedlichen Stellen aufgezeichnet. * Log-Dateien des Web Servers Apache * Log-Dateien des FCGI Process Managers php5-fpm * Log-Dateien der Korrekturengine * Log-Dateien der Webapplikation Rotation der Log-Dateien ------------------------ Die geschriebenen Log-Dateien werden über den Standard-Mechanismus `logrotate` in zyklischen Abständen rotiert, wobei alte Log-Dateien gelöscht werden, um Plattenplatz einzusparen. Für den Web-Server und für php5-fpm werden die Standardeinstellungen verwendet. Eine eventuell erforderliche Anpassung kann in den Dateien :file:`/etc/logrotate.d/apache2` und :file:`/etc/logrotate.d/php5-fpm` vorgenommen werden. Für die Korrekturengine sind in der Datei :file:`/etc/logrotate.d/phdpf` folgende Einstellungen hinterlegt: :: /var/log/phdpf.log { daily rotate 4 delaycompress compress notifempty missingok copytruncate } Die Webapplikation speichert ihre Logs in :file:`/opt/epc/dks/var/log/` Für die Korrekturengine sind in der Datei :file:`/etc/logrotate.d/dks` folgende Einstellungen hinterlegt: :: /opt/epc/dks/var/log/*.log { daily rotate 4 delaycompress compress notifempty missingok copytruncate } Sicherung ================================== Der |DKS| speichert bzw. verändert keine lokalen Dateien, sondern speichert alle Informationen in einer MySQL-Datenbank. Für Backup und Restore eines |DKSs| werden daher nur die ursprünglichen Installationsquellen für den |DKS| und ein aktueller Dump der Datenbank benötigt. .. note:: Die folgenden Abschnitte beziehen sich auf Installationen des |DKSs|, die **nicht** in einer Docker-Umgebung betrieben werden. Für Docker-Umgebungen gilt, dass das Datenbanksystem nicht innerhalb des gleichen Containers laufen sollte wie der |DKS|. Backup und Restore der Datenbank sollten über geeignete Mechanismen erfolgen, die von Installation und Betrieb der Datenbank abhängen. Die Sicherung der Datenbank erfolgt nächtlich über einen cron-job, der einen vollständigen Dump der Datenbank in der Datei :file:`/opt/epc/dks/backup/dump.sql` hinterlegt. Die Datenbanksicherung wird wie die Log-Dateien über den logrotate-Mechanismus zyklisch rotiert. Dazu sind in der Datei :file:`/etc/logrotate.d/dksdb` folgende Einstellungen hinterlegt: :: /opt/epc/dks/backup/dump.sql { daily rotate 4 compress nocreate notifempty missingok } Bei der täglichen Rotation der Log-Dateien wird die Sicherungsdatei komprimiert. Nach erfolgter Rotation der Log-Dateien findet sich der jeweils aktuellste Dump der Datenbank in der Datei :file:`/opt/epc/dks/backup/dump.sql.1.gz` Rücksicherung ------------- Zur Rücksicherung ist die gewünschte Datei zunächst zu dekomprimieren. :: gunzip /opt/epc/dks/backup/dump.sql.1.gz Die dekomprimierte Datei kann dann als Eingabe für :command:`mysql` verwendet werden. Komfortabler geht es mit folgendem Shell-Script, das auch in der Datei :file:`/opt/epc/dks/scripts/restoredb.sh` hinterlegt ist:: #!/bin/bash # Script to restore the database from a dump file # This is meant to restore a database backup into an existing DKS database BASEDIR=/opt/epc/dks # default values for backup: Useful to answer the question "Where is my dump?" BACKUPDIR=$BASEDIR/backup BACKUPFILE=$BACKUPDIR/dump.sql PARMFILE=$BASEDIR/app/config/parameters.yml MYSQL=/usr/bin/mysql # get db partameters source $BASEDIR/.env.local DBNAME=$DATABASE_NAME USER=$DATABASE_USER PASS=$DATABASE_PASSWORD if [ $# -ne 1 ] ; then echo "Usage: $0 filename" echo "Restore database from file" exit fi BACKUPFILE=$1 if [ ! -r $BACKUPFILE ] ; then echo "Cannot read file $BACKUPFILE" exit fi echo "About to overwrite existing data base tables with contents of file" echo " $BACKUPFILE" echo "Press Enter to continue or CTRL-C to cancel" read echo -n "Restoring database..." $MYSQL -u $USER -p$PASS $DBNAME < $BACKUPFILE echo "done" Cron Jobs ===================== Für wiederkehrende Aufgaben sind auf dem Server mehrere cron jobs eingerichtet, die über Dateien im Verzeichnis :file:`/etc/cron.d` gesteuert werden. :: # /etc/cron.d/dksjobs: crontab fragment for dks # This removes orphanded cache entries and dumps the database PATH=/usr/sbin:/usr/sbin:/usr/bin:/sbin:/bin # at 03:37 every night: clean cache 37 3 * * * duden [ -x /opt/epc/dks/scripts/cleanup.sh ] && /opt/epc/dks/scripts/cleanup.sh # at 03:48 every night: dump database 48 3 * * * duden [ -x /opt/epc/dks/scripts/dumpdb.sh ] && /opt/epc/dks/scripts/dumpdb.sh Abschalten von Funktionen ========================= Um bei etwaigen Fehlfunktionen des Servers dessen Funktionen teilweise oder vollständig abschalten zu können, bestehen zwei Möglichkeiten: * Um bestimmte Worte von der Silbentrennung auszuschließen, lässt sich eine Ausnahmeliste solcher Worte anlegen. * Die gesamten Funktionen zur Rechtschreibprüfung und zur Silbentrennung lassen sich stilllegen. .. note:: Bitte benachrichtigen Sie EPC unter dpf-support@epc.de, falls Sie auf einen dieser Mechanismen zurückgreifen müssen. Ausschluss von der Silbentrennung ---------------------------------- Falls bestimmte Worte bei der Silbentrennung zu internen Serverproblemen führen sollten, lässt sich eine Liste solcher Worte anlegen. Worte, die in dieser Liste gefunden werden, werden nicht an die Funktionen zur Silbentrennung weitergeleitet. Um eine solche Liste anzulegen, kann eine Datei erstellt werden, die die auszuschließenden Wortformen enthält. In dieser Datei müssen die betroffenen Wörter jeweils auf einer einzelnen Zeile in richtiger Groß- und Kleinschreibung angegeben werden. Die Datei muss UTF-8 kodiert sein! In der Standardeinstellung wird nach einer solchen Datei unter :file:`/opt/epc/dks/etc/nohyph.txt` gesucht. Falls diese Datei existiert, wird die Liste der auszuschließenden Wörter beim Start des Servers eingelesen. Änderungen an dieser Liste erfordern einen Neustart des Services php-fpm, um wirksam zu werden. Dieses Verfahren ist eine Notfallmaßnahme, falls der unwahrscheinliche Fall eintreten sollte, dass bestimmte Wörter bei der Silbentrennung zu internen Serverfehlern führen. Die üblichen Informationen zur Silbentrennung können über Wörterbucheinträge zu den betreffenden Wörtern hinterlegt werden - durch Trenneinträge ohne Trennstellen kann auch die Trennung eines Wortes mit Wörterbucheinträgen verhindert werden. .. Abschalten des Check-APIs .. ------------------------- .. .. Es ist möglich, die Funktion des Check-APIs abzuschalten. In diesem Fall .. liefert jeder Aufruf ein formal richtiges Ergebnis ohne Korrektur- und .. Silbentrenninformationen - es ist somit möglich, Clients weiter zu betreiben, .. ohne die Fehlersituation auf der Client-Seite behandeln zu müssen. .. .. Das Check-API lässt sich über einen Parameter in der Konfigurationsdatei .. :file:`/opt/epc/dks/app/config/config.yml` abschalten. Hierzu ist der Wert .. des Parameters `server_disabled` auf `true` zu setzen. .. .. :: .. .. parameters: .. locale: en .. # Disabling the server in critical conditions: Change the value in .. # in following line to true to put the server in disabled mode - and do .. # not forget to set it back to false after the issue has been solved! .. server_disabled: false .. .. Diese Änderung erfordert einen Neustart des Services mit dem Kommando .. `sudo service php5-fpm restart`, um wirksam zu werden. .. Skalierung und Performanz ========================= Die Auslastung eines |DKSs| hängt von der der konkreten Nutzung und den verwendeten Funktionen ab. Es ist daher nicht ohne Weiteres möglich, pauschale Konfigurationsvorgaben zu machen. Wir empfehlen stattdessen, mit einer an Richtwerten orientierten Konfiguration zu beginnen, die Systemparameter zu überwachen und bei Bedarf nachzujustieren.