Come utilizzare UptimeKuma per monitorare server e servizi web

Che siate gestori di un piccolo homelab o professionisti in cerca di uno strumento di monitoring affidabile e gratuito, UptimeKuma è senza dubbio un alleato prezioso da aggiungere al vostro arsenale.

Dalla prima commit sul progetto GitHub a Maggio 2021, UptimeKuma ha visto una crescita esponenziale, diventando rapidamente una delle soluzioni open source più apprezzate per il monitoraggio dell'uptime, arrivando ad avere 70'000 stelle su Github e un milione e mezzo di Pull dell'immagine Docker ufficiale.

Vediamo insieme come installare, configurare ed utilizzare UptimeKuma per monitorare al meglio i nostri servizi.

Prerequisiti

Per installare ed utilizzare UptimeKuma avrete bisogno di:

• Una macchina Linux, preferibilmente Ubuntu Server (per installazione da sorgente) o un'istanza di Docker (per installazione tramite Docker)
• Uno o più dispositivi, servizi o siti web da monitorare

Installazione

A seconda delle vostre esigenze, potete installare UptimeKuma tramite Docker, o come applicativo direttamente sul sistema operativo (in questa guida, useremo Ubuntu Server).

Al momento della scrittura di questo articolo, l'unico modo per installare la versione 2.0 di UptimeKuma è quella tramite Docker, che è anche la modalità consigliata dallo sviluppatore.

A. Installazione su Docker

• Create una cartella dedicata, che conterrà i file di configurazione di UptimeKuma. Per esempio, il comando seguente crea una cartella uptime-kuma nella root del filesystem.

mkdir /uptime-kuma

• Eseguite il seguente comando docker run per creare ed avviare il container

docker run -d \
  --restart=unless-stopped \
  -p 3001:3001 \
  -v /uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:1

B. Installazione da sorgente

(procedura testata su Ubuntu Server 24.04)

• Installate le dipendenze

sudo apt install git unzip

• Installate fnm, che è un gestore di versioni di Node.js

curl -o- https://fnm.vercel.app/install | bash

• Riavviate la shell di Ubuntu

source /home/ubuntu/.bashrc

• Scaricate ed installate Node.js (il runtime richiesto da UptimeKuma)

fnm install 20

• Verificate che quella che avete appena installato sia la versione 20 di Node.js

node -v # Dovrebbe restituire "v20.x.y".

• Verificate di avere installato la versione 20 di npm (il gestore di pacchetti di Node.js)

npm -v # Dovrebbe restituire "10.x.y".

• Scaricate ed installate UptimeKuma

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

• Avviatelo manualmente la prima volta

node server/server.js

• Potrebbe essere necessario aprire la porta 3001 TCP sul firewall di Ubuntu (di default, viene utilizzato iptables). Per farlo, eseguire i seguenti comandi:

sudo iptables -I INPUT -p tcp --dport 3001 -j ACCEPT
sudo netfilter-persistent save

• Controllate che non risultino errori

pm2 monit

• UptimeKuma dovrebbe quindi essere raggiungibile su
  http://ip.della.macchina.ubuntu:3001

Provate ad accedere alla pagina web e, se tutto funziona, potete impostare UptimeKuma per l'avvio automatico.

• Impostate l'avvio automatico di UptimeKuma all'avvio della macchina

pm2 save && pm2 startup

Utilizzo

Monitorare un server, un servizio o un sito web con UptimeKuma è davvero semplice, vediamo insieme alcuni esempi:

1. Monitorare un dispositivo (Client, Server, VM) tramite Ping (ICMP)

• Accedete ad UptimeKuma
• Premete su Aggiungi nuovo monitor in alto a sinistra

• In Modalità di monitoraggio selezionate Ping
• In Nome indicate il nome che volete dare al monitor (verrà indicato nell'interfaccia web e nelle notifiche)
• In Nome Host specificate l'indirizzo IP o l'FQDN del dispositivo da monitorare
• Nella barra di destra, alla sezione Notifiche, abilitate tutti i canali di notifica a cui deve essere inviato un messaggio per i cambiamenti di stato del monitor

Opzionalmente, potete modificare alcuni valori relativi alla frequenza dei controlli ed al numero di tentativi prima di segnalare un "Down":

• In Intervallo di controllo indicate ogni quanti secondi UptimeKuma deve pingare l'host
• In Tentativi, indicate quante volte riprovare a pingare l'host prima di segnalarlo come Offline (se impostate 0, alla prima mancata risposta verrà subito segnalato come Offline. Aumentate il numero di tentativi se ottenete troppi falsi positivi)
• In Intervallo tra i tentativi di controllo, indicate dopo quanti secondi effettuare un nuovo tentativo di ping quando il primo non è andato a buon fine

Infine, se avete tanti monitor diversi, potete categorizzarli in Gruppi ed assegnargli una o più Etichette

2. Monitorare un servizio web (HTTP e HTTPS)

Per monitorare un servizio web (una pagina di stato, una webapp, o anche un intero sito) è possibile selezionare HTTP(s).

Per i parametri principali da configurare, fate riferimento al punto precedente.

Il protocollo che verrà utilizzato per controllare il monitor deve essere indicato nel campo URL, ad esempio https://blog.firenetwork.it.

Se vi basta che l'endpoint risponda, anche se con un codice di errore, potete aggiungere al campo Codici di stato accettati i codici di stato HTTP che ritenete validi (di default, solo i codici da 200 a 299 vengono considerati validi).

Infine, potete personalizzare il Metodo della chiamata, il Body e gli Headers, così come il metodo di autenticazione, se richiesto.

3. Monitorare la risoluzione DNS

Per monitorare la risoluzione DNS di un dominio, selezionate la modalità di monitoraggio DNS.

Tramite questo monitor potrete controllare che un nome DNS venga risolto con successo, e monitorare il risultato della query per tenere traccia, per esempio, dei cambiamenti di puntamento di un DNS Dinamico come quelli del dominio duckdns.org .

I campi configurabili sono simili agli altri tipi di monitor, ma in questo caso dovrete specificare il dominio da risolvere nel campo Nome Host, ed il Server DNS da utilizzare per la risoluzione.

Inoltre potete specificare il tipo di record da cercare, come A (l'indirizzo IPv4), AAAA (l'indirizzo IPv6), CNAME (il nome canonico), MX (il mail exchanger), NS (il nameserver) o TXT (un record di testo associato all'FQDN).

Configurazione

Vediamo insieme qualche configurazione che vi consiglio fortemente di impostare per utilizzare al meglio UptimeKuma.

• Accedete all'interfaccia web di UptimeKuma
• In alto a destra, premete sull'icona del vostro profilo ed andate su Impostazioni

Nella sezione Generale:

• Configurate Fuso orario del server a UTC+02:00 per il fuso orario italiano
• Selezionate Automatico alla voce Mostra fuso orario
• In Visibilità ai motori di ricerca, se avete pubblicato UptimeKuma su internet, indicate Evita l'indicizzazione ai motori di ricerca
• Disattivate l'opzione Abilita la cache DNS per i monitor HTTP(s) in modo da monitorare anche gli errori dati dalla risoluzione dei nomi

Nella sezione Notifiche:

• Censite i vostri canali di notifica preferiti, come Email e Telegram

Vuoi creare un bot Telegram da impostare qui? Segui la mia guida:

Come creare un Bot Telegram

In questa guida vedremo insieme i passaggi per creare un bot Telegram personale, che potremo poi utilizzare per ricevere notifiche automatizzate da servizi come UptimeKuma o Apprise.

Firenetwork - BlogSamuele Gabbrielli

In Storico monitor:

• Indicate la retention dei dati storici. Più giorni di retention indicherete, più aumenteranno le dimensioni del DB di UptimeKuma col passare del tempo, perciò non esagerate.

In Sicurezza:

• Vi consiglio caldamente di abilitare l'autenticazione a due fattori (2FA)

Configurare lo scraping tramite Prometheus

• Accedete all'interfaccia web di UptimeKuma
• In alto a destra, premete sull'icona del vostro profilo ed andate su Impostazioni

• Andate alla sezione API Keys e premete su Add API Key

• Date un nome all'API Key che state creando (ad esempio, "Prometheus") e spuntate l'opzione Don't expire, poi premete su Generate e salvatevi la API Key appena generata.

Adesso possiamo andare a configurare il Job di Scraping su Prometheus

• Accedete tramite SSH alla vostra istanza di Prometheus
• Modificate il file prometheus.yml

sudo nano prometheus/prometheus.yml

• Aggiungete un nuovo job seguendo questo formato:

  - job_name: 'UptimeKuma'
    scrape_interval: 30s
    scheme: http
    static_configs:
      - targets: ['indirizzo.ip.di.uptimekuma:3001']
    basic_auth:
      password: api_key_di_uptimekuma

• Salvate il file e riavviate Prometheus

sudo systemctl restart prometheus

Adesso potrete utilizzare le metriche di UptimeKuma per creare grafici e dashboard su Grafana. Per esempio, per ottenere lo status dei vostri monitor, potete usare la metrica monitor_status e filtrare il monitor tramite il campo monitor_name.

Conclusioni

Adesso che avete installato e configurato UptimeKuma, potrete monitorare i vostri server, servizi e siti web in modo semplice ed efficace.

Come step successivo, potreste integrare le notifiche di UptimeKuma col vostro personale Bot Telegram, o esplorare la funzionalità Dashboards per creare una pagina di stato pubblica per far visualizzare a chiunque lo stato dei vostri servizi, come questa.