.. _rrdcached:

RRDCached
=========

.. toctree::
   :maxdepth: 1

.. contents:: Contenuti
   :depth: 3


Introduzione
------------

Sanet3 utilizza i file RRD come sistema di storage per mantenere lo storico dei "datasource".

RRDCached e' un demone che permette di ottimizzare l'accesso in scrittura/lettura ai file RRD.

L'utilizzo di RRDCached puo' essere attivato/disabilitato in qualunque momento.

Installazione
-------------

Sistemi debian
~~~~~~~~~~~~~~~~

Eseguire: 

	::
		
		apt-get install rrdcached

.. _rrdcached-basedir:




Configurazione permessi di lettura di Apache sul socket di RRDCached
------------------------------------------------------------------------

Se il demone Apache e' in esecuzione con utente/gruppo diverso da root, per poter far comunicare correttamente l'interfaccia web di Sanet con RRDCACHED e' necessario
configurare i permessi su socket specificato con RRDCACHED_ADDRESS.


Sistemi debian
~~~~~~~~~~~~~~~~~~

Creiamo il gruppo "rrdcached":

	::
		
		groupadd rrdcached

Assegnamo all'utente "www-data" (Apache 2) gruppo "rrdcached"

	::
		
		usermod -a -G rrdcached www-data


Configurazione di RRDCACHED
----------------------------------------------------------------------------------------


Sistemi debian
~~~~~~~~~~~~~~~~~~

.. warning:: In alcuni sistemi (es: Debian) la configurazione di default (/etc/rrdcached) limita l'accesso al filesystem con le opzioni "-b" e "-B". 
             Questi parametri sono incompatibili con Sanet.
             ::
                 
                 OPTS="-l unix:/var/run/rrdcached.sock"
                 OPTS="$OPTS -j /var/lib/rrdcached/journal/ -F"
                 OPTS="$OPTS -b /var/lib/rrdcached/db/ -B"        <-----------


Modificate il file: 

	::
		
		/etc/default/rrdcached

cosi': 

	::
		
		cat >> /etc/default/rrdcached <<ENDOFFILE
		
		#
		# RRDCached 1.7 per debian 10
		#
		JOURNAL_PATH=""
		SOCKFILE=""
		BASE_PATH=""
		BASE_OPTIONS=""
		BASE_OPTIONS="\$BASE_OPTIONS -s rrdcached"
		BASE_OPTIONS="\$BASE_OPTIONS -l unix:/var/run/rrdcached.sock -F"
		BASE_OPTIONS="\$BASE_OPTIONS -t 2"
		BASE_OPTIONS="\$BASE_OPTIONS -z 3600 -w 3600 -f 7200"
		
		ENDOFFILE

Riavviate rrdcached

	::
		
		/etc/init.d/rrdcached restart



Verifica esecuzione:

	::
		
		apt-get install socat
		echo 'STATS' | socat - unix:/var/run/rrdcached.sock

	L'output dovrebbe essere qualcosa del tipo:
	
	::
		
		9 Statistics follow
		QueueLength: 0
		UpdatesReceived: 0
		FlushesReceived: 0
		UpdatesWritten: 0
		DataSetsWritten: 0
		TreeNodesNumber: 0
		TreeDepth: 0
		JournalBytes: 0
		JournalRotate: 0





Configurazione del sistema
--------------------------

Per utilizzare correttamente RRDCACHED e' necessario che sia valorizzata correttamente la variabile d'ambiente:

	::
		
		RRDCACHED_ADDRESS

Esempio:

	::
		
		export RRDCACHED_ADDRESS='unix:/var/run/rrdcached.sock'


.. danger:: Questo garantisce che qualunque accesso ai file RRD tramite Sanet o direttamente con i tool di RRDTOOL passi attraverso il demone rrdcached.



Environment utente di default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sistemi debian
~~~~~~~~~~~~~~~~~~~

Aggiungere il file:

	::
		
		/etc/profile.d/rrdcached.sh

cosi':

	::
		
		cat > /etc/profile.d/rrdcached.sh <<ENDOFFILE
		export RRDCACHED_ADDRESS='unix:/var/run/rrdcached.sock'
		ENDOFFILE
		
		chmod 755 /etc/profile.d/rrdcached.sh


.. danger:: Questo e' fondamentale per assicurare che qualunque script eseguito da utenti normali, per accedere ai file RRD acceda corramente a RRDCached.

.. warning:: Questa configurazione non gestisce l'utente "root".





Aggiungere al file 

	::
		
		/etc/environment

cosi':

	::
		
		cat >> /etc/environment <<ENDOFFILE
		RRDCACHED_ADDRESS='unix:/var/run/rrdcached.sock'
		ENDOFFILE
		




Environment di Cron
~~~~~~~~~~~~~~~~~~~~~~~~~

Se sanet viene configurato per essere ravviato tramite comandi in crontab, assicurarsi che
all'inizio della configurazione di cron compia la variable RRDCACHED_ADDRESS.

.. warning:: Questo e' fondamentale per assicurare che qualunque script esterno a Sanet che deve accedere ai file RRD acceda corramente a RRDCached.


Environment di Apache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sistemi debian
+++++++++++++++++

Aggiungere al file:

	::
		
		/etc/apache2/envvars

la configurazione:

	::
		
		cat >> /etc/apache2/envvars <<ENDOFFILE
		export RRDCACHED_ADDRESS=unix:/var/run/rrdcached.sock
		ENDOFFILE


Riavviare apache:

	::
		
		apache2ctl restart


.. danger:: La presenza della variabile d'ambiente RRDCACHED_ADDRESS e' fondamentale per assicurare che qualunque applicazione WEB che deve accedere ai file RRD acceda corramente ai file tramite il demone RRDCached.





Configurazione di Sanet
------------------------------------------------------------------------

RRDCACHED_ADDRESS
~~~~~~~~~~~~~~~~~~~

E' **FONDAMENTALE**  che il parametro di configurazione DATASOURCE_STORAGE_PARAMS contenga la chiave *RRDCACHED_ADDRESS* valorizzata:

	::
		
		DATASOURCE_STORAGE_PARAMS.update({ 
			"RRDCACHED_ADDRESS": "unix:/var/run/rrdcached.sock"
		})

Esempio:

	::
		
		cat >> /usr/local/sanet/conf/settings.py <<ENDOFFILE
		DATASOURCE_STORAGE_PARAMS.update({ 
			"RRDCACHED_ADDRESS": "unix:/var/run/rrdcached.sock"
		})
		ENDOFFILE


.. danger:: Se la variabile d'ambinete RRDCACHED_ADDRESS  e  la chiave DATASOURCE_STORAGE_PARAMS["RRDCACHED_ADDRESS"] sono valorizzate diversamente, la CLI e altri componenti di Sanet si arrestano immediatamente dopo il lancio per prevenire eventuali comportamenti imprevedibili.


FLUSH automatico 
~~~~~~~~~~~~~~~~~~

E' possibile configurare Sanet per obbligare RRDCACHED a fare flush dei dati prima di effettuare una operazione di fetch dai file RRD.

Mettere nel file:

	::
		
		{SANET_INSTALL_DIR}/conf/settings.py

Aggiungere:

	::
		
		DATASOURCE_STORAGE_PARAMS.update({ 
			"rrdcached_flush_before_read": True
		})

Esempio:

	::
		
		cat >> /usr/local/sanet/conf/settings.py <<ENDOFFILE
		DATASOURCE_STORAGE_PARAMS.update({ 
			"rrdcached_flush_before_read": True
		})
		ENDOFFILE

.. note:: se la variabile d'ambiente RRDCACHED_ADDRESS non e' configurata nell'environment, la configurazione precedente viene ignorata.


.. warning:: RRDCACHED puo' essere configurato per effettuare un journaling dei dati e garantire che dati bufferizzati non vengano persi in caso di terminazione/riavvio del processo.
             L'opzione per attivare il journaling (-j) vanifica in parte l'effetto del flushing dei dati.




Riavvio processi coinvolti
--------------------------------

Per rendere effettive le configurazioni e' necessario riavviate tutti i processi in esecuzione che hanno bisogno dell'enviroment corretto: 

	::
		
		cd {{SANET_INSTALL_DIR}}
		./script/server/sanetd restart

	::
		
		apachectl restart

Statistiche di RRDCached
------------------------------------------------------

E' possibile interagire con RRDCached attraverso comandi inviati sul suo unix socket con il comando *socat*:


.. important:: Su sistemi Debian serve installare il pacchetto "socat"
	::
		
		apt-get install socat


Interrogare RRDCACHED:

	::
		
		echo 'STATS' | socat - unix:/var/run/rrdcached.sock

Dovreste vedere in output il valore *UpdatesReceived* crescere con il tempo:

	::
		
		9 Statistics follow
		QueueLength: 0
		UpdatesReceived: 776     <--------------- UPDATE RICEVUTI
		FlushesReceived: 7       <--------------- FLUSH RICEVUTI
		UpdatesWritten: 1
		DataSetsWritten: 1       <--------------- WRITE SU DISCO
		TreeNodesNumber: 263
		TreeDepth: 10
		JournalBytes: 114393
		JournalRotate: 0





Configurazioni particolari: attenzione ai link simbolici
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**IMPORTANTE**: Rrrdcached puo' essere configurato per salvare i file con nomi relativi specificando una directory di base (opzione -b).
Come scritto nella documentazione di rrdcached questa opzione non funziona se il full path finale del file contiene link simbolici.
Questa opzione mal si presta a sistemi configurati in maniera particolare (con link simbolici appunto) o che utilizzano rrdcached in piu'
applicazioni poiche' applicazioni diverse rischiano di scrivere nella stessa directory.
Per sicurezza accertarsi che questa opzione non venga usata.

Dalla doc di rrdcached:

::
	
	-b dir
	
		The daemon will change into a specific directory at startup. All files passed to 
		the daemon, that are specified by a relative path, will be interpreted to be 
		relative to this directory. If not given the default, "/tmp", will be used.
		
		+------------------------+------------------------+
		! Command line           ! File updated           !
		+------------------------+------------------------+
		! foo.rrd                ! /tmp/foo.rrd           !
		! foo/bar.rrd            ! /tmp/foo/bar.rrd       !
		! /var/lib/rrd/foo.rrd   ! /var/lib/rrd/foo.rrd   !
		+------------------------+------------------------+

		Paths given on the command  line and paths actually updated by the daemon,  assuming 
		the base directory "/tmp".
		
		WARNING: The paths up to and including the base directory MUST NOT BE symbolic 
		links. In other words, if the base directory is specified as:
		
			-b /base/dir/somewhere
			... then NONE of the following should be symbolic links:
			/base
			/base/dir
			/base/dir/somewhere