2.1. Directory e files¶
Contenuti
2.1.1. Premesse¶
Sanet3 e’ composto da:
- un pacchetto principale (programma principale, scripts, files, ecc.)
- moduli/librerie python.
2.1.2. Pacchetto principale Sanet3 e {{SANET_INSTALL_DIR}}¶
Indichiamo con {{SANET_INSTALL_DIR}} la directory di installazione del pacchetto principale di Sanet.
Important
Quando Sanet viene installato manualmente, in assenza di configurazioni specifiche, di default (e in assenza di altre configurazioni descritte piu’ avanti), Sanet assume che la directory scelta come {{SANET_INSTALL_DIR}} sia:
/usr/share/sanet/
2.1.3. File di configurazione principale (settings.py)¶
Il file di configurazione principale e’:
{{SANET_INSTALL_DIR}}/conf/settings.py
2.1.3.1. Check file di configurazione¶
Per verificare che il file di configurazione sia almeno sintatticamente corretto si puo’ eseguire il comando:
{{SANET_INSTALL_DIR}}/scripts/config_check.sh
Note
questo script viene richiamato automaticamente dallo script di start/stop principale di sanet.
2.1.3.2. Configurazioni di default¶
Tutte le configurazioni di default sono contenute nel file:
{{SANET_INSTALL_DIR}}/conf/default_settings.py
Danger
Questo file NON DEVE essere modificato per nessun motivo.
2.1.4. Come personalizzare i parametri di configurazione¶
Per sovrascrivere una configurazione di default (impostata nel file default_settings.py) bisogna modificare/aggiungere parametri nel file settings.py.
Important
il file di configurazione (default_settings.py e settings.py) e’ un file python e quindi il file deve rispettare le regole di sintassi e di semantica di un qualunque altro file python.
Il file di configurazione puo’ contenere:
- parametri semplici
- parametri complessi
2.1.4.1. Parametri semplici¶
I parametri semplici sono variabili python valorizzate con valori singoli (interi, stringhe, boolean, None, ecc.).
Esempio:
...
DEFAULT_ADMIN_USERNAME = 'admin'
DEFAULT_ADMIN_GROUP = 'admins'
...
Per sovrascrivere questi parametri e’ necessario scrivere in settings.py il parametro con il nuovo valore:
DEFAULT_ADMIN_USERNAME = 'foo'
2.1.4.2. Parametri complessi¶
I parametri complessi sono variabili python strutturate (liste di valori, dizionari con chiavi, ecc…).
Esempio di parametro complesso:
DATABASES = {
'default': {
'ENGINE': DEFAULT_DATABASE_BACKEND,
'NAME': 'sanet3',
'USER': 'sanet3',
'PASSWORD': '',
'HOST': '',
'PORT': '',
}
}
Se bisogna modificare parametri complessi bisogna stare attenti e valutare il modo corretto per scovrascrivere uno o piu’ sotto-parametri di configurazione.
Esempi (tutti ugualmente validi a seconda dei casi) di metodi di modifica/sovrascrittura di parametri complessi:
Esempio 1:
DATABASES['default']['NAME'] = 'foo'
DATABASES['default']['USER'] = 'foo'
DATABASES['default']['USER'] = 'password'
Esempio 2:
DATABASES['default'].update({
'NAME' : 'foo',
'USER' : 'foo',
'PASSWORD': 'password',
})
Esempio 3:
DATABASES.update({
'default': {
'ENGINE': DEFAULT_DATABASE_BACKEND,
'NAME': 'sanet3',
'USER': 'sanet3',
'PASSWORD': '',
'HOST': '',
'PORT': '',
}
})
Attenzione a non sovrascrivere in maniera distruttiva (ottenendo come effetto la rimozione di valori pre-impostati) parametri complessi.
Esempio:
NO:
conf/default_settings.py INSTALLED_APPS = [ 'core', 'webui' ] conf/settings.py INSTALLED_APPS = [ 'webtests' ] -------------> INSTALLED_APPS non conviene 'core' e 'webui'SI:
conf/default_settings.py INSTALLED_APPS = [ 'core', 'webui' ] conf/settings.py INSTALLED_APPS.append('webtests') oppure INSTALLED_APPS += ['webtests'] oppure if 'webtests' not in INSTALLED_APPS: INSTALLED_APPS.append('webtests') oppure if 'webtests' not in INSTALLED_APPS: INSTALLED_APPS += ['webtests'] -------------> INSTALLED_APPS contiene 'core', 'webui' e 'webtests'
Note
come si vede dall’esempio, non c’e’ un unico modo correto per modificare il file di configurazione.
2.1.5. Altre directory¶
2.1.5.1. Dati applicativi {{VAR}}¶
Quasi tutti i dati applicativi vengono salvati nel database interno di Sanet. Tutti gli altri file di appoggio e dati specifici per una installazione vengono salvati nella directory privata {{VAR}}.
La posizione di questa directory puo’ essere specificata in file di configurazione.
Il path di default di questa directory e’:
/var/lib/sanet3/
Important
Questa directory viene modificata anche dall’interfaccia Web di Sanet, quindi e’ indispensabile che essa e tutti i file contenuti siano accessibili anche in scrittura dal processo Apache.
Esempio:
chown -R www-data:www-data /var/lib/sanet3
Warning
la disposizione interna dei file in questa directory potrebbe cambiare nel tempo. Non e’ lecito implementare script di Supporto a sanet che fanno assunzioni “forti” sulla posizione dei file in questa directory.**
Warning
Verificare sempre che eventuali programmi esterni (vedi rrdcached-basedir) accedano correttamente a questa directory.
Note
se la variabile SANET_HOME e’ settata vedere il paragrafo 1.5.2.
2.1.5.1.1. Backup dei dati¶
Se si vuole effettuare un backup periodico dei dati del sistema, bisogna assicurarsi di salvare tutto il contenuto di questa directory (oltre al dump del database di Sanet)
2.1.5.1.2. Sotto-directory dei tenant¶
La directory {{VAR}} suddivide i file per “tenant”. Ogni tenant ha una sua directory il cui nome corrisponde dall’UUID del tenant.
Per facilitare l’accesso alla directory esiste anche un link simbolico con il nome del tenant:
drwxrwxr-x 6 root root 4096 Jul 23 16:28 a575bd788451436cbe8cf0582965a035
lrwxrwxrwx 1 root root 52 Sep 25 07:55 site -> /var/lib/sanet3/a575bd788451436cbe8cf0582965a035
La directory del tenant contiene diverse sotto directory:
media Immagini e icone caricate/usante dall'interfaccia web
rrds File RRD con i dati dei datasource
stats File sistema di diagnostica interna
2.1.5.2. Directory file temporanei {{RUN}}¶
Tutti i file temporanei (pid, lock, ecc…) vengono salvati in una directory chiamata in gergo {{RUN}}.
Esattamente come “VAR”, la posizione di questa directory e’ specificata in file di configurazione.
Il default e’:
/var/run/sanet3
Esempio di contenuto della directory:
-rwxrwxr-x 1 root labsdev 6 Oct 16 14:40 cli.pid
-rw-rw-rw- 1 root root 6 Nov 11 00:00 main-agent-48d262d0743f474f8d225c46adb00e3d.pid
-rw-rw-rw- 1 root root 6 Nov 11 00:00 main-agent-d30c06dc5eb44141ad149420c5a745b2.pid
-rw-rw-rw- 1 root root 6 Nov 11 00:00 sanet_localpollers_supervisor.pid
Note
questi file vengono usati dagli script di start/stop. E’ preferibile non intervenire manualmente su questi file a meno che non si sappia esattamente cosa si sta facendo.
Note
se la variabile SANET_HOME e’ settata vedere il paragrafo 1.5.2.
2.1.5.3. Directory file di log {{LOG}}¶
Tutti i log di sistema vengono salvati nella directory “LOG”.
La directory di default e’:
/var/log/sanet3/
Esiste (in pratica) un file di log per ogni (sub-)processo di Sanet.
Questi sono i file dei processi “supervisor” che si occupano di rilanciare i sotto-sistemi di sanet quando non si verifica un errore o i sub-processi vanno in crash:
sanetd_supervisor.log Log "sanetd" supervisor.
sanet_localpollers_supervisor.log Log "poller" supervisor.
Questi sono i log specifici dei singoli sotto-sistemi:
sanetd.log Log server principale
poller.log Log dove scrivono tutti gli agenti "locali"
entables_log Log "entables".
autoconfd_log Log discovery
wdog_log Log sistema di watchdog
statusd_log Log process statusd
2.1.5.4. Directory Moduli e librerie¶
I moduli di Sanet sono package (librerie) python e vengono trattati come tali.
Normalmente vengono installati nelle directory di sistema che dipendono dalla versione di python utilizzata.
Tipicamente una di queste directory:
/usr/lib/pyshared/...
/usr/lib/python-<version>/dist-packages/...
/usr/lib/python-<version>/site-packages/...
2.1.6. Sistemi Debian¶
Se si installa il sistema tramite pacchetti Debian alcune delle directory descritte vengono FORZATE (hard-coded nel codice) e non sono (teoricamente) modificabili:
Directory Valore Modificabile da file di configurazione {{SANET_INSTALL_DIR}} /usr/share/sanet NO {{VAR}} /var/lib/sanet3 si {{RUN}} /var/run/sanet3 si {{LOG}} /var/log/sanet3 si moduli e librerie {directory di sistema o altro} NO
Il file di configurazione principale settings.py viene creato nella directory /etc/sanet e linkato
{{SANET_INSTALL_DIR}}/conf/settings.py -> /etc/sanet/settings.py
2.1.7. Modifiche/Eccezioni nell’installazione manuale¶
Installando manualemente SANET e’ possibile forzare o meno la directory di installazione e rendere “hard-coded” il path.
Se la directory di installazione non e’ stata forzata, puo’ essere modificata variando precisi parametri nei file di configurazione di Sanet e variabili d’ambiente presenti nel sistema.
2.1.7.1. Installazione manuale dei moduli e utilizzo di PYTHONPATH¶
Per installare manualmente i moduli necessari a SANET bisogna scaricare ogni singolo modulo separatamente e lanciare il comando:
python setup.py install
E’ possibile posizionare i moduli in directory non standard purche’ la variabile d’ambiente PYTHONPATH contenga i path per puntare alle directory corrette.
Esempio: Ipotizzando che i moduli siano tutti stati installati nella directory /usr/local/sanet3-modules :
/usr/local/sanet3-modules/sanet-common/
/usr/local/sanet3-modules/sanet-libsnmp/
/usr/local/sanet3-modules/sanet-poller/
/usr/local/sanet3-modules/sanet-ipmon/
/usr/local/sanet3-modules/engables/
La variabile d’ambiente PYTHONPATH dovra’ specificare la directory di ogni singolo modulo:
PYTHONPATH=$PYTHONPATH:/usr/local/sanet3-modules/sanet-common
PYTHONPATH=$PYTHONPATH:/usr/local/sanet3-modulest/sanet-libsnmp
PYTHONPATH=$PYTHONPATH:/usr/local/sanet3-modules/sanet-poller
PYTHONPATH=$PYTHONPATH:/usr/local/sanet3-modules/sanet-ipmon
PYTHONPATH=$PYTHONPATH:/usr/local/sanet3-modules/engables
2.1.7.2. Variabile d’ambiente SANET_HOME¶
E’ possibile impostare la variabile d’ambiente SANET_HOME per gestire contemporaneamente piu’ installazioni di Sanet3 sulla stessa macchina e “confinare” ogni installazione in una unica directory.
Se la variabile d’ambiente SANET_HOME e’ valorizzata il sistema si aspettera’ di trovare la directory di installazione principale {{SANET_INSTALL_DIR}} e tutte le directory aggiuntive nei seguenti punti:
Directory Posizione directory di default Posizione directory con SANET_HOME Modificabile da file di configurazione {{SANET_INSTALL_DIR}} /usr/share/sanet $SANET_HOME/ NO {{VAR}} /var/lib/sanet3 $SANET_HOME/var/lib si {{RUN}} /var/run/sanet3 $SANET_HOME/var/run si {{LOG}} /var/log/sanet3 $SANET_HOME/var/log si moduli e librerie {directory di sistema} {directory di sistema o altro} NO
Danger
Non bisogna assolutamente utilizzare il meccanismo basato su SANET_HOME con installazioni fatte tramite pacchetti DEBIAN poiche’ in queste installazioni il percorso di installazione ({{SANET_INSTALL_DIR}}) e’ hard-coded nel software ed crea problemi con la variabile d’ambiente anche se {{SANET_INSTALL_DIR}} e $SANET_HOME coincidono.
2.1.8. Installazioni completamente non standard¶
E’ possibile utilizzare una struttura di installazione completamente personalizzata (directory posizione in maniera completamente customizzata) intervenendo sui file di configurazione contenuti in {{SANET_INSTALL_DIR}}/conf/.
La trattazione di come configurare Sanet per ottenere questo risultato NON e’ affrontata in questo documento.