.. _web-tagging: ################################################################################ Tagging ################################################################################ .. contents:: Contenuti Introduzione ================================================================================ I tag sono un sistema di *etichette* di classificazione per catalogare tutti gli elementi definiti di Sanet. Un tag quindi e' composto da due informazioni principali: * una *stringa* puramente informativa, detta anche *nome* del tag. * una descrizione. Ad un tag possono essere associati: * altri tag, chiamati sotto-tag o sub-tag * elementi del monitoraggio (nodi, interfacce, storage, ecc...) Questa struttura di associazioni (ricorsiva) permette di definire "alberi" di tag e sub-tag chiamati *tagtree*. .. digraph:: prova tag1 -> tag2; tag2 -> tag3; tag2 -> tag4; tag5 -> tag6; tag5 -> tag7; tag8 -> tag9; Organizzazione ad albero di tag: tag e tagtree ================================================================================ Il tagtree e' una entita' puramente logica utilizzata per poter associare a tutti i tag dello stesso *albero* le stesse proprieta (il proprietario, i permessi, ecc.). Un tagtree puo' avere un solo tag come radice, chiamato *root tag* o *root*. Una volta definito un tag radice e' possibile definire ricorsivamente un numero illimitato di sotto-tag. A ogni tag dell'albero e' possibile associare gli elementi di monitoraggio. .. digraph:: prova node [fontsize="8"]; subgraph tree1 { "Tree1" [shape=box]; Servizi ; Posta ; Web ; "Tree1" -> Servizi; Servizi -> Posta; Servizi -> Web; } "node1" [shape=box]; "node2" [shape=box]; "node3" [shape=box]; Posta -> node1 [style=dotted]; Posta -> node2 [style=dotted] Web -> node2 [style=dotted]; Web -> node3 [style=dotted]; Pagina principale e vista dei tag ------------------------------------------------------------------------------------ Nella pagina principale di un *tenant* sono visibili tutti e soli i tag radice di tutti i *tagtree* visibili dall'utente che si sta utilizzando. .. image:: ../_static/web/pages/tags_roots.png :width: 640px Visibilita di tagtree e gruppi utenti ------------------------------------------------------------------------------------ Si distinguino due tipologie di tagtree: * **tagree di sistema**: Non sono associati a nessun utente. * **tagree definiti dall'utente** : Sono tagtree create dagli utenti via web. Tagree utente ~~~~~~~~~~~~~ I tagtree utente sono visibili all'utente che li ha creati. Se l'utente vuole rendere visibile il tagtree a tutti gli altri utenti dei gruppi di cui lui fa parte deve esplicitare questa configurazione. .. _CLI_CONFIG_TAGS: Configurazione Web ------------------------------------------------ Per creare nuovi tag bisogna accedere alla lista dei tag nella spalla a sinistra e cliccare sul pulsante "Aggiungi Tag": .. image:: ../_static/web/pages/tags_list.png :width: 640px Inserire ii dati di creazione del tag e le autorizzazioni necessarie: .. image:: ../_static/web/pages/tags_create.png :width: 640px Configurazione CLI ------------------------------------------------ La definizione di tagtree e tag avviene utilizzando gli omonimi comandi 'tagtree' e 'tag'. :: tagree tag ... exit exit Le gerarchie di tag vengono definite utilizzando ricorsivamente il comando 'tag'. :: tagtree geo tag Globale tag Bologna tag Muratori exit exit exit exit Per cancellare un intero tree si usa il comando: :: no tagtree Per cancellare tag si usa il comando: :: no tag Rename dei tag ================================================================================ E' possibile cambiare il nome logico di *tagtree* e *tag*. Configurazione WEB --------------------------------------- Questa funzionalita' non e' al momento disponibile via interfaccia web. Configurazione CLI --------------------------------------- Per rinominare un tagtree: :: rename tagtree Esempio: :: conf t rename tagree geo geographic Per rinominare un tag all'interno di un tagree si deve entrare nella sezione di configurazione del tagree (al livello del tag di interesse) ed usare il comando: :: rename tag Esempio: :: conf t tagree geo tag Global rename tag Bologna City exit exit Tagging (Assegnamento) manuale di nodi ai tag ================================================================================ Quando si associa un elemento o una condition ad un tag, si sta *taggando* l'elemento. Il *tagging* puo' essere: * **diretto** L'elemento da taggare e tutti i suoi sotto-elementi (interfacce, datagroup, condition, ecc.) vengono automaticamente taggati. **QUESTA E' LA MODALITA' DI DEFAULT** **IMPORTANTE**: sotto-elementi aggiunti successivamente vengono taggati ricorsivamente in maniera automaticamente. * **indiretto** Un elemento viene taggato perche' figlio di un elemento taggato indirettamente. Questa operazione deve essere esplicitata manualmente ogni volta. Configurazione WEB --------------------------------------- Per associare un elemento di monitoraggio ad un tag bisogna fare *drag & drop* dell'elmento sull'icona del tag. Configurazione CLI --------------------------------------- Taggare ~~~~~~~ Per assegnare un elemento all'interno di un tag i comandi sono i seguenti: :: node exit interface exit storage exit service exit device exit condition Esempi ~~~~~~~ Esempio di configurazione di un tree: :: tagtree tree1 tag tag1 tag tag2 storage mason root exit exit tag tag3 condition foo::datagroup:check explosive group 1 condition bar::datagroup:check explosive group 1 condition bob::datagroup:check explosive group 2 condition adam::datagroup:check explosive group 2 exit interface xha eth0 exit node mason exit condition xha;;prova exit exit Assegnamento automtico di nodi ai tag (flag all-nodes) ================================================================================ E' possibile configurare il sistema per assegnare automaticamente un nodo ad un tag all'interno di un tag tree secondo regole configurabili. Per fare questo deve essere attivato il flag *all nodes* di tagtree (vedi :ref:`CLI_CONFIG_TAGS`. ). **IMPORTANTE**: L'assegnamento automatico funziona solo in fase di creazione di un nuovo nodo. Se il nodo viene rinominato successivamente rimane taggato ai tag gia' assegnati. Configurazione WEB ------------------------------------------------------------------ Questa funzionalita' non e' al momento disponibile via interfaccia web. Configurazione CLI ------------------------------------------------------------------ Per attivare il flag *all nodes* su un tag tree bisogna dare il comando: :: allnodes true|false Esempio: :: tagree geo allnodes true exit Le Regole di assegnamento automatico ------------------------------------------------------------------ Ad ogni tag di un tagtree possono essere assegnate una o piu' regole di assegnamento automatico. Una regola di assegnamento e' una tupla: :: < tag , expressione regolare > In fase di creazione di un nuovo nodo, se il nome fa match con l'espressione regolare di una o piu' regole, il nodo viene assegnato al tag corrispondente. Se il tag radice non ha regole di assegnamento, tutti i nodi che non sono stati ancora assegnati a nessun tag vengono aggiunti al tag radice. **IMPORTANTE**: Se anche il tag radice ha regole di assegnamento che possono escludere dei nodi, e' possibile che alcuni nodi non vengano assegnati a nessun tag: Configurazione WEB ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Questa funzionalita' non e' al momento disponibile via interfaccia web. Configurazione CLI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Per definire regole di assegnamento ad un tag bisogna posizionarsi all'interno di un tag e dare il comando: :: insert-rule **Esempio**: Tagga tutti i nodi *switch* o *router*, tutti i nodi che non fanno match finiscono in "Visione globale" :: tagtree geo allnodes true tag "Visione globale" tag switchs insert-rule sw.* exit tag routers insert-rule rt.* exit exit exit **Esempio**: Tagga tutti i nodi *cisco* o *hp*, tutti i nodi che non fanno match finiscono in "Visione globale": :: tagtree apparati allnodes true tag "Marche" tag cisco insert-rule hp exit tag hp insert-rule cs exit exit exit **Esempio**: Suddivide i nodi tra *sede1*, *sede2*. I nodi che matchano con "sd3*" finiscono in visione globale. Tutti quelli che non matchano non vengono aggiunti al tree. :: tagtree prova allnodes true tag "Visione globale" insert-rule sd3.* tag sede1 insert-rule sd1-.* exit tag sede2 insert-rule sd2-.* exit exit exit Refresh di un tagtree --------------------------------------------------------------------------- All'interno di un tagtree, e' possibile usare il comando *refresh* per applicare nuovamente le regole di assegnamento automatico. Anche dopo il refresh, i nodi non perdono i tag assegnati in precedenza. La modalita' di refresh e' *additiva*, e **non** *distruttiva*. Tagging parziale ================================================================================ Quando si tagga un elemento di monitoraggio vengono taggati automaticamente: * L'elemento stesso * Tutte le sue condition * Tutti i sotto element (e tutte le loro condition) Se all'elemento vengono aggiunti nuove entita' (sotto elementi, datagroup, condition, ecc.) queste vengono automaticamente taggate. In un secondo momento pero' e' possibile pero' *staggare* le diverse entita' taggate automaticamente. Configurazione WEB -------------------------------------------- Questa funzionalita' non e' al momento disponibile via interfaccia web. Configurazione CLI -------------------------------------------- Bisogna: * entrare nella sezione di configurazione di un tag * entrare nell'elemento desiderato * esplicitare la dissocaizione al tag Esempio: :: tagtree tree tag tag1 tag tag2 node localhost no interface wlan0 exit exit exit exit Assegnamento univoco di elementi in un tagtree (Flag 'unique') ======================================================================================================== All'interno di un tag tree una entita' (nodo, interfaccia, condition) puo' essere taggata piu' volte in tag diversi. Questo comportamento puo' essere cambiato e forzare che una entita compaia (sia taggata) solo una volta all'interno del tagtree. Questo modalita' attivabile impostatondo il flag "unique" a *true*. *IMPORTANTE*: il flag unique e' impostato a *false* di default. Comandi di tagging con il flag unique attivo ---------------------------------------------------------------------- Quando il flag "unique" e' attivo e si cerca di taggare un elemento gia' taggato in un altro tag dello stesso albero, l'elmento e tutti i suoi sotto-elementi (interfacce, datagroup, condition, ecc.) vengono "staggati" e "ritaggati" con il nuovo tag. L'effetto pratico e' che si *sposta* un elemento taggato da un tag ad un altro. Configurazione flag *unique* da WEB ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Questa funzionalita' non e' al momento disponibile via interfaccia web. Configurazione flag *unique* da CLI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Esempio: :: tagtree geo unique true tag "Visione globale" ... exit exit Limiti sull'attivazione del flag unique --------------------------------------------------------------------- Se si cerca di attivare il flag "unique" in un albero che contiene elementi taggati in piu' punti il sistema dara' errore. Per attivare il flag e' necessario "staggare" tutti elementi con tag multipli in modo da rendere univoco il tagging. **Esempio**: Se si cercasse di attivare il flag unique su questo albero il sistema darebbe errore. E' necessario togliere il nodo "localhost" da Tag2 o Tag3. :: tagtree prova tag Tag1 tag Tag2 node localhost exit tag Tag3 node localhost exit exit exit Copia di tag tra nodi ======================================================================================================== Configurazione via CLI ------------------------------------------------------------------------ Per copiare i tag tra diversi nodi sono disponibili i seguenti comandi: :: copy tags node like [ask-confirm] Tagga con i tag di . Se era gia' associato ad altri tag, l'associazione NON viene persa. (tagging in aggiunta) :: copy tags node exactly-as [ask-confirm] Tagga con esattamente gli stessi tag di . Se era gia' associato ad altri tag, i tag vecchi vengono "disassociati". Meta-informazioni associate ai tag =========================================================================================================================== E' possibile associare informazioni testuali generiche ai tag. In gergo sono chiamate *meta-informazioni*. Tutte le *meta-informazioni* sono identificate da un nome (*key*) e un valore in formato stringa. :: < key, string value > **IMPORTANTE**: La *key* e' univoca per tag. Configurazione via CLI ------------------------------------------------------------------------ Aggiungere ~~~~~~~~~~~~~ Per aggiungere *meta-dati* ad un tag e' necessario posizionarsi all'interno dell'albero di configurazione di un tag e usare il comando :: meta Esempio: :: tag Sede1 meta indirizzo "Via Carlo Carli" meta telefono "3312596071" meta referenti "foo@bar.com" exit **IMPORTANTE**: il valore di un meta-attributo e' sempre codificato con una stringa. Questa stringa puo' contenere caratterei di interlinea o altri caratteris speciali usando il normale escaping. :: meta referenti "referente1@mycompany.com\nreferente2@maicompany.com" Rimuovere ~~~~~~~~~~~~~ Per rimuovere un *meta-dato* bisogna dare il comando: :: no meta Esempio: :: tag Sede1 no meta refrenti referenti exit Stato e colorazione dei tag ================================================================================ Introduzione -------------------------------------------------------- Sanet calcola uno stato delle seguenti entita' in base alla struttura del tagging: * Tagtree: lo stato corrisponde dallo stato del tag radice. * Tag: lo stato dipende dallo stato dei sotto-tag e di tutti gli elementi e condition taggati all'interno. * Elementi di monitoraggio taggati: lo stato dipende dalle condition e sotto-elementi taggati *indirettamente*. * Condition Stati di tag ed elementi taggati. -------------------------------------------- Gli stati dei tag e degli elementi taggati si possono distinguere in base al colore: +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | STATO | DESCRIZIONE | +=======================+==================================================================================================================================================================================+ | VERDE (UP) | Il tag o l'elemento taggato non contengono condition allarmate. (*) | +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | GIALLO/NERO (FAILING) | IL tag o l'elemento contengono condition in stato FAILING o DOWN (*) | +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ROSSO (DOWN) | Il tag o l'elemento taggato contegono condition (A) solo esclusivamente condition DOWN (B) COndition critical, (C) stati esplosivi. Vai a :ref:`tagging-tag-explosive-elements`. | +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | GRIGIO (UNCHECK) | Lo stato dell'elemento non puo' essere calcolato poiche' non ci sono condition "significative" da analizzare (uncheckable o fuori sogli di rilevanza) | +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ (*) non sono conteggiate le condition uncheckable o con priority sotto minimum level. Contatori ~~~~~~~~~~~~ Via web le icone di tag e elementi taggati possono presentare due glifi aggiuntivi per indicare: 1. Numero di condition allarmate con priorita' sopra il minimum level. 2. Icona con segnale di avvertenza (Punto esclamativo) per indicare che ci sono condition sopra "critical level". .. image:: ../_static/web/pages/tag-state-icons.png Sottosistema di calcolo degli stati (Tagsd) -------------------------------------------- Gli stati dei tag viene calcolato da un sottosistema di Sanet (processo Tagsd). Il compito di Tags e' il seguente: * Legge dal Database la configurazione del tagging * Comunica con le interfacce di sanet (CLI e WEB) rispondendo alle interrogazioni e inviando i dati sugli stati. Schema di funzionamento: :: +----------------------------+ | sanetd | +-----+ | | +-------> | CLI | | +-----+ | | +----- +-----+ | |tagsd| ----------------------------+ | | +-----+ | STATO (4) | | +-----+ | ^ | | +--|----> | WEB | +-------------|-|------------+ +----- +-----+ | | | (2) NOTIFICA | | LETTURA (3) | | v | +-------+ UPDATE (1) | | SANET | <-----------------------------+ | DB | +-------+ Quando viene modificata la configurazione di Sanet (configurazioni di nodi o del taggging) viene notificato al sistema Tagsd che e' necessario aggiornare gli stati calcolati. .. warning:: il sistema tagsd mantiene in memoria lo stato degli elementi taggati. La quantita' di memoria occupata dipende linearmente dal numero di TagTree con flag nostate=False ( vedi sezione :ref:`tagging-flag-nostate`) e di elementi taggati. Se il server centrale di sanet non e' in esecuzione, Tags non e' in esecuzione e puo' rispondere alle richieste di interrogazione lo stato dei tag ed elementi taggati. Quando tagsd non e' in esecuzione lo stato del tagging mostrato via CLI e in alcune sezioni dell'interfaccia WEB e' rappresentato come UNCHECKABLE (grigio). Criteri di calcolo degli stati (algoritmo di calcolo) ------------------------------------------------------------ .. TODO: dettagliare l'algormtimo di cacolo e i vari casi di colorazione. TODO: TODO: TODO: TODO: TODO: TODO: Le condition che vengono considerate per il calcolo degli stati dipendono dal *critical level* e *minimum level* (vedi :ref:`web-critical-minimum-level`) .. _tagging-flag-nostate: Tag senza stato (flag no-state) ---------------------------------------- Per alcuni tag (tagtree) si potrebbe non voler calcolare lo stato, per diversi motivi: * nessun interesse a voler calcolarne lo stato * evitare computazione inutile da parte del server * ecc. Per evitare che il Sanet calcoli lo stato di alcuni tag e' necessario marcare il tagtree corrispondente come *nostate*. I tagtree configurati con *nostate* vengono visualizzati in prima pagina in una sezione a parte *Tag di Servizio*. .. important:: settando il flag *nostate* a "false" viene automaticamente settato a "false" anche il flag *nomap* illustrato sotto. .. important:: settando il flag *nostate* a "true", il flag *nomap* **NON** viene settato a "true". .. important:: settando il flag *nomap* a true|false, il flag *nostate* rimane invariato. Configurazione Web ~~~~~~~~~~~~~~~~~~ Questa funzionalita' non e' al momento disponibile via interfaccia web. Configurazione CLI ~~~~~~~~~~~~~~~~~~ Comando: :: tagtree geo nostate true|false exit Esempio: :: tagtree geo nostate true exit .. _tagging-tag-explosive-elements: Definire elementi *esplosivi* ---------------------------------------- E possibile alterare il normale calcolo di stato di un tag definendo degli elementi taggati come *esplosivi*. Se un elemento taggato e' flaggato come *esplosivo*, il suo stato DOWN forza lo stato DOWN del tag in cui e' contenuto e di tutti i tag della gerarchia. **Esempio**: il nodo *node2* e' taggato (associato) sia al tag *Cisco* che al tag *Posta*, ma solo per il tag *Posta* e' marcato come *esplosivo*. Lo stato del tag *Posta* e di tutti i tag dell'albero e' DOWN. .. digraph:: prova node [fontsize="8"]; subgraph tree1 { Servizi [color=red]; Posta [color=red]; Web [color=yellow]; Servizi -> Posta; Servizi -> Web; } subgraph tree2 { Apparati [color=yellow] Cisco [color=yellow]; Hp [color=green]; Apparati -> Cisco; Apparati -> Hp; } "node1" [shape=box, color=green]; //[image="./source/_static/resources/node.png", shape=none, imagescale="true", fixedsize="true", width="1pt" , color=red , bgcolor=red ]; "node2" [shape=box, color=red] ; //[image="./source/_static/resources/node.png", shape=none, imagescale="true", fixedsize="true", width="1pt" , color=red , bgcolor=red ]; "node3" [shape=box, color=green]; //[image="./source/_static/resources/node.png", shape=none, imagescale="true", fixedsize="true", width="1pt" , color=red , bgcolor=red ]; Posta -> node1 [style=dotted, color=blue]; Posta -> node2 [style=dotted, color=red]; Web -> node2 [style=dotted, color=blue]; Web -> node3 [style=dotted, color=blue]; Cisco -> node1 [style=dotted, color=blue]; Cisco -> node2 [style=dotted, color=blue]; Hp -> node3 [style=dotted, color=blue]; **NOTA**: Questo sistema permette di gestire alcuni elementi critici del monitoraggio in situazioni particolari. Ad esempio, lo stato di un disco puo' essere critico per la gestione complessiva del servizio di posta, ma completamente insignificante per la gestione della rete. Gruppi di elementi ~~~~~~~~~~~~~~~~~~ All'interno di uno stesso tag e' possibile raggruppare elementi taggati in *gruppi esplosivi*. Quando e' definito un *gruppo esplosivo*, la gestione dell'*esplositiva* entra in funzione solo se tutti gli elementi del gruppo sono DOWN. I gruppi sono identificati da un numero intero .. note:: la numerazione dei gruppi puo' partire da qualunque valore (non necessariamente da 1). Configurazione CLI ^^^^^^^^^^^^^^^^^^ Per settare il flag di esplosivita' su un elemento taggato bisogna espressamente dare i comandi : :: explosive node [ group ] explosive interface [ group ] explosive service [ group ] explosive storage [ group ] explosive device [ group ] explosive condition [ group ] Esempio: :: tagtree geo tag Global node www.google.com exit node localhost exit explosive node www.google.com group 666 explosive node localhost group 666 exit exit Configurazione Web ^^^^^^^^^^^^^^^^^^ Questa funzionalita' non e' al momento disponibile via interfaccia web. .. _web-tagging-alarms: Allarmi e notifiche ================================================================================ .. _web-tagging-alarms-wildcards: Wildcard disponibili ----------------------- E' possibile espandere i valori dei customfield associati ad un nodo monitorato utilizzando la seguente wildcard: +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ | Simbolo | Descrizione | +===================================================+======================================================================================================================+ | {{ tags.tree.<> }} | Stringa con tutti i tag del tree specificato associati alla condition (e all'elemento) che ha generato l'allarme. | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ Esempio: :: I tag associati a questo allarme sono: {{tags.tree.geo}}