====== Infrastructure de Test : Cisco TRex & Stack d'Observabilité (Docker Compose) ======

Ce document détaille la configuration, le déploiement et l'observabilité de la plateforme de génération de trafic **Cisco TRex v3.08** entièrement conteneurisée et supervisée en temps réel à l'aide de **Prometheus** et **Grafana**.

===== 1. Architecture Globale =====

La solution est orchestrée via un unique fichier **Docker Compose** exécutant 4 services complémentaires :
  * **trex-server** (TRex) : Le moteur de génération de trafic s'exécutant en mode privilégié et réseau hôte pour permettre l'accès matériel direct via DPDK aux interfaces réseau physiques.
  * **ciscotrex-exporter** : Un exportateur de télémétrie Python qui se connecte au serveur TRex sur le port API ZMQ ''4501'', convertit les statistiques brutes et les expose pour Prometheus sur le port ''8000''.
  * **prometheus** : La base de données de séries temporelles configurée pour scraper l'exportateur toutes les 10 secondes.
  * **grafana** : L'interface de visualisation affichant les graphiques temps réel de trafic (Bitrates, PPS, Utilisation CPU et Perte de paquets).

===== 2. Structure des Répertoires =====

Le projet est structuré sur l'hôte sous le chemin `/home/jonathan/docker/trex-bundle/` de la manière suivante :

<code>
/home/jonathan/docker/trex-bundle/
├── docker-compose.yaml        # Fichier d'orchestration multi-conteneurs
├── docker-compose.yaml.bak    # Copie de sauvegarde historique
├── trex/                      # Répertoire dédié au service TRex
│   ├── Dockerfile             # Image système TRex (Ubuntu 24.04 + Setuptools)
│   ├── trex_cfg.yaml          # Fichier de configuration d'interfaces et CPU
│   └── scratch/               # Dossier monté contenant les binaires et profils
└── monitoring/                # Répertoire dédié à la stack d'observabilité
    ├── Dockerfile             # Image système de l'exportateur Prometheus
    ├── prometheus.yml         # Configuration de collecte (Scraping)
    └── grafana-datasource.yml # Provisionnement automatique de la source Prometheus
</code>

===== 3. Configuration de l'Orchestrateur (docker-compose.yaml) =====

Ce fichier orchestre l'ensemble des dépendances, gère l'accès privilégié au matériel hôte et configure les volumes persistants.

<code yaml>
services:
  trex:
    build:
      context: .
      dockerfile: ./trex/Dockerfile
    container_name: trex-server
    image: local/trex:3.08
    restart: unless-stopped
    privileged: true
    network_mode: "host"
    volumes:
      # Montage du dossier scratch contenant les scripts et exécutables TRex
      - ./trex/scratch:/scratch
      # Montage de la configuration réseau/matériel TRex
      - ./trex/trex_cfg.yaml:/etc/trex_cfg.yaml
      # Montage des Hugepages pour les performances d'accès mémoire DPDK (Critique)
      - /dev/hugepages:/dev/hugepages
      # Montage en lecture seule des modules noyau de l'hôte pour le chargement des pilotes
      - /lib/modules:/lib/modules:ro
      # Montage des répertoires systèmes pour le mapping PCI
      - /sys:/sys
      - /dev:/dev
    working_dir: /scratch
    command: ["-i", "--no-watchdog"]
  
  ciscotrex-exporter:
    build:
      context: .
      dockerfile: ./monitoring/Dockerfile
    container_name: ciscotrex-exporter
    network_mode: "host"
    environment:
      - TREX_EXT_LIBS=/scratch/external_libs
      - TREX_HOST=127.0.0.1
      - TREX_ZMQ_PORT=4501
      - PYTHONPATH=/scratch/automation/trex_control_plane/interactive
    volumes:
      - ./trex/scratch:/scratch:ro
    restart: unless-stopped
    depends_on:
      - trex

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus

  grafana:
    image: grafana/grafana-oss:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - ./monitoring/grafana-datasource.yml:/etc/grafana/provisioning/datasources/datasource.yml
      - grafana-data:/var/lib/grafana

volumes:
  prometheus-data:
  grafana-data:
</code>

===== 4. Service TRex (Dossier /trex) =====

==== Dockerfile (trex/Dockerfile) ====
Ce fichier utilise **Ubuntu 24.04** comme base. Afin d'assurer la compatibilité avec l'API interne de TRex v3.08 écrite pour des versions de Python antérieures à Python 3.12 (qui a déprécié/retiré ''distutils''), le paquet ''python3-setuptools'' est installé pour émuler l'import de ''distutils'' à la volée.

<code dockerfile>
FROM ubuntu:24.04

# Évite les interruptions lors des installations interactives APT
ENV DEBIAN_FRONTEND=noninteractive

# Supprime les avertissements de syntaxe hérités d'anciennes versions de Python
ENV PYTHONWARNINGS="ignore"

# Installation des dépendances requises par DPDK et TRex
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-setuptools \
    libz-dev \
    pciutils \
    iproute2 \
    kmod \
    procps \
    libc6 \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /scratch
ENV PATH="/scratch:${PATH}"

ENTRYPOINT ["./t-rex-64"]
</code>

==== Configuration TRex (trex/trex_cfg.yaml) ====
Définit les adresses PCI des ports réseau configurés pour le test ainsi que la topologie CPU (Socket 0, Threads 4 à 7 dédiés à la génération de paquets).

<code yaml>
- version: 2
  interfaces: ['03:00.0', '03:00.1']
  port_info:
      - ip: '192.168.100.11'            # Port 0 TRex IP
        default_gw: '192.168.100.1'     # Port 0 Router Gateway IP
      - ip: '192.168.101.12'            # Port 1 TRex IP
        default_gw: '192.168.101.1'     # Port 1 Router Gateway IP
  platform:
      master_thread_id: 0
      latency_thread_id: 1
      dual_if:
        - socket: 0
          threads: [4,5,6,7]
</code>

===== 5. Service Observabilité (Dossier /monitoring) =====

==== Dockerfile de l'exportateur (monitoring/Dockerfile) ====
Utilise une image légère Debian-slim et clone le dépôt de l'exportateur officiel de Cisco TRex pour l'exposer sur l'hôte.

<code dockerfile>
FROM python:3.10-slim

# Installation de git pour cloner le dépôt de l'exportateur
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

# Clonage de l'exportateur Prometheus pour TRex
RUN git clone https://github.com/Civil/ciscotrex_exporter.git /app
WORKDIR /app

# Installation des paquets Python (ZMQ, Prometheus Client, etc.)
RUN pip install --no-cache-dir -r requirements.txt

EXPOSE 9362

ENV TREX_EXT_LIBS=/scratch/external_libs
ENV TREX_HOST=127.0.0.1
ENV TREX_ZMQ_PORT=4501

ENTRYPOINT ["python", "main.py"]
CMD ["--web.listen-address=0.0.0.0:9362"]
</code>

==== Configuration de Collecte (monitoring/prometheus.yml) ====
Configure Prometheus pour requêter l'exportateur local à une fréquence rapide (toutes les 10 secondes) afin de capturer l'ensemble des spikes de trafic.

<code yaml>
global:
  scrape_interval: 10s
  evaluation_interval: 10s

scrape_configs:
  - job_name: 'cisco-trex'
    static_configs:
      - targets: ['host.docker.internal:8000']
</code>

==== Provisionnement de la Source de Données (monitoring/grafana-datasource.yml) ====
Ajoute automatiquement Prometheus comme source de données active lors de l'initialisation de Grafana.

<code yaml>
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
</code>

===== 6. Configuration Requise sur l'Hôte (Prise en charge DPDK) =====

Avant de démarrer le conteneur, l'hôte physique doit disposer des modules noyau adéquats et de mémoire Hugepages configurée.

==== Allocation des Hugepages ====
<code>
# Allouer 1024 pages de 2MB (2 Go de RAM au total pour DPDK)
echo 1024 | sudo tee /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages

# Rendre la modification permanente au redémarrage
echo "vm.nr_hugepages = 1024" | sudo tee -a /etc/sysctl.conf
</code>

==== Chargement des Pilotes Noyau ====
Assurez-vous que les modules requis par DPDK sont actifs sur l'hôte physique :
<code>
sudo modprobe uio
sudo modprobe vfio-pci
sudo modprobe uio_pci_generic
</code>

===== 7. Guide d'Exploitation (Commandes Clés) =====

^ Description de l'action ^ Commande ^
| **Construire & Démarrer la stack** | ''docker compose up -d --build'' |
| **Arrêter la stack** | ''docker compose down'' |
| **Afficher les logs globaux** | ''docker compose logs -f'' |
| **Vérifier l'export des métriques** | ''curl http://localhost:8000/metrics'' |
| **Accéder à la Console interactive TRex** | ''docker exec -it trex-server ./trex-console'' |

===== 8. Adresses d'Accès aux Services =====

  * **Prometheus Dashboard** : [[http://<IP_HOTE>:9090/targets]] //(Vérifier que le statut du endpoint "cisco-trex" est à "UP")//
  * **Grafana Web UI** : [[http://<IP_HOTE>:3000]]
    * **Identifiants de connexion** : ''admin'' / ''admin''
    * **Dashboard TRex Officiel** : Menu > Dashboards > Import > Saisir l'ID **23559** > Sélectionner la source de données **Prometheus** > Import**.

===== 9. Référence des Commandes TRex (Cheat Sheet) =====

Cette section regroupe les commandes essentielles pour administrer le serveur, interagir avec la console et lancer des profils de trafic.

==== 9.1. Gestion du Serveur ====

Démarrer le serveur TRex en mode interactif (Stateless) tout en désactivant le thread de surveillance matérielle :
<code bash>
sudo ./t-rex-64 -i --no-watchdog
</code>

==== 9.2. Connexion à la Console ====

Ouvrir la console CLI interactive permettant d'acquérir les ports et d'injecter le trafic :
<code bash>
sudo ./trex-console
</code>

==== 9.3. Gestion des Ports et Mode Service ====

Ces commandes sont executees directement a l'interieur de trex-console :

Acquerir le controle exclusif des ports de test :
  acquire

Activer le Mode Service (necessaire pour le trafic ARP et de controle) :
  service

Activer le mode Promiscuous (promiscuite) sur tous les ports :
  portattr -a --prom on

Desactiver le Mode Service (retour au mode haute performance) :
  service --off

==== 9.4. Lancement et Arret du Trafic IMIX ====

Lancer le trafic IMIX a un taux de 10 000 PPS sur le Port 0 :
  start -f stl/imix.py -m 10kpps --port 0

Lancer le trafic IMIX a un taux de 10 000 PPS sur le Port 1 :
  start -f stl/imix.py -m 10kpps --port 1

Arreter la generation de trafic sur le Port 0 :
  stop --port 0

Arreter la generation de trafic sur le Port 1 :
  stop --port 1

Arreter la generation sur les Ports 0 et 1 simultanement :
  stop --port 0 1

==== 9.5. Visualisation des Statistiques en Console ====

Ouvrir l'interface utilisateur textuelle (TUI) en temps reel :
  tui

Afficher un tableau recapitulatif instantane des compteurs :
  stats

==== 9.6. Profils Avances et Tests L3 (Routage SRX) ====

Ces commandes simulent des flux IP traversant votre equipement Juniper SRX300.

Gaspillage de bande passante UDP (Port 0 uniquement, trames de 512 octets) :
  start -f stl/udp_1pkt-jo1.py -m 960mbps --port 0 -t fsize=512

Test UDP bidirectionnel a 985 Mbps (Trames de 1518 octets) :
  start -f stl/udp_1pkt-jo1.py -m 985mbps --port 0 1 -t fsize=1518

Simulation de flux UDP Route (L3) a 960 Mbps de Port 0 a Port 1 :
  start -f stl/udp_1pkt-l3.py -m 960mbps --port 0 -t fsize=1518,src_ip=192.168.100.11,dst_ip=192.168.101.12

Simulation de flux TCP Route (L3) a 960 Mbps de Port 0 a Port 1 :
  start -f stl/tcp_1pkt-l3.py -m 960mbps --port 0 -t fsize=1518,src_ip=192.168.100.11,dst_ip=192.168.101.12

Simulation de flux TCP Route (L3) a 960 Mbps de Port 1 a Port 0 :
  start -f stl/tcp_1pkt-l3.py -m 960mbps --port 1 -t fsize=1518,src_ip=192.168.101.12,dst_ip=192.168.100.11