Cosa fa questo modulo #

Un'istanza ha molte cose da raccontare: fail2ban ha bannato un IP, aide ha visto cambiare un file di sistema, il backup di stanotte è fallito, il disco root è al 95 %. Se ogni modulo avvisa a modo suo —una mail qui, una riga di log là— non se ne accorge nessuno, e con dieci istanze il problema si moltiplica per dieci.

Il modulo global-alerts è il bus centrale di alert di imaxe: un unico comando attraverso cui passano tutti quegli avvisi e un'unica destinazione a cui arrivano, un topic Amazon SNS condiviso da tutta la tua flotta. Da lì SNS smista come vuoi: mail, SMS, una funzione Lambda, una coda SQS, il tuo sistema di reperibilità. Pubblica con il ruolo IAM dell'istanza (permesso sns:Publish), quindi non c'è nessuna credenziale da conservare. E filtra il rumore prima di inviare: una soglia di severità scarta ciò che non raggiunge il livello che ti interessa e una finestra di deduplicazione evita che lo stesso alert ti svegli quaranta volte.

Se SNS non è disponibile —rete giù, ruolo ancora senza permessi, regione irraggiungibile— l'alert non si perde: viene messo in coda su disco e un timer di systemd lo ritenta ogni 5 minuti.

Prima di iniziare

Ti serve l'ARN di un topic SNS (arn:aws:sns:regione:account:topic) e che l'istanza possa pubblicarci. Se hai lanciato l'AMI dal launcher, il template di CloudFormation crea già il topic, iscrive la tua mail, crea il ruolo IAM con sns:Publish e passa l'ARN all'istanza come tag: il modulo si configura da solo e qui non c'è niente da fare.

Guida rapidaattività passo passo

Attività comuni #

Scegli cosa vuoi fare. Ogni ricetta porta il comando già scritto — cambia l'ARN e il testo con i tuoi, e premi Copia.

Impostare il topic SNS Inviare un alert di prova Inviare un alert da uno script Vedere lo stato del bus Abbassare il rumore Vedere la coda e ritentare Silenziare il modulo

1

Impostare il topic SNS

Di' all'istanza dove deve pubblicare i suoi avvisi.

Collegati via SSH al tuo server con l'utente ubuntu.

Punta il modulo all'ARN del tuo topic. La regione si deduce dall'ARN stesso, quindi di solito non serve indicarla:

terminale

$ sudo imaxe global-alerts configure \
    --topic-arn arn:aws:sns:eu-west-1:123456789012:imaxe-alerts

Più istanze che pubblicano sullo stesso topic? Dai a ognuna un'etichetta di origine riconoscibile con --source (di default si usa l'hostname):

terminale

$ sudo imaxe global-alerts configure --source web-produzione-1

La configurazione resta in /etc/imaxe/global-alerts.yml e l'invio è abilitato. Continua con la ricetta Inviare un alert di prova.

2

Inviare un alert di prova

Verifica che il ruolo IAM pubblichi davvero prima di fidarti del canale.

Pubblica un alert di prova sul topic configurato:

terminale

$ sudo imaxe global-alerts test

La prova salta la soglia e la deduplicazione —esce sempre— e, se qualcosa fallisce, ti restituisce l'errore reale di AWS invece di accodare in silenzio. Controlla la casella dell'indirizzo iscritto al topic (e la cartella spam).

Se vedi il MessageId e l'avviso ti arriva, il canale funziona. Se esce AuthorizationError, all'istanza manca il permesso sns:Publish su quel topic.

3

Inviare un alert da uno script

Lo stesso canale che usano i moduli, disponibile per le tue cose.

Un alert con la sua severità e la sua origine:

terminale

$ sudo imaxe global-alerts send --severity critical \
    --source backup --subject "backup fallito" \
    "il backup notturno del database è terminato con errore"

Se il testo lo genera un altro comando, passalo per stdin usando - come messaggio:

terminale

$ df -h / | sudo imaxe global-alerts send --severity warning -

In qualcosa che viene eseguito ogni pochi minuti, dagli una chiave di deduplicazione stabile: entro la finestra configurata uscirà solo il primo:

terminale

$ sudo imaxe global-alerts send --severity warning \
    --dedup-key disco-root-pieno "disco root al 95%"

L'alert viaggia come JSON verso il topic, con istanza, regione e marca temporale già incluse. Senza --dedup-key il modulo ne deriva una da origine + severità + oggetto.

4

Vedere lo stato del bus

Topic, regione, CLI di AWS e alert in attesa, a colpo d'occhio.

Riassunto dello stato attuale:

terminale

$ sudo imaxe global-alerts status

Per verificare quale configurazione comanda davvero —inclusa quella che arriva dai tag dell'istanza, che hanno priorità sul file—:

terminale

$ sudo imaxe global-alerts show
$ sudo imaxe global-alerts status --json

Saprai se c'è un topic configurato, in quale regione si pubblica e quanti alert aspettano in coda. Con --json, pronto per un pannello o uno script.

5

Abbassare il rumore

Alza la soglia di severità e allarga la finestra di deduplicazione.

Se vuoi sapere solo quello che conta, scarta tutto ciò che sta sotto warning:

terminale

$ sudo imaxe global-alerts configure --min-severity warning

La finestra di deduplicazione non ha flag: si regola nel file di configurazione. Alzala se uno stesso alert si ripete molto:

/etc/imaxe/global-alerts.yml

dedup_window: 1h   # 30s, 5m, 1h… (default 5m)

Gli alert sotto la soglia vengono scartati prima di uscire (non si accodano) e le ripetizioni entro la finestra vengono soppresse. test continua a pubblicare sempre, quindi non perdi il modo di verificare il canale.

6

Vedere la coda e ritentare

Cosa è rimasto in sospeso quando SNS non ha risposto, e come forzare l'invio.

Guarda cosa è in sospeso e le ultime chiavi inviate:

terminale

$ sudo imaxe global-alerts history

Il ritentativo lo fa già un timer di systemd ogni 5 minuti, ma puoi forzarlo dopo aver sistemato il permesso o la rete:

terminale

$ sudo imaxe global-alerts flush
$ systemctl status imaxe-global-alerts-flush.timer

Vedrai quanti sono usciti e quanti stanno ancora aspettando. Se il primo fallisce di nuovo, la passata si ferma lì e lascia il resto al tentativo successivo: non si scarta niente.

7

Silenziare il modulo

Smetti di pubblicare senza perdere la configurazione.

Disabilita l'invio di alert e togli il timer di ritentativo:

terminale

$ sudo imaxe global-alerts remove

Il topic, la regione e il resto delle impostazioni restano nel file: per riattivarlo basta un configure, che riabilita il modulo.

L'istanza smette di pubblicare. I send successivi non falliscono: avvisano su stderr che il modulo è disabilitato e terminano con codice 0.

Senza ruolo IAM non ci sono alert

Il modulo pubblica con le credenziali del ruolo dell'istanza, non con chiavi salvate. Se il ruolo non permette sns:Publish su quel topic, gli alert si accoderanno uno dopo l'altro senza arrivare mai. Un imaxe global-alerts test te lo dice sul momento, con l'errore così come lo restituisce AWS.

Riferimento CLIcomandi, flag e file

Sinossi #

uso

imaxe global-alerts <sottocomando> [--topic-arn ARN] [--severity LIVELLO] [flag]

Tutti i sottocomandi richiedono privilegi di root (usa sudo) perché scrivono in /etc/imaxe/, mantengono lo stato in /var/lib/imaxe/ e gestiscono un'unità di systemd. Non ci sono segreti da gestire: la pubblicazione passa dal ruolo IAM dell'istanza. Aggiungi --json a status, show, history o flush per ottenere output leggibile da una macchina.

Sottocomandi #

Sottocomando	Cosa fa	Flag rilevanti
status	Stato: topic configurato, regione effettiva, CLI di AWS disponibile e alert in coda.	--json
configure	Fissa il topic SNS e le opzioni di invio. Riabilita il modulo se era disabilitato.	--topic-arn, --region, --source, --min-severity
send	Pubblica un alert. È il canale che usano l'operatore e gli altri moduli.	--severity, --source, --subject, --dedup-key
test	Pubblica un alert di prova saltando soglia e deduplicazione, e riporta l'errore reale se fallisce.	--severity
show	Mostra la configurazione effettiva (file + tag dell'istanza già applicati).	--json
history	Alert in sospeso in coda e chiavi di deduplicazione inviate di recente.	--json
flush	Ritenta gli alert accodati. Lo esegue anche il timer di systemd.	--json
remove	Disabilita l'invio e toglie il timer. Conserva la configurazione.	—

Argomenti e flag #

Flag	Tipo	Default	Descrizione
--topic-arn obbl.	string	—	ARN del topic SNS di destinazione (`arn:aws:sns:regione:account:topic`). Senza di esso il modulo non può pubblicare.
--region	string	dall'ARN	Regione AWS. Se omessa, si deriva dall'ARN del topic; altrimenti da IMDS o da `AWS_REGION`.
--source	string	hostname	Etichetta di origine. In `configure`, quella dell'istanza; in `send`, quella di quel singolo alert (p. es. il modulo che lo emette).
--min-severity	string	info	Soglia: scarta gli alert sotto questo livello. Valori: `info`, `warning`, `critical`.
--severity	string	info	In `send`/`test`: livello di questo alert. Sono accettate le forme brevi `warn` e `crit`.
--subject	string	dal messaggio	Oggetto breve. Se omesso, si deriva dal messaggio stesso.
--dedup-key	string	derivata	Chiave di deduplicazione: sopprime le ripetizioni entro `dedup_window`. Di default si calcola con origine + severità + oggetto.
<messaggio> obbl.	posizionale	—	In `send`: il testo dell'alert, oppure `-` per leggerlo da `stdin`.
--json	bool	false	In `status`, `show`, `history` e `flush`, emette il risultato come JSON su `stdout`.

Scartare non è fallire

Quando un alert viene scartato —modulo disabilitato, severità sotto la soglia o duplicato entro la finestra— send lo spiega su stderr e termina con codice 0. Così lo script che l'ha emesso non si rompe per un filtro che hai configurato tu stesso.

Configurazione tramite tag dell'istanza #

Ogni deployment deve puntare al suo topic, e ricostruire l'AMI per questo non avrebbe senso. Per questo il modulo legge, oltre al file, i tag dell'istanza con prefisso imaxe.global-alerts. via IMDSv2: se esistono, vincono sul YAML. È quello che fa il template di CloudFormation del launcher, che inoltre richiede MetadataOptions.InstanceMetadataTags: enabled perché si possano leggere.

Tag	Equivale a	Valori
imaxe.global-alerts.topic_arn	topic_arn	ARN del topic SNS di destinazione.
imaxe.global-alerts.region	region	Regione AWS; vuota = si deriva dall'ARN o da IMDS.
imaxe.global-alerts.source	source	Etichetta di origine; vuota = hostname.
imaxe.global-alerts.min_severity	min_severity	`info` · `warning` · `critical`
imaxe.global-alerts.dedup_window	dedup_window	Durata: `30s`, `5m`, `1h`…
imaxe.global-alerts.enabled	enabled	`true`/`false` (anche `1`/`0`, `yes`/`no`, `on`/`off`).

Fuori da AWS, o con IMDS bloccato, la lettura fallisce in millisecondi e il modulo prosegue con quello che dice il file. Per vedere cosa è rimasto davvero attivo, imaxe global-alerts show.

File e percorsi #

Percorso	Contenuto
/etc/imaxe/global-alerts.yml	Configurazione del modulo: topic, regione, origine, soglia e finestra di deduplicazione.
/var/lib/imaxe/state/global-alerts/spool/	Coda degli alert in sospeso, uno per file `.json`, in ordine cronologico.
/var/lib/imaxe/state/global-alerts/sent.json	Registro delle chiavi di deduplicazione con l'ora dell'ultimo invio.
/etc/systemd/system/imaxe-global-alerts-flush.timer	Timer di ritentativo: parte 2 min dopo l'avvio e si ripete ogni 5 min.

Esempio di global-alerts.yml:

/etc/imaxe/global-alerts.yml

enabled: true
topic_arn: arn:aws:sns:eu-west-1:123456789012:imaxe-alerts
region: ""            # vuota = si deriva dall'ARN o da IMDS
source: ""            # vuota = hostname dell'istanza
min_severity: info
dedup_window: 5m

Lo stato (coda e registro di deduplicazione) vive in /var/lib/imaxe/ e non in /etc/ di proposito: è stato, non configurazione. Entrambi i percorsi si possono spostare con le variabili d'ambiente IMAXE_CONFIG_DIR e IMAXE_STATE_DIR.

Formato dell'alert #

Il corpo del messaggio SNS è JSON versionato (schema: 1), perché l'iscritto possa trattarlo con una Lambda o una coda oltre che leggerlo per mail:

corpo del messaggio

{
  "schema": 1,
  "severity": "critical",
  "source": "backup",
  "subject": "backup fallito",
  "message": "il backup notturno del database è terminato con errore",
  "host": "web-produzione-1",
  "instance_id": "i-0abc123def4567890",
  "region": "eu-west-1",
  "ts": "2026-07-25T03:14:07Z",
  "dedup_key": "9f2c1b7e44a0d513"
}

L'oggetto del messaggio SNS si compone come [imaxe][severità] host: oggetto, ripulito ad ASCII stampabile e tagliato a 100 caratteri, che è il limite imposto da SNS.

Codici di uscita e log #

Ogni esecuzione restituisce un codice che puoi verificare con echo $? — utile per concatenare negli script:

0OKOperazione completata. Anche quando l'alert viene scartato o accodato di proposito.

1ERRErrore generico: la prova non si è potuta pubblicare, oppure non si è potuta né pubblicare né accodare.

2USAGEArgomenti non validi: flag sconosciuto, messaggio mancante o severità non valida.

64NO TOPICNessun topic SNS configurato, né da file né da tag.

Il modulo risponde anche al controllo di salute di imaxe: se è abilitato ma senza topic, l'health fallisce, così un imaxe health lo smaschera prima che serva il primo alert.

terminale

$ sudo imaxe global-alerts test; echo "uscita: $?"
$ journalctl -u imaxe-global-alerts-flush.service -n 50

Risoluzione dei problemi #

Sintomo	Causa probabile	Soluzione
Esce NO TOPIC (codice 64)	Né il file né i tag portano un ARN di topic.	Lancia `configure --topic-arn …`, o controlla che l'istanza abbia il tag `imaxe.global-alerts.topic_arn` e i tag abilitati nei metadati.
«SNS non disponibile; alert accodato» in continuazione	Al ruolo dell'istanza manca `sns:Publish` su quel topic, o l'ARN è di un altro account o di un'altra regione.	Lancia `test` per vedere l'errore esatto di AWS, correggi la policy del ruolo e poi `flush`.
«CLI aws disponibile: false» nello status	L'istanza non ha la CLI di AWS installata; il modulo pubblica attraverso di essa.	Installa la CLI di AWS. Le AMI di imaxe la portano di serie; su un host tuo va aggiunta.
Configuri qualcosa e show continua a mostrare un altro valore	Un tag `imaxe.global-alerts.*` sta scavalcando il file: ha priorità per progetto.	Cambia il tag dell'istanza (o il parametro dello stack di CloudFormation) invece del YAML.
Arriva solo il primo di più alert uguali	La finestra di deduplicazione li sta sopprimendo.	È il comportamento previsto. Abbassa `dedup_window`, o usa `--dedup-key` diverse se sono davvero eventi distinti.
Non arriva niente e non ci sono errori	Il modulo è disabilitato, o la severità è sotto `min_severity`.	`show` ti mostra `enabled` e la soglia; `configure` riabilita l'invio.
Gli alert vengono pubblicati ma non ti arrivano per mail	L'iscrizione al topic SNS non è confermata.	Cerca la mail di conferma di AWS (controlla lo spam) e accetta l'iscrizione nella console SNS.

Bloccato con il modulo Alert?

Scrivici allegando l'output di «imaxe <module> status --json» e ti rispondiamo in fretta.

Contatta il supporto

Un unico punto da cui ascoltare tutta la tua flotta

Cosa fa questo modulo #

Attività comuni #

Impostare il topic SNS

Inviare un alert di prova

Inviare un alert da uno script

Vedere lo stato del bus

Abbassare il rumore

Vedere la coda e ritentare

Silenziare il modulo

Sinossi #

Sottocomandi #

Argomenti e flag #

Configurazione tramite tag dell'istanza #

File e percorsi #

Formato dell'alert #

Codici di uscita e log #

Risoluzione dei problemi #

Bloccato con il modulo Alert?