serv_benchmark/docs/FEATURE_PROXMOX_DETECTION.md

# Détection environnement Proxmox

**Date:** 2026-01-10
**Version script:** 1.5.0
**Type:** Feature

## Problème

Les systèmes Proxmox VE sont basés sur Debian, donc la détection OS standard affiche simplement "debian" sans distinction entre :
- Un serveur Proxmox VE (hôte hyperviseur)
- Une VM hébergée sur Proxmox
- Un conteneur LXC Proxmox
- Un système Debian standard

## Solution

Ajout d'une détection complète Proxmox dans le script `bench.sh` avec trois nouveaux indicateurs :

### Nouveaux champs collectés

1. **`is_proxmox_host`** (boolean)
   - `true` si le système est un hôte Proxmox VE
   - `false` sinon

2. **`is_proxmox_guest`** (boolean)
   - `true` si le système est une VM ou conteneur hébergé sur Proxmox
   - `false` sinon

3. **`proxmox_version`** (string)
   - Version de Proxmox VE (ex: "8.1.3")
   - Uniquement pour les hôtes Proxmox

4. **`virtualization_type`** (string)
   - Type de virtualisation détecté : `kvm`, `qemu`, `lxc`, `none`, etc.

## Méthodes de détection

### 1. Détection hôte Proxmox

Le script vérifie si le système EST un serveur Proxmox :

```bash
# Méthode 1 : Commande pveversion
if command -v pveversion &>/dev/null; then
    is_proxmox_host="true"
    proxmox_version=$(pveversion 2>/dev/null | grep 'pve-manager' | awk '{print $2}')
fi

# Méthode 2 : Présence du dossier de config Proxmox
if [[ -d /etc/pve ]]; then
    is_proxmox_host="true"
fi
```

**Indicateurs :**
- Commande `pveversion` disponible
- Dossier `/etc/pve` existe (configuration cluster Proxmox)

### 2. Détection guest Proxmox

Le script détecte si le système tourne DANS une VM/conteneur Proxmox :

```bash
# Détection virtualisation
virtualization_type=$(systemd-detect-virt 2>/dev/null || echo "none")

# Si KVM/QEMU détecté
if [[ "$virtualization_type" == "kvm" || "$virtualization_type" == "qemu" ]]; then
    # Vérifier QEMU Guest Agent (installé par défaut sur VM Proxmox)
    if command -v qemu-ga &>/dev/null || systemctl is-active qemu-guest-agent &>/dev/null; then
        is_proxmox_guest="true"
    fi

    # Vérifier DMI pour indicateurs Proxmox/QEMU
    dmi_system=$(sudo dmidecode -t system 2>/dev/null | grep -i "manufacturer\|product")
    if echo "$dmi_system" | grep -qi "qemu\|proxmox"; then
        is_proxmox_guest="true"
    fi
fi

# Si conteneur LXC détecté
if [[ "$virtualization_type" == "lxc" ]]; then
    is_proxmox_guest="true"  # Probablement un CT Proxmox
fi
```

**Indicateurs :**
- Type virtualisation : `kvm`, `qemu`, `lxc`
- Agent QEMU guest présent
- DMI system contient "QEMU" ou "Proxmox"

## Affichage dans le script

Lors de l'exécution du benchmark, les informations Proxmox sont affichées :

```
✅ Collecte des informations système de base
Hostname: debian-vm
OS: debian 13 (trixie)
Kernel: 6.12.57+deb13-amd64
💠 VM/Conteneur Proxmox détecté (type: kvm)
```

Ou pour un hôte Proxmox :

```
Hostname: pve-host
OS: debian 12 (bookworm)
Kernel: 6.8.12-1-pve
🔷 Proxmox VE Host détecté (version: 8.1.3)
```

## Structure JSON collectée

Le script génère un objet JSON `virtualization` dans `SYSTEM_INFO` :

```json
{
  "hostname": "debian-vm",
  "os": {
    "name": "debian",
    "version": "13 (trixie)",
    "kernel_version": "6.12.57+deb13-amd64",
    "architecture": "x86_64"
  },
  "virtualization": {
    "is_proxmox_host": false,
    "is_proxmox_guest": true,
    "proxmox_version": "",
    "virtualization_type": "kvm"
  }
}
```

## Stockage base de données

### Migration 017

Ajout de 3 nouvelles colonnes à `hardware_snapshots` :

```sql
ALTER TABLE hardware_snapshots ADD COLUMN is_proxmox_host BOOLEAN DEFAULT FALSE;
ALTER TABLE hardware_snapshots ADD COLUMN is_proxmox_guest BOOLEAN DEFAULT FALSE;
ALTER TABLE hardware_snapshots ADD COLUMN proxmox_version TEXT;
```

### Modèle SQLAlchemy

```python
# app/models/hardware_snapshot.py
is_proxmox_host = Column(Boolean, nullable=True)
is_proxmox_guest = Column(Boolean, nullable=True)
proxmox_version = Column(String(100), nullable=True)
```

### Schéma Pydantic

Nouvelle classe `VirtualizationInfo` :

```python
# app/schemas/hardware.py
class VirtualizationInfo(BaseModel):
    is_proxmox_host: bool = False
    is_proxmox_guest: bool = False
    proxmox_version: Optional[str] = None
    virtualization_type: Optional[str] = None
```

Et ajout dans `HardwareData` :

```python
class HardwareData(BaseModel):
    cpu: Optional[CPUInfo] = None
    ram: Optional[RAMInfo] = None
    # ...
    virtualization: Optional[VirtualizationInfo] = None
```

## Extraction backend

Dans `app/api/benchmark.py`, extraction des données virtualization :

```python
# Virtualization (support both old and new format)
if hw.virtualization:
    snapshot.virtualization_type = hw.virtualization.virtualization_type
    snapshot.is_proxmox_host = hw.virtualization.is_proxmox_host
    snapshot.is_proxmox_guest = hw.virtualization.is_proxmox_guest
    snapshot.proxmox_version = hw.virtualization.proxmox_version
elif hw.os and hw.os.virtualization_type:
    # Fallback for old format
    snapshot.virtualization_type = hw.os.virtualization_type
```

## Cas d'usage

### 1. Identifier les hôtes Proxmox dans l'inventaire

```sql
SELECT hostname, os_name, proxmox_version
FROM hardware_snapshots
WHERE is_proxmox_host = 1;
```

Résultat :
```
hostname       | os_name  | proxmox_version
---------------|----------|----------------
pve-host-01    | debian   | 8.1.3
pve-host-02    | debian   | 8.0.4
```

### 2. Lister les VM Proxmox

```sql
SELECT hostname, virtualization_type
FROM hardware_snapshots
WHERE is_proxmox_guest = 1;
```

Résultat :
```
hostname       | virtualization_type
---------------|--------------------
debian-vm      | kvm
ubuntu-ct      | lxc
```

### 3. Distinguer Debian standard vs Proxmox

```sql
SELECT
    hostname,
    CASE
        WHEN is_proxmox_host = 1 THEN 'Proxmox Host'
        WHEN is_proxmox_guest = 1 THEN 'Proxmox Guest'
        ELSE 'Debian Standard'
    END as type
FROM hardware_snapshots
WHERE os_name = 'debian';
```

## Référence technique

### systemd-detect-virt

Outil systemd pour détecter la virtualisation :

```bash
$ systemd-detect-virt
kvm

$ systemd-detect-virt --container
none
```

**Valeurs possibles :**
- `kvm` - VM KVM (Proxmox utilise KVM)
- `qemu` - Émulation QEMU
- `lxc` - Conteneur LXC (Proxmox CT)
- `vmware` - VMware
- `virtualbox` - VirtualBox
- `xen` - Xen hypervisor
- `docker` - Conteneur Docker
- `none` - Pas de virtualisation

### pveversion

Commande Proxmox pour afficher la version :

```bash
$ pveversion
pve-manager/8.1.3/b46aac3b42da5d15 (running kernel: 6.8.12-1-pve)

$ pveversion | grep pve-manager
pve-manager/8.1.3/b46aac3b42da5d15
```

### dmidecode -t system

Informations DMI du système :

```bash
$ sudo dmidecode -t system
System Information
    Manufacturer: QEMU
    Product Name: Standard PC (Q35 + ICH9, 2009)
    Version: pc-q35-8.1
```

Sur une VM Proxmox, on voit typiquement "QEMU" comme fabricant.

## Avantages

### 1. Distinction claire des environnements

✅ **Avant :** Tous les systèmes Debian affichaient simplement "debian"
✅ **Après :** Distinction entre hôte Proxmox, guest Proxmox, et Debian standard

### 2. Inventaire précis

✅ Savoir quels serveurs sont des hyperviseurs Proxmox
✅ Identifier les VM/CT hébergés sur Proxmox
✅ Suivre les versions de Proxmox déployées

### 3. Optimisations futures

✅ Benchmarks adaptés (VM vs bare metal)
✅ Métriques spécifiques Proxmox (QEMU agent)
✅ Alertes sur versions Proxmox obsolètes

## Rétrocompatibilité

✅ **Anciens benchmarks** : Nouveaux champs NULL, pas d'impact
✅ **Ancien format JSON** : Le backend supporte l'ancien format avec `os.virtualization_type`
✅ **Nouveaux benchmarks** : Utilise le nouveau format avec objet `virtualization`

## Tester la détection

### Sur une VM KVM

```bash
sudo systemd-detect-virt
# kvm

sudo dmidecode -t system | grep -i manufacturer
# Manufacturer: QEMU

systemctl is-active qemu-guest-agent
# active (si installé)
```

### Sur un hôte Proxmox

```bash
command -v pveversion
# /usr/bin/pveversion

pveversion
# pve-manager/8.1.3/...

ls /etc/pve
# authkey.pub  ceph.conf  corosync.conf  ...
```

### Sur Debian standard

```bash
systemd-detect-virt
# none

command -v pveversion
# (vide, pas de sortie)
```

## Fichiers modifiés

1. **scripts/bench.sh**
   - Ajout fonction `detect_proxmox()` (lignes 268-322)
   - Intégration dans `collect_system_info()` (ligne 343)
   - Affichage des infos Proxmox (lignes 415-426)
   - Ajout objet `virtualization` dans JSON (ligne 407)

2. **backend/migrations/017_add_proxmox_fields.sql**
   - Migration BDD pour nouveaux champs

3. **backend/apply_migration_017.py**
   - Script d'application migration 017

4. **backend/app/models/hardware_snapshot.py**
   - Ajout colonnes BDD (lignes 70-72)

5. **backend/app/schemas/hardware.py**
   - Classe `VirtualizationInfo` (lignes 123-128)
   - Ajout dans `HardwareData` (ligne 191)

6. **backend/app/api/benchmark.py**
   - Extraction données virtualization (lignes 133-141)

## Voir aussi

- [BENCH_SCRIPT_VERSIONS.md](BENCH_SCRIPT_VERSIONS.md) - Historique versions script
- [systemd-detect-virt man page](https://www.freedesktop.org/software/systemd/man/systemd-detect-virt.html)
- [Proxmox VE Documentation](https://pve.proxmox.com/wiki/Main_Page)

---

**Auteur:** Claude Code
**Version:** 1.0