The idea is simple:

• When the printer is connected, the container starts.
• When the printer is disconnected, the container stops.
• A stable device symlink is created for the printer inside Docker.

This is useful when you only want OctoPrint running while the printer is actually present.

OctoPrint Docker Setup

First, make sure OctoPrint runs in Docker and that the printer device is exposed to the container.

A typical Docker setup looks like this:

services:
  octoprint:
    # You should not use :latest as it may cause problems on update with your data
    # prefer updating within the UI, and then update the version here 
    image: octoprint/octoprint:1.10
    container_name: octoprint
    restart: unless-stopped
    ports:
      - 5000:80
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
      - /dev/video0:/dev/video0
    volumes:
      - ./config:/octoprint
      - ./data:/octoprint/data

The important part is the device mapping:

• /dev/ttyUSB0 is the device name for the printer USB port
• /dev/video0 is the device name for the camera USB port ; remove it if you don’t need it

You can adapt the internal device path if your OctoPrint configuration expects something else.

Rules udev on host

Create the file /etc/udev/rules.d/90-docker-octoprint.rules with the following content:

# This is the Creality Ender 3v2 printer mapped into the Octoprint container
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", ACTION=="add",  SYMLINK+="docker/ender"
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", ACTION=="add",  RUN+="/usr/bin/docker start octoprint"
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", ACTION=="remove", RUN+="/usr/bin/docker stop octoprint"

The USB identifiers here match the common CH340-based adapter used by the Creality Ender 3 V2. You may need to change this according to your printer (use lsusb to see the vendor:product identifiers)

This rule does three things:

• Creates /dev/docker/ender when the printer is detected.
• Starts the Docker container on plug-in.
• Stops the Docker container on unplug.

After adding the rule, reload udev with systemctl restart udev, then reconnect the printer to test the rule.

If something does not work, enable debug logging and watch the journal: udevadm control --log-priority=debug && journalctl -f ; plug and unplug the printer while watching the logs. This usually helps confirm whether the device is detected and whether the Docker commands are triggered.

Proxmox USB hotplug setup

You can use Proxmox USB device mapping to pass the printer and camera USB. Once the VM is launched, and if you have defined USB as hotplug, it will work as expected. But doing so requires that the USB devices exist to start the VM, else the VM will fail to start. In my case this is very annoying.

The solution is to use a hook script. I have used this script already in a few articles as it is very useful in this article to pass USB-IP devices and in this article to add a VNC password after the VM startup ; here is the script to be created in the snippets folder with executable flag (chmod +x), create the file /var/lib/vz/snippets/hook-hotplug.sh with the following contents:

#!/bin/bash

# From Perplexity: hook script pour proxmox qui ajoute dans le qm monitor 
# après le démarrage le contenu du fichier à .hotplug.conf 
# à coté du fichier de configuration de la VM

# Installation
# - chmod +x 
# - copy dans /var/lib/vz/snippets
# - ajouter dans la VM avec: qm set <VMID> --hookscript local:snippets/hook-hotplug.sh

# Variables transmises par Proxmox à chaque appel hook
VMID="$1"
PHASE="$2"

# Chemin du fichier de hotplug à appliquer si présent
HOTPLUG_CONF="/etc/pve/qemu-server/${VMID}.hotplug.conf"

# Lancement après démarrage effectif
if [ "$PHASE" = "post-start" ] && [ -f "$HOTPLUG_CONF" ]; then
    # Lire chaque ligne et l’injecter dans le monitor QEMU de la VM
    while IFS= read -r line; do
        # On ignore les lignes vides ou commentaires (#)
        [[ "$line" =~ ^#.*$ || -z "$line" ]] && continue
        # Injecte la commande dans qm monitor
        echo "$line" | qm monitor "$VMID"
    done < "$HOTPLUG_CONF" >> /var/log/hook-hotplug.log 2>&1
fi

And to use it, put in each VM you want the following line:

hookscript: local:snippets/hook-hotplug.sh  

This script is triggered by the eventpost-start emitted at the end of the startup of the VM, will read the hotplug configuration file <vmid>.hotplug.conf next to the VM configuration, and will send it to the QEMU Monitor interface.

In our case: /etc/pve/qemu-server/<vmid>.hotplug.conf

device_add usb-host,vendorid=0x1a86,productid=0x7523,id=print3d
device_add usb-host,vendorid=0x1908,productid=0x2311,id=webcamrouge

Conclusion

With this setup:

• Plug the printer in, and OctoPrint starts automatically.
• Unplug the printer, and OctoPrint stops cleanly.
• The printer is exposed through a stable device name.

This keeps the system lightweight and avoids running OctoPrint when the printer is not connected.

Pourquoi ?

Mon serveur sous Linux s’était construit au fil du temps, de mon premier PC il y a plus de 20 ans à l’école, mis dans un placard plus tard pour en faire en serveur, et en lui ajoutant au fil du temps différentes fonctions et logiciels. Le résultat était devenu une accumulation qui n’était plus très maîtrisée de scripts, de batch cron, de services que j’utilise tous les jours, au milieu de différentes expérimentations et de mon desktop Linux me servant également d’environnement de développement. Chaque montée de version de debian était un défi, et si généralement la première se passait bien, la suivante posait problème sur certaines subtilités et j’avais à réinstaller en urgence, avec la difficulté de ne rien oublier… Avec les solutions actuelles de virtualisation et de containérisation, il était temps de restructurer et rationaliser.

Cette situation n’avait cependant pas que des inconvénients, dans les avantages :

• cette architecture “monolithique” était très performante pour optimiser l’usage des ressources physiques limitées de mon serveur, car l’intégralité des ressources CPU et mémoire était disponible pour tous les services, sans segmentation, sans overhead
• même chose pour les accès aux disques, tous les services ont accès au matériel avec des IOs optimales
• quasiment tous les services étaient installés depuis les paquets debian, la mise à jour était ainsi très simple, avec une gestion des mises à jour très simple à faire

C’est ce qui a fait que la migration a déjà pris du temps à concevoir, pour trouver la bonne architecture cible, puis réaliser la transition. A noter que j’avais tenté une première tentative il y a quelques années, à l’arrache lors d’une réinstallation, et j’avais fini par revenir en arrière car je m’étais retrouvé bloqué par l’absence de réflexion préalable sur l’architecture.

Les étapes suivies

J’ai suivi les étapes suivantes :

1. Des expérimentations sur machine virtuelle sur mon PC pour choisir les solutions principales
2. Recenser tous les services dont je me sers, choisir ce que je conserve et ce que j’abandonne, et voir dans quel environnement je les positionne (container, VM,…)
3. Commencer à migrer en container petit à petit mes services en docker sur le serveur précédent
4. Installer Proxmox sur mon serveur debian actuel, Proxmox est basé sur debian et il est possible de l’ajouter sur une debian existante ; cette étape permet de poursuivre la migration petit à petit, en migrant sur VM
5. Installer Proxmox en standalone sur un nouveau disque, en maintenant un double boot pour revenir en arrière tant que ce n’est pas finalisé
6. Basculer sur la nouvelle architecture
7. Finaliser avec toutes les améliorations (notamment l’ajout d’un idp, de l’authentification, du routage https, des backups…)

On peut aussi prendre une image du serveur précédent et le faire tourner en VM (qemu-img convert -O qcow2 /dev/nvme0n1p5 /mnt//images/100/old-server.qcow2, désactiver le secure-boot, créer une nouvelle VM debian, ajouter le disque, le mettre en premier, booter, chroot, et réinstaller le boot avec pve-efiboot-tool)

Les solutions et l’architecture retenue

Hyperviseur Proxmox

Proxmox VE, solution open source populaire, basée sur debian dont j’ai l’habitude, avec un modèle économique entreprise et une bonne communauté ; en alternatives Xen ne m’avait pas convaincu en test, et coté VMware, même si plus facile à utiliser, n’est pas libre (avec les changements de politique suite au rachat par Broadcom, je suis content de ne pas avoir fait le choix de VMWare…)

NAS et Docker dans une VM Debian

Eh oui, encore et toujours debian depuis 25 ans :) j’étais plutôt parti initialement sur utiliser OpenMediaVault ou TrueNAS, que j’ai essayé pendant plusieurs semaines, mais pas vraiment moderne et assez limité pour le premier, et également un peu rigide pour le second, avec des doutes sur la pérennité de la gratuité ; ce sera donc debian, mais avec un maximum sous docker et en limitant son paramétrage local (et en notant tout, dans la perspective de scripter l’installation de la VM plus tard) ; j’espère qu’une solution type NixOS se développera sur debian pour pouvoir avoir une configuration scriptée et complètement reproductible (en fait, il y a déjà des tentatives, mais qui ne me semblaient pas encore assez matures).

Stockage en passthrough PCI

Un point qui m’a bloqué pendant longtemps, j’ai en gros un stockage SSD pour le quotidien et des disques en raid logiciel pour le stockage. Mes exigences sont que ces stockages restent directement lisibles en cas de crash, sans utiliser des filesystems virtuels ou autres, et que les performances soient décentes.

Expérimental avec Proxmox 8, virtiofs devient facile à utiliser avec Proxmox 9. J’étais donc parti sur cette option avec le hardware géré par Proxmox et les dossiers montés dans chaque VM suivant les besoins, mais la compatibilité avec notamment Docker, Samba, et NFS n’était pas bonne. Mauvaise piste… Par ailleurs le fait que le stockage soit directement traité par proxmox ne me plaisait pas non plus, car lorsque les disques en raid ont des problèmes (et ça arrive plus souvent qu’on voudrait…), cela bloque potentiellement tout le boot, avec besoin se connecter physiquement.

J’ai finalement pensé au passthrough PCI :

• d’une part pour passer un SSD NVMe (et donc PCI), à la VM server ; comme il n’est pas possible de le couper en deux, j’ai donc ajouté un NVMe : 1 pour les VMs géré par Proxmox, et 1 autre pour le stockage quotidien géré par la VM Server
• d’autre part pour passer le contrôleur SATA de ma carte mère, et que les disques durs SATA soient directement gérés par la VM Server ; et après 15 ans d’usage du raid logiciel mdadm avec une très grande résilience (le raid m’a sauvé plusieurs fois, y compris les fonctions de récupération robustes de mdadm, par contre ext4fs a eu quelques corruptions…), j’ai cédé aux sirènes de ZFS. J’espère que je n’aurai pas à le regretter…

La VM Server fera serveur de fichiers, avec Samba pour l’usage bureautique, et NFS pour partager avec les autres VMs.

Home Assistant OS en VM

J’avais commencé ma migration de domoticz vers Home Assistant en docker, cependant on perd beaucoup à ne pas utiliser la version VM Home Assistant OS avec les mises à jour facile et les apps/addons qui permettent d’étendre les fonctions avec des dockers directement gérés par Home Assistant OS. Cette VM est parfaitement bien prévue, avec les mises à jour et les backups automatiques distants.

Routage et VPN avec OPNsense

J’ai testé différents routeurs, soit en virtuel en VM ou en physique avec un firmware custom comme OpenWRT. OPNsense correspond parfaitement à ce que je cherchais, très riche en fonctionnalités, très facile à utiliser avec son IHM simple, et extensible avec les plugins. Il permet de couvrir les fonctions de firewall, de VPN et de proxy dont j’ai besoin.

Le maximum de services en docker

Pour que chaque service intègre ses propres dépendances et découpler au maximum les services, les containers sont l’idéal.

Pour en faciliter la gestion, j’ai fait le choix de :

• déployer uniquement avec docker compose en fichier yaml, notamment à l’aide de Portainer au début, et Dockhand maintenant
• stocker les configurations et les volumes à conserver en répertoires absolus dans le système de fichier de l’hôte (et non perdu dans l’arborescence docker de la VM)
• sélectionner avec soin les images docker à utiliser, en évitant les exotiques non maintenues ou risquées
• pour mes scripts maison, de créer des scripts de setup à partir d’une base docker debian-slim plutôt que des Dockerfile à reconstruire, pour bénéficier des mises à jour sans avoir à mettre en place une CI complète sur les Dockerfile

J’ai ainsi actuellement une cinquantaine de containers en une trentaine de stacks, et notamment :

• Dockhand pour l’administration de l’ensemble docker (stacks, logs, mises à jour automatiques,…)
• Ofelia pour l’orchestration des batchs ; j’ai essayé beaucoup d’alternatives, sans trouver la solution qui me convienne parfaitement en simplicité et interface, mais après avoir appris à utiliser ofelia, j’en suis très content ; j’ai également quelques conteneurs customs qui intègrent directement leur cron locale
• duplicati pour les sauvegardes, avec rclone pour des destinations non supportées
• syncthing pour la synchronisation entre les différents PC et le serveur
• Traefik, PocketID, TinyAuth pour la sécurisation (voir l’article dédié sur la sécurisation de l’infrastructure)
• et en vrac, Gogs, LanguageTool, MiniDLNA, Scrutiny

Des dockers VNC pour administrer

La ligne de commande c’est sympa, mais les interfaces graphiques aussi. Pour pouvoir administrer le serveur, que ce soit pour l’édition des fichiers de configuration ou également pour gérer les fichiers en direct, j’avais initialement prévu une VM GUI, sous debian avec interface graphique et en montant les répertoires en NFS. C’est lourd et pas très pratique. Une excellente alternative est de créer un docker qui créé un serveur VNC.

Voici un exemple de docker-compose (il existe une image docker sur le même principe consol/debian-xfce-vnc) :

services:
  vnc:
    image: debian
    restart: unless-stopped
    container_name: server-vnc
    mem_limit: 2g
    environment:
      HOME_DIR: /home
      USERNAME: username
      PASSWORD: xxxxxx
      UID: 1000
      GID: 1000
      VNC_PASSWORD: yyyyyyy
      VNC_OPTIONS: -geometry 1600x1000
    ports:
      - "5900:5900"
    command: 
      - bash
      - -c
      - |
        # Escape $ to $$
        if ! id -u "$${USERNAME}" > /dev/null 2>&1; then
          echo "Création de l'utilisateur '$${USERNAME}' ..."
          groupadd -g "$${GID}" "$${USERNAME}"
          useradd -m -u "$${UID}" -g "$${GID}" -d "$${HOME_DIR}" -s /bin/bash -p "$$(mkpasswd -m sha-512 $${PASSWORD})" "$${USERNAME}"
          mkdir -p "$${HOME_DIR}"
          chown -R "$${UID}:$${GID}" "$${HOME_DIR}"
        else
          echo "L'utilisateur $${USERNAME} existe déjà."
        fi
        unset PASSWORD

        echo 'Setting up container...'
        
        export DEBIAN_FRONTEND=noninteractive
        
        echo "locales locales/locales_to_be_generated multiselect fr_FR.UTF-8 UTF-8" | debconf-set-selections
        echo "locales locales/default_environment_locale select fr_FR.UTF-8" | debconf-set-selections
        echo "localepurge localepurge/multiselect multiselect fr en" | debconf-set-selections
        echo "keyboard-configuration  keyboard-configuration/xkb-keymap select fr" | debconf-set-selections
        echo "keyboard-configuration  keyboard-configuration/layoutcode string fr" | debconf-set-selections
        echo "keyboard-configuration  keyboard-configuration/layout toggle" | debconf-set-selections 
        
        apt-get update
        apt-get install -y unattended-upgrades \
        	tigervnc-standalone-server tigervnc-tools \
        	locales localepurge keyboard-configuration tzdata \
        	lxqt-core openbox dbus-x11 xdg-user-dirs \
        	screen symlinks nano scite ncdu \
        	qterminal pcmanfm-qt qdirstat \
            \
            sudo vlc wget baobab chromium
        
        apt-get remove -y xfwm4 upower xscreensaver
        apt-get autoremove -y
        apt-get clean

        ln -sf /usr/share/zoneinfo/Europe/Paris /etc/localtime
        dpkg-reconfigure -f noninteractive tzdata

        usermod -aG sudo $${USERNAME}

        echo "Write xstartup"
        echo '
          export LANG=fr_FR.utf8
          export LANGUAGE=fr_FR:fr
          export LC_ALL=fr_FR.utf8
          export SHELL=/bin/bash
          
          unset SESSION_MANAGER
          vncconfig -nowin &
          xhost +
          setxkbmap fr
          
          (sleep 5 && pcmanfm-qt /home ) &
          startlxqt
        ' > /xstartup
        chmod a+rx xstartup

        echo "Switching to user $${USERNAME}"
        su --preserve-environment "$${USERNAME}" -c '

          export HOME=$${HOME_DIR}
  
          write_conf_file() {
             mkdir -p $$(dirname "$$1")
             [ ! -f "$$1" ] && echo -e "$$2" > "$$1"
          }
          
          write_conf_file "$${HOME_DIR}/.config/lxqt/lxqt.conf" "[General]\ntheme=light\n" 
          
          echo "Starting VNC server..."
          echo -e "$${VNC_PASSWORD}\n$${VNC_PASSWORD}\n" | tigervncpasswd $${HOME_DIR}/.vnc_passwd
          unset VNC_PASSWORD
          tigervncserver :2 -fg -localhost no -passwd $${HOME_DIR}/.vnc_passwd -xstartup /xstartup $${VNC_OPTIONS}
        '
    volumes:
      - /docker/vnc/home:/home
      - /:/mnt/host

J’utilise comme client VNC RealVNC Viewer en version 7 (version Classic dont le téléchargement semble malheureusement réduit maintenant), qui fonctionne très bien en enregistrement de sessions, restauration de connectivité en sortie de veille, et gestion des copier/coller.

Il est possible d’avoir le même principe sous RDP avec xrdp.

Autres machines virtuelles

• une VM Linux pour avoir un desktop pour le dev, l’idée est d’en faire un template et d’instancier par projet ou réinitialisation
• une VM Lab pour avoir un environnement desktop qui me serve de lab pour tester des nouveautés sans pourrir le serveur
• une VM Windows pour avoir un desktop de secours, accessible avec Remote Desktop Protocol de Windows, en cas de problème avec mon PC portable (setup comparable)

Autres détails

Pour des sauvegardes automatiques long terme, la VM Server expose en NFS à Proxmox un dossier qui est monté en storage pour être une destination de backup.

Ressources utiles

Autres articles LPRP.fr liés à la migration Proxmox

• Sécuriser votre infrastructure maison avec Proxmox, OPNsense, Traefik, Home Assistant et PKI XCA
• USB d’un PC Windows distant dans une VM Proxmox via USB-IP
• Proxmox - Réduire la taille d’un disque
• Accès distant VNC avec Proxmox/QEMU

Documentations

• Documentation Proxmox
• Proxmox Helper Scripts

Trucs et astuce pour Proxmox

• Pour utiliser la console xterm.js et ses copier/coller facilités, il faut ajouter une console série dans hardware et ajouter dans /etc/default/grub: GRUB_CMDLINE_LINUX="console=tty0 console=ttyS0,115200" et GRUB_TERMINAL="console serial"
• Hotplug automatique via Proxmox, voir le hookscript de cet article
• Eviter de passer par un cluster pour migrer d’une instance Proxmox à une autre ; le mode cluster n’est pas prévu pour fonctionner avec 2 serveurs ; il existe maintenant Proxmox Datacenter Manager qui devrait être plus adapté (sorti malheureusement après ma migration, donc non testé) ; si vous faites la même erreur que moi, pour forcer la sortie du mode cluster il faut suivre Cluster_Manager / remove_a_cluster_node
• Pour le passthrough PCI il peut être nécessaire de faire des group iommu séparés : /etc/default/grub: GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt pcie_acs_override=downstream,multifunction" pour AMD, ou pour Intel GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt pcie_acs_override=downstream,multifunction" puis update-grub && reboot
• Pour optimiser la consommation électrique : `

  apt install powertop linux-cpupower
  cpupower frequency-set -g powersave
  powertop --auto-tune
  systemctl enable powertop
  

• Pour installer via DKMS des modules noyaux signés compatible avec secure boot (typiquement ZFS pour debian): https://www.linuxtricks.fr/wiki/signer-les-modules-noyau-tiers-dkms-pour-le-secure-boot-sous-linux

Présentation de la stack

La stack s’articule autour de plusieurs briques complémentaires :

• Box opérateur : accès Internet avec NAT IPv4 et firewall IPv6
• Proxmox Firewall : filtre le trafic au niveau des VM et de l’hyperviseur.
• Routeur OPNsense : gère le routage, le proxy HTTPS externe avec LetsEncrypt, et une partie des certificats locaux.
• XCA : sert à créer et administrer l’autorité de certification interne.
• Traefik : reverse proxy pour les services Docker avec SSL.
• TinyAuth + PocketId : brique d’authentification et d’OpenID Connect.
• Nginx Proxy Manager : reverse proxy SSL pour Home Assistant.

Il serait possible d’utiliser des certificats publics LetsEncrypt pour tous, ce qui simplifierait le setup, mais cela impose d’exposer les services internes à l’extérieur (en HTTP ou en DNS). Une autorité de certification interne (AC) permet plus de souplesse, et également de générer des certificats pour des systèmes qui n’ont pas le support LetsEncrypt, avec l’inconvénient de devoir installer le certificat sur tous les appareils et dockers ayant besoin de valider une connexion https avec des certificats issus de cette AC.

Firewall

Box opérateur

Les box opérateurs proposent généralement deux fonctions de protection à utiliser :

• NAT (Network Address Translation, typiquement pour IPv4) : est une première forme de protection, car les ports non exposés sont de facto filtrés ; n’exposez que les ports utiles et sécurisés (typiquement https/443), sur une association fixe (les box modernes permettent souvent d’associer à l’adresse MAC de la cible, pour que ce soit indépendant de l’adresse IP donnée par le DHCP ; si ce n’est pas le cas, configurez votre DHCP ou votre cible pour avoir une IP fixe)
• Firewall (typiquement pour IPv6) : assurez-vous que le firewall est bien actif (souvent par défaut maintenant), sinon vos appareils sont directement tous exposés sur internet en IPv6 ; les accès IPv6 sont maintenant plus courants, vous pouvez également ouvrir les ports que vous avez ouverts en NAT sur les IPv6 concernées

Proxmox Firewall

Le firewall Proxmox sert de premières barrières sur l’infrastructure virtuelle. Il permet de filtrer les accès aux nœuds Proxmox eux-mêmes, mais aussi aux VM comme le routeur OPNsense, le serveur Docker ou Home Assistant.

Il est nécessaire d’activer l’option Firewall à tous les niveaux (Datacenter, nœud et VM) pour que le firewall soit actif. Il est ensuite possible de définir (ou non) des règles de filtrage à chaque niveau. Vous pouvez également définir des politiques de filtrage par défaut, par exemple pour interdire tout trafic par défaut, ou au contraire laisser ouvert. Sur le nœud et le datacenter, Proxmox intègre automatiquement les règles pour ouvrir les ports utiles à la gestion de Proxmox.

Proxmox offre plusieurs options utiles pour définir efficacement vos règles :

• les IPSets permettent de définir des groupes d’adresses IP ou réseaux qui seront utilisables dans les règles par la suite ; j’ai défini par exemple un IPset LAN et LAN-broadcastavec les réseaux IPv4 et IPv6 correspondant, ce qui facilite l’écriture des règles, et leur maintenance si par exemple le préfixe IPv6 change
• les Security Groups permettent de définir des groupes de règles, qu’on pourra ensuite ajouter dans chacun des firewall ; j’ai par exemple défini des groupes générique lan-genericet lan-mdns avec des règles par défaut, que je peux activer sur chaque VM si j’ai besoin d’un filtrage LAN classique, d’ajouter le support UPNP / discovery, etc. La prise en compte des modifications nécessite parfois de décocher / cocher le security group sur la VM.

Enfin, sur une VM donnée, pour identifier les ports réellement écoutés et potentiellement candidats à être ouverts, une commande utile est ss -tulnrp qui permet de lister tous les ports TCP ou UDP exposés, et par quel processus (Si la commande n’est pas disponible, sous debianapt install iproute2). Tous n’ont bien sûr pas vocation à être exposés, mais cela permet d’étudier chaque port et d’éviter d’en oublier.

Routeur OPNsense

En plus du premier filtrage de la box opérateur, j’ai choisi d’ajouter une seconde couche de sécurité via un routeur OPNsense. C’est notamment utile pour ajouter une couche de sécurité et utiliser des fonctions de filtrage IP par des blacklists communautaires, des règles de filtrage plus avancées, etc. Et bien sûr, il intègre des fonctions de routeur avancé que nous ne traiterons pas ici.

Le principe est de déclarer deux interfaces réseaux sur la VM OPNsense :

• une interface WAN : c’est sur cette interface qu’on fera pointer nos règles NAT ou notre exposition externe, et sur cette interface que nous définirons nos règles firewall
• une interface LAN : c’est via cette interface qu’on proxifiera les services exposés

Proxy HTTPS

Gestion des certificats avec XCA et OPNsense

XCA sert à gérer l’autorité de certification interne. C’est la brique qui permet de créer votre autorité de certification racine (AC), d’émettre les certificats internes et d’organiser leur cycle de vie. C’est une application desktop disponible pour Windows, Mac et Linux (selon la distribution, ou en compilation)

J’ai opté pour la logique suivante :

• une AC root définies dans XCA ; qui permet de gérer certains certificats en direct dans XCA
• une AC secondaire gérée par OPNsense ; il faut créer cette AC dans XCA, puis l’importer dans OPNsense ; OPNsense pourra ensuite l’utiliser et signer de nouveaux certificats avec cette AC secondaire, qui sera automatiquement reconnu dans la mesure où on a installé l’autorité racine
• un certificat wildcard pour le server docker exposé par Traefik (ce n’est pas une bonne pratique, mais suffisant pour mon cas)

Un point d’attention dans OPNsense dans la gestion des certificats, il faut déclarer uniquement les noms de domaines (en CN ou en SAN) que doivent gérer ces certificats, et ne pas inclure des noms de domaine destinés à Let’s Encrypt, car dès que Caddy trouve un certificat qui correspond, il prendra celui là et n’en demandera pas à Letsencrypt, même si les options “Auto HTTPS” sont activées.

Les champs à bien remplir pour des certificats correctement retenus :

• CN (Common Name) : l’adresse DNS principale sécurisée (l’adresse seule, sans le préfixe https)
• Extension SAN (Subject Alternative Names), en cochant critical : toutes les adresses DNS et/ou IP qui peuvent être utilisées avec ce certificat (toujours les adresses seules, mais vous pouvez utiliser un wildcard *.madns.com)
• Key Usage, en cochant critical : Digital Signature, Key Encipherment
• Extended Key Usage : TLS Web Server Authentication, TLS Web Client Authentication
• et n’oubliez pas bien sûr de créer une clé privée, sélectionner la signature par la bonne AC et ajuster la durée de validité selon votre convenance

Caddy pour OPNsense

Comme proxy HTTPS, j’utilise caddy, qui est très bien intégré dans OPNsense, avec une interface complète et facile à utiliser, et la possibilité de demander automatiquement des certificats ACME/LetsEncrypt, ou des certificats locaux via la gestion des certificats intégrée à OPNsense, et très pratique également.

Si vous souhaitez rediriger vers des DNS pointant vers des IP locales définies avec un DNS qui ne serait pas géré par OPNsense (comme OVH, Cloudflare, etc. si vous avez un domaine personnalisé), il vous faudra les déclarer également dans OPNsense, car par défaut pour des raisons de sécurité, OPNsense interdit des adresses DNS qui se résolvent sur une IP locale. Il faut alors les déclarer dans Unbound DNS / Contournements.

Traefik pour les containers docker

Il serait possible d’utiliser seulement Caddy comme proxy https, en exposant sur le réseau interne tous les ports http des containers docker. Le problème est que cela ne permettrait pas de les protéger des autres périphériques connectés sur votre réseau local (y compris les IoT type prises connectées ou autres qui ouvrent un tunnel avec leur cloud et peuvent présenter des risques de sécurité), ni de les protéger par l’authentification qui sera ajoutée ensuite.

L’usage de traefik permet ainsi d’avoir un autre étage de proxy SSL au niveau du server docker, et de n’ouvrir au niveau du firewall que le port https. Si on cumule avec caddy pour l’exposition externe on aura donc :

• pour les services externes : Internet –> Box (NAT / Firewall) –> Caddy/OPNsense (Firewall + SSL avec Letsencrypt) –> VM Docker (Firewall Proxmox) –> Traefik (SSL avec AC interne et authentification) –> service docker
• pour les services internes, on aura seulement : LAN –> VM Docker (Firewall Proxmox) –> Traefik (SSL avec AC interne et authentification) –> service docker

L’utilisation de Traefik est particulièrement pratique avec docker compose. Pour sécuriser, on va déclarer un réseau proxy qui sera partagé entre traefik et les différents containers. Si on veut sécuriser encore plus, et éviter qu’un service docker compromis puisse accéder à d’autres services docker sans sécurisation, on peut créer un réseau dédié pour chaque service docker proxy_xxx.

Exemple de docker compose pour Traefik :

services:
  traefik:
    image: traefik
    restart: always
    command:
      - "--providers.docker=true"
      - "--providers.docker.watch=true"
      - "--providers.docker.exposedByDefault=false"
      - "--providers.docker.network=proxy"
      - "--providers.file.filename=/config/dynamic.yml"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--api.dashboard=true" # Pour l'interface graphique
    ports:
      - "80:80"
      - "443:443"
    networks: ["proxy"]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /docker/auth/traefik-config:/config
      - /docker/auth/traefik-certs:/certs

networks:
  proxy:
    external: true

Notez "--providers.docker.network=proxy" qui permet d’indiquer à traefik quelle IP sélectionner pour les containers qui ont plusieurs networks.

Fichier `dynamic.yml:

tls:
  stores:
    default:
      defaultCertificate:
        certFile: /certs/wildcard.crt
        keyFile: /certs/wildcard.key

  options:
    default:
      minVersion: VersionTLS12

serversTransport:
  insecureSkipVerify: false   # Optionel, utile pour router vers du HTTPS autosigné

wildcard.crt et wildcard.keysont le certificat wildcard et la clé privée générée par XCA pour ce server, et exporté au format PEM.

Sur chaque docker, on pourra ajouter :

# dans le service
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.monservice.rule=Host(`monservice.customdns`)
      - traefik.http.routers.monservice.tls=true
      # Si le port n'est pas directement déductible par Traefik
      #- traefik.http.services.monservice.loadbalancer.server.port=80
      
networks:
  proxy:
    external: true

Si plusieurs services doivent partager un réseau commun sans pour autant le partager avec tout le monde (comme par exemple entre un backend et sa base de données), vous pouvez ajouter un réseau internal, le déclarer sur chacun des containers concernés.

Et comme l’exposition est maintenant assurée par Traefik, on peut retirer ou commenter l’exposition des ports en commentait les options ports:. Il ne sera plus possible d’accéder au service par http:///<IP>:<PORT>mais seulement via https://monservice.customdns

Traefik offre également une interface graphique permettant la lecture des configurations actives (lecture seule, la configuration ne se fait que via les labels ou les fichier yaml) ; vous pouvez également l’exposer et la sécuriser via Traefik en ajoutant

    labels:
      - traefik.enable=true
      - traefik.http.routers.traefik.rule=Host(`traefik.customdns`)
      - traefik.http.routers.traefik.tls=true
      - traefik.http.routers.traefik.service=api@internal
      - traefik.http.routers.traefik.middlewares=tinyauth  # Pour la sécurisation tinyauth qu'on verra par la suite

Il est facile de faire une erreur dans la configuration de Traefik et que le service ne fonctionne pas ; dans les erreurs courantes :

• 404 :
  • vérifier que les noms de router et de service sont bien distincts dans le YAML.
  • vérifier que le conteneur a bien terminé son démarrage (éventuellement forcer sa recréation)
  • vérifier que le port exposé est correct et non déjà utilisé
  • vérifier que Traefik voit bien les configurations (éventuellement forcer la relecture en redémarrant Traefik)
• Gateway Timeout :
  • le container peut avoir un problème, vérifier qu’il est bien healthydans docker et que tout va bien dans les logs du container
  • si le container a plusieurs réseaux, Traefik peut ne pas prendre la bonne IP ; il faut indiquer a Trafik quel réseau utiliser

Nginx Proxy Manager pour Home Assistant

Dans Home Assistant il existe deux addons pour sécuriser en SSL :

• NGINX Home Assistant SSL proxyest le plus simple, il est préconfiguré pour Home Assistant, vous pouvez fournir un certificat ou laisser un autosigné généré automatiquement
• Nginx Proxy Manager est un reverse proxy simple et complet administrable avec une interface graphique efficace, vous pouvez le paramétrer pour Home Assistant (activer le support WebSockets), mais également d’autres services

Dans tous les cas, suivez bien la documentation pour ajouter la configuration http:pour l’ajout du proxy de confiance.

Authentification

Deux mécanismes d’authentification sont possibles :

• via un Identity Prodiver OIDC (OpenID Connect / OAuth2) : l’application supporte nativement l’authentification OIDC et on va créer pour chaque un client_id / client_secret et déclarer le server dans l’application ; on va utiliser PocketID pour cela
• via authentification dans Traefik : pour les applications sans authentification, on va demande à Traefik de s’en occuper, et de vérifier auprès d’un service que l’utilisateur a le droit d’utiliser le service ; on va utiliser TinyAuth pour ça

Serveur OIDC PocketID

PocketID est un serveur OIDC hyper léger, et pourtant avec l’ensemble des fonctions utiles pour un homelab et une interface graphique très simple à utiliser pour le paramétrage. La spécificité de PocketID est qu’il gère seulement et exclusivement les passkeys. Donc notamment, pas de support de login / mot de passe. Les passkeys sont cependant maintenant bien gérées par les navigateurs, et assez pratique à utiliser, mais définissez en autant que possible pour ne pas être bloqué (par exemple Windows Hello sur PC, Google sur android et chrome,…)

Il existe de nombreuses alternatives de serveur OIDC comme Keycloak, Authentik, Zitadel, LemonLDAP::NG et beaucoup d’autres ; généralement nécessitant plus de ressources, et avec des interfaces plus ou moins abouties ou plus ou moins simples.

La configuration est également ultra-simple en docker :

  pocketid:
    image: ghcr.io/pocket-id/pocket-id:latest
    restart: always
    networks: ["proxy"]
    environment:
      - APP_URL=https://id.customdns
      - ENCRYPTION_KEY=supersecret
      - TRUST_PROXY=True
      - PORT=3000
      - POCKETID_CA_CERT=/certs/internal_ca.pem
    volumes:
      - /docker/pocketid-data:/app/data
      - /docker/crt:/certs
    labels:
      - traefik.enable=true
      - traefik.http.routers.pocketid.rule=Host(`id.customdns`)
      - traefik.http.routers.pocketid.tls=true
      - traefik.http.services.pocketid.loadbalancer.server.port=3000
      - traefik.http.services.pocketid.loadbalancer.server.scheme=http

On en profite aussi pour l’exposer en https via Traefik. A la première connexion, on va pouvoir créer une passkey admin, en créer d’autre et configurer d’autres utilisateurs.

L’interface d’administration est très complète:

et permet de :

• paramétrer de nouvelles applications OIDC (client_id / client_secret / redirect_uri / … très simple et pourtant tout ce qui sert pour un homelab)
• paramétrer de nouveaux utilisateurs
• paramétrer des groupes, afin de restreindre des applications à des groupes utilisateurs

L’interface de connexion quant à elle est hyper simple :

Le bouton permet ensuite la sélection de la passkey à utiliser, et la suite est gérée par le navigateur / l’OS.

Proxy d’authentification TinyAuth

PocketId n’intègre pas nativement d’intégration pour s’authentifier dans Traefik, et Traefik ne supporte pas nativement d’authentification OIDC (il existe un plugin tiers). Pour faire le pont entre les deux, on va utiliser un serveur d’authentification très léger TinyAuth. TinyAuth sait également faire server OIDC (et remplacer à ce titre PocketId), cependant :

• il ne supporte pas les passkeys
• il ne dispose pas d’une interface graphique d’administration, la configuration doit passer par des fichiers de configuration ou labels docker, ce qui n’est pas le plus pratique au quotidien pour ajouter une application ou un utilisateur

Pour le configurer sous docker

  tinyauth:
    image: ghcr.io/tinyauthapp/tinyauth:latest
    restart: always
    networks: ["proxy"]
    # entrypoint:  'sh -c "set -a; source /data/oidc_clients.env; set +a; exec /tinyauth/tinyauth" '
    environment:
      - TINYAUTH_APPURL=https://auth.customdns
      #- TINYAUTH_AUTH_USERSFILE=/data/users
      - TINYAUTH_ANALYTICS_ENABLED=false
      - TINYAUTH_AUTH_SESSIONEXPIRY=86400
      - TINYAUTH_UI_TITLE=RP Auth
      
      # --- OIDC PocketID ---
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID=<client_id>
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET=<client_secret>
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL=https://id.customdns/authorize
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL=http://pocketid:3000/api/oidc/token
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL=http://pocketid:3000/api/oidc/userinfo
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL=https://auth.customdns/api/oauth/callback/pocketid
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME=PocketID
      - TINYAUTH_OAUTH_PROVIDERS_POCKETID_INSECURE=true   # CA privé

      # Redirection automatique vers PocketID (passkeys)
      - TINYAUTH_OAUTH_AUTOREDIRECT=pocketid
    volumes:
      - /docker/tinyauth-data:/data
    labels:
      - traefik.enable=true
      - traefik.http.routers.tinyauth.rule=Host(`auth.customdns`)
      - traefik.http.routers.tinyauth.tls=true
      - traefik.http.services.tinyauth.loadbalancer.server.port=3000

      # Middleware ForwardAuth
      - traefik.http.middlewares.tinyauth.forwardauth.address=http://tinyauth:3000/api/auth/traefik
      - traefik.http.middlewares.tinyauth.forwardauth.trustForwardHeader=true
      - traefik.http.middlewares.tinyauth.forwardauth.authResponseHeaders=remote-user,remote-email

Quelques précisions :

• TinyAuth permet aussi une gestion de login / mot de passe ; vous pouvez ajouter un fichier users (voir ligne commentée + fichier avec des lignes <username>:<bcrypt-hash> et pour créer le hash mkpasswd --method=bcrypt --rounds=12 ( mkpasswd dans apt install whois )
• Pour faciliter la configuration et éviter de tout mettre dans le docker compose, une option est de déplacer les variables dans un fichier d’environnement et de décommenter la ligne entrypoint ; il faut restart le container à chaque modification.
• Notez les subtilités dans la configuration OIDC PocketID (qui sera également à suivre avec les autres clients OIDC de PocketId) :
  • pour les URL qui passent par le navigateur de l’utilisateur (auth, redirect,…), il faut utiliser l’adresse externe https://id.customdns
  • pour les URL directes entre TinyAuth et PocketId, on utilise directement l’adresse interne docker via le nom du service et le port exposé en http http://pocketid:3000

L’option TINYAUTH_OAUTH_AUTOREDIRECT=pocketid permet de se connecter automatiquement via PocketId, cependant en cas d’échec (ou sans cette option), l’écran de login ci-dessous est proposé et permet le choix entre PocketId ou le mot de passe si vous l’avez activé :

Quelques points de configuration spécifiques

Certains clients OIDC peuvent avoir des contraintes particulières, notamment :

• de devoir paramétrer les utilisateurs via OIDC (notamment le mapping pour déterminer quel champ OIDC utiliser pour le nom d’utilisateur), ou une création automatique des utilisateurs par OIDC
• d’exiger des emails validés ; il est préférable de systématiquement renseigner une adresse email dans l’utilisateur PocketId, et il est possible d’activer l’option Administration / Configuration de l’application / E-mail / E-mail vérifiés par défaut ; après l’activation de cette option, il faut mettre à jour les emails de vos utilisateurs pour que le paramètre fasse effet.
• de devoir paramétrer l’autorité de confiance interne SSL également coté client OIDC (certains vérifient que l’adresse d’authentification est valide) ; voir les différentes méthodes ci-dessous

Configuration des servers/containers pour utilisation de l’AC interne

Pour que les applications fassent confiance à l’AC interne, il faut importer le certificat racine dans l’environnement concerné. Certaines applications le permettent directement dans leur configuration, soit globale, soit liée à la partie OIDC, d’autres nécessitent de l’ajouter en dehors de l’application, via les composants logiciels utilisés. Certains cas ne permettent pas d’importer un certificat AC, mais de désactiver la vérification SSL.

Debian

Sur Debian, le certificat racine doit être copié dans le répertoire des autorités locales, puis le trust store doit être régénéré.

sudo cp internal_ca.crt /usr/local/share/ca-certificates/internal_ca.crt
sudo update-ca-certificates

Après cela, le certificat est pris en compte par les outils système qui s’appuient sur le trust store Debian.

Java

Pour créer le keystore (une seule fois) :

keytool -importcert -trustcacerts -alias internal_ca -file /crt/internal_ca.crt -keystore /keystore/internal_ca.p12 -storepass changeme_not_that_secret -storetype PKCS12

Pour utiliser ce keystore au démarrage de l’application, ajouter en JAVA_OPTS :

-Djavax.net.ssl.trustStore=/keystore/internal_ca.p12
-Djavax.net.ssl.trustStorePassword=changeme_not_that_secret

Si l’application utilise des variables d’environnement ou un fichier java_opts, il suffit d’y ajouter ces options.

Node.js

Pour Node.js et les outils npm, le plus simple consiste à utiliser la variable d’environnement NODE_EXTRA_CA_CERTS.

export NODE_EXTRA_CA_CERTS=/crt/internal_ca.crt

Go

Pour Go, la variable SSL_CERT_FILE peut être utilisée pour pointer vers le certificat racine de l’AC interne.

export SSL_CERT_FILE=/crt/internal_ca.crt

Selon le contexte, SSL_CERT_DIR peut aussi être nécessaire si l’environnement attend un répertoire de certificats plutôt qu’un fichier unique.

Python

En Python, le plus simple est d’utiliser REQUESTS_CA_BUNDLE ou SSL_CERT_FILE selon l’outil utilisé.

export REQUESTS_CA_BUNDLE=/crt/internal_ca.crt

Ou, pour un usage plus générique :

export SSL_CERT_FILE=/crt/internal_ca.crt

Appliquer les mises à jour

Vouloir se sécuriser sans suivre les mises à jour serait complètement inutile. Il n’y a qu’à voir à quelle fréquence sortent les failles de sécurité à l’heure de l’IA. L’inconvénient d’avoir de nombreux applicatifs dans la stack est que cela peut faire beaucoup d’éléments à mettre à jour (OS, VM, dockers,…).

Il existe généralement des options de mise à jour automatique, comme :

• Unattended upgrades pour Proxmox, Debian, OPNsense ; n’oubliez cependant pas de redémarrer lors des mises à jour de kernel
• Mise à jour automatique des containers docker avec Dockhand ou watchtower
• Alors oui, ça vous expose aux attaques type “Supply chain”, mais si vous n’êtes pas admin au quotidien sur votre homelab, c’est sans doute le moins pire…

Les différentes étapes :

• installer usbipd-win sur le PC Windows et exposer (bind) le device USB
• installer le client USB-IP sur Proxmox et attacher le périphérique
• ajouter le périphérique dans une VM
• rendre automatique l’attachement à Proxmox et l’ajout à la VM

Installer usbipd-win sur le PC Windows

usbipd-win utilise WSL (Windows Subsystem pour Linux), vous devez avoir WSL opérationnel, configuré et en cours d’exécution sur votre Windows

usbipd-win est la déclinaison Windows du serveur USB-IP en utilisant WSL, vous pouvez l’installer facilement via winget

winget install usbipd

ou manuellement en téléchargeant la dernière version .msi sur GitHub - dorssel/usbipd-win et exécutant l’installateur.

Ce que l’installation ajoute :

• Un service usbipd (USBIP Device Host)
• L’outil en ligne de commande usbipd (ajouté à PATH)
• Une règle de pare-feu pour autoriser les connexions locales sur TCP 3240

Note : Si vous utilisez un pare-feu tiers, reconfigurez pour autoriser les connexions entrantes sur TCP port 3240.

Lister et lier (bind) le périphérique USB sur Windows

Option ligne de commande

Ouvrez PowerShell ou CMD en mode administrateur sur le PC Windows.

Pour lister les périphériques USB disponibles

usbipd list

Exemple de résultat :

BUSID DEVICE STATE
1-7 USB Input Device Not shared
4-4 STMicroelectronics STLink dongle Not shared
5-2 Surface Ethernet Adapter Not shared

Identifiez le BUSID de votre périphérique (ex: 4-4).

Ensuite pour lier (bind) le périphérique au réseau

usbipd bind --busid=4-4

Remplacez 4-4 par le BUSID de votre appareil.

Vérifier que le périphérique est partagé

usbipd list

Le STATE doit maintenant être Shared.

Important : Le bind est persistant — il survit aux redémarrages. À faire une seule fois par périphérique.

Option GUI sous Windows - WSL USB Manager

Si vous préférez une interface graphique pour gérer les périphériques USB vers WSL, utilisez WSL USB Manager, qui est une interface pratique et légère à utiliser.

• Dans l’onglet “Connected” sont listés tous les périphériques USB connectés au PC, pour exposer en USB-IP l’un d’entre eux, utiliser le bouton “Bind”
• La liste des périphériques “Binded” est visible dans l’onglet “Persisted”

N’oubliez pas que cela utilise WSL sous le capot, donc pour que l’exposition soit active, il faut vous assurer que WSL soit bien lancé. Typiquement après un reboot Windows, dès que vous voulez exposer un device USB, ouvrez une ligne de commande WSL pour forcer.

Configuration USB/IP sur Proxmox

On va ici installer le client USB/IP directement sur Proxmox. Cela va permettre de pouvoir l’ajouter à n’importe quelle VM très simplement, qu’elle sous Windows ou Linux. Mais vous pouvez également configurer USB/IP directement dans les VMs, avec le même procédé.

Installation des binaires et modules noyaux

Ouvrez une Shell sur le nœud Proxmox et installez les outils USB/IP :

apt update
apt install usbip usbip-utils

Chargez les modules noyaux nécessaires :

modprobe usbip-core
modprobe vhci-hcd
modprobe usbip-host

Ajoutez ces modules dans /etc/modules pour qu’ils soient chargés au démarrage :

echo "usbip-core" >> /etc/modules
echo "vhci-hcd" >> /etc/modules
echo "usbip-host" >> /etc/modules

Attacher le périphérique USB remote à Proxmox

Pour lister les périphériques distants disponibles, sur Proxmox (remplacez IP_WINDOWS par l’adresse IP ou DNS de votre PC Windows, par ex 192.168.1.50) :

usbip list --remote=<IP_WINDOWS>

Exemple :

BUSID DEVICE STATE
4-4 STMicroelectronics STLink dongle Shared

Ensuite, pour attacher (attach) un des périphériques USB (Remplacez IP_WINDOWS par l’adresse IP ou DNS de votre PC Windows et 4-4 par le BUSID de votre appareil)

usbip attach --remote=<IP_WINDOWS> --busid=4-4

Vous pouvez ensuite vérifier que le périphérique est bien attaché avec usbip port et lsusb, et vous pouvez ensuite l’ajouter à une VM depuis Hardware / Add USB Device comme s’il était directement branché sur l’hôte Proxmox (ou en ligne de commande avec qm set 100 -usb0 host=0483:374b)

Configurer l’attachement automatique

Pour un attachement automatique du périphérique à Proxmox et à la VM dès qu’il est détecté sur le Windows distant, il faut configurer deux parties :

• sur Proxmox, on va ajouter un script qui scanne régulièrement les devices exposés et disponibles, et les attache automatique à Proxmox
• sur la VM, on va rendre l’ajout USB dynamique pour qu’il soit ajouté dès que détecté, mais ne bloque pas le lancement de la VM

Sur Proxmox - usbip-watch.sh

Script usbip-watch.sh (vibecodé avec Copilot)

#!/usr/bin/env bash
set -euo pipefail

SERVER="${SERVER:-votre_windows.lan}"
INTERVAL="${INTERVAL:-60}"
USBIP="${USBIP:-/usr/sbin/usbip}"

log() {
  echo "[$(date '+%F %T')] $*"
}

load_modules() {
  modprobe usbip_core || true
  modprobe vhci_hcd || true
}

remote_busids_available() {
  "$USBIP" list --remote="$SERVER" 2>/dev/null \
    | sed -n 's/^[[:space:]]*-\{0,1\}[[:space:]]*\([0-9][0-9]*-[0-9.][0-9.]*\).*/\1/p' \
    | sort -u
}

remote_busids_mounted() {
  "$USBIP" port 2>/dev/null \
    | sed -n "s#.*usbip://$SERVER:3240/\([0-9][0-9]*-[0-9.][0-9.]*\).*#\1#p" \
    | sort -u
}

debug_state() {
  log "Remote busids available:"
  remote_busids_available | sed 's/^/  - /' || true
  log "Remote busids already mounted:"
  remote_busids_mounted | sed 's/^/  - /' || true
}

attach_missing() {
  mapfile -t mounted < <(remote_busids_mounted)

  while read -r busid; do
    [[ -z "$busid" ]] && continue
    if printf '%s\n' "${mounted[@]:-}" | grep -qx "$busid"; then
      continue
    fi
    log "Attaching $busid from $SERVER"
    "$USBIP" attach --remote="$SERVER" --busid="$busid" || true
  done < <(remote_busids_available)
}

detach_disappeared() {
  mapfile -t mounted < <(remote_busids_mounted)
  mapfile -t available < <(remote_busids_available)

  local busid port
  for busid in "${mounted[@]:-}"; do
    if printf '%s\n' "${available[@]:-}" | grep -qx "$busid"; then
      continue
    fi
    port="$("$USBIP" port 2>/dev/null | sed -n "/usbip:\/\/$SERVER:3240\/$busid/,\$p" | sed -n 's/^Port \([0-9][0-9]*\):.*/\1/p' | head -n1)"
    if [[ -n "${port:-}" ]]; then
      log "Detaching port $port for missing remote busid $busid"
      "$USBIP" detach --port="$port" || true
    fi
  done
}

log "Loading kernel modules"
load_modules
log "Starting usbip watcher for server=$SERVER interval=${INTERVAL}s"

while true; do
  # debug_state
  attach_missing
  detach_disappeared
  sleep "$INTERVAL"
done

et lancé au démarrage via la ligne crontab suivante (édité avec crontab -e) :

@reboot         /usr/bin/bash /root/bin/usbip-watch.sh

Le script scanne régulièrement les périphériques disponibles à la fréquence INTERVAL à modifier selon votre convenance, et attache automatiquement les nouveaux périphériques exposés et détache ceux qui ne sont plus disponibles.

Sur la VM - en hotplug

Il ne fait pas inclure le périphérique USB directement dans la liste du Hardware, car sinon la VM refusera de se lancer si le périphérique n’est pas trouvé. L’astuce pour la VM est d’utiliser le hotplug en ajoutant le périphérique juste après que la VM soit lancée. On va réutiliser le hook créé dans l’article accès distant VNC avec Proxmox

On va créer le hook script dans le répertoire des snippets et le rendre exécutable : /var/lib/vz/snippets/hook-hotplug.sh

#!/bin/bash

# From Perplexity: hook script pour proxmox qui ajoute dans le qm monitor 
# après le démarrage le contenu du fichier à .hotplug.conf 
# à coté du fichier de configuration de la VM

# Installation
# - chmod +x 
# - copy dans /var/lib/vz/snippets
# - ajouter dans la VM avec: qm set <VMID> --hookscript local:snippets/hook-hotplug.sh

# Variables transmises par Proxmox à chaque appel hook
VMID="$1"
PHASE="$2"

# Chemin du fichier de hotplug à appliquer si présent
HOTPLUG_CONF="/etc/pve/qemu-server/${VMID}.hotplug.conf"

# Lancement après démarrage effectif
if [ "$PHASE" = "post-start" ] && [ -f "$HOTPLUG_CONF" ]; then
    # Lire chaque ligne et l’injecter dans le monitor QEMU de la VM
    while IFS= read -r line; do
        # On ignore les lignes vides ou commentaires (#)
        [[ "$line" =~ ^#.*$ || -z "$line" ]] && continue
        # Injecte la commande dans qm monitor
        echo "$line" | qm monitor "$VMID"
    done < "$HOTPLUG_CONF" >> /var/log/hook-hotplug.log 2>&1
fi

Et pour l’utiliser il faut ajouter dans chaque VM concernée la ligne suivante :

hookscript: local:snippets/hook-hotplug.sh  

Le principe de ce script va être de répondre à l’évènement post-start lancé à la fin du démarrage de la VM, de lire le fichier de configuration <vmid>.hotplug.conf à côté du fichier de configuration de la VM, et de l’injecter dans l’interface QEMU Monitor.

Pour notre cas, le fichier hotplug sera simplement : /etc/pve/qemu-server/<vmid>.hotplug.conf

device_add usb-host,vendorid=0x0549,productid=0x0720,id=remoteusb

Et voilà il ne reste plus qu’à redémarrer Proxmox (ou lancer manuellement le script et redémarrer la VM concernée)

Commandes récapitulatives

Démarrer sur GParted

• Ajouter l’ISO GParted en CDROM à la VM
• Modifier l’ordre de boot pour démarrer dessus
• Lancer la VM

Réduire la partition

Dans GParted :

• Sélectionner le disque
• Réduire la partition à la taille souhaitée (ex: 16G)
• Appliquer les changements
• Éteindre la VM

Réduire le disque côté Proxmox

Sur l’hôte Proxmox :

lvreduce -L 16G /dev/mapper/pve-vm--102--disk--1

⚠️ Adapter le chemin du volume si nécessaire (vm--ID--disk--X).

Réparer la table de partition

Toujours sur l’hôte :

gdisk /dev/mapper/pve-vm--102--disk--1

Ensuite dans gdisk :

• x (mode expert)
• e (réparer la table GPT)
• m (retour menu principal)
• p (vérifier)
• w (écrire)
• q (quitter)

Redémarrer la VM

qm start 102

Dans Home Assistant, certains plugins peuvent échouer après modification du disque. Si c’est le cas désactiver temporairement SSL ou reconfigurer correctement les certificats

Références

• https://forum.proxmox.com/threads/decrease-a-vm-disk-size.122430/

Comprendre ce qui est stocké

Il y a plusieurs espaces de stockage sous Home Assistant:

• la configuration de vos entités et intégration gérée par Home Assistant, sous forme d’une collection de fichiers json dans /config/.storage (en complément des éventuels yaml de configuration dans /config)
• l’historique des états de vos entités, gérée par le Recorder de Home Assistant ; par défaut il va stocker dans une base SQLite dans le fichier /config/home-assistant_v2.db (d’autres bases sont supportées, ou des recorder spécialisées, mais c’est en dehors du scope de cet article). Ce recorder stocke plusieurs choses :
  • l’historique des états de vos entités (table states)
  • lorsque les états ont des attributs, ceux-ci sont stockés dans une autre table states_attributes ; une nouvelle entrée n’est créée que lorsque les attributs changent pour optimiser le stockage ; c’est donc rarement un problème d’avoir de nombreux attributs lorsqu’ils sont tous stables, mais si un seul change (comme un simple timestamp) et c’est la porte ouverte à une forte inflation
  • ces états et attributs sont stockés seulement quelque jours, souvent 10 jours, passé ce délai les états et attributs sont supprimés, et suivant le type de capteur seuls des statistiques sont conservées, par exemple pour les sensors une valeur moyenne, min et max sue chaque période. Il y a des statistiques court terme (avec une granularité 5mn pour un historique très détaillé) et long terme (agrégées à l’heure).

Les références pour tout comprendre :

• la documentation officielle Home Assistant du Recorder
• le tutoriel sur HACF

Et pour suivre la taille de votre base, je vous conseille d’ajouter une entité File Size qui pointe sur votre fichier de base de données:

L’addon dbstats

Il existe un addon dbstats qui permet de faciliter la compréhension du contenu de la base. Cet addon est l’inspiration pour la suite de cet article, et déjà très utile, mais présente quelques inconvénients :

• les graphiques sont des images, il n’est pas possible de copier les identifiants des libellés pour les exclure du recorder
• les tables s’arrêtent aux premières valeurs
• les tables présentent souvent un nombre de lignes sans qu’il soit possible de se rendre compte de la taille occupée
• les tables présentent des éléments unitaires, mais il manque une vision de synthèse

Des requêtes custom utiles

J’ai donc créé quelques requêtes SQL pour me fournir une vision agrégée, à copier coller dans l’addon SQLite Web

SELECT 
  entity,
  SUM(states_count) AS states_count,
  SUM(attributes_count) AS attributes_count,
  SUM(attributes_size) AS attributes_size
FROM (
  -- Requête 1 : Nombre d'états par entité
  SELECT 
    sm.entity_id AS entity, 
    COUNT(*) AS states_count,
    0 AS attributes_count,
    0 AS attributes_size
  FROM states s
  JOIN states_meta sm ON s.metadata_id = sm.metadata_id
  WHERE s.last_updated_ts >= (strftime('%s', 'now') - 24*60*60)
  GROUP BY sm.entity_id
  
  UNION ALL
  
  -- Requête 2 : Attributs par entité 
  SELECT 
    sm.entity_id AS entity,
    0 AS states_count,
    COUNT(*) AS attributes_count,
    SUM(LENGTH(sa.shared_attrs)) AS attributes_size
  FROM states s
  JOIN states_meta sm ON s.metadata_id = sm.metadata_id
  JOIN state_attributes sa ON sa.attributes_id = s.attributes_id
  WHERE s.last_updated_ts >= (strftime('%s', 'now') - 24*60*60)
  GROUP BY sm.entity_id
) AS requetes_combinees
GROUP BY entity
ORDER BY states_count + attributes_count DESC;

-- See what tables/indexes are taking space
SELECT name, sum(pgsize)/1024/1024 as size
FROM dbstat
GROUP BY name
ORDER BY size DESC

-- List entities with lot of states
SELECT sm.entity_id as entity, count(*) as count
FROM states s, states_meta sm
WHERE s.metadata_id = sm.metadata_id
GROUP BY entity
ORDER BY count DESC

-- Get size of state attributes by entities
SELECT sm.entity_id as entity, sum(length(sa.shared_attrs)) as count
FROM states s, states_meta sm, state_attributes sa
WHERE s.metadata_id = sm.metadata_id
AND sa.attributes_id = s.attributes_id
GROUP BY entity
ORDER BY count DESC

-- Inspect attributes of an entity
SELECT DISTINCT sm.entity_id as entity, sa.attributes_id, sa.shared_attrs
FROM states s, states_meta sm, state_attributes sa
WHERE s.metadata_id = sm.metadata_id
AND sa.attributes_id = s.attributes_id
AND sm.entity_id = "device_tracker.capteur_fuite_eau"

RETEX du vibe-coding d’un addon

Après avoir itéré plusieurs voir sur ma base avec les requètes manuelles ci-dessus, ça m’a donné envie d’avoir quelque chose d’un peu plus industriel, dont la première expression de fonctionnalité a été

1er tableau: Liste des tables : Mo (est.)
2ème tableau: Liste des entités : nombre / attributs Mo (est.)
- si clic sur attributs, affichage des 10 derniers attributs
- si clic sur nombre, lien page historique
- si clic sur entité, lien page entité

Par ailleurs comme je n’avais encore jamais fait d’addon Home Assistant, et que j’étais en train d’expérimenter les possibilités de Github Copilot (avec simplement l’offre gratuite), je me suis dit que c’était une bonne occasion de vibe-coder l’application à partir de cette liste de requirements et des SQL ci-dessus, que j’ai un peu plus étoffée et ajouté quelques contraintes techniques pour éviter des frameworks et fichiers trop complexes. La première génération est assez bluffante, car on arrive littéralement à avoir en quelques minutes une première application qui ressemble à quelque chose, et quasi fonctionnelle. Comme je n’avais pas défini de tests, il y avait cependant quelques erreurs de calcul que j’ai du lui demande de refaire. Et c’est assez addictif, on se retrouve très facilement à ajouter des fonctionnalités, et itérer pour avoir exactement ce que l’on veut. Au fur et à mesure, le code perd en simplicité et en cohérence, car Github Copilot va plus facilement générer du spécifique que du générique réutilisé, ou pas forcément comme on l’aurait fait. J’imagine qu’il faudrait que je lui fasse faire des tests et réécrire intégralement sur la base des requirements actualisés et tests, mais c’est la limite de l’offre gratuite Github Copilot et ses quotas un peu bas. Bref, une première expérience de vibe-coding intéressante, je ne me serais sans doute pas lancé dans cet addon sans ça.

Et sinon la documentation officielle pour développer un addon/app HomeAssistant

L’addon SQLite HA DB Usage

Le résultat est disponible dans ce repo github.com/rpeyron/ha-dbusage. Il suffit de suivre les instructions d’installation sur la page.

Le grand ménage

Cet addon vous permet maintenant de bien identifier les sources de ce qui prend de la place, et:

• soit de désactiver les extensions qui ne vous seraient plus utiles mais génère beaucoup d’entités ou de grande tailles
• soit d’exclure ce qui prend de la place et qui n’est pas nécessaire à conserver

A noter qu’à ce jour le paramétrage du recorder est assez basique, et qu’il n’est pas possible d’exclure simplement toute une extension, ou seulement le stockage long terme, ou d’avoir une durée de rétention différente par entités / type d’entité. Egalement, un petit piège, dès qu’on utilise include alors l’enregistrement par défaut disparait et seules les entités inclues sont enregistrées. Il n’est donc pas possible d’utiliser un exclude_globs et un include pour réinclure une entité qui aurait été exclue. Vous pouvez bien sûr choisir de n’inclure que les entités que vous souhaitez, mais c’est facile d’oublier donc j’ai préféré conserver l’enregistrement par défaut et des exclusions.

L’usage du plugin permet de selectionner les entités et de générer le code yaml de configuration à compier coller dans configuration.yaml.

Pour ma part je généralise souvent les entités trouvées dans des globs sur les patterns associés ; par exemple un extrait de ma configuration:

recorder:
  exclude:
    entity_globs:
      - media_player.*
      - camera.*_stream
      - sensor.*_uptime*

      # Portainer
      - sensor.*_cpu_usage_total*
      - sensor.*_memory_limit*
      - sensor.*_memory_usage*
      - sensor.*_memory_usage_percentage*
      - sensor.*_du_processeur*
      - sensor.*_du_disque*
      - sensor.*_de_la_memoire*
      - sensor.*_image
      # ZHA
      - sensor.*_rssi
      - sensor.*_niveau_de_signal
      - sensor.*_battery
      - sensor.*_battery_level
      - sensor.*_batterie
      # Proxmox
      - sensor.*_utilisation_maximale_du_disque
      - sensor.*_utilisation_maximale_de_la_memoire
      - sensor.*_backup_duration
      - sensor.storage_*_usage_percentage
      - sensor.storage_*_storage
      - sensor.storage_*_available_storage
      - sensor.storage_*_total_storage
      - sensor.*_network_input
      - sensor.*_network_output

Pour aller jusqu’au bout du cleanup, il faut quelques étapes manuelles, pour d’une part purger les entités, et d’autre part supprimer également les statistiques.

Pour prendre en compte vos nouvelles exclusions, soit vous êtes patients et vous attendez 15 jours que les purges automatiques fasse le travail, soit vous le faites manuellement, via les outils de développement et l’action recorder.purge ; il faut bien cocher sur les 2 cases à cocher appliquer le filtre (supprimer directement vos nouvelles exclusions), et le reconditionnement (ce qui va réécrire le fichier SQLite pour le réduire à la taille minimum des données utilisées)

Enfin, la purge, qu’elle soit manuelle ou automatique, ne supprime pas les statistiques. Pour ce faire, on va utiliser le menu Statistiques dans les outils de développements, et sélectionner toutes les entités avec “problèmes”. Comme la purge supprime les états des entités, elles vont automatiquement apparaitre ici. Bien relire la liste des entités sélectionner pour vérifier qu’il n’y a pas d’autres entités avec des problèmes d’intégration passagers et qu’on ne voudrait pas supprimer.

Résultat, une base divisée par cinq !

Au fur et à mesure de mes optimisations, installations de nouvelles intégrations, nouvelles optimisations… j’ai pu diviser la taille de ma base de donnée par 5 !

Au quotidien ça ne change pas grand-chose, mais c’est notamment appréciable pour les sauvegardes multiples qui avaient fini par saturer le disque.

Bonus : SQL pour fusionner l’historique de deux capteurs

La meilleure solution pour fusionner l’historique est de renommer l’entité du nouveau capteur en celui de l’ancien capteur via le paramétrage de l’entité. Cela permettra à cette nouvelle entité d’hériter automatiquement de l’historique de l’entité précédente. Si toutefois ce n’est pas possible, typiquement pour celles générées automatiquement depuis des intégrations type MQTT, alors un petit script SQL peut résoudre le problème.

Attention, le script correspond à l’usage dont j’avais besoin, sur les statistiques long terme, mais ne couvre pas toutes les tables de la base de données. À utiliser avec précautions !! Notamment il faut que les plages de dates des statistiques à merger soient disjointes. Si ce n’est pas le cas, vous pouvez supprimer la partie de redondance avant le merge.

-- Step 1: identifier les statistics_id source et cible (et via l'IHM)
SELECT * FROM "statistics_meta" WHERE statistic_id LIKE '%puissance%'

-- Step 2: vérifier
SELECT * FROM states 
WHERE last_updated_ts BETWEEN strftime('%s', '2025-12-07 19:00:00') AND strftime('%s','2026-01-24 17:22:00')
AND metadata_id = 895

-- Step 3: changer l'identifiant
UPDATE states SET metadata_id = <id_cible>
WHERE last_updated_ts BETWEEN strftime('%s', '2025-12-07 19:00:00') AND strftime('%s','2026-01-24 17:22:00')
AND metadata_id = <id_source>

La vieille tablette Android peut aussi être une option, mais je souhaite également fonctionner uniquement avec des logiciels mis à jour, même si ce choix pourrait être discutable pour un usage réduit à un réseau local.

Matériel utilisé

J’ai voulu suivre l’approche inverse, en partant de ce que j’avais à disposition :

• Un écran tactile 14” acheté 31€ en promo sur AliExpress
• Un raspberry Pi Zero 1 acheté il y a quelques années 8 euros, et que je n’utilise plus depuis quelque temps, ayant upgradé depuis vers un Zero 2WH
• Une clé USB Wifi compatible Linux
• Une alimentation USB suffisante pour alimenter le Raspberry Pi et l’écran en USB Type C ; un seul fil à brancher pour allumer le tout.

J’ai complété avec la connectique adaptée pour que ce soit pratique à utiliser et suffisamment compact. Le Raspberry Pi Zero est connecté en HDMI à l’écran, alimenté avec un port USB, et l’autre port USB est relié à un Hub USB pour brancher la clé USB Wifi et le volet tactile de l’écran aussi en USB. Pendant le setup, j’ai également branché un clavier et souris sans fil pour faciliter.

Incompatibilité logicielle

Dans l’absolu, il suffit faire en sorte que le Pi lance un navigateur en plein écran sur la bonne adresse au démarrage. Cependant l’usage du Pi Zero 1 s’est avéré être une grosse contrainte, car le processeur utilisé, sur ARMv6, ne comporte pas l’unité NEON (Advanced SIMD) et Chromium a supprimé la compatibilité avec cette ancienne architecture. Depuis 2023 il n’est donc plus possible d’utiliser Chromium sur Pi Zero 1. J’ai essayé les navigateurs alternatifs disponibles pour Raspberry Pi, mais Home Assistant nécessitant une bonne compatibilité sur les technologies web modernes, aucun n’a réussi à faire fonctionner Home Assistant.

J’ai donc opté pour une approche un peu plus compliquée avec un partage d’écran en VNC, mais qui répond à l’ensemble de mes contraintes : le Raspberry Pi Zero 1 lance en mode kiosque un viewer VNC vers un serveur VNC en docker dont la seule fonction est d’afficher un Chromium sur la bonne page en plein écran

Mise en place

Stack docker

Je suis parti du container mrcolorrain/vnc-browser qui correspond à mon usage et semble bien maintenu. La stack correspondante est :

version: "3.9"
services:
  vnc-browser:
    container_name: vnc-homeassistant
    image: mrcolorrain/vnc-browser:debian
    restart: unless-stopped
    ports:
      - "5900:5900"
      - "6080:6080"
    environment:
      VNC_PASSWORD: "YOUR_PASSWORD"
      VNC_RESOLUTION: "1920x1200"
      STARTING_WEBSITE_URL: "https://homeassistant.lan/dashboard-home/0"
      LANG: fr_FR.UTF-8
      LC_ALL: fr_FR
      AUTO_START_BROWSER: true
      AUTO_START_XTERM: true
      BROWSER_OPTIONS: "--start-fullscreen --touch-events=enabled  --force-dark-mode --enable-features=WebUIDarkMode --test-type=ui"
      #CUSTOMIZE: true
    volumes:
      - vnc_ha_chrome_data:/root/.config/chromium/Default
      - vnc_ha_pki:/root/.locale/share/pki
volumes:
  vnc_ha_chrome_data:
  vnc_ha_pki:

Ici un volume est déclaré pour les données Chromium et un autre pour la partie pki (utile par exemple si vous ajoutez une autorité de certification locale dans Chromium par exemple).

Client VNC

J’ai opté pour TigerVNC qui est maintenant le défaut du paquet xvnc4viewer

sudo apt install tigervnc-viewer tigervnc-tools

Puis un script pour lancer automatiquement le viewer en plein écran :

#!/bin/bash
sleep 10
while true; do
  # Use tigervncpasswd  installed by apt install tigervnc-tools
  xvncviewer -passwd ~/.vnc/pwd_ha -fullscreen 192.168.x.x:5900
  echo "Stopped, restart"
  sleep 5
done

Et enfin, il faut enregistrer le mot de passe VNC avec vncpasswd -f ~/.vnc/pwd_ha

Lancez le script pour vérifier que ça fonctionne correctement.

Démarrage automatique

On va maintenant faire en sorte que ça se lance automatiquement. Dans les réglages Raspberry (Settings / Control Center), activez la connexion automatique de l’utilisateur (Desktop Auto login). Puis on va définir un fichier de lancement automatique

mkdir -p ~/.config/autostart
nano ~/.config/autostart/vnc-client.desktop

avec le contenu

[Desktop Entry]
Type=Application
Name=VNC Client Fullscreen
Exec=/home/remi/start_vnc.sh
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true

Finalisation

Je vous conseille également :

• d’activer VNC : vous pourrez ensuite vous connecter depuis votre PC sur le Raspberry, lui même connecté en VNC sur votre serveur :-) ; plus sérieusement ça sera utile pour re-rentrer votre mot de passe Home Assistant si besoin de le changer plus facilement que via le clavier tactile, de modifier la configuration, etc ; pour sortir du client VNC en plein écran et accéder à l’interface raspberry OS, il faut dans le menu de votre client VNC selectionner l’option “Envoyer la touche F8” ; cela va faire apparaitre un menu dans lequel vous pourrez sortir du mode plein écran
• faire un backup de la carte SD
• activer le mode overlayfs (Settings / Control Center / Performances / Overlayfs) : permet notamment d’éviter les corruptions sur les coupures de courant

Compare solutions

My needs are very basic:

• free for a low traffic website
• privacy‑friendly analytics (GDPR-compliant)
• lightweight script
• easy integration with my Jekyll static website
• an API allowing to access data and reuse metrics in other tools (for instance in an Home Assistant dashboard)

Several alternatives were evaluated during a few weeks to compare some results:

• Umami has a cloud-hosted free plan for low traffic and also an open source version that you can self-host for free
• GoatCounter is also free for low traffic, and the origin of this tool is exactly what I am looking for
• As I am using Cloudflare as CDN, I have also tested the free Cloudflare Web Analytics ; there is also a GraphQL API, but I discovered a bit late that it was exluded from the free plan

Main collection techniques and major issues

Web analytics has become quite complex:

1. Website logs: some years ago, the easiest way to get data was from access logs from the web server ; you were certain at that time to get all the requests, but this method have now several problems: Content Delivery Network will cache and serve contents without soliciting your own web server, so you will miss a good part of your traffic ; also, I am using GitHub Pages, and GitHub does not make available the server logs, also you won’t be able to differentiate users/sessions. This method is fairly limited and no more usable
2. JavaScript snippet to collect data: the most common one, you include a small JavaScript snippet that will run on your page, in the browser of the user, and it will call an API to record usages ; this can record a lot of information, including personal information ; the choice of the solution you use is very important to record only the information you need, in my case without personal information, and without the need of cookies ; the drawback of this method is that it depends on the user browser settings regarding JavaScript, or ad-blockers browser extension that may filter those snippets out
3. pixel images are 1-pixel transparent image, that will trigger the record of the usage ; you can pass some basic information with the query parameters of the image ; as this is included as an image, it is less likely to be deactivated by the browser or extensions, but you will usually get less information

Also, there are now a lot of crawlers and search engines to be known to filter out crawlers from usage, and find the relevant source of traffic.

I have activated both JavaScript snippet and pixel image for Umami and Goatcounter to be able to compare the difference between all the methods.

Test Dashboard Comparison

Due to the short notice of Piwik Pro end of free plan, I have only tested the different methods on a week, but still we can see some interesting elements. The following dashboards show the collected metrics during the evaluation period.

From those dashboards we can see:

• we have large differences between all the results!
• Goatcounter is clearly having some troubles recording the usages, quite consistently for JavaScript snippet or pixel image ; it seems that the totals are correct, but maybe some collected usages were treated lately at the time of the test ; remember this is a non-professional solution and is totally free, so anyway, it is very good for what you pay
• Umami Cloud and Cloudflare display quite comparable information, with the same curve as Piwik, but counts more users than Piwik
• Umami Self-hosted is counting more visits, and with a curve looking a bit different ; this can be explained in different ways: the script and URL is unknown from adblockers and do not get blocked, or the self-hosted version is less accurate in crawlers filtering
• anyway, do not expect exact values from any web analytics engine, but use it as rough estimates and trends

Final Choice: Umami Cloud

After testing the different solutions, I decided to go mainly with Umami Cloud. Main reasons are simple setup, privacy-friendly, lightweight, clean dashboard with everything that I need, good API, no infrastructure to maintain, and all that for free for my low traffic website. That was also the solution with the most consistent numbers in the test period. I think I will keep the other solution for some time to see webstats differences in a longer period, and also in the case Umami Cloud have in the future the same bad idea than Piwik of removing the free plan.

The migration part

Jekyll data collection

I included in my Jekyll build the required files and lines for data collection

    {% when 'umami' %}
        <!-- Umami cloud or self-hosted https://github.com/umami-software/umami -->
        {% if analytic[env].token %}
            <script defer src="{{ analytic.script |default: 'https://cloud.umami.is/script.js' }}" 
                    data-website-id="{{ analytic[env].token }}"
                    {% if analytic.host %}data-host-url="{{ analytic.host }}"{% endif %}
                    data-tag="page_{{ include.lang }}"></script>
        {% endif %}
        {% if analytic[env].noscript-pixel %}
            <noscript>
            <img src="{{ analytic[env].noscript-pixel }}" loading="lazy" style="position: absolute; top: 0; right: 0; width: 4px;">
            </noscript>
        {% endif %}
        {% if analytic[env].pixel %}
            <img src="{{ analytic[env].pixel }}" loading="lazy" style="position: absolute; top: 0; right: 0; width: 4px;">
        {% endif %}

Full script for all services on my GitHub

Jekyll use of Umami results

I use top pages on the front page to display most viewed pages in the corresponding order, and in the blog view to display top ten. To make the data available, here is what I am using:

• I have created a share URL for my Umami ; this enables to share a readonly view of all the data ; this URL gives a readonly UI on your data, and also enables to get a read-only token and use the allowed API with that token
• This URL can be shared as is, as it is readonly, but I added another layer to avoid making available the full data ; a script is run weekly as action workflow on my github repository, run a script that authenticate to Umami share URL (given as github “secret”), and save the result in a gist.
• The URL of the corresponding GIST in included in my jekyll website, and a javascript code fetchs the gist to display the posts or widget, the corresponding code is:
  • top-article-script.html
  • top-article-widget.html

A dashboard in Home Assistant with Umami web stats

I also have created a dashboard in my Home Assistant to integrate directly Umami visitors graphs and top pages. I have a dedicated GitHub repository rpeyron/homeassistant_umami with all the elements and a usage guide.

This ends the last feature I wanted with my new Umami web analytics.

Annexes

Cloudflare GraphQL Explorer for Web Analytics

One last thing about Cloudflare, the GraphQL API is not available with the free plan, but you still can use the Cloudflare GraphQL Explorer to query your data (and see what you could get with the paid plan). Anyway, this is a good solution to be able to manually query your data.

You first have to login to the {Cloudflare GraphQL Explorer](https://graphql.cloudflare.com/explorer)

You will need to configure the identifiers you will use: {"accountTag":"<your account id>","siteTag":"<your site id>","dateFrom":"2026-02-01T00:00:00Z"}

And then use the following GraphQL to get visitors number:

query($accountTag: string!, $siteTag: string!, $dateFrom: Time!) {
        viewer {
          accounts(filter: {accountTag: $accountTag}) {
            rumPageloadEventsAdaptiveGroups(
              filter: {
                datetime_geq: $dateFrom
                siteTag: $siteTag
              }
              limit: 31
              orderBy: [date_ASC]
            ) {
              dimensions {
                date
              }
              sum {
                visits
              }
            }
          }
        }
      }
    

Tentative à la colle

Ma première tentative a été de recoller la pièce avec de la colle cyanoacrylate. J’ai tenté en même temps de consolider avec du bicarbonate collé, une technique dont on peut voir plusieurs vidéos impressionnantes.

C’est un échec complet à la première tentative de fermeture, la contrainte mécanique casse toute la colle instantanément :

Modélisation 3D avec Inkscape et Fusion360

Scan

La première étape est de scanner le modèle à reproduire. La meilleure solution pour la 3D est le scan 3D, soit avec un appareil dédié (mais assez cher), soit avec de la photogrammétrie (à recommander si vous avez un iPhone avec capteur à détection de profondeur, il y a des applications dédiées). Cependant pour cet objet c’est tout à fait surdimensionné, et un simple scan 2D suffit amplement.

Je l’ai fait assez simplement avec mon scanner, en positionnant les pièces directement sur la vitre et en ajoutant des règles pour pouvoir garder des repères de taille qui seront très utiles lors de l’étape de calibration. J’ai scanné une pièce cassée, et une autre en bon état d’une autre persienne.

C’est également possible sans scanner, en prenant en photo les pièces ; il faut prévoir de traiter l’image par la suite pour supprimer la déformation, par exemple avec Darktable et ses fonctionnalités de correction de lentille, ou de correction de perspective. Une alternative pour minimiser la déformation sans post-traitement consiste à prendre les objets assez loin et à la verticale, puis de zoomer ensuite sur l’image.

Vectorisation

Cette partie est facultative, vous pouvez importer l’image directement dans Fusion360. Mais j’ai voulu tester la vectorisation dans Inkscape et la possibilité d’utiliser le profil correspondant dans Fusion360. Ce n’est finalement pas ce que j’ai utilisé.

Cette photo montre les différentes étapes, de gauche à droite, en vectorisant via détection de contours, puis nettoyant les imperfections et en simplifiant un maximum sans affecter la forme globale :

Modélisation sous Fusion360

Dans Fusion360, on peut ensuite insérer l’image:

Puis la calibrer en utilisant le clic droit sur l’image, puis option Calibrer ; il suffit ensuite de tracer une cote et la dimension associée. Parfait pour utiliser notre règle repère.

J’ai ensuite créé une esquisse au-dessus de l’image, puis créé les volumes 3D à partie de l’esquisse.

Impression

Enfin la dernière étape est l’impression ; j’ai utilisé les réglages suivants :

• utilisation d’un filament PETG pour plus de résistance mécanique et thermique (et moins cassant que le PLA), à 240°C et 80°C pour le plateau
• un remplissage de 50% en Cubic (un remplissage plus important ne donne pas plus de résistance mécanique)
• 3 épaisseurs de murs, et 4 couches en haut et en bas
• et bien sûr des supports

Le résultat est plutôt OK, et semble résister correctement aux tests que j’ai faits à confirmer dans le temps :

J’avais oublié à ce stade les coins cassés, j’ai corrigé sur le dernier modèle. Les modèles sont disponibles sous Thingiverse ou Printables.

Exemple d’une annonce AliExpress

Il existe énormément d’annonces qui présente cette “particularité”, prenons en exemple cette annonce AliExpress :

La présentation rapide parle d’un “Hub USB 3.0 à 4 ports haute vitesse” :

On voit bien une mention à la fin du titre mentionnant “4 ports USB 3.0, 2.0”, mais à ce stade on peut comprendre que le titre veuille dire que les ports sont également compatibles USB 2.0

La présentation détaillée donne des indications plus précises, et contradictoires !

Une première phrase dans la description (mis en évidence par le premier rectangle en rouge) mentionne sans équivoque possible 4 ports USB 3.0. Cette partie est fausse. Mais un deuxième passage dans la description (mis en évidence par le premier rectangle en vert) donne quant à lui l’information exacte, à savoir un seul port en USB3.0 et les autres en USB2.0.

Le “piège” des couleurs des ports

Je me suis rendu compte à cette occasion que je faisais un peu trop confiance à la couleur des ports USB. En effet, j’avais en tête “connecteur bleu = USB 3.0”. Certain sites, comme celui de Corsair, mentionnent d’ailleurs toute une palette de couleurs de ports :

Dans notre exemple, que ce soit les 4 connecteurs ou le câble, tout est bleu, impossible de se douteur que les 4 ports ne sont pas identiques :

Cependant, j’ai cherché dans la norme USB, et je n’ai trouvé nulle part de norme portant sur la couleur des ports USB. Je ne sais pas si je n’ai pas bien cherché ou si ce n’est effectivement pas normé. Il est probable que ce ne soit qu’une convention, très répandue, mais que le fabricant ne soit pas réellement “non conforme” s’il ne suit pas la convention…

La surprise au démontage

Le démontage du Hub est très instructif pour comprendre comment cela fonctionne :

On voit effectivement assez clairement d’après le câblage que les 3 ports USB de gauches n’ont que 4 fils et plots (rectangle blanc), et ne peuvent donc pas physiquement aller au-delà de la compatibilité USB 2.0 (2 fils d’alimentation, et 2 fils pour les données).

Le premier connecteur quant à lui, comporte le bon nombre de fils, avec 2 fils provenant de la puce qui doit être un hub USB 2.0, et les 5 fils USB 3.0 relié en directe depuis le câble (rectangle bleu).

Je n’ai pas pu vérifier car le hub n’étant plus fonctionnel, les résultats ne seraient pas exacts, et je n’ai pas envie de cramer un port USB, mais il est probable que le firmware de la puce hub USB 2.0 soit modifié pour annoncer le premier port en USB 3.0.

Les Hubs à 7 ou 10 ports

La norme USB permet des hubs de 4 ports. Lorsqu’il y a plus que 4 ports, c’est qu’il y a en réalité plusieurs hubs en cascade :

• 7 ports : un premier hub 4 ports, dont un des ports est utilisé par un autre hub, ce qui donne 7 ports disponibles ( 4 - 1 pour le premier hub, et 4 pour le deuxième)
• 10 ports : un premier hub 4 ports, dont deux des ports sont utilisés par deux autres hubs (4 - 2 + 2 x 4)

J’ai ainsi pu constater sur un Hub USB 3.0 à 7 ports, qu’en réalisé, seuls 3 ports supportent réellement l’USB 3.0, et les 4 ports restants sont seulement en USB 2.0. Comme il fonctionne encore, je ne l’ai pas démonté, mais il est certainement constitué d’un premier Hub 3.0, dont l’un des ports est ensuite utilisé par un second hub en cascade uniquement en 2.0. Encore une fois, de l’extérieur rien de ne permet de distinguer les ports. C’est un peu dommage, ce format 3 USB 3.0 + 4 USB 2.0 est plutôt intéressante, on a rarement besoin de plus en USB 3.0, et si c’était le cas il y aurait probablement d’autres limitations de bande passante ou d’alimentation, mais c’est dommage qu’aucune indication visuelle ne permette de comprendre la différence entre les ports, pour brancher les bons périphériques sur les bons ports.

Conclusion

En conclusion, méfiez-vous des hubs marqués USB 3.0 de marque inconnue (qu’ils ne soient pas chers ou non…) et ne faites pas une confiance aveugle à la couleur des connecteurs…

Dans la jungle des câbles USB, faîtes également très attention aux spécifications des câbles Type C, qui peuvent être très différentes sur la compatibilité avec le transport de vidéo, la bande passante disponible, ou encore la puissance maximum supportée.