.. _install-dirs: ######################################################################## Directory e files ######################################################################## .. contents:: Contenuti Premesse ====================================================================================================== Sanet3 e' composto da: * un pacchetto principale (programma principale, scripts, files, ecc.) * moduli/librerie python. 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/ File di configurazione principale (settings.py) ====================================================================================================== Il file di configurazione principale e': :: {{SANET_INSTALL_DIR}}/conf/settings.py 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. 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. 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 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' 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. Altre directory ====================================================================================================== 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 :ref:`rrdcached-basedir`) accedano *correttamente* a questa directory. .. note:: se la variabile SANET_HOME e' settata vedere il paragrafo 1.5.2. 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) 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 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. .. _sanet-logs: 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 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-/dist-packages/... /usr/lib/python-/site-packages/... 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 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. 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 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. 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.