Come Scrivere e Gestire File di Unità Systemd Personalizzati in Modo Efficace

I file di unità systemd personalizzati trasformano un comando che funziona nel tuo terminale in un servizio che il sistema operativo può avviare, fermare, riavviare, registrare e supervisionare. La differenza è importante. Un comando in una shell eredita il tuo ambiente e termina quando la sessione finisce. Un servizio ha un utente esplicito, una directory di lavoro, una politica di riavvio, dipendenze, limiti di risorse e log.

Questo è il percorso pratico che uso per piccole API interne, worker, script sidecar e demoni occasionali: scrivere l'unità corretta più semplice, eseguirla come utente dedicato, lasciare che i log vadano al journal, e aggiungere direttive avanzate solo quando appare un requisito reale.

Comprendere i File di Unità Systemd

Systemd gestisce varie risorse di sistema, note come unità, definite da file di configurazione. Queste unità includono servizi (.service), punti di mount (.mount), dispositivi (.device), socket (.socket) e altro. Per la gestione di applicazioni e processi in background, il tipo di unità .service è il più comune e rilevante.

I file di unità systemd sono file di testo semplice tipicamente memorizzati in directory specifiche. Le posizioni principali, in ordine di precedenza, sono:

/etc/systemd/system/: Questa è la posizione raccomandata per file di unità personalizzati e override, poiché hanno la precedenza sulle impostazioni predefinite di sistema e persistono attraverso gli aggiornamenti di sistema.
/run/systemd/system/: Utilizzato per file di unità generati a runtime.
/usr/lib/systemd/system/: Contiene file di unità forniti dai pacchetti installati. Non modificare i file in questa directory direttamente.

Posizionando i tuoi file di unità personalizzati in /etc/systemd/system/, ti assicuri che siano correttamente riconosciuti e gestiti da systemd.

Anatomia di un File di Unità `.service`

Un file di unità .service di systemd è strutturato in diverse sezioni, ciascuna denotata da [NomeSezione], contenente varie direttive (coppie chiave-valore). Le tre sezioni principali per un'unità di servizio sono [Unit], [Service] e [Install].

Analizziamo le direttive più cruciali che utilizzerai:

Sezione [Unit]

Questa sezione contiene opzioni generiche sull'unità, la sua descrizione e le dipendenze.

Description: Una stringa leggibile dall'uomo che descrive il servizio. Appare nell'output di systemctl status.
```
Description=My Custom Python Web Application
```
Documentation: Un URL che punta alla documentazione del servizio (opzionale).
```
Documentation=https://example.com/docs/my-app
```
After: Specifica che questa unità dovrebbe avviarsi dopo le unità elencate. Aiuta a gestire l'ordine di avvio. Per applicazioni web, potresti volerti assicurare che la rete sia attiva.
```
After=network.target
```
Requires: Una dipendenza forte. Se l'unità richiesta non si avvia, questa unità non si avvierà. Se l'unità richiesta viene fermata, anche questa unità potrebbe essere fermata.
```
Requires=docker.service
```
Wants: Una dipendenza più debole. Se l'unità desiderata fallisce o non viene trovata, questa unità tenta comunque di avviarsi. Di solito è un'impostazione predefinita migliore di Requires.
```
Wants=syslog.target
```

Sezione [Service]

Questa sezione definisce i parametri di esecuzione per il tuo servizio, inclusi come si avvia, si ferma e si comporta.

Type: Definisce il tipo di avvio del processo. Critico per come systemd monitora il tuo servizio.
- simple (predefinito): Il comando ExecStart è il processo principale del servizio. Systemd considera il servizio avviato immediatamente dopo l'invocazione di ExecStart. Si aspetta che il processo venga eseguito indefinitamente in primo piano.
- forking: Il comando ExecStart crea un processo figlio e il genitore esce. Systemd considera il servizio avviato una volta che il processo genitore esce. Usalo se la tua applicazione si demonizza.
- oneshot: Il comando ExecStart è un processo una tantum che esce quando ha finito. Utile per script che eseguono un compito e terminano (ad esempio, uno script di backup).
- notify: Simile a simple, ma il servizio dice a systemd quando è pronto. Richiede il supporto dell'applicazione per le notifiche systemd.
- idle: Il comando ExecStart viene eseguito solo quando tutti i lavori sono finiti, ritardando l'esecuzione fino a quando il sistema è quasi inattivo.
```
Type=simple
```
ExecStart: Il comando da eseguire quando il servizio si avvia. Questa è la direttiva più importante in questa sezione. Usa sempre il percorso assoluto del tuo eseguibile o script.
```
ExecStart=/usr/bin/python3 /opt/my_app/app.py
```
ExecStop: Il comando da eseguire quando il servizio viene fermato (opzionale). Se non specificato, systemd invia SIGTERM ai processi.
```
ExecStop=/usr/bin/pkill -f 'my_app/app.py'
```
ExecReload: Il comando da eseguire per ricaricare la configurazione del servizio (opzionale).
```
ExecReload=/bin/kill -HUP $MAINPID
```
User: L'account utente sotto il quale verranno eseguiti i processi del servizio. Essenziale per la sicurezza; evita root a meno che non sia assolutamente necessario.
```
User=myappuser
```
Group: L'account di gruppo sotto il quale verranno eseguiti i processi del servizio.
```
Group=myappgroup
```
WorkingDirectory: La directory di lavoro per i comandi eseguiti.
```
WorkingDirectory=/opt/my_app
```
Restart: Definisce quando il servizio dovrebbe essere riavviato automaticamente.
- no (predefinito): Non riavviare mai.
- on-success: Riavvia solo se il servizio esce correttamente.
- on-failure: Riavvia solo se il servizio esce con un codice di stato non zero o viene ucciso da un segnale.
- always: Riavvia sempre il servizio, indipendentemente dallo stato di uscita.
```
Restart=on-failure
```
RestartSec: Quanto tempo attendere prima di riavviare il servizio (ad esempio, 5s per 5 secondi).
```
RestartSec=5s
```
Environment: Imposta variabili d'ambiente per i comandi eseguiti.
```
Environment="APP_ENV=production" "DEBUG=false"
```
EnvironmentFile: Legge le variabili d'ambiente da un file. Ogni riga dovrebbe essere KEY=VALUE.
```
EnvironmentFile=/etc/default/my_app
```
LimitNOFILE: Imposta il numero massimo di descrittori di file aperti consentiti per il servizio (ad esempio, 100000). Importante per applicazioni ad alta concorrenza.
```
LimitNOFILE=65536
```

Sezione [Install]

Questa sezione definisce come il servizio viene abilitato per avviarsi automaticamente all'avvio.

WantedBy: Specifica l'unità target che "vuole" questo servizio. Quando l'unità target è abilitata, questo servizio verrà collegato simbolicamente nella sua directory .wants, rendendolo effettivamente avviato con il target.
- multi-user.target: Il target standard per la maggior parte dei servizi server, che indica un sistema con login multiutente non grafici.
- graphical.target: Per servizi che richiedono un ambiente grafico.
```
WantedBy=multi-user.target
```
RequiredBy: Simile a WantedBy, ma una dipendenza più forte. Se il target è abilitato, anche questa unità è abilitata, e se questa unità fallisce, anche il target fallirà.

Per la maggior parte dei servizi personalizzati destinati a funzionare in background su un server, Type=simple e WantedBy=multi-user.target sono il punto di partenza giusto. Se l'applicazione si demonizza già, disabilita quel comportamento o usa Type=forking con cautela. Un processo in primo piano è più facile da supervisionare per systemd.

Passo-passo: Creare e Gestire un Servizio Systemd Personalizzato

Creiamo un esempio pratico: un semplice server HTTP Python che serve file da una directory specificata. Lo configureremo come servizio systemd.

Passo 1: Preparare la tua Applicazione/Script

Prima, crea lo script dell'applicazione. Per questo esempio, useremo un semplice server HTTP Python. Crea una directory per la tua applicazione, ad esempio /opt/my_app, e posiziona app.py al suo interno.

# /opt/my_app/app.py

import http.server
import socketserver
import os

PORT = int(os.environ.get("PORT", 8000))
DIRECTORY = os.environ.get("DIRECTORY", os.getcwd())

class Handler(http.server.SimpleHTTPRequestHandler):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, directory=DIRECTORY, **kwargs)

print(f"Serving directory {DIRECTORY} on port {PORT}")

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("Server started.")
    httpd.serve_forever()

Crea la directory e il file:

sudo mkdir -p /opt/my_app
sudo nano /opt/my_app/app.py

(Incolla il codice Python)

Assicurati che lo script sia eseguibile (opzionale per il comando python3, ma buona pratica):

sudo chmod +x /opt/my_app/app.py

Considera la creazione di un utente dedicato per il tuo servizio per ragioni di sicurezza:

sudo useradd --system --no-create-home myappuser

Imposta la proprietà appropriata per la directory della tua applicazione:

sudo chown -R myappuser:myappuser /opt/my_app

Passo 2: Creare il File di Unità

Ora, crea il file di unità systemd per la nostra applicazione Python. Lo chiameremo my_app.service.

sudo nano /etc/systemd/system/my_app.service

Incolla il seguente contenuto:

# /etc/systemd/system/my_app.service

[Unit]
Description=My Custom Python HTTP Server
Documentation=https://github.com/example/my_app
After=network.target

[Service]
Type=simple
User=myappuser
Group=myappuser
WorkingDirectory=/opt/my_app
Environment="PORT=8080" "DIRECTORY=/var/www/html"
ExecStart=/usr/bin/python3 /opt/my_app/app.py
Restart=on-failure
RestartSec=10s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Nota: Abbiamo impostato StandardOutput=journal e StandardError=journal per indirizzare l'output del servizio al journal di systemd, rendendo facile visualizzare i log con journalctl.

Se la tua app ha bisogno di segreti, evita di metterli direttamente nel file di unità. Usa un file di ambiente con permessi restrittivi, un gestore di segreti o un supporto per credenziali specifico della distribuzione. I file di unità sono spesso leggibili da più persone di quanto ti aspetti.

Passo 3: Posizionare il File di Unità

Come indicato, abbiamo posizionato il file di unità in /etc/systemd/system/. Questa è la posizione in cui dovrebbero risiedere i file di unità personalizzati.

Passo 4: Ricaricare il Demone Systemd

Dopo aver creato o modificato un file di unità, systemd deve essere informato delle modifiche. Questo viene fatto ricaricando il demone systemd:

sudo systemctl daemon-reload

Passo 5: Avviare il Servizio

Ora puoi avviare il tuo servizio:

sudo systemctl start my_app.service

Passo 6: Controllare lo Stato del Servizio e i Log

Verifica che il tuo servizio sia in esecuzione correttamente:

systemctl status my_app.service

Esempio di output (troncato):

● my_app.service - My Custom Python HTTP Server
     Loaded: loaded (/etc/systemd/system/my_app.service; disabled; vendor preset: enabled)
     Active: active (running) since Tue 2023-10-26 10:30:00 UTC; 5s ago
       Docs: https://github.com/example/my_app
   Main PID: 12345 (python3)
      Tasks: 1 (limit: 1100)
     Memory: 6.5M
        CPU: 45ms
     CGroup: /system.slice/my_app.service
             └─12345 /usr/bin/python3 /opt/my_app/app.py

Oct 26 10:30:00 yourhostname python3[12345]: Serving directory /var/www/html on port 8080
Oct 26 10:30:00 yourhostname python3[12345]: Server started.

Per visualizzare i log del servizio, usa journalctl:

journalctl -u my_app.service -f

Questo comando mostra i log per my_app.service e -f (follow) mostrerà nuovi log in tempo reale.

Puoi anche testare il server dal tuo browser o con curl su http://localhost:8080 (supponendo che /var/www/html esista e contenga alcuni file).

Passo 7: Abilitare il Servizio per l'Avvio Automatico

Per far sì che il tuo servizio si avvii automaticamente ogni volta che il sistema si avvia, devi abilitarlo:

sudo systemctl enable my_app.service

Questo comando crea un collegamento simbolico da /etc/systemd/system/multi-user.target.wants/my_app.service a /etc/systemd/system/my_app.service.

Passo 8: Fermare e Disabilitare il Servizio

Per fermare un servizio in esecuzione:

sudo systemctl stop my_app.service

Per impedire a un servizio di avviarsi automaticamente all'avvio (lasciandolo abilitato per essere avviato manualmente):

sudo systemctl disable my_app.service

Se vuoi rimuovere completamente il servizio, prima disable lo, poi stop lo, e infine elimina il file .service da /etc/systemd/system/ ed esegui sudo systemctl daemon-reload.

Passo 9: Aggiornare un Servizio

Se modifichi il tuo script app.py o il file di unità my_app.service, dovrai aggiornare systemd e riavviare il servizio:

Modifica /opt/my_app/app.py o /etc/systemd/system/my_app.service.
Se hai modificato il file di unità, esegui sudo systemctl daemon-reload.
Riavvia il servizio: sudo systemctl restart my_app.service.

Pattern Più Sicuri per Servizi Reali

Un'unità che funziona non è sempre un'unità che vuoi mantenere per anni. Questi pattern prevengono errori comuni:

Esegui in primo piano. Lascia che systemd supervisioni il processo principale. Evita nohup, screen, tmux, & in background o modalità demone dell'applicazione all'interno di ExecStart.
Mantieni ExecStart diretto. Se hai bisogno di funzionalità della shell come pipe o espansione di variabili, chiama /bin/sh -c '...' intenzionalmente. Altrimenti, esegui l'eseguibile direttamente.
Usa un utente dedicato. Un servizio che deve solo leggere /opt/my_app e associarsi a una porta non privilegiata non dovrebbe essere eseguito come root.
Ricarica dopo modifiche all'unità. sudo systemctl daemon-reload è richiesto quando il file di unità cambia.
Separa i deploy del codice dalle modifiche all'unità. Se solo il codice Python è cambiato, riavvia il servizio. Se l'unità è cambiata, ricarica prima systemd.

Risoluzione dei Problemi di una Nuova Unità

Se il servizio fallisce, inizia con:

systemctl status my_app.service
journalctl -u my_app.service -n 100 --no-pager
systemctl cat my_app.service

I fallimenti comuni sono di solito semplici:

status=203/EXEC spesso significa che il percorso dell'eseguibile è sbagliato, il file manca o il file non è eseguibile.
Permission denied di solito significa che l'utente del servizio non può leggere un file, entrare in una directory, scrivere log o associarsi alla porta richiesta.
address already in use significa che un altro processo possiede la porta. Controlla con sudo ss -tulpen | grep ':8080'.
Un servizio che si avvia manualmente ma fallisce sotto systemd spesso dipende da variabili d'ambiente, una directory di lavoro diversa o file nella tua home directory.

Puoi testare il comando come utente del servizio:

sudo -u myappuser /usr/bin/python3 /opt/my_app/app.py

Questa non è una riproduzione perfetta dell'ambiente di systemd, ma cattura errori evidenti dell'applicazione prima di inseguire dettagli del file di unità.

Una Variante Più Adatta alla Produzione

Per un servizio interno a lunga esecuzione, di solito aggiungerei alcune protezioni:

[Unit]
Description=My Custom Python HTTP Server
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=myappuser
Group=myappuser
WorkingDirectory=/opt/my_app
EnvironmentFile=-/etc/my_app/my_app.env
ExecStart=/usr/bin/python3 /opt/my_app/app.py
Restart=on-failure
RestartSec=10s
TimeoutStopSec=30s
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ReadWritePaths=/opt/my_app /var/log/my_app
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

ProtectSystem=full rende gran parte del sistema in sola lettura per il servizio, quindi aggiungi ReadWritePaths= solo per le directory in cui l'app deve effettivamente scrivere. Testa l'indurimento una direttiva alla volta. Le opzioni di sicurezza sono utili, ma un servizio che non può leggere la sua configurazione o scrivere i suoi dati fallirà all'avvio.

Migliori Pratiche e Risoluzione dei Problemi

Percorsi Assoluti: Usa sempre percorsi assoluti per ExecStart, WorkingDirectory e qualsiasi altro percorso di file all'interno del tuo file di unità. I percorsi relativi possono portare a comportamenti imprevisti.
Utenti Dedicati: Esegui i servizi sotto account utente non privilegiati e dedicati (ad esempio, myappuser) per migliorare la sicurezza e limitare i potenziali danni in caso di compromissione.
Registrazione Chiara: Utilizza StandardOutput=journal e StandardError=journal per indirizzare l'output del servizio al journal di systemd. Usa journalctl -u <nome_servizio> per visualizzare i log.
Dipendenze: Considera attentamente After, Wants e Requires per assicurarti che il tuo servizio si avvii nell'ordine corretto rispetto alle sue dipendenze (ad esempio, rete, database).
Test delle Modifiche: Prima di abilitare un servizio per l'avvio all'avvio, testalo accuratamente avviandolo e fermandolo manualmente. Controlla il suo stato e i log.
Limiti di Risorsa: Usa direttive come LimitNOFILE, LimitNPROC e MemoryMax quando il servizio ha limiti noti o modalità di fallimento.
Variabili d'Ambiente: Usa Environment= o EnvironmentFile= per valori di configurazione che potrebbero cambiare o variare tra ambienti, piuttosto che codificarli nel file di unità o nello script.
Gestione degli Errori negli Script: Assicurati che gli script della tua applicazione gestiscano gli errori con garbo. Un codice di uscita non zero attiverà Restart=on-failure.

Avvertenza: Evita di modificare i file di unità direttamente in /usr/lib/systemd/system/. Qualsiasi modifica verrà probabilmente sovrascritta dagli aggiornamenti dei pacchetti. Usa /etc/systemd/system/ per unità personalizzate o override.

Una buona unità personalizzata è noiosa nel modo migliore: il comando è esplicito, l'utente è non privilegiato, il comportamento di riavvio è intenzionale e i log sono facili da trovare. Una volta che questo è solido, i timer di systemd, l'attivazione dei socket e i controlli più profondi dei cgroup sono passi naturali successivi.