Custom Service Control

Die Custom Service Control (Abgekürzt CSC) ist ein Werkzeug, welches Ihnen ermöglicht, auf einem Flex Server eigene Dienste zu betreiben. Solche «Custom Services» können zum Beispiel Backends für Web-Applikationen oder eigene Daemons mit speziellen Aufgaben sein. Mit dem CSC Framework von Hostpoint können Sie solche eigenen Applikationen so einrichten, dass diese bei einem Server-Neustart automatisch gestoppt, sauber heruntergefahren und danach wieder gestartet werden.

Anforderungen

Die CSC steht Ihnen ab Managed Flex Server M zur Verfügung.

Welche Funktionen bietet ihnen die Custom Service Control?

• Sie können eigene Applikationen als Daemon starten und stoppen. Das kann zum Beispiel eine Node.js Applikation sein, welche Sie via Proxy-Funktion von NGINX einbinden.
• Die CSC kann abgestürzte Applikationen erkennen und neu starten. Über Event Listener können Sie in einem solchen Fall Aktionen ausführen lassen, z. B. ein E-Mail versenden.
• Die CSC kann sich um das Logging und um die Logrotation für Ihre Applikation kümmern. Damit haben Sie immer Ordnung in den Logs Ihrer Applikation.
• Die CSC kann Ihre Applikationen und Custom Services vor einem Neustart Ihres Servers (z. B. bei System-Updates) sauber beenden und wieder starten, sobald Ihr Server wieder läuft.

Übersicht über das Custom-Service Control-Framework

Die CSC setzt sich aus zwei Komponenten zusammen:

• Dem hpservices Tool, welches das gesamte Framework verwaltet und den Supervisor Service aktiviert und steuert.
• Dem Supervisor Service Supervisord, welcher die eigentliche Überwachung und Kontrolle der Prozesse erlaubt. Als Supervisor Service kommt der weit verbreitete Supervisord zum Einsatz.

Schnellübersicht über das hpservices Utility

Das hpservices Utility ist die Schaltzentrale zur Administration des CSC. Dieses Tool aktiviert, startet und stoppt den Supervisord und unterstützt Sie beim Einrichten von neuen Custom Services.

Die wichtigsten Funktionen in der Übersicht:

hpservices supervisord start

Startet den Supervisord. Ihr Server prüft danach periodisch (ungefähr alle 60 Sekunden), ob der Supervisord läuft. Falls er das nicht tut, wird er automatisch gestartet. Wenn Sie den Supervisord das erste Mal starten, wird die Grundkonfiguration angelegt und der Supervisord aktiviert. Dieser Zustand wird gespeichert. Nach einem Reboot Ihres Servers (z. B. nach einem Update) wird der Supervisord mit der von Ihnen hinterlegten Konfiguration wieder gestartet.

hpservices supervisord stop

Stoppt den Supervisord und all seine Applikationen. Dieser Zustand wird ebenfalls gespeichert, bis Sie den Supervisord wieder starten.

hpservices supervisord status

Zeigt an, ob der Supervisord läuft oder nicht.

hpservices supervisord restart

Stoppt und startet den Supervisord neu. Dabei wird die Konfiguration frisch eingelesen. Auch die von Supervisord verwalteten Applikationen werden gestoppt und neu gestartet. Sie können damit testen, ob Ihre Gesamtkonfiguration nach einem Neustart das gewünschte Ergebnis erzielt.

hpservices supervisord add beispiel1

Erstellt ein Skelett bestehend aus den benötigten Verzeichnissen und einer Vorlage für die Supervisord-Konfiguration für den Service beispiel1.

hpservices supervisord remove beispiel2

Entfernt die Verzeichnisse und die Supervisord-Konfiguration für den Service beispiel2.

hpservices supervisord list

Listet alle Applikationen auf, welche Sie mit hpservices supervisord add hinzugefügt haben.

Arbeiten mit der CSC

Genau so, wie Ihre Applikation als «Custom Service» auf Ihrem Server läuft, wird auch die CSC auf Ihrem Server betrieben und auch von dort aus gesteuert, konfiguriert und bedient. Um die CSC zu benützen loggen Sie sich per SSH auf Ihrem Server ein.

Starten des Supervisord

Damit Sie mit der CSC eigene Services starten, stoppen und verwalten können, müssen Sie den Supervisord auf Ihrem Server aktivieren. Beim ersten Start werden die benötigten Verzeichnisse und eine sinnvolle Initialkonfiguration erstellt.

hpservices supervisord start
supervisord successfully started

Mit dem status Subkommando können Sie sich vergewissern, ob Ihr Supervisord läuft:

hpservices supervisord status
supervisord is running as pid 1337

Sollte Ihr Supervisord abstürzen oder von Ihnen manuell gestoppt (gekillt) werden, startet die CSC den Supervisord mit der von Ihnen hinterlegten Konfiguration und Ihren Applikationen automatisch neu. Wenn Sie die Funktion des Supervisord unterbinden wollen, deaktivieren Sie entweder die entsprechenden Applikationen via supervisorctl (temporäre Wirkung bis zum nächsten Restart des Supervisord) oder stoppen Sie den Supervisord mit dem hpservices Utility (dauerhafte Wirkung für alle Applikationen, bis Sie ihn mit hpservices wieder starten).

Stoppen des Supervisord

Wenn Sie die Funktionen der CSC und des Supervisord deaktivieren möchten, können Sie diesen stoppen.

hpservices supervisord stop
supervisord has been stopped

Dabei wird der Supervisord und alle von ihm gestarteten Applikationen gestoppt. Dieser Zustand wird gespeichert. Das heisst, auch nach einem Neustart Ihres Servers werden der Supervisord und die allfällig konfigurierten Applikationen nicht automatisch gestartet.

Hinzufügen eines neuen Services

Am Beispiel einer «hellojs» Beispielapplikation zeigen wir, wie eine Applikation als Custom Service eingerichtet wird.

Wenn Sie eine eigene Applikation unter der Regie der CSC betreiben möchten, müssen Sie diese der Konfiguration von Supervisord hinzufügen. Die Konfigurationsdateien des Supervisord befinden sich im Ordner ~/.services/supervisord/ in Ihrem Home (sehen Sie dazu auch den Abschnitt «Anhang: Verzeichnis- und Datei-Struktur» ganz am Schluss dieser Anleitung). Das Subkommando hpservices supervisord add gefolgt von Ihrem gewünschten Applikationsnamen erstellt ein Skelett aus den notwendigen Verzeichnissen und der Service-Konfiguration für den Supervisord. Für unsere hellojs-Beispielapplikation sieht das so aus:

hpservices supervisord add hellojs
successfully created dir for hellojs: /home/username/.services/supervisord/hellojs
successfully created dir for hellojs: /home/username/.services/supervisord/hellojs/log
supervisord service config file written: /home/username/.services/supervisord/hellojs/service.conf

Installation der Applikation

Wir schlagen als Best Practice vor, dass Sie Ihre Applikationen im Unterordner ~/app/applikationsname/ installieren. So haben Sie eine saubere Ordnung in Ihrem Home und es ist sichergestellt, dass sich der Quellcode Ihrer Applikation ausserhalb des Document Roots Ihrer Webserver befinden. Selbstverständlich ist es aber auch möglich, Ihre Applikation an einem anderen Ort in Ihrem Home zu installieren.

cd app/hellojs

var express = require('express');
var app = express();
				
app.get('*', function (req, res) {
  res.send('Hello World!\n'.concat(process.argv[2],'\n'));
  console.log(req.method,req.url.concat('\n'),req.headers);
});
				
app.listen(process.argv[2], function () {
  console.log('Example app listening on port '.concat(process.argv[2],'!'));
});

ls
start.js
npm install express
ls
log     node_modules     package-lock.json     start.js

node start.js 1234
Example app listening on port 1234!
^C

Konfiguration als Supervisord Service

Das hpservices Utility hat im Konfigurationsverzeichnis des Supervisord einen Unterordner für unsere hellojs-Applikation erstellt: ~/.services/supervisord/hellojs/. Darin befindet sich eine auskommentierte Beispielkonfiguration als Ausgangspunkt für Sie sowie ein «log»-Ordner, wo die Standardausgabe (stdout) und Standardfehlerausgabe (stderr) Logfiles Ihres Services hingeschrieben werden können (sehen Sie dazu auch die detaillierte Beschreibung der Logging-Optionen weiter unten):

ls -l
total 8
drwxr-xr-x 2 username username 4096 Jan 22 17:45 log
-rw-r--r-- 1 username username 882 Jan 22 17:45 service.conf

In der Datei service.conf können Sie den neuen Service, die hellojs-Applikation, konfigurieren. Sie finden darin ein Gerüst aus Vorschlägen, die Sie übernehmen, anpassen oder ergänzen können. Zeilen, die mit einem Semikolon (";") beginnen, gelten als Kommentar und werden nicht berücksichtigt. Damit Supervisord einen Service starten kann, braucht es als Minimalkonfiguration einen program-Block und ein command:

[program:hellojs]
command=/usr/local/bin/node %(ENV_HOME)s/app/hellojs/start.js 1234 ; the program (can take args)
;directory=/home/username/app/hellojs/ ; directory to cwd to before exec (default no cwd)
;autostart=true ; start application at supervisord start (default: true)
;stopwaitsecs=10 ; max num secs to wait before SIGKILL (default 10)
;stdout_logfile=/home/username/.services/supervisord/hellojs/log/default.log
;stdout_logfile_maxbytes=1MB ; filesize at which to rotate logfiles (default ist 50MB)
;stdout_logfile_backups=10 ; number of stdout logfile backups (0 means none, default 10)
;stderr_logfile=/home/username/.services/supervisord/hellojs/log/default.err
;stderr_logfile_maxbytes=1MB ; filesize at which to rotate logfiles (default is 50MB)
;stderr_logfile_backups=10 ; number of stderr logfile backups (0 means none, default 10)

Service-Optionen

[program]

Name des Services. Dieser wird verwendet, um den Service mit dem Kommando supervisorctl zu verwalten.

command

Das Kommando, das zum Starten des Services verwendet werden soll. In unserem Beispiel geben wir den Interpreter "/usr/local/bin/node", unser Programm "%(ENV_HOME)s/app/hellojs/start.js" und als einziges Argument, welches unsere hellojs App erwartet, den Port "1234" an.

directory

Arbeitsverzeichnis des Services. Vor dem Starten der Applikation «wechselt» Supervisord in dieses Verzeichnis.

autostart

Wenn Sie diesen Wert auf «false» setzen, wird das Programm beim Starten von Supervisord nicht automatisch gestartet. Das kann zum Beispiel beim Entwickeln von Services nützlich sein.

stopwaitsecs

Definiert die maximale Zeit, die Supervisord beim Stopp-Vorgang auf das Beenden der Applikation wartet. Nach dem Verstreichen dieser Zeit beendet er die Applikation forciert (KILL).
Warnung: Erhöhen Sie diesen Wert nur bei dringend begründeter Notwendigkeit. Sie erhöhen damit die Downtime Ihres Servers bei Wartungsarbeiten! Die maximal mögliche Wartezeit beträgt 120 Sekunden.

Logging-Optionen

Wenn Ihr Programm Ausgaben auf der Standardausgabe (stdout) oder Standardfehlerausgabe (stderr) macht, können Sie diese in ein Logfile schreiben lassen. Dies ist eine sehr elegante Möglichkeit, das Logging für Ihre Applikation zu realisieren. Sie können nämlich Supervisord so konfigurieren, dass er sich um die saubere Buchhaltung und Rotation dieser Logs kümmert. So ist sichergestellt, dass Sie immer eine übersichtliche Ordnung mit Ihren Logfiles haben. Die vorgeschlagenen, auskommentierten Zeilen enthalten bereits sinnvolle Voreinstellungen, Sie können diese einfach übernehmen, wenn Sie wollen.

stdout_logfile

Definiert den Pfad zum Logfile der Standardausgabe

stdout_logfile_maxbytes

Die maximale Grösse eines Logfiles der Standardausgabe. Wird diese erreicht, wird das aktuelle Logfile archiviert und ein neues angefangen.

stdout_logfile_backups

Die Anzahl der archivierten Logfiles der Standardausgabe, welche aufbewahrt werden.

stderr_logfile

Definiert den Pfad zum Logfile der Standardfehlerausgabe

stderr_logfile_maxbytes

Die maximale Grösse eines Logfiles der Standardfehlerausgabe. Wird diese erreicht, wird das aktuelle Logfile archiviert und ein neues angefangen.

stderr_logfile_backups

Die Anzahl der archivierten Logfiles der Standardfehlerausgabe, welche aufbewahrt werden.

Details und weitere Möglichkeiten zur Konfiguration Ihrer Services entnehmen Sie der offiziellen Dokumentation von Supervisord.

Starten des neuen Services

Wenn Sie Ihre Applikation installiert und getestet sowie den dazugehörigen Service im Supvervisord konfiguriert haben, können Sie Ihren Supervisord anweisen, die neue Konfiguration einzulesen. Dazu gibt es verschiedene Möglichkeiten.

supervisord restart

Die einfachste Variante ist es, den Supervisord als Ganzes neu zu starten. Dabei werden jedoch auch alle von ihm verwalteten Applikationen neu gestartet. Der Vorteil davon ist, dass Sie damit gleich geprüft haben, ob Ihre CSC-Konfiguration als Ganzes korrekt ist und funktioniert.

hpservices supervisord restart
supervisord has been stopped
supervisord successfully started

Alternativ können Sie die neue Konfiguration manuell mit supervisorctl einlesen und den neuen Service aktivieren. Dabei gibt es zwei verschiedene Varianten:

supervisorctl update

Mit dem Subkomando update wird die Supervisord-Konfiguration frisch eingelesen und angewendet. Ein neuer Service wird damit automatisch gestartet:

supervisorctl
hello-world                   RUNNING     pid 11106, uptime 21:47:53
supervisor> update
hellojs: added process group
supervisor> status
hello-world                   RUNNING     pid 11106, uptime 21:47:59
hellojs                       RUNNING     pid 11105, uptime 21:47:59
supervisor>

supervisorctl reread & add

Etwas vorsichtiger ist das Hinzufügen mit den Subkommandos reread und add. Mit diesem Vorgehen können Sie vorher sehen, welche Änderungen bei einem update angewendet würden, und mit add können Sie diese selektiv ausführen.

1. Die Konfiguration neu einlesen. Dabei entdeckt Supvervisord, dass ein neuer Service verfügbar ist, und teilt das mit:

   supervisorctl reread
   hellojs: available

   Die neue Applikation ist damit jedoch noch nicht aktiv:

   supervisorctl status
   hello-moon                    RUNNING    pid 2408, uptime 0:11:36
   supervisorctl avail
   hello-moon                    in use     auto      999:999
   hellojs                       avail      auto      999:999

2. Unser «hellojs» zu den laufenden Applikationen hinzufügen:

   supervisorctl add hellojs
   hellojs: added process group

   Der neue Service wird hinzugefügt und automatisch gestartet:

   supervisorctl status
   hello-moon                    RUNNING     pid 2408,   uptime 0:11:36
   hellojs                       RUNNING     pid 234269, uptime 0:0:07

Best Practices

Damit Sie Ihre Applikationen möglichst zuverlässig und problemlos betreiben können, empfehlen wir Ihnen, sich an folgende Best Practices zu halten:

• Loggen Sie in Ihrer Applikation auf stdout und stderr und lassen Sie Supvervisord sich um das Schreiben der Logfiles, deren Rotation und das Aufräumen kümmern.
• Wenn Ihre Applikation selbst loggt, dann schreiben Sie bewusst an eine Stelle, die es Ihnen leicht macht, sich um die Bewirtschaftung Ihrer Logfiles zu kümmern. Das kann zum Beispiel ~/app/appname/log/ sein. Richten Sie einen Automatismus ein, der Ihre Logfiles regelmässig rotiert und löscht. Mit einem aktiven Bewirtschaften Ihrer Logs erkennen Sie Probleme und verhindern, dass Ihr Webspace womöglich bis zum Betriebskollaps mit Logmeldungen gefüllt wird.
• Prüfen Sie nach jeder Änderung Ihrer Supvervisord-Konfiguration und auch an Ihrer Applikation, ob sich beide wie von Ihnen gewünscht verhalten. Das können Sie zum Beispiel tun, indem Sie das ganze CSC-Framework mit hpservices supervisord restart restarten.
• Legen Sie eine E-Mail-Adresse für technische Nachrichten an. Damit werden Sie informiert, falls Ihr Supervisord aufgrund eines Fehlers in Ihrer Konfiguration beim Systemstart nicht aktiviert werden konnte.

Arbeiten mit den Services: supervisorctl

Die Applikationen, die Sie als Service im Supervisord eingerichtet haben, können Sie mit dem supervisorctl-Utility bequem einzeln manipulieren und steuern.

Wenn Sie sie per SSH supervisorctl starten, präsentiert es sich Ihnen als interaktive Shell, auf der Sie die verschiedenen Subkommandos direkt aufrufen können.

supervisorctl
hello-world                   RUNNING    pid 11106, uptime 0:00:03
hellojs                       RUNNING    pid 11105, uptime 0:00:03
hellojs2                      STOPPED    Not started
supervisor>

Die interaktive Supervisorctl Shell unterstützt eine einfache Form von Befehlszeilenergänzung mit der Tabulatortaste (zum Ausprobieren drücken Sie zum Beispiel den Buchstaben «h» gefolgt von der Tabulatortaste oder die Buchstaben «st» und danach zweimal die Tabulatortaste). Auch eine kleine eingebaute Hilfe gibt es:

Alle Subkommandos können Sie aber auch direkt ausführen, ohne den interaktiven Modus zu benützen:

Eine ausführliche Anleitung zum Umgang und zu den Möglichkeiten von supervisorctl finden Sie in der offiziellen Dokumentation zu supervisorctl.

Beispiel

Im folgenden Abschnitt laden wir Sie auf einen kleinen Rundgang ein. Wir möchten Ihnen einen Eindruck vermitteln, wie es beim (Weiter-)Entwickeln einer Applikation zu und her gehen könnte, wie Sie supervisorctl dabei unterstützt und wie Sie dieses Werkzeug einsetzen können.

In unserem Beispielszenario möchten wir unser oben vorgestelltes hellojs weiterentwickeln. Um ungestört testen zu können, haben wir eine Kopie davon angefertigt und einen einen neuen Service angelegt: hellojs2. Das Original befindet sich derweilen weiter im produktiven Einsatz. Als Erstes möchten wir die noch unveränderte hellojs2-Applikation genau gleich wie unser hellojs starten:

supervisor> start hellojs2
hellojs2: ERROR (spawn error)

Oha! Leider gab es einen Fehler. Mit dem status Subkommando ist das ebenfalls ersichtlich:

supervisor> status
hello-world                   RUNNING    pid 11106, uptime 0:20:52
hellojs                       RUNNING    pid 11105, uptime 0:20:52
hellojs2                      FATAL      Exited too quickly (process log may have details)

Im stderr-Logfile, das wir Supervisord für uns schreiben lassen, finden wir auch den Grund dafür:

tail -18 .services/supervisord/hellojs2/log/default.err
Error: listen EADDRINUSE: address already in use :::1234
    at Server.setupListenHandle [as _listen2] (net.js:1290:14)
    at listenInCluster (net.js:1338:12)
    at Server.listen (net.js:1425:7)
    at Function.listen
(/home/username/app/hellojs2/node_modules/express/lib/application.js:618:24)
    at Object.<anonymous> (/home/username/app/hellojs2/index.js:14:5)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)
Emitted 'error' event at:
    at emitErrorNT (net.js:1317:8)
    at process._tickCallback (internal/process/next_tick.js:63:19)
    at Function.Module.runMain (internal/modules/cjs/loader.js:745:11)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:743:3)

Richtig! Wir erinnern uns: Weiter oben haben wir den Port 1234 bereits für die produktive hellojs-App verwendet. Da auf einem TCP-Port einer IP-Adresse nur ein einziges Listening Socket geöffnet werden kann, schlägt das natürlich fehl: Der Port ist schon besetzt. Um das Problem zu beheben, passen wir die command Zeile in der Supervisord-Konfiguration von hellojs2 an und wählen einen anderen, freien Port:

command=/usr/local/bin/node /home/username/app/hellojs2/index.js 1235 ; the program (relative uses PATH, can take args)

Danach können wir die neue Konfiguration einlesen und aktivieren:

supervisor> update
hellojs2: stopped
hellojs2: updated process group
supervisor> status
hello-world                   RUNNING    pid 11106, uptime 0:20:02
hellojs                       RUNNING    pid 11105, uptime 0:20:02
hellojs2                      STOPPED    Not started

Der nächste Startversuch klappt nun und wir sind bereit, mit der Weiterentwicklung von hellojs2 zu starten:

supervisor> start hellojs2
hellojs2: started
supervisor> status
hello-world                   RUNNING    pid 11106, uptime 0:20:52
hellojs                       RUNNING    pid 11105, uptime 0:20:52
hellojs2                      RUNNING    pid 21305, uptime 0:00:04

Jetzt können wir unsere neue Applikation nach Belieben neu starten, um Änderungen zu testen:

supervisor> restart hellojs2
hellojs2: stopped
hellojs2: started

Irgendwann ist auch der aufgeweckteste Programmierer müde. Dann stoppen wir unsere hellojs2-Applikation bis zur nächsten Entwicklungssession.

supervisor> stop hellojs2
hellojs2: stopped

Und weil wir in der Service-Konfiguration von hellojs2 autostart auf «false» gesetzt haben, bleibt das auch zuverlässig so.

Entfernen eines Services

Wenn Sie eigene Applikationen dauerhaft entfernen (löschen) möchten, können Sie dies mit dem hpservices-Tool und supervisorctl erledigen. Dabei werden die Ordnerstruktur mit der entsprechenden Supervisord-Konfiguration (~/.services/supervisord/beispiel) und der Ordner mit der Applikation gelöscht.

supervisorctl stop ahoi.js

Dann mit dem hpservices-Tool die Konfiguration entfernen:

hpservices supervisord remove ahoi.js
Are you sure to delete the service in the following directory with all its content?
/home/username/.services/supervisord/ahoi.js
Are you sure? (y/n): y
successfully removed service ahoi.js
Are you sure to delete the application directory with all its content?
/home/username/app/ahoi.js
Are you sure? (y/n): y
successfully removed application directory ahoi.js

Und schliesslich den Service mit dem folgenden Befehl von supervisor entfernen:

supervisorctl remove ahoi.js

Service deaktivieren anstatt entfernen

Alternativ können Sie die Supvervisord-Konfiguration für diese App so anpassen, dass der Supervisord diese nicht mehr automatisch startet. Ändern Sie dazu den Wert von autostart auf «false».

autostart=false          ; start at supervisord start (default: true)

Wenn Sie nicht mehr benötigte Services deaktivieren, anstatt sie zu löschen, bedenken Sie bitte, dass nicht mehr gepflegte Software auf Ihrem Server ein potenzielles Sicherheitsrisiko für Sie darstellt. All zu plötzlich ist die seit Jahren nicht mehr aktualisierte Software aufgrund einer Unachtsamkeit wieder gestartet. Fertigen Sie besser ein Backup von nicht mehr benötigten Daten und Applikationen an und löschen Sie diese von Ihrem produktiven Server.

Anhang: Verzeichnis- und Datei-Struktur

~/.services/supervisord/hostpoint.conf

Die Supervisord-Hauptkonfigurationsdatei

~/.services/supervisord/myservice/service.conf

Die Supervisord-Service-Konfigurationsdatei für den Service myservice

~/.services/supervisord/myservice/log/

Das Verzeichnis, für die stdout- und stderr-Logfiles des Services myservice