##################################################################################### Introduzione ##################################################################################### .. toctree :maxdepth: 2 :numbered: Flusso allarmi da Sanetd a Entables ===================================================================================== Quando un agente di monitoraggio nota una variazione di stato di una *condition* (da *down* a *up*, da *up* a *down*) invia a *Sanetd* le informazioni sulla variazione di stato. *Sanetd* analizza i dati, li storicizza e produce un *allarme* che viene consegnato ad *entables* per essere processato e inviato. In base alla configurazione *Entables* decide se ed in che modo consegnare l'allarme ricevuto, oppure *silenziarlo* (azione di *drop*). .. image:: ../../_static/web/images/sanetd_to_entables_alarms.png Formato degli allarmi ===================== Un *allarme* e' un pacchetto dati (in formato JSON) composto da diversi *campi/attributi* che contengono informazioni su: * ID dell'allarme * il tenant di riferimento * l'elemento a cui e' associato l'allarme (nodo, interfaccia, ecc.) * la condition che ha generato l'allarme e il suo stato corrente * Destinatario, soggetto e corpo del messaggio configurato nella condition. *Entables* puo' essere configurato per analizzare il contenuto di uno o piu' di questi *campi* e decidere di utilizzarli o meno per notificare l'allarme in diversi modi. Questo e' un esempio di messaggio JSON: :: { 'uuid': '2a0a23eaeab74b96a85b932877a77dfb' 'tenantid': '10a279a6ce5c4438a98f9c33c0b77cde', 'condition': { 'uuid': '7b87d0fc87a340bba6a5e1d9cf03a76d' 'name': 'reach', 'path': "localhost;;icmp-reachability;reach", 'priority': 1, }, 'datasources': [], 'element': { 'uuid': 'c3af80abb3104a2cad031b90e30efbdb' 'name': 'localhost', 'parent_id': None, 'parent_name': None, 'type': 1, }, 'event': { 'uuid': '37f99ce859534a959f82a07eeed2c728' }, 'flow-information': [], 'mail_data': { 'to' : "netwarning, 'subject': "Nodo down", 'body' : "Il nodo localhost e' down", 'headers': { "X-SANET-Target-Id" : "localhost;;icmp-reachability;reach", "X-SANET-Target-Status" : "DN", "X-SANET-Priority" : 1 } 'result': { 'laststatus': 100, 'status': 10, 'verbastatus': '' }, 'snmp_values': [], } Per analizzare il contenuto dei campi dell'allarme e' necessario configuare delle *regole*. Queste regole che contengono dei comandi, chiamati *match*, per estrarre i valori e analizzarli. (Vedi sezione :ref:`entables-matches`). **IMPORTANTE**: i campi presenti all'interno di un allarme e la loro organizzazione possono variare nel tempo. Per questo motivo un allarme deve essere analizzato utilizzando i *match* (comandi) messi a disposizione di entables. Notifica di default degli allarmi ================================= In assenza di configurazioni specifiche Sanet configura automaticamente (di default) Entables per inviare gli allarmi tramite protocollo SMTP (vedi anche :ref:`entables-appendix-default-config`). Parametri SMTP -------------- Alcune dei parametri SMTP necessari ( indirizzi recipient, indirizzo mittente, soggetto, corpo del messaggio ) vengono estratti dall'allarme. All'interno di un allarme esiste un campo (*mail_data*) che contiene diversi sotto-campi, ogniuno dei quali valorizzato partendo dal corrispondente campo della *condition* che ha generato l'allarme. Si faccia riferimento alla sezione :ref:`condition-fields`. +------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------+ | Campi | Descrizione | Campi della condition | +========================+========================================================================================+=======================================================+ | to | Stringa con i recipient dell'allarme. | mail / upemail | +------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------+ | subject | Stringa con il subject dell'allarme. | msg-downsubj o msg-upsubj | +------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------+ | body | Corpo del messaggio | msg-downbody o msg-upbody | +------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------+ | headers | Tuple opzionali con dati interni di sanet (per diagnostica) | - | +------------------------+----------------------------------------------------------------------------------------+-------------------------------------------------------+ Se i campi *to*, *subject*, *body* non contengono un valore (perche' la condition non e' stata configurata opportunamente) o contengono *stringa vuota* (""), Entables tenta comunque di inviare il messaggio in qualche modo. In caso di anomalie controllare nel log del'MTA Per conoscere i valori di default di tutti gli altri parametri utilizzati nella notifica tramite SMTP si rimanda alla sezione :ref:`target-SMTP`. Server MTA ---------- La configurazione di default prevede come *localhost* come server MTA locale, in ascolto sulla porta TCP 25. Recipient validi e aliases -------------------------- Poiche' Sanet si appoggia ad un server MTA per la notifica tramite email, il campo *to* di un allarme puo' essere valorizzato con un qualunque indirizzo email o alias valido. Per altri dettagli si rimanda alla sezione: :ref:`target-SMPT-invalid-recipients`. ##################################################################################### Regole di inoltro degli allarmi ##################################################################################### E' possibile decidere di compiere numerosi azioni sullo stesso *allarme* in base a piu' di una *regola*. Il sistema di regole per procesare una allarme e' organizzato/suddiviso in: * tabelle * catene * regole .. image:: ../../_static/web/images/entables_flow.png Tabelle ======================================= Le tabelle sono divisioni logiche delle operazioni (dette anche *regole*) che possono essere fatte sul ogni nuovo allarme. Le tabelle disponibili sono: +-----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | TABELLA | Descrizione | +===========+===================================================================================================================================================================================================================================================================================+ | mangle | In questa tablessa possono essere tutte le operazioni che cambiano l'allarme di partenza. Potra' essere utilizzata per arricchire un allarme con dati relativi alla sua gestione, o che riguardando la sua posizione, reperibili da fonti esterne | +-----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | correlate | In questa tabella vengono analizzate coorelazioni complesse sugli allarmi | +-----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | notify | In questa tabella si metteranno tutte le regole finali di notifica degli allarmi | +-----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Queste tabelle sono fisse e non e' possibile definire nuove tabelle. **NOTA**: La tabella *correlate* attualmente esiste, ma al momento non vengono fornite operazioni/regole di correlazione. **IMPORTANTE**: Non c'e' differenza tra le regole che possono essere inserite nelle tre tabelle. QUesto significa che invece di inserire regole nella tabella *notify* potrei mettere tutte le mie regole nella tabella *mangle*. Questa scelta e' sconsigliata poiche' e' preferibile tenere distinte operazioni che alterano gli allarmi (*mangle*) dalle operazioni che si occupano del semplice smistamento (*notify*). Attraversamento delle tabelle ----------------------------- Ogni volta che un allarme viene ricevuto, vengono consultate tutte e tre le tabelle rigorosamente nel seguente ordine: 1. mangle 2. correlate 3. notify E' possibile che un allarme venga *bloccato* da una regola in una qualunque di queste tabelle e che il suo attraversamento delle altre tabelle venga interrotto definitivamente. Entables, tenant e tabelle -------------------------- Ogni tenant ha le sue tabelle mangle/correlate/notify separate da quelle degli altri tenant. Un allarme generato da un controllo gestito in un tenant viene processato solo dalle tabelle del tenant di appartenenza. Non e' possibile processare allarmi di tenant diversi in tabelle comuni. Catene ======================================= Le *regole* all'interno di ogni tabella possono essere raggruppate in blocchi chiamate *catene*. Le catene sono raggruppamenti di *regole* che vengono *applicate* in sequenza per effettuare operazioni su un allarme. Ogni catena e' identificata in maniera univoca da un *nome* che deve essere unico all'interno della tabella di appartenenza. Ogni tabella contiene almeno una catena, chiamata *default* ed e' possibile configurare (*creare*) un numero illimitato di catene. Salto di catena --------------- E' possibile scrivere regole per far *saltare* un allarme da una catena ad un'altra. Quando un allarme passa da una catena ad un'altra il sistema ricorda in che punto della catena di partenza e' stato effettuato il salto. Quando (e se) l'allarme termina la sua traversata della nuova catena, riprende l'elaborazione nella catena di partenza, dalla regola immediatamente successiva a quella che aveva prodotto il salto. **NOTA**: e' possibile configurare salti in *cascata*. .. image:: ../../_static/web/images/entables_chains.png Esempio: allarmi in preperibilita. --------------------------------------- Se si vuole gestire in maniera particolari allarmi prodotti in alcune fasce orarie e' possibile procedere in due modi: 1) Specificare in tutte le regole dei parametri di *match* per filtrare gli allarmi in alcune fasce orarie. 2) Creare una *catena* con tutte le regole da applicare a tutti gli allarmi in alcune fasce orarie e creare una regola nella catena di *default* che smista gli allarmi di interesse alla nuova catena. Policy di default ----------------- Ogni catena contiene una azione (*target*) di default da eseguire sugli allarmi quando tutte le regole della catena sono state valutate. Configurazione -------------- CLI: Si rimanda alla sezione :ref:`entables-config-chains`. WEB: Questa parte della documentazione non e' ancora stata prodotta. Regole ======================================= Una regola rappresenta una *operazione* che e' possibile effettuare su un allarme. Una regola e' composta da due parti: 1. Un gruppo di *match*: filtri per indicare se la regola puo' essere applicata all'allarme. 2. Un *target*: l'azione vera e propria da eseguire sull'allarme (di solito un invio via mail) 3. Flag per indicare se l'allarme deve essere fermato quando la regola viene applicata. (*stop if match* flag) Se una regola non contiene nessun *match*, allora la regola viene sempre applicata all'allarme. Se una regola specifica uno o piu' match, il *target* viene eseguito _SOLO_ se l'allarme soddisfa tutti i *match*. Numeri e posizioni delle regole ------------------------------- Ogni regola e' identificata dalla sua posizione all'interno della *catena* di appartenenza. La prima posizione valida e' la posizione 1. Match ------------------ Esistono diversi tipi di match. Ogni match puo' accettare diverse opzioni per parametrizzare il tipo di filtro che un allarme deve soddisfare. Target ------------------ I target indicano le azioni da compiere su un allarme. Alcuni tipi di target accettano opzioni per parametrizzare il tipo di azioni da svolgere. Target di default ~~~~~~~~~~~~~~~~~ Esistono target predefiniti (di sistema) +--------------+-----------------------------------------------------------+ | Target | Descrizione | +==============+===========================================================+ | CONTINUE | procede con la prossima regola | +--------------+-----------------------------------------------------------+ | DROP | l'allame viene ignorato | +--------------+-----------------------------------------------------------+ | ENDTABLE | l'allarme salta alla prossima tabella | +--------------+-----------------------------------------------------------+ | RETURN | l'allarme ritorna dopo un salto | +--------------+-----------------------------------------------------------+ | | il flusso dell'allarme prosegue sulla catena specificata. | +--------------+-----------------------------------------------------------+ Per l'elenco completo dei target utilizzabili si rimanda alla sezione: :ref:`entables-available-targets`. **NOTA**: e' possibile configurare entables per utilizzare nuovi tipi di target implementati in base ad esigenze specifiche. Configurazione -------------- CLI: Si rimanda alla sezione :ref:`entables-config-rules`. WEB: Questa parte della documentazione non e' ancora stata prodotta. Flusso ============================================== Ogni allarme segue piu' o meno questo flusso: : :: sorgente dell'allarme (sanet) -> listener per sanet -> tabella mangle -> tabella correlate -> tabella notify -> alarm log. Se un allarme riceve un DROP, viene comunque loggato ##################################################################################### Configurazione di default ##################################################################################### In assenza di qualunque tipo di configurazione, il sistema aggiungere una sola regola alla catena NOTIFY per inviare gli allarmi tramite email. La configurazione di default e' la stessa che si otterrebbe con le seguenti operazioni: :: entables -F DEFAULT entables -A DEFAULT -j SMTP --smtp_rcpt_to '${mail_to}' --smtp_subject '${mail_subject}' --smtp_message '${mail_body}' ##################################################################################### Start / Stop ##################################################################################### Comandi di Start/Stop ============================ Entables viene gestito dagli script di stop/start di Sanet. Vedi :ref:`start-stop`. Log ======== Il file di log di entablesd e' salvato nella directory dei log di Sanet. Vedi :ref:`sanet-logs`.