2.1. Directory e files

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}} e virtual-env

Indichiamo (in questa documentazione) con {{SANET_INSTALL_DIR}} la directory di installazione del pacchetto principale di Sanet.

Seguendo la procedura di installazione questa directory corrisponde a:

/usr/local/sanet -> /usr/local/src/sanet-svn

E' prevista anche la seguente cartella per ragioni di compatibilita' (con Sanet 3.6 installato tramite APT):

/usr/share/sanet -> /usr/share/sanet           link simbolico

Il "virtual environement" usato per installare le dipendenze/librerie usate da sanet e' normalmente posizionato allo stesso livello della directory di installazione:

/usr/local/sanet-env
/usr/share/sanet-env -> /usr/local/sanet-env

Attention

in caso di installazioni molto particolari la directory del virtualenv puo' essere specificata esplicitamente con la variabile d'ambiente SANET_VIRTUAL_ENV. L'uso di questa variabile d'ambiente e' fortemente sconsigliato.

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.

2.1.5.1.1. File generici accessibili via web

All'interno della directory dati esiste la cartella:

{{VAR}}/media

che consente di esporre via HTTP file con la URL.

<base WEB>/MEDIA/<nomefile>

Esempio: Se si espone Sanet tramite la URL "https://localhost/sanet/" e se si vuole esporre un file "test.png" bisogna metterlo nella directory:

/var/lib/sanet3/media/test.png

e sara' accessibile tramite la URL:

https://localhost/sanet/MEDIA/test.png

2.1.5.1.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)

2.1.5.1.3. 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.

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/local/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. 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.

DEFAULT
prova
pippo paperino "prova"
pluto
/usr/local/sanet3-modules/sanet-common/
BASH
/usr/local/sanet3-modules/sanet-common/


cd {{SANET_INSTALL_DIR}}
./scripts/db-save.sh

entables -t notify -A DEFAULT -j SMTP --smtp_rcpt_to root --smtp_message '#template:message1' --smtp_xheaders '${mail_xheaders}' --smtp_subject '[nodo: ${nodename}] ${mail_subject}'
CONFIGURAZIONE
DATABASES = {
    'default': {
        'ENGINE': DEFAULT_DATABASE_BACKEND,
        'NAME': 'sanet3',
        'USER': 'sanet3',
        'PASSWORD': '',
        'HOST': '',
        'PORT': '',
    }
}

CLI

# Questo e' un commento

datagroup test-trap

   title "Trap Tester"

   passive-match  regex:1\\.2\\.3\\.4\\.5\\..$
   minperiod 0

   passive-period 30

   condition check7
      title "Simple condition 7"
      expr " 1.3.6.1.6.3.1.1.4.1.0@ == '1.2.3.4.5.7'  and   1.3.6.1.2.1.1.6.6.6.0@ == 'SI'"
      max-tries 1

      msg-upsubj   "TRAP 7 UP"
      msg-upbody   "TRAP 7 UP TEXT"
      msg-downsubj "TRAP 7 DOWN SUBJECT"
      msg-downsubj "TRAP 7 DOWN BODY"

      passive-force-status 1

   exit

   condition check8
      title "Simple condition 8"
      expr " 1.3.6.1.6.3.1.1.4.1.0@ == '1.2.3.4.5.8'  and   1.3.6.1.2.1.1.6.6.6.0@ == 'SI'"
      max-tries 1

      msg-upsubj   "TRAP 8 UP"
      msg-upbody   "TRAP 8 UP TEXT"
      msg-downsubj "TRAP 8 DOWN SUBJECT"
      msg-downsubj "TRAP 8 DOWN BODY"

      passive-force-statu 1

   exit

exit

no node localhost localhost
node localhost
   datagroup test-trap
   exit
exit