Che cosa vede il tuo cliente quando la tua VM si avvia

Vendi macchine virtuali con il tuo nome. Un cliente ne accende una, e la prima cosa sullo schermo è il logo di qualcun altro.

Quella è una VM Proxmox di serie. Non c’è niente di rotto, e Proxmox non sta facendo niente di sbagliato: è il loro prodotto e il loro nome, hanno scritto loro il firmware e l’interfaccia in cui compare, e hanno tutto il diritto di metterlo lì, così come un produttore di server mette il proprio marchio sul frontale della macchina. Solo che non è il tuo.

Il logo è solo l’inizio. Ecco che cosa dichiara un guest UEFI di serie sul firmware attuale di Proxmox, pve-edk2-firmware 4.2026.08-1, letto da dentro il guest con dmidecode:

Dove guarda il guestChe cosa leggeDi chi è il nome
Schermata di avvioil logo di ProxmoxProxmox
Vendor del firmware (SMBIOS tipo 0)Proxmox distribution of EDK IIProxmox
Versione del firmware4.2026.08-1la versione del pacchetto di Proxmox
Produttore del sistema (tipo 1)QEMUQEMU
Nome del prodotto (tipo 1)Standard PC (Q35 + ICH9, 2009)QEMU
Produttore dello chassis (tipo 3)QEMUQEMU
Scheda madre (tipo 2)del tutto assentenessuno
Interfaccia web di gestioneil logo di Proxmox, in alto a sinistraProxmox

E il logo di avvio non si ferma nemmeno al firmware. Il firmware UEFI passa l’immagine che ha disegnato al sistema operativo tramite una tabella ACPI chiamata BGRT, la Boot Graphics Resource Table, che esiste per dire «an image was drawn on the screen during boot»1, e il sistema operativo poi la ridisegna sulla propria schermata di avvio. Il Fisher-Price OS (Windows) la mette sopra la sua rotellina, e Microsoft definisce la BGRT «the standard interface that Windows uses to access the logo»2. Il tema Plymouth predefinito di Fedora fa lo stesso su Linux3. Quindi un guest sul firmware di Proxmox mostra il logo di Proxmox due volte prima che qualcuno abbia fatto login.

Niente di tutto questo è difficile da cambiare. Il difficile è che resti cambiato. Il prossimo apt full-upgrade ne rimetterà a posto metà in silenzio, e la metà che non rimette a posto è quella che dovrebbe preoccuparti, ed è di questo che parla gran parte del post.

Dove entra nell'avvio ogni pezzo del marchioAccensioneQEMU costruisceSMBIOS e ACPIdalla configFirmwareOVMF disegna illogo integrato,SeaBIOS uno splashPassaggiotabelle SMBIOS,ACPI con BGRTe MSDMAvvio del SOridisegna illogo del firmwareda BGRTGuest avviatolegge le stringhe,l'attivazione leggela chiave MSDMconfig della VMfile di pacchettoconfig della VMfile di pacchettoconfig della VMsta in /etc/pve, sopravvive a ogni upgradesta sotto /usr/share, apt lo sostituisce
Il marchio entra nell’avvio in cinque punti. Tre vengono dalla config della VM stessa e sopravvivono a qualunque cosa faccia apt. Due vengono da file di un pacchetto Proxmox, e sono quelli che un aggiornamento si riprende.

La tabella MSDM in quel passaggio di consegne non è affatto branding. Porta una chiave di licenza, e spostarne una dentro una VM ha un post tutto suo: Moving an OEM Licence Into a Proxmox VM.

Tutto ciò che sta sotto /usr/share appartiene ad apt

Una sola regola decide ogni scelta qui sotto. Un file installato da un pacchetto è un file del pacchetto. Modificalo sul posto e il prossimo aggiornamento di quel pacchetto sovrascrive la tua modifica senza dire una parola, perché per dpkg sta solo rimettendo il proprio file dove l’aveva lasciato.

Quindi ogni pezzo di branding deve vivere da qualche parte che apt non possiede. Un nodo Proxmox ha tre posti così, e ognuno costa qualcosa di diverso:

Dove viveCome ci arrivaSopravvive a un aggiornamentoChe cosa ti costa
La config della VM in /etc/pvesmbios1, e args per tutto il restoSì, la config non viene mai toccata da un pacchettoargs è solo per root, e non si vede nella GUI
Un file che dpkg ha avuto ordine di lasciare staredpkg-divertSì, la copia del pacchetto finisce invece sotto un nome .distribGli aggiornamenti non raggiungono più il file, il che conta quando il file è firmware
Una tua directory, fuori dall’albero dei pacchetti/usr/local, richiamata da argsSì, nessun pacchetto la possiedeDevi metterla su ogni nodo da solo

La descrizione che Debian stessa dà di una diversion è la più chiara: «a way of forcing dpkg not to install a file into its location, but to a diverted location»4. Questo copre l’interfaccia web. Per il firmware è una di due opzioni, e la più pericolosa.

Lo chassis è una manciata di stringhe e un controllo dei permessi

SMBIOS è la tabella con cui una macchina descrive sé stessa: chi l’ha fatta, che modello è, il suo numero di serie, che cosa sono la scheda e il case5. La legge dmidecode, la legge ogni strumento di inventario che tu abbia mai puntato su una rete, la legge il pannello informazioni di sistema del Fisher-Price OS (Windows), e lo fa anche la maggior parte dei controlli di licenza che decidono se un software girerà o no su una data macchina. Su una VM la scrive QEMU. Da qui QEMU e Standard PC nella tabella qui sopra.

Il tipo 1 tramite smbios1

Proxmox espone una sola struttura SMBIOS nella config della VM: il tipo 1, System Information, come smbios16. Accetta manufacturer, product, version, serial, sku, family e uuid.

Il tranello sta in qemu-server, non nella documentazione. Ogni campo tranne uuid deve corrispondere a uno schema base64, [A-Za-z0-9+\/]+={0,2}, quindi un valore semplice con uno spazio dentro viene rifiutato e basta. Le stringhe vere vanno codificate in base64 con base64=1 impostato, e qemu-server le decodifica di nuovo prima di costruire la riga di comando di QEMU7. L’editor SMBIOS della GUI lo fa a ogni salvataggio, con il commento «smbios values can be arbitrary, so encode and mark config as such»8. Da riga di comando è compito tuo:

b() { printf %s "$1" | base64 -w0; }
qm set 9000 --smbios1 "uuid=$(qm config 9000 | sed -n 's/.*uuid=\([0-9a-f-]*\).*/\1/p'),base64=1,\
manufacturer=$(b 'Example Cloud Ltd'),product=$(b 'EC Compute Instance'),\
version=$(b '2026.10'),family=$(b 'General Purpose'),sku=$(b 'ec-gp-4c16g')"

Nota l’uuid che viene rimesso dentro. È l’identità di macchina del guest, e qualunque cosa passi a --smbios1 viene salvata come l’intera opzione, quindi leggilo prima e tienilo.

Metti il marchio sul template, non su ogni VM. Un clone Proxmox riceve un UUID generato da zero e mantiene ogni altro campo di smbios1, quindi ogni clone esce con la propria identità e le tue stringhe9, con un’eccezione, più sotto.

I tipi 0, 2, 3 e 11 tramite args

smbios1 si ferma al tipo 1. Il vendor del firmware, la scheda madre, lo chassis e le stringhe OEM passano tutti da args, la riga che Proxmox passa dritta a QEMU e che la sua stessa documentazione definisce «for experts only»6. L’opzione -smbios di QEMU accetta i campi di ciascun tipo10:

args: -smbios 'type=0,vendor=Example Cloud Ltd,version=EC-FW 1.0,date=10/04/2026,uefi=on' -smbios 'type=2,manufacturer=Example Cloud Ltd,product=EC Virtual Board,version=1.0' -smbios 'type=3,manufacturer=Example Cloud Ltd,version=1.0,asset=EC-ASSET-123,sku=ec-gp' -smbios 'type=11,value=example-cloud:instance=123'

Avviato su QEMU con quelle righe, il dmidecode del guest legge:

StrutturaCampoDi serieCon il marchio
Tipo 0VendorProxmox distribution of EDK IIExample Cloud Ltd
Tipo 0Version4.2026.08-1EC-FW 1.0
Tipo 1ManufacturerQEMUExample Cloud Ltd
Tipo 1Product NameStandard PC (Q35 + ICH9, 2009)EC Compute Instance
Tipo 1Familynon specificatoGeneral Purpose
Tipo 2Manufacturerstruttura assenteExample Cloud Ltd
Tipo 2Product Namestruttura assenteEC Virtual Board
Tipo 3ManufacturerQEMUExample Cloud Ltd
Tipo 3Asset Tagnon specificatoEC-ASSET-123
Tipo 11String 1struttura assenteexample-cloud:instance=123

Lungo la strada sono saltate fuori quattro trappole. Tutte e quattro silenziose.

Fornire il tipo 0 fa sparire «UEFI is supported». OVMF scrive il proprio tipo 0 solo quando QEMU non ne ha fornito uno; il ciclo che percorre le tabelle di QEMU imposta NeedSmbiosType0 = FALSE nel momento in cui incontra un tipo 011. La tua stringa del vendor sostituisce quella di Proxmox, che è lo scopo. Ma il tipo 0 di QEMU sostituisce anche le caratteristiche del firmware di OVMF, e senza uefi=on la riga «UEFI is supported» sparisce da dmidecode. Rimettila con uefi=on. Per i guest UEFI c’è comunque una casa migliore per la stringa del vendor, dentro il firmware stesso, più sotto.

Il tipo di chassis non si può impostare. Il tipo 3 di QEMU accetta manufacturer, version, serial, asset e sku, e nient’altro10. Resta Other.

Due definizioni dello stesso tipo si fondono, e vince quella successiva. qemu-server mette il suo -smbios type=1 presto nella riga di comando e i tuoi args alla fine12, quindi un secondo -smbios type=1,manufacturer=… in args non butta via il primo: QEMU li ha fusi campo per campo, il produttore è venuto da args, e l’UUID è rimasto dove l’aveva messo smbios1. Questo conta per la quarta trappola.

Le due metà hanno proprietari diversi. qemu-server controlla i permessi opzione per opzione. smbios1 sta con le opzioni hardware e richiede VM.Config.HWType, mentre args ricade nel caso generico in fondo, che dice «only root can set»13. La scheda madre, lo chassis, il vendor del firmware e le stringhe OEM sono solo tuoi. Il tipo 1 no. Chiunque abbia ricevuto da te i diritti sull’hardware può riscriverlo, e su un prodotto in hosting potrebbe benissimo essere il cliente. Se la stringa del produttore conta, impostala anche in args. Vince la definizione successiva.

Il numero di serie è già nella config

La maggior parte di ciò che va nel tipo 1 è già nella config della VM. Il nome è un buon numero di serie, perché qemu-server accetta lì solo un nome DNS14: corto, stampabile, mai una virgola dentro, e l’unica cosa della VM che un cliente riconoscerà.

Campo del tipo 1Preso daPer una VM da 4 core e 16 GiB chiamata web-01, con tag production;web
Serial Numbernameweb-01
SKU Numbercores × sockets, e memoryec-4c16g
Familyla prima voce in tagsproduction
UUIDl’UUID di smbios1 che ha giàinvariato
Manufacturer, Productle tue stringhe fisseExample Cloud Ltd, EC Compute Instance

Due cose restano fuori. Il nodo cambia a ogni migrazione, e vmgenid è fatto apposta per cambiare: tutto il suo lavoro è dire al guest che è stato ripristinato da uno snapshot o creato da un template15. Nessuno dei due è un’identità.

#!/bin/bash
# /usr/local/sbin/ec-smbios VMID: rebuild smbios1 from the VM's own config.
set -euo pipefail
id=$1
cfg=$(qm config "$id" --current)
get() { sed -n "s/^$1: //p" <<<"$cfg"; }
b() { printf %s "$1" | base64 -w0; }

name=$(get name)
[ -n "$name" ] || { echo "VM $id has no name to use as a serial" >&2; exit 1; }
cores=$(get cores); sockets=$(get sockets); vcpu=$(( ${cores:-1} * ${sockets:-1} ))
mem=$(get memory); mem=${mem#current=}; mem=${mem%%,*}; mem=${mem:-512}
(( mem % 1024 )) && size="${mem}m" || size="$(( mem / 1024 ))g"
tag=$(get tags); tag=${tag%%;*}
uuid=$(get smbios1 | grep -o 'uuid=[0-9a-fA-F-]*' | cut -d= -f2 || true)
uuid=${uuid:-$(cat /proc/sys/kernel/random/uuid)}

s="uuid=$uuid,base64=1,manufacturer=$(b 'Example Cloud Ltd'),product=$(b 'EC Compute Instance')"
s+=",serial=$(b "$name"),sku=$(b "ec-${vcpu}c${size}")"
[ -n "$tag" ] && s+=",family=$(b "$tag")"
qm set "$id" --smbios1 "$s"

I default sono quelli di qemu-server stesso, un core, un socket e 512 MiB16, quindi anche una config che li omette ottiene uno SKU veritiero. Eseguito sulla config della tabella, con qm sostituito da uno script che la serviva, la riga che ha scritto è arrivata a QEMU decodificata come la decodifica qemu-server, e il dmidecode del guest ha restituito web-01, ec-4c16g, production e l’UUID che aveva già. Una VM senza nome viene rifiutata invece di ricevere un numero di serie vuoto.

La casa ovvia per questo è un hookscript. È quella sbagliata. qemu-server esegue l’hook pre-start dentro il lock della config che ha preso per avviare la VM, e costruisce la riga di comando di QEMU dalla config che aveva caricato prima che l’hook girasse17. Un hook che riscrive il numero di serie cambia il prossimo avvio, non questo.

Quindi lancialo dal tuo provisioning, nei quattro momenti in cui i suoi dati di partenza cambiano: creazione, clone, rinomina e ridimensionamento. Il clone è quello che morde. Un clone mantiene ogni campo di smbios1 tranne l’UUID9, quindi se lo salti ogni VM costruita da web-template dichiarerà come numero di serie il nome del template.

Il logo di avvio vive in due posti diversi

Quale logo mostri un guest dipende dal suo firmware. I due firmware che Proxmox distribuisce lo prendono da posti completamente diversi:

SeaBIOS (bios: seabios, il default)OVMF (bios: ovmf, UEFI)
Da dove viene il logoun JPEG che QEMU passa all’avviouna bitmap compilata dentro il firmware
Il file di Proxmox/usr/share/qemu-server/bootsplash.jpg, 640×480Logo.bmp, 400×120, 8 bit, compilato in OVMF_CODE_4M*.fd
Pacchetto proprietarioqemu-serverpve-edk2-firmware-ovmf
Cambiarlo per singola VMargs: -boot splash=…args che punta la VM a un altro firmware
Cambiarlo senza ricompilare nullasìno
Arriva al sistema operativo del guest tramite BGRTnosì

SeaBIOS: un JPEG sulla riga di comando

qemu-server mette la stessa opzione -boot su ogni VM che avvia, menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg18. La documentazione di QEMU dice che l’immagine viene mostrata «when option splash=sp_name is given and menu=on, If firmware/BIOS supports them. Currently Seabios for X86 system support it»10. OVMF non ne prende nulla tranne splash-time, che usa come timeout del menu di avvio, e in OvmfPkg non c’è alcun riferimento al file di splash19.

Sostituirlo è una riga nella config della VM:

args: -boot splash=/etc/pve/branding/splash.jpg

Un secondo -boot non fa a pugni con il primo. QEMU lo fonde nello stesso modo in cui fonde -smbios, vince il valore successivo, e con due file di splash indicati lo screenshot mostrava il secondo. /etc/pve è la casa giusta per il file, perché è il filesystem del cluster e ogni nodo vede lo stesso splash, e il suo limite di 1 MiB per file è lontanissimo da un JPEG 640×48020.

L’immagine stessa deve rispettare tre condizioni, e sbagliarne una qualsiasi ti costa il logo o i suoi colori:

CondizionePerchéChe cosa succede altrimenti
JPEG o BMP a 24 bitQEMU controlla il file prima che la VM partasplash file … format not recognized; must be JPEG or 24 bit BMP
JPEG baseline, crominanza 4:2:0il decoder di SeaBIOS non gestisce altro21ERR_NOT_SEQUENTIAL_DCT o ERR_NOT_YCBCR_221111, e uno schermo vuoto
640×480, come quello di ProxmoxSeaBIOS chiede al VGA BIOS una modalità esattamente della dimensione dell’immaginenessuna modalità corrispondente, nessuno splash

La maggior parte degli strumenti per immagini scrive baseline 4:2:0 di default, quindi il modo tipico di perdere il logo è una delle opzioni «salva per il web» che attiva in silenzio la codifica progressiva, che appare identica in ogni visualizzatore che hai e lascia SeaBIOS a disegnare il nulla.

La trappola dei colori

Questa è costata un pomeriggio. Lo stesso JPEG, reso da due build di SeaBIOS 1.17.0, esce in due colori diversi:

Uno splash di Example Cloud tre volte: il JPEG sorgente con un riquadro del logo blu, SeaBIOS come lo distribuisce Proxmox con lo stesso blu, e una build di SeaBIOS che gira a 32 bit per pixel con il blu diventato oro

Sta in jpeg.c di SeaBIOS. Lo scrittore a 24 bit per pixel ha un ramo little-endian che mette il blu nel primo byte di ogni pixel, e lo scrittore a 32 bit per pixel, PIC_32, non ha quel ramo e lì scrive invece il rosso21. Su un framebuffer little-endian questo scambia rosso e blu. Il blu esce oro, e l’arancione uscirebbe blu.

Quale scrittore gira dipende dalla modalità video che il VGA BIOS offre:

FirmwareModalità VBE per 640×480Bit per pixelColori
Il SeaBIOS 1.17.0 precompilato di QEMU upstream, come lo distribuisce pve-qemu-kvm 11.0.3-40x11116giusti, quantizzati a 65.536
La build seabios 1.17.0-10 di Fedora 440x14232rosso e blu scambiati

I numeri delle modalità sono quelli della tabella di SeaBIOS stesso22, e la riga di Proxmox è stata verificata sui blob esatti del pacchetto: identici byte per byte al precompilato di QEMU rel-1.17.0-0-gb52ca86e094d. Quindi su Proxmox i tuoi colori sono giusti, ma sono solo 65.536, e una sfumatura delicata farà le bande. E se il tuo logo dovesse mai comparire con i colori sbagliati su qualche altro hypervisor, non è colpa del tuo JPEG.

Il logo UEFI è compilato dentro il firmware

I guest UEFI sono la metà più difficile, e su un Proxmox moderno sono la maggior parte dei guest.

Non c’è alcuna opzione di splash da sovrascrivere. Il logo è una bitmap dentro l’immagine del firmware, e la build di Proxmox ce la mette con una riga in debian/rules:

debian/setup-build-stamp:
	cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp

Questo copia il loro Logo.bmp da 400×120 a 8 bit sopra quello di TianoCore prima che edk2 venga compilato23. Lo stesso file imposta il vendor del firmware come costante di compilazione, PcdFirmwareVendor=L"Proxmox distribution of EDK II", ed è da lì che viene il vendor del tipo 0 nella prima tabella23.

Logo nuovo, firmware nuovo. Il modo di ottenerne uno che si comporti esattamente come quello di Proxmox è compilarlo esattamente come fa Proxmox: il loro albero al tag che corrisponde al pacchetto che distribuiscono, le loro patch, i loro flag, e una sola bitmap cambiata. pve-edk2-firmware 4.2026.08-1 fissa edk2 a 2970e56, che è il tag upstream edk2-stable20260823.

git clone https://git.proxmox.com/git/pve-edk2-firmware.git
cd pve-edk2-firmware
git checkout f37039e52d228a7844a90aa2aaf1e161ebd04fcd   # 4.2026.08-1
git submodule update --init --recursive
cd edk2
QUILT_PATCHES=../debian/patches quilt push -a
cp /path/to/your/Logo.bmp MdeModulePkg/Logo/Logo.bmp
. ./edksetup.sh && make -C BaseTools

F="-DNETWORK_HTTP_BOOT_ENABLE=TRUE -DNETWORK_IP6_ENABLE=TRUE -DNETWORK_TLS_ENABLE
   -DSECURE_BOOT_ENABLE=TRUE -DPVSCSI_ENABLE=TRUE -DTPM2_ENABLE=TRUE
   --pcd PcdUninstallMemAttrProtocol=TRUE -DFD_SIZE_4MB"
P=(--pcd "PcdFirmwareVendor=LExample Cloud Ltd\\0"
   --pcd "PcdFirmwareVersionString=L4.2026.08-1+ec1\\0")

build -a IA32 -a X64 -t GCC -p OvmfPkg/OvmfPkgIa32X64.dsc $F "${P[@]}" -b RELEASE
cp Build/Ovmf3264/RELEASE_GCC/FV/OVMF_CODE.fd OVMF_CODE_4M.fd
rm -rf Build/Ovmf3264
build -a IA32 -a X64 -t GCC -p OvmfPkg/OvmfPkgIa32X64.dsc $F -DSMM_REQUIRE=TRUE "${P[@]}" -b RELEASE
cp Build/Ovmf3264/RELEASE_GCC/FV/OVMF_CODE.fd OVMF_CODE_4M.secboot.fd

I flag sono presi da debian/rules così com’è a quel commit. Attenzione alla stringa del vendor: il loro Makefile la scrive tra virgolette doppie, la shell di make le toglie, ed edk2 la riceve nuda, quindi qui è passata così, e metterla tra virgolette una seconda volta è un errore di compilazione. Tieni la bitmap a 400×120 e 8 bit come la loro e nient’altro si sposta sulla schermata di avvio.

Ti servono entrambe le immagini. qemu-server avvia qualunque VM Q35 con un disco EFI da 4M su OVMF_CODE_4M.secboot.fd, la build con SMM obbligatorio, e usa il semplice OVMF_CODE_4M.fd solo per i440fx24. Su un Proxmox attuale quella secboot è ciò che fa girare quasi ogni guest UEFI.

Compilata così, senza cambiare nulla dell’albero di Proxmox tranne la bitmap e due stringhe, l’immagine SMM si avvia così:

La schermata di avvio di un guest disegnata dall’immagine OVMF ricompilata, con un logo di Example Cloud dove ci sarebbe quello di Proxmox

E con essa cambia anche la vista che il guest ha del proprio firmware, senza una sola opzione -smbios sulla riga di comando:

Letto dentro il guest4.2026.08-1 di ProxmoxRicompilato dallo stesso albero
Vendor del firmwareProxmox distribution of EDK IIExample Cloud Ltd
Versione del firmware4.2026.08-14.2026.08-1+ec1
«UEFI is supported»presentepresente
Tabelle ACPIBGRT, WSMT e le altrelo stesso insieme

Questo rende il vendor di compilazione la risposta migliore per i guest UEFI. È il tipo 0 di OVMF stesso, quindi il bit UEFI resta al suo posto senza che nessuno debba ricordarsi uefi=on. La via di args per il tipo 0 è per i guest SeaBIOS, e per chi non ricompila affatto il firmware.

Due modi di dare il nuovo firmware a una VM

qemu-server ha cablato nel codice dove cercare il firmware: OVMF.pm contiene una tabella di percorsi sotto /usr/share/pve-edk2-firmware/, indicizzata per tipo di macchina e opzioni di Secure Boot, e non c’è alcuna opzione nella config della VM, nella GUI o nell’API che scelga un file diverso24. Restano due strade.

Compilare OVMF con il tuo marchio e le due vie per darlo a una VML'albero di Proxmoxpve-edk2-firmware 4.2026.08-1Il tuo marchioLogo.bmp + stringa vendorStessa build, stessi flagOVMF_CODE_4M.fd + .secboot.fdA: divert su ogni nodoogni VM UEFI lo riceve,config delle VM invariateB: per VM tramite argsscegli VM per VM,file di Proxmox intattiapt full-upgradearriva il firmware nuovo, il tuo resta vecchiohook Post-Invokeversioni diverse: ricompila prima del riavvio
Una build, due vie d’ingresso. In entrambi i casi, il prossimo aggiornamento installa il nuovo firmware di Proxmox accanto al tuo e lascia il tuo com’era, ed è per questo che esiste l’hook in fondo.

Strada A: fare la diversion su ogni nodo. Di’ a dpkg che le due immagini di codice di Proxmox ora stanno da un’altra parte, e metti le tue dove stavano loro:

D=/usr/share/pve-edk2-firmware
for f in OVMF_CODE_4M.fd OVMF_CODE_4M.secboot.fd; do
  dpkg-divert --package example-branding --add --rename --divert "$D/$f.distrib" "$D/$f"
  install -m 0644 "/root/branding/$f" "$D/$f"
done

Dal suo prossimo avvio, ogni VM UEFI del nodo avvia il tuo firmware. Nessuna modifica alla config delle VM.

Strada B: puntarci le VM che scegli. Tieni le immagini in una tua directory e sovrascrivi il firmware una VM alla volta. Da quando è passato a -blockdev, qemu-server collega l’immagine di codice come un nodo di blocco chiamato pflash0 e lo nomina in -machine24, e QEMU fonde un secondo -machine nello stesso modo in cui fonde -boot, quindi args può aggiungere un nodo suo e puntare pflash0 su quello:

args: -blockdev driver=raw,node-name=brandcode,read-only=on,file.driver=file,file.filename=/usr/local/share/example-branding/OVMF_CODE_4M.secboot.fd -machine pflash0=brandcode

È stato provato facendo il giro lungo. Il firmware secboot di Proxmox è stato collegato come pflash0 esattamente come lo fa qemu-server, con SMM attivo, poi dopo è stata aggiunta quella riga args, e il guest ha avviato l’immagine con il marchio con sia il logo sia la stringa del vendor: è da lì che viene lo screenshot qui sopra.

Strada A, diversionStrada B, args per VM
Quali VM lo ricevonoogni VM UEFI del nodosolo le VM su cui lo imposti
I file di Proxmoxspostati in .distribintatti
Config della VMinvariatauna riga args, solo root
Il tipo di macchina deve corrisponderegestito, entrambe le immagini sono deviatecompito tuo: immagine secboot per Q35
Annullaredpkg-divert --remove --renamecancellare la riga
Migrazioneanche il nodo di destinazione deve avere la diversionil nodo di destinazione deve avere il file

L’immagine di codice pesa circa 3,5 MB, contro un limite di 1 MiB per file in pmxcfs20. Per questo non può stare in /etc/pve, e qualunque strada prendi, va messa su ogni nodo. Migra una VM su un nodo che non ce l’ha e ottieni uno di due risultati, a seconda della strada: con la strada A tornano il firmware e il logo di Proxmox, con la strada B una VM che non parte affatto perché QEMU non riesce ad aprire un file che non c’è.

L’aggiornamento che ti lascia indietro

Una diversion è lo strumento giusto per un logo. Il firmware è un’altra cosa.

Una diversion significa che gli aggiornamenti di Proxmox non raggiungono più il file. È esattamente ciò che hai chiesto. Ed è anche esattamente ciò che impedisce alle correzioni di sicurezza di edk2 di arrivare ai tuoi guest: il changelog di Proxmox per la 4.2026.08-1 si apre con «Besides many bug and security fixes» e prosegue elencando una correzione per CVE-2024-1374525, e una build con il tuo marchio della release precedente non ne ha nessuna. Niente te lo dice.

Questo è stato provato, non supposto. In un container Debian trixie con il repository di Proxmox è stato installato pve-edk2-firmware-ovmf 4.2025.05-3, entrambe le immagini di codice sono state deviate, e il pacchetto è stato aggiornato alla 4.2026.08-1:

Dopo l’aggiornamentoRisultato
dpkg-query -W pve-edk2-firmware-ovmf4.2026.08-1
La nuova immagine di Proxmoxinstallata come OVMF_CODE_4M.fd.distrib, hash cambiato
L’immagine con il marchioinvariata, ancora compilata dalla 4.2025.05-3
Qualcosa sulla console in propositoniente, fino all’hook qui sotto

Quindi aggiungi un hook. apt esegue un elenco di comandi DPkg::Post-Invoke dopo ogni esecuzione di dpkg26. Registra da quale versione di Proxmox hai compilato, e confronta dopo ciascuna:

cat > /usr/local/sbin/example-branding-check <<'EOF'
#!/bin/sh
built=$(cat /usr/local/share/example-branding/ovmf.built-from 2>/dev/null)
now=$(dpkg-query -W -f '${Version}' pve-edk2-firmware-ovmf 2>/dev/null)
[ "$built" = "$now" ] && exit 0
echo "W: branded OVMF was built from pve-edk2-firmware-ovmf $built, Proxmox now ships $now." >&2
echo "W: guests still boot the old firmware. Rebuild before the next VM restart." >&2
exit 0
EOF
chmod +x /usr/local/sbin/example-branding-check
echo 'DPkg::Post-Invoke { "/usr/local/sbin/example-branding-check"; };' \
  > /etc/apt/apt.conf.d/80example-branding

Su quello stesso aggiornamento ha stampato:

W: branded OVMF was built from pve-edk2-firmware-ovmf 4.2025.05-3, Proxmox now ships 4.2026.08-1.
W: guests still boot the old firmware. Rebuild before the next VM restart.

Esce con 0 di proposito. apt si interrompe se un comando Post-Invoke fallisce26, e un controllo sul branding non è un buon motivo per lasciare un nodo aggiornato a metà. Un avviso ben visibile basta.

Un’ultima cosa. I riavvii. Un guest prende il nuovo firmware solo quando il suo processo QEMU riparte, quindi una ricompilazione richiede uno stop e uno start da Proxmox invece di un riavvio da dentro il guest, ed è esattamente così che anche gli aggiornamenti del firmware di Proxmox stesso arrivano a una VM in esecuzione. Solo che quelli non hanno bisogno che tu ti ricordi prima di ricompilare.

Oppure lascia stare il firmware di Proxmox

Ogni via per il logo vista finora cambia il firmware, e la sezione precedente è il conto di quella scelta. Ce n’è una che non lo fa, e per questo post ne è stato costruito un prototipo.

Un dispositivo PCI in QEMU può portare una option ROM, qualunque file indichi con romfile=27, e OVMF esegue il driver EFI che ci trova dentro. La build di Proxmox lo esegue che sia firmato o no: OVMF imposta PcdOptionRomImageVerificationPolicy a 0x00, esegui sempre28. OVMF disegna il proprio logo tardi, nella selezione del dispositivo di avvio29, e costruisce la BGRT solo a ReadyToBoot, l’istante prima di passare la mano a un boot loader. E il driver BGRT di edk2 accetta un’immagine sostitutiva tramite EDKII_BOOT_LOGO2_PROTOCOL, ricostruendo la tabella a ReadyToBoot ogni volta che l’immagine è cambiata30.

Non serve altro. Il driver aspetta ReadyToBoot a TPL_NOTIFY, che gira prima del gestore TPL_CALLBACK del driver BGRT, pulisce lo schermo, disegna il suo logo e consegna la stessa immagine. Compilato, è un unico file da 8 KB, collegato con una riga:

args: -device pci-testdev,romfile=/etc/pve/branding/brandrom.rom

Con 8 KB sta comodamente dentro il limite di 1 MiB di pmxcfs20, quindi a differenza di un’immagine firmware da 3,5 MB può vivere in /etc/pve e seguire la VM su ogni nodo.

È stato provato contro il firmware di Proxmox così com’è, preso da pve-edk2-firmware-ovmf 4.2026.08-1: OVMF_CODE_4M.secboot.fd con le chiavi Microsoft già registrate in OVMF_VARS_4M.ms.fd, su Q35 con SMM, avviato tramite lo shim firmato di Fedora così che Secure Boot fosse attivo e applicato:

Letto dal guestSenza la ROMCon la ROM
Variabile SecureBoot11
Sullo schermoil logo di Proxmoxquello di Proxmox per circa 250 ms, poi il tuo
Immagine BGRT, 400×120 in posizione (440, 340)quella di Proxmox, SHA-256 be5afe4b…quella della ROM, SHA-256 6c494576…
File del firmware modificatinessunonessuno

L’immagine che un guest ha riletto dalla sua tabella BGRT con la option ROM collegata: un logo di Example Cloud, con la didascalia drawn by an option ROM

L’ultima riga è il punto. Il firmware di Proxmox è intatto, quindi la loro prossima release di sicurezza arriva ai tuoi guest con il prossimo riavvio, e niente della sezione precedente si applica.

Non è gratis:

CostoPerché
Il logo di Proxmox si vede per circa un quarto di secondoOVMF lo disegna prima che qualunque driver di option ROM prenda lo schermo; solo una ricompilazione lo evita
Il guest vede un dispositivo PCI in più, senza driverla ROM deve viaggiare su un dispositivo, e pci-testdev è quello di QEMU che non fa niente
Il tipo 0 dice ancora Proxmoxla stringa del vendor è compilata dentro; impostala tramite args con uefi=on, come sopra
Solo rootè una riga args

E la scoperta che ci sta sotto va detta chiaramente. Un driver non firmato è stato eseguito nel firmware su un guest con le chiavi Microsoft registrate e Secure Boot applicato, perché l’OVMF di Proxmox non controlla le option ROM. Qui questo è utile. Significa anche che su questo firmware Secure Boot controlla i boot loader, non quello che la config hardware della VM ci collega, e visto che solo root scrive args, la domanda diventa chi ha root sui tuoi nodi.

È un prototipo. È girato su QEMU 10.2.2 con il firmware di Proxmox, non ancora su un nodo Proxmox, e ciò che segue è codice sorgente, non un prodotto:

github.com/damo2929/RebrandPCIRom: il driver della option ROM, il convertitore del logo e la build in container.

L’interfaccia web sono due pacchetti

Il logo in alto a sinistra dell’interfaccia web non sta in pve-manager. Workspace.js chiede un componente proxmoxLogoSvg con il prefisso pwt, e quello vive in proxmox-widget-toolkit, che il Backup Server e il Mail Gateway condividono31. In pve-manager ci sono solo le icone della scheda:

Che cosaFilePacchetto
Logo dell’intestazione, disegnato a 200×35/usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svgproxmox-widget-toolkit
Icona della scheda del browser/usr/share/pve-manager/images/favicon.icopve-manager
Icona 128×128, usata anche come touch icon/usr/share/pve-manager/images/logo-128.pngpve-manager

Sono tutti e tre file normali, quindi questo è un lavoro per dpkg-divert, e qui il costo della sezione precedente non si applica affatto, perché un logo non ha correzioni di sicurezza da perdere e il guest di nessuno è meno sicuro per colpa di un nodo che serve ancora la favicon del mese scorso.

divert() {
  dpkg-divert --package example-branding --add --rename --divert "$1.distrib" "$1"
  install -m 0644 "$2" "$1"
}
divert /usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svg /root/branding/logo.svg
divert /usr/share/pve-manager/images/favicon.ico   /root/branding/favicon.ico
divert /usr/share/pve-manager/images/logo-128.png  /root/branding/logo-128.png

Provato nello stesso container, su pacchetti veri:

PassoRisultato
Diversion su proxmox-widget-toolkit 5.2.9, installazione del proprio SVGl’SVG di Proxmox rinominato in proxmox_logo.svg.distrib
Aggiornamento alla 5.2.10il proprio SVG ancora al suo posto, la copia 5.2.10 di Proxmox in .distrib
dpkg --verify proxmox-widget-toolkitnessuna lamentela, dpkg sa della diversion
apt-get install --reinstall proxmox-widget-toolkitil proprio SVG ancora al suo posto
dpkg-divert --remove --renamel’originale di Proxmox di nuovo lì, byte per byte

Due cose restano di Proxmox. L’immagine dell’intestazione è disegnata in un riquadro fisso da 200×35, quindi disegna il tuo SVG in quella forma o verrà schiacciato. E il testo alt dice Proxmox e l’immagine porta a https://www.proxmox.com, entrambi scritti nel componente JavaScript invece che in un file che puoi deviare31. Cambiarli significa fare la patch di un bundle minificato che si rompe a ogni aggiornamento. Non ne vale la pena per un testo alternativo.

Che cosa ti chiedono la licenza e il marchio di Proxmox

Proxmox VE è distribuito sotto la AGPL versione 332, e la sezione 13 di quella licenza è la clausola di rete: «if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network … an opportunity to receive the Corresponding Source of your version»33. Cambiare tre immagini conta come modificare il Programma? Quella è una domanda per un avvocato. La risposta economica è mettere le tue immagini e lo script di diversion da qualche parte in pubblico e collegarli dalla pagina di login. Non costa niente e chiude la questione.

Sul marchio è più chiaro. Il media kit di Proxmox dice «Don’t alter the logo or incorporate the logo or symbol into your logo»34. Quindi sostituisci il loro del tutto con il tuo, mai una versione ricolorata o rimaneggiata del loro, e tieni Proxmox fuori dal nome del tuo prodotto.

Il tuo nome sopra significa la tua manutenzione

Mettere il marchio su una VM costa poco. Una manciata di stringhe SMBIOS, un JPEG, una bitmap e tre immagini in un’interfaccia web: un pomeriggio di lavoro, la maggior parte passato a scoprire dove stanno le cose.

Tenerlo è il lavoro vero. Ed è anche la parte che si salta.

Le stringhe SMBIOS e lo splash si arrangiano da soli, perché vivono in una config che nessun pacchetto toccherà mai, e il logo dell’interfaccia web si arrangia da solo perché a dpkg è stato detto di lui. Il firmware no. Il giorno in cui metti il tuo logo in un’immagine firmware, ti prendi in carico un pezzo del processo di rilascio di qualcun altro, e Proxmox compila, prova e distribuisce nuovo firmware con dentro correzioni di sicurezza che i loro clienti ricevono con il prossimo aggiornamento, e i tuoi ricevono quando ti decidi a ricompilare.

È uno scambio che va bene, se fatto sapendolo. Un’azienda di hosting i cui guest avviano un firmware indietro di due release perché il logo contava più del changelog non ha costruito un prodotto. Ha costruito un adesivo.

Se il tuo nome è sulla schermata di avvio, il firmware dietro è tuo da tenere aggiornato, chiunque l’abbia scritto. Nessuno controllerà. È proprio per questo che va fatto.


  1. UEFI Forum, ACPI Specification 6.6, §5.2.23 Boot Graphics Resource Table — «The Boot Graphics Resource Table (BGRT) is an optional table that provides a mechanism to indicate that an image was drawn on the screen during boot». Copia d’archivio; la pagina viva restituisce 403 alle richieste automatiche. ↩︎

  2. Microsoft Learn, Boot screen components — «This is the standard interface that Windows uses to access the logo.» ↩︎

  3. Fedora Project, Changes/FlickerFreeBoot — «a new plymouth theme which incorporates the firmware’s bootsplash image»; il plymouth.spec di Fedora rende bgrt il tema predefinito. ↩︎

  4. Debian, dpkg-divert(1), trixie — «File diversions are a way of forcing dpkg(1) not to install a file into its location, but to a diverted location.» ↩︎

  5. DMTF, DSP0134 System Management BIOS Reference Specification 3.10.0 — tipo 1 System Information, tipo 2 scheda madre, tipo 3 «the system’s mechanical enclosure(s)», tipo 11 «free-form strings defined by the OEM». ↩︎

  6. Proxmox VE, qm.conf(5) — smbios1: «Specify SMBIOS type 1 fields»; args: «Arbitrary arguments passed to kvm … this option is for experts only.» ↩︎ ↩︎

  7. qemu-server, src/PVE/QemuServer.pm, the smbios1 format and command-line builder — ogni campo tranne uuid ha lo schema [A-Za-z0-9+\/]+={0,2}; i valori vengono decodificati quando base64 è impostato. ↩︎

  8. pve-manager, www/manager6/Parser.js, printQemuSmbios1 — «smbios values can be arbitrary, so encode and mark config as such». ↩︎

  9. qemu-server, src/PVE/API2/Qemu.pm, clone — «auto generate a new uuid», gli altri campi di smbios1 vengono mantenuti. ↩︎ ↩︎

  10. QEMU, System Emulation, Invocation — i campi di -smbios per tipo; -acpitable «For file=, take whole ACPI table from the specified files, including all ACPI headers»; -boot «Currently Seabios for X86 system support it.» ↩︎ ↩︎ ↩︎

  11. edk2-stable202608, OvmfPkg/SmbiosPlatformDxe/SmbiosPlatformDxe.c — OVMF aggiunge il proprio tipo 0 solo quando NeedSmbiosType0 è ancora impostato dopo aver percorso le tabelle di QEMU. ↩︎

  12. qemu-server, src/PVE/QemuServer.pm, custom args — gli args vengono divisi e accodati alla fine della riga di comando. ↩︎

  13. qemu-server, src/PVE/API2/Qemu.pm, config permission checks — smbios1 è un’opzione di tipo hardware che richiede VM.Config.HWType; il caso di riserva «catches args, lock, etc.» e termina con «only root can set». ↩︎

  14. qemu-server, src/PVE/QemuServer.pm, the name option — format => 'dns-name'. ↩︎

  15. qemu-server, src/PVE/QemuServer.pm, vmgenid — «notify the guest operating system when the virtual machine is executed with a different configuration (e.g. snapshot execution or creation from a template)». ↩︎

  16. qemu-server, src/PVE/QemuServer/Memory.pm — memoria default => 512; cores e sockets hanno default 1 in QemuServer.pm. ↩︎

  17. qemu-server, src/PVE/QemuServer.pm, vm_start — lock_config alla riga 5457, exec_hookscript($conf, $vmid, 'pre-start', 1) alla 5581, e config_to_command alla 5634 con lo stesso $conf, non ricaricato nel frattempo. ↩︎

  18. qemu-server, src/PVE/QemuServer.pm, -boot — menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg. ↩︎

  19. edk2-stable202608, OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c — OVMF legge etc/boot-menu-wait, il valore di splash-time, e nient’altro da -boot. ↩︎

  20. pve-cluster, src/pmxcfs/memdb.h — #define MEMDB_MAX_FILE_SIZE (1024 * 1024) // 1 MiB. ↩︎ ↩︎ ↩︎

  21. SeaBIOS, src/jpeg.c — PIC scrive prima il blu su little-endian, PIC_32 alla riga 946 scrive prima il rosso senza alcun ramo per l’endianness; ERR_NOT_SEQUENTIAL_DCT ed ERR_NOT_YCBCR_221111 sono gli unici formati rifiutati. ↩︎ ↩︎

  22. SeaBIOS, vgasrc/svgamodes.c — la modalità 0x111 è 640×480 a 16 bit, 0x142 è 640×480 a 32. ↩︎

  23. pve-edk2-firmware, debian/rules at 4.2026.08-1 — cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp, la stringa PcdFirmwareVendor e i flag di compilazione di OVMF. ↩︎ ↩︎ ↩︎

  24. qemu-server, src/PVE/QemuServer/OVMF.pm — la tabella del firmware cablata sotto /usr/share/pve-edk2-firmware/, la scelta SMM e il nodo di blocco pflash0. ↩︎ ↩︎ ↩︎

  25. pve-edk2-firmware, debian/changelog — 4.2026.08-1: «Besides many bug and security fixes … fix CVE-2024-13745». ↩︎

  26. Debian, apt.conf(5), trixie — «Pre-Invoke, Post-Invoke: This is a list of shell commands to run before/after invoking dpkg(1) … should any fail APT will abort.» ↩︎ ↩︎

  27. QEMU v11.0.3, hw/pci/pci.c — DEFINE_PROP_STRING("romfile", PCIDevice, romfile), una proprietà che ha ogni dispositivo PCI. ↩︎

  28. edk2-stable202608, OvmfPkg/OvmfPkgIa32X64.dsc — gEfiSecurityPkgTokenSpaceGuid.PcdOptionRomImageVerificationPolicy|0x00, il file di piattaforma che Proxmox compila. ↩︎

  29. edk2-stable202608, OvmfPkg/Library/PlatformBootManagerLib/BdsPlatform.c — BootLogoEnableLogo (), chiamata da PlatformBootManagerAfterConsole. ↩︎

  30. edk2-stable202608, BootGraphicsResourceTableDxe.c — SetBootLogo2 alla riga 239 copia l’immagine; il gestore di ReadyToBoot alla 417 disinstalla e reinstalla la tabella «If BGRT data change happens». ↩︎

  31. proxmox-widget-toolkit, src/Logo.js — proxmoxLogoSvg, 200×35, alt: 'Proxmox', con link a proxmox.com; usato da pve-manager Workspace.js con prefix: 'pwt'. ↩︎ ↩︎

  32. Proxmox VE wiki, FAQ — «Proxmox VE code is licensed under the GNU Affero General Public License, version 3.» ↩︎

  33. GNU Affero General Public License v3, §13 Remote Network Interaction — citata per intero nel testo qui sopra. ↩︎

  34. Proxmox, Media kit — «Don’t alter the logo or incorporate the logo or symbol into your logo.» ↩︎