Custom Service Control

Il Custom Service Control (abbreviato CSC) è uno strumento che vi permette di gestire i vostri servizi su un Flex Server. Questi "Custom Service" possono essere, ad esempio, i backend per le applicazioni web o propri demoni con attività speciali. Con il framework CSC di Hostpoint è possibile configurare tali applicazioni in modo che queste, in caso di un riavvio del server, vengano arrestate automaticamente, chiuse in modo corretto e dopodiché riavviate.

Requisiti

Il CSC è disponibile a partire da Managed Flex Server M.

Quali funzioni offre il Custom Service Control?

• Potete avviare e arrestare applicazioni proprie come demone. Può trattarsi, ad esempio, di un’applicazione Node.js che è possibile integrare tramite la funzione proxy di NGINX.
• Il CSC può riconoscere e riavviare le applicazioni arrestate in modo anomalo. In questo caso è possibile far eseguire delle azioni tramite Event Listener, ad esempio inviare un’e-mail.
• Il CSC può occuparsi del logging e della rotazione dei log per la vostra applicazione. In questo modo mantenete sempre l’ordine nei log dell’applicazione.
• Il CSC può terminare correttamente le applicazioni e i custom service prima di un riavvio del server (ad es. in caso di aggiornamenti di sistema) e avviarli di nuovo non appena il server torna in funzione.

Panoramica sul framework Custom Service Control

Il CSC è composto da due componenti:

• Il tool hpservices che gestisce l’intero framework e attiva e controlla il supervisor service.
• Il servizio di supervisione Supervisord, che permette l'effettivo monitoraggio e controllo dei processi. Il Supervisord ampiamente diffuso viene utilizzato come servizio Supervisor.

Rapida panoramica sull’utility hpservices

L’utility hpservices è la centrale operativa per l’amministrazione del CSC. Questo strumento attiva, avvia e arresta il Supervisord e vi supporta nella configurazione di nuovi custom service.

Le funzioni più importanti in sintesi:

hpservices supervisord start

Avvia il Supervisord. Successivamente il vostro server verifica periodicamente (all’incirca ogni 60 secondi) se il Supervisord è in esecuzione. In caso negativo quest’ultimo viene avviato automaticamente. Al primo avvio del Supervisord viene creata la configurazione di base e viene attivato il Supervisord. Questo stato viene salvato. Dopo un riavvio del vostro server (ad es. in seguito a un aggiornamento) il Supervisord si riavvia con la configurazione da voi memorizzata.

hpservices supervisord stop

Arresta il Supervisord e tutte le sue applicazioni. Anche questo stato viene salvato fino a quando non riavviate il Supervisord.

hpservices supervisord status

Mostra se il Supervisord è in esecuzione o no.

hpservices supervisord restart

Arresta e riavvia il Supervisord. La configurazione viene letta nuovamente. Anche le applicazioni gestite da Supervisord vengono arrestate e riavviate. In questo modo è possibile testare se dopo un riavvio la configurazione completa ottiene il risultato desiderato.

hpservices supervisord add esempio1

Crea una struttura composta dalle directory necessarie e da un modello per la configurazione di Supervisord per il servizio esempio1.

hpservices supervisord remove esempio2

Rimuove le directory e la configurazione di Supervisord per il servizio esempio2.

hpservices supervisord list

Elenca tutte le applicazioni aggiunte con hpservices supervisord add.

Lavorare con il CSC

Nello stesso modo in cui la vostra applicazione viene eseguita come "Custom Service" sul vostro server, così il CSC è gestito sul vostro server e da lì viene anche controllato, configurato e utilizzato. Per utilizzare il CSC effettuate l’accesso al vostro server tramite SSH.

Avvio del Supervisord

Affinché sia possibile avviare, arrestare e gestire i vostri servizi con il CSC è necessario attivare il Supervisord sul vostro server. Al primo avvio vengono create le directory necessarie e una pratica configurazione iniziale.

hpservices supervisord start
supervisord successfully started

Con il sottocomando status è possibile accertarsi che il Supervisord funzioni:

hpservices supervisord status
supervisord is running as pid 1337

Se il Supervisord si arresta in modo anomalo o viene arrestato (kill) manualmente da voi, il CSC riavvia automaticamente il Supervisord con la configurazione da voi memorizzata e le vostre applicazioni. Se desiderate impedire la funzione del Supervisord, disattivate le applicazioni corrispondenti tramite supervisorctl (effetto temporaneo fino al successivo riavvio del Supervisord) o arrestate il Supervisord con l’utility hpservices (effetto permanente per tutte le applicazioni fino a quando viene avviato di nuovo con hpservices).

Arresto del Supervisord

Se desiderate disattivare le funzioni del CSC e del Supervisord, potete arrestare quest’ultimo.

hpservices supervisord stop
supervisord has been stopped

In questo modo vengono arrestati il Supervisord e tutte le applicazioni da esso avviate. Questo stato viene salvato. In altre parole, anche dopo un riavvio il Supervisord e le applicazioni eventualmente configurate non vengono avviate automaticamente.

Aggiunta di un nuovo servizio

Con l’esempio di un’applicazione "hellojs" mostriamo in che modo un’applicazione viene configurata come custom service.

Se desiderate gestire un’applicazione sotto la guida del CSC, è necessario aggiungerla alla configurazione di Supervisord. I dati di configurazione del Supervisord si trovano nella cartella ~/.services/supervisord/ nella vostra home (a tale proposito vedere anche la sezione "Appendice: Struttura dei file e delle directory" alla fine di questa guida). Il sottocomando hpservices supervisord add seguito dal nome dell'applicazione desiderato crea una struttura composta dalle directory necessarie e dalla configurazione di servizio per il Supervisord. La nostra applicazione esemplificativa hello.js si presenta quindi così:

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

Installazione dell’applicazione

Come Best Practice si consiglia di installare le applicazioni nella sottocartella ~/app/nome applicazione/. In questo modo mantenete la vostra home in ordine e vi assicurate che il codice sorgente delle applicazioni si trovi all’esterno della document root del server web. Naturalmente è possibile anche installare le applicazioni altrove nella home.

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

Configurazione come servizio Supervisord

Nella directory di configurazione del Supervisord l’utility hpservices ha creato una sottocartella per l’applicazione hello.js: ~/.services/supervisord/hello.js/. Al suo interno si trova una configurazione esemplificativa commentata utile come base iniziale per l’utente e una cartella "log" dove possono essere scritti i file di log standard output (stdout) e standard error (stderr) del proprio servizio (a tale proposito vedere anche la descrizione dettagliata delle opzioni di logging più in basso):

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

Nel file service.conf è possibile configurare il nuovo servizio, ovvero l’applicazione hellojs. Al suo interno si trova uno schema di proposte che possono essere adottate, adeguate o integrate. Le righe che iniziano con un punto e virgola (“;”) sono dei commenti e non sono considerate. Affinché Supervisord possa avviare un servizio, come configurazione minima sono necessari un blocco di program e un 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)

Opzioni di servizio

[program]

Nome del servizio. Viene utilizzato per gestire il servizio con il comando supervisorctl.

command

Il comando da utilizzare per l’avvio del servizio. Nel nostro esempio indichiamo l’interprete “/usr/local/bin/node”, il nostro programma “%(ENV_HOME)s/app/hellojs/start.js” e la porta “1234” che si aspetta come unico argomento la nostra app hellojs.

directory

Directory di lavoro del servizio. Prima dell’avvio dell’applicazione Supervisord "passa" in questa directory.

autostart

Se impostate questo valore su "false", il programma non viene avviato automaticamente all’avvio di Supervisord. Questa impostazione può essere utile, ad esempio, per lo sviluppo di servizi.

stopwaitsecs

Definisce il tempo massimo che Supervisord attende per terminare l’applicazione durante la procedura di arresto. Al termine di questo intervallo Supervisord forza la chiusura dell’applicazione (KILL).
Attenzione: aumentate questo valore solo se strettamente necessario. In questo modo aumentate il downtime del server in caso di interventi di manutenzione! Il tempo di attesa massimo possibile è di 120 secondi.

Opzioni di logging

Se il programma reagisce su standard output (stdout) o su standard error (stderr), è possibile registrare questa informazione in un file di log. Si tratta di una possibilità molto elegante per realizzare il logging per la vostra applicazione. È possibile infatti configurare Supervisord in modo che si occupi della corretta registrazione e della rotazione di questi log. In questo modo i vostri file di log saranno sempre ordinati. Le righe proposte e commentate contengono già pratiche impostazioni iniziali che possono essere facilmente adottate, se lo si desidera.

stdout_logfile

Definisce il percorso fino al file di log dello standard output.

stdout_logfile_maxbytes

Dimensioni massime di un file di log dello standard output. Al raggiungimento di queste dimensioni il file di log in uso viene archiviato e ne viene iniziato uno nuovo.

stdout_logfile_backups

Numero dei file di log archiviati dello standard output che vengono conservati.

stderr_logfile

Definisce il percorso fino al file di log dello standard error.

stderr_logfile_maxbytes

Dimensioni massime di un file di log dello standard error. Al raggiungimento di queste dimensioni il file di log in uso viene archiviato e ne viene iniziato uno nuovo.

stderr_logfile_backups

Numero dei file di log archiviati dello standard error che vengono conservati.

Per maggiori dettagli e ulteriori possibilità di configurazione dei propri servizi, fare riferimento alla documentazione ufficiale di Supervisord.

Avvio del nuovo servizio

Se la vostra applicazione è stata installata e testata e il relativo servizio è stato configurato nel Supervisord, potete ordinare al Supervisord di caricare la nuova configurazione. A tal fine vi sono diverse possibilità.

supervisord restart

La soluzione più semplice consiste nel riavviare il Supervisord. Allo stesso tempo, tuttavia, saranno riavviate anche tutte le applicazioni da esso gestite. Il vantaggio risiede nella possibilità di verificare contemporaneamente che l’intera configurazione CSC sia corretta e funzioni.

hpservices supervisord restart
supervisord has been stopped
supervisord successfully started

In alternativa, potete caricare manualmente la nuova configurazione con supervisorctl e attivare il nuovo servizio. Vi sono due diverse varianti:

supervisorctl update

Con il sottocomando update la configurazione di Supervisord viene caricata nuovamente e viene applicata. Viene quindi avviato automaticamente un nuovo servizio:

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

L’aggiunta con i sottocomandi reread e add è una soluzione più prudente. Con questa procedura è possibile prevedere quali modifiche verrebbero applicate in caso di un update, mentre con add è possibile eseguire queste modifiche in modo selettivo.

1. Leggere nuovamente la configurazione. Supervisord rileva che è disponibile un nuovo servizio e lo comunica:
   

   supervisorctl reread
   hellojs: available

   La nuova applicazione, tuttavia, non è ancora attiva:

   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. Aggiungere la nostra "hellojs" alle applicazioni in esecuzione:
   

   supervisorctl add hellojs
   hellojs: added process group

   Il nuovo servizio viene aggiunto e avviato automaticamente:

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

Best Practices

Affinché possiate gestire le applicazioni senza problemi e nel modo più affidabile possibile, si consiglia di attenersi alle seguenti best practice:

• Dalla vostra applicazione utilizzate i comandi stdout e stderr per generare messaggi di output e di errore e fate in modo che Supervisord si occupi della registrazione dei file di log, della loro rotazione e del riordino.
• Se la vostra applicazione genera automaticamente questi messaggi, specificate il luogo della loro registrazione al fine di facilitare la gestione dei file di log. Può trattarsi ad esempio di ~/app/appname/log/. Configurate un automatismo che consenta la rotazione e l’eliminazione regolare dei file di log. Grazie a una gestione attiva dei vostri log potete riconoscere i problemi e impedire che lo spazio web venga riempito di segnalazioni log fino a provocare il blocco dell’applicazione.
• Dopo ogni modifica della configurazione di Supervisord e sulla vostra applicazione, verificate che entrambe funzionino come desiderato. È possibile svolgere questa operazione riavviando l’intero framework CSC con il comando hpservices supervisord restart.
• Creare un indirizzo e-mail per i messaggi tecnici. In questo modo si viene informati nel caso in cui non sia stato possibile attivare il Supervisord a causa di un errore nella configurazione durante l’avvio del sistema.

Lavori con i servizi: supversisorctl

Le applicazioni configurate come servizio nel Supervisord possono essere gestite e controllate singolarmente e in tutta comodità con l’utility supversisorctl.

Se supversisorctl viene avviato tramite SSH, si presenta come una shell interattiva su cui è possibile richiamare direttamente i diversi sottocomandi.

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

La shell interattiva Supversiorctl supporta una forma semplice di completamento delle righe di comando con il tasto TAB (per eseguire una prova premere ad esempio la lettera "h" seguita dal tasto TAB o le lettere "st" e quindi due volte il tasto TAB). È disponibile anche una breve guida integrata:

Tutti i sottocomandi possono essere eseguiti anche in modo diretto senza l’utilizzo della modalità interattiva:

Istruzioni dettagliate sull’utilizzo e sulle possibilità di supervisorctl sono disponibili nella documentazione ufficiale relativa a Supervisorctl.

Esempio

La seguente sezione contiene una breve panoramica che descrive: l’ipotetico sviluppo di un’applicazione, in che modo supervisorctl può coadiuvare l’operazione e come utilizzare tale strumento.

Il seguente esempio mostra come continuare a sviluppare l’elemento hello.js precedentemente menzionato. Per effettuare il test in modo sicuro, è possibile realizzare una copia e creare un nuovo servizio: hellojs2. L’originale continua intanto ad essere utilizzato in modo attivo. Innanzitutto, avviamo l’applicazione hellojs2 non ancora modificata proprio come la nostra hellojs:

supervisor> start hellojs2
hellojs2: ERROR (spawn error)

Ops! Spiacenti, si è verificato un errore. Questo è visibile anche con il sottocomando status:

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)

La causa viene specificata nel file di log stderr creato da Supervisord:

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)

Esatto! Ricordatevi che in precedenza abbiamo già utilizzato la porta 1234 per l’app in funzione hellojs. Poiché su una porta TCP di un indirizzo IP può essere aperto solo un socket di ascolto, naturalmente la procedura fallisce: la porta è già occupata. Per risolvere il problema modifichiamo la riga di command nella configurazione di Supervisord di hellojs2 e selezioniamo un’altra porta libera:

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

Dopodiché possiamo caricare e attivare la nuova configurazione:

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

Il successivo tentativo di avvio va a buon fine e siamo pronti per iniziare lo sviluppo di hellojs2:

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

Ora possiamo riavviare liberamente la nostra nuova applicazione al fine di testare le modifiche:

supervisor> restart hellojs2
hellojs2: stopped
hellojs2: started

Prima o poi anche il programmatore più infaticabile si stanca. Arrestiamo quindi la nostra applicazione hellojs2 fino alla prossima sessione di sviluppo.

supervisor> stop hellojs2
hellojs2: stopped

Poiché nella configurazione di servizio di hellojs2 abbiamo impostato autostart su "false", ciò rimane invariato in modo affidabile.

Rimozione di un servizio

Se volete rimuovere dfinitivamente (cancellare) le applicazioni personalizzate, potete farlo con lo strumento hpservices e supervisorctl. In questo modo vengono eliminate sia la struttura delle cartelle con la relativa configurazione di Supervisord (~/.services/supervisord/esempio) sia la cartella con l’applicazione.

Pirma dovete terminare il servizio con il seguente comando:

supervisorctl stop ahoi.js

Poi usate lo strumento hpservices per togliere la configurazione:

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

Alla fine, rimuovere il servizio dal supervisore con il seguente comando:

supervisorctl remove ahoi.js

Disattivare un servizio invece di rimuoverlo

In alternativa, è possibile modificare la configurazione di Supervisord per questa app in modo che quest’ultima non sia più avviata automaticamente dal Supervisord. A tal fine modificate il valore di autostart su "false".

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

Se i servizi non più necessari non vengono eliminati ma disattivati, ricordate che la presenza di un software non più aggiornato sul proprio server rappresenta un potenziale rischio per la sicurezza. A volte, a causa di una disattenzione, si avvia di nuovo un software non aggiornato da anni. È consigliabile eseguire un backup dei dati e delle applicazioni non più necessari ed eliminarli dal server in funzione.

Appendice: Struttura dei file e delle directory

~/.services/supervisord/hostpoint.conf

File di configurazione principale di Supervisord

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

File di configurazione di servizio di Supervisord per il servizio myservice

~/.services/supervisord/myservice/log/

Directory per i file di log stdout e stderr del servizio myservice