Traffic Stats & QoS Adaptive Shaper

traffic-stats è un sistema distribuito per il monitoraggio del traffico di rete locale/WAN e per l'adattamento dinamico della qualità del servizio (QoS). È basato su un demone Python modulare eseguito sul firewall, un'istanza centrale di TimescaleDB (PostgreSQL 16) e una dashboard web Flask per la visualizzazione delle statistiche in tempo reale e storiche.

---

Architettura del Sistema

Il sistema è strutturato per operare su due nodi principali:

                  +-----------------------------------+
                  |        Macchina: antares          |
                  |  - Web UI (Flask)                 |
                  |  - Database (TimescaleDB Docker)  |
                  +-----------------------------------+
                                    ^
                                    | (PostgreSQL Port 5432)
                                    v
                  +-----------------------------------+
                  |        Macchina: firewall         |
                  |  - nftables & Traffic Control     |
                  |  - Demone di monitoraggio Python  |
                  +-----------------------------------+

1. antares (Dashboard + Database):

   • Ospita il database centrale TimescaleDB eseguito tramite Docker Compose.
   • Esegue l'applicazione Flask che interroga il DB ed espone la dashboard web reattiva (basata su Bootstrap 5 e Chart.js).
   • Esegue uno script di aggregazione giornaliera (daily_aggregate.py) che consolida i log grezzi ad alta frequenza in totali giornalieri per ridurre l'uso del disco.

2. firewall (Gestore di Rete & QoS):

   • Esegue il demone Python net-admin che misura la latenza (RTT) verso internet in tempo reale.
   • Adatta dinamicamente la banda di upload usando tc-cake (algoritmo Cake) per prevenire il bufferbloat in caso di congestione.
   • Applica regole nftables per marcare il traffico (DSCP) dando priorità a VoIP/DNS/SSH e declassando social e YouTube.
   • Rileva i contatori dei singoli IP e invia costantemente i log di utilizzo al database su antares.

---

Caratteristiche Principali

• Shaper Adattivo basato su RTT: Modula la banda in upload a livello di millisecondi per mantenere la latenza sotto controllo (particolarmente ottimizzato per connessioni instabili come 5G/LTE).
• Ottimizzazione I/O del disco: Configurato con synchronous_commit = off su TimescaleDB, aggregando le scritture dei log in memoria per salvaguardare la vita degli SSD o SD card del server.
• Separazione dei Privilegi: I parametri sensibili e le regole del firewall sono slegati dal codice Python e gestiti tramite configurazioni YAML e template delle regole.
• Aggregazioni Intelligenti: I log grezzi (acquisiti ogni 10s per dispositivo) vengono aggregati a mezzanotte e purgati dopo 15 giorni per mantenere stabile lo spazio su disco, preservando lo storico dei grafici per anni.

---

Installazione e Configurazione

1. Configurazione su antares (Database & Dashboard)

Installazione dei file

1. Crea la cartella operativa /opt/fwstats/ sulla macchina antares e copia al suo interno i file dalla cartella antares/ del repository:

   mkdir -p /opt/fwstats/
   cp -r antares/* /opt/fwstats/
   

2. Crea il file .env copiando il template d'esempio:

   cd /opt/fwstats/
   cp env.example .env
   

3. Modifica .env inserendo le credenziali desiderate per il database TimescaleDB e l'applicazione Flask.

Avvio del Database

1. Avvia il container Docker:

   docker compose up -d
   

   (TimescaleDB si avvierà sulla porta 5432 e inizializzerà automaticamente lo schema caricando il file init/init.sql).

Avvio della Dashboard Flask (Gunicorn)

Per avviare la dashboard come servizio di sistema gestito da Gunicorn, crea il file /etc/systemd/system/antares-stats.service su antares:

[Unit]
Description=Traffic Stats Flask Dashboard
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/fwstats
ExecStart=/usr/bin/gunicorn --bind 0.0.0.0:5000 --workers 4 app:app
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Abilita e avvia il servizio:

systemctl daemon-reload
systemctl enable antares-stats.service
systemctl start antares-stats.service

Aggregazione Giornaliera (Cron)

Per consolidare periodicamente i log ed evitare di riempire l'hard disk, imposta un cron job su antares per eseguire lo script di aggregazione ogni notte a mezzanotte:

1. Apri il crontab di root:

   crontab -e
   

2. Aggiungi la riga seguente:

   0 0 * * * cd /opt/fwstats && /usr/bin/python3 utils/daily_aggregate.py >> /var/log/fwstats-aggregate.log 2>&1
   

---

2. Configurazione su firewall (Demone Modulare)

Installazione dei file

1. Crea la cartella operativa /opt/net-admin/ e copia i file all'interno:

   mkdir -p /opt/net-admin/
   cp -r firewall/* /opt/net-admin/
   

2. Crea il file di configurazione reale copiando il template d'esempio:

   cd /opt/net-admin/
   cp config.example.yaml config.yaml
   

3. Modifica config.yaml inserendo le interfacce di rete del tuo firewall, le credenziali del database PostgreSQL su antares e i parametri del QoS Cake.

Configurazione dei Servizi Systemd

Crea i seguenti file all'interno di /etc/systemd/system/ sul firewall per automatizzare l'avvio:

• /etc/systemd/system/net-admin-init.service (Inizializzazione al Boot):

  [Unit]
  Description=Network Admin Initialization
  After=network.target
  
  [Service]
  Type=oneshot
  WorkingDirectory=/opt/net-admin
  Environment=PYTHONPATH=.
  ExecStart=/usr/bin/python3 -m net_admin.main init
  RemainAfterExit=yes
  
  [Install]
  WantedBy=multi-user.target
  

• /etc/systemd/system/net-admin-monitor.service (Demone in background):

  [Unit]
  Description=Network Latency Monitor & QoS Adaptor
  After=network.target
  
  [Service]
  Type=simple
  WorkingDirectory=/opt/net-admin
  Environment=PYTHONPATH=.
  ExecStart=/usr/bin/python3 -m net_admin.main monitor
  Restart=always
  User=root
  
  [Install]
  WantedBy=multi-user.target
  

• /etc/systemd/system/net-admin-adapt.service (Adattamento manuale/timer oneshot):

  [Unit]
  Description=Network Admin Adaptation Cycle
  
  [Service]
  Type=oneshot
  WorkingDirectory=/opt/net-admin
  Environment=PYTHONPATH=.
  ExecStart=/usr/bin/python3 -m net_admin.main adapt
  

Abilita e avvia i servizi:

systemctl daemon-reload
systemctl enable net-admin-init.service
systemctl enable net-admin-monitor.service
systemctl start net-admin-init.service
systemctl start net-admin-monitor.service

---

Utilizzo CLI del Firewall

Puoi interagire con lo script principale net_admin tramite CLI eseguendo i comandi all'interno di /opt/net-admin/ con privilegi di root:

# Esegue un dry-run (simulazione) per verificare le regole nftables compilate
python3 -m net_admin.main --dry-run init

# Inizializza il firewall, applica le regole e resetta la cronologia RTT
python3 -m net_admin.main init --reset

# Esegue un singolo ciclo di misurazione latenza e aggiornamento banda QoS
python3 -m net_admin.main adapt

# Sospende temporaneamente il QoS rimuovendo le code TC-Cake
python3 -m net_admin.main suspend

# Ripristina la coda QoS iniziale
python3 -m net_admin.main resume

---

Pubblicazione Sicura su GitHub (Pulizia Cronologia)

Se desideri pubblicare questo repository su GitHub (o su un server Git pubblico/privato) eliminando ogni traccia di vecchi dati sensibili (come host, token o password presenti nei commit storici), puoi ricreare il repository partendo da un branch orfano:

1. Crea un nuovo branch orfano (senza cronologia):

   git checkout --orphan main-clean
   

2. Aggiungi tutti i file attuali all'area di staging:

   git add .
   

   (Grazie al file .gitignore, i file di configurazione reali config.yaml, .env e le cartelle dei dati del database non verranno inclusi).

3. Effettua il primo commit pulito:

   git commit -m "Initial commit - Clean modularized architecture"
   

4. Rinomina il branch orfano come branch principale (main):

   # Cancella il vecchio main locale (ormai obsoleto)
   git branch -D main
   # Rinomina il branch corrente in main
   git branch -m main
   

5. Configura il tuo repository remoto su GitHub (si consiglia un repository privato) ed esegui il push forzato:

   git remote set-url origin https://github.com/tuo-utente/traffic-stats.git
   git push -f origin main