Co widzi twój klient, kiedy twoja VM startuje

Sprzedajesz maszyny wirtualne pod własną nazwą. Klient włącza jedną z nich, a pierwsze, co widzi na ekranie, to cudze logo.

Tak wygląda VM z Proxmoxa prosto z pudełka. Nic tu nie jest zepsute i Proxmox nie robi nic złego: to ich produkt i ich nazwa, napisali firmware i interfejs, w którym się pojawia, i mają pełne prawo ją tam umieścić, tak samo jak producent serwera przykręca swoją plakietkę z przodu obudowy. Tyle że to nie jest twoje.

Logo to dopiero początek. Tak przedstawia się standardowy gość UEFI na obecnym firmware Proxmoxa, pve-edk2-firmware 4.2026.08-1, odczytany z wnętrza gościa przez dmidecode:

Gdzie patrzy gośćCo odczytujeCzyja nazwa
Ekran startowylogo ProxmoxaProxmox
Producent firmware’u (SMBIOS typ 0)Proxmox distribution of EDK IIProxmox
Wersja firmware’u4.2026.08-1wersja pakietu Proxmoxa
Producent systemu (typ 1)QEMUQEMU
Nazwa produktu (typ 1)Standard PC (Q35 + ICH9, 2009)QEMU
Producent obudowy (typ 3)QEMUQEMU
Płyta główna (typ 2)w ogóle jej nie maniczyja
Webowy interfejs zarządzanialogo Proxmoxa, w lewym górnym roguProxmox

Logo startowe nie kończy się zresztą na firmware. Firmware UEFI przekazuje narysowany obraz systemowi operacyjnemu przez tabelę ACPI o nazwie BGRT, Boot Graphics Resource Table, która istnieje po to, żeby powiedzieć „an image was drawn on the screen during boot”1, a system operacyjny rysuje go potem jeszcze raz na własnym ekranie startowym. Fisher-Price OS (Windows) umieszcza go nad swoim kółkiem ładowania, a Microsoft nazywa BGRT „the standard interface that Windows uses to access the logo”2. Domyślny motyw Plymouth w Fedorze robi to samo na Linuksie3. Gość na firmware Proxmoxa pokazuje więc logo Proxmoxa dwa razy, zanim ktokolwiek się zaloguje.

Nic z tego nie jest trudne do zmiany. Trudne jest utrzymanie tej zmiany. Następne apt full-upgrade po cichu przywróci połowę, a ta połowa, której nie przywróci, to właśnie ta, która powinna cię martwić, i o niej jest większość tego wpisu.

Gdzie każdy element marki wchodzi do startuWłączenieQEMU budujeSMBIOS i ACPIz konfiguracjiFirmwareOVMF rysuje swojewbudowane logo,SeaBIOS splashPrzekazanietabele SMBIOS,ACPI z BGRTi MSDMEkran startu OSrysuje ponownielogo firmware'uz BGRTDziałający gośćczyta ciągi,aktywacja czytaklucz MSDMkonfiguracja VMplik pakietukonfiguracja VMplik pakietukonfiguracja VMw /etc/pve, przetrwa każdą aktualizacjępod /usr/share, apt go podmienia
Marka wchodzi do procesu startu w pięciu miejscach. Trzy pochodzą z konfiguracji samej VM i przetrwają wszystko, co zrobi apt. Dwa pochodzą z plików należących do pakietu Proxmoxa i to właśnie je aktualizacja zabiera z powrotem.

Tabela MSDM w tym przekazaniu to w ogóle nie jest branding. Niesie klucz licencyjny, a przeniesienie go do VM ma własny wpis: Moving an OEM Licence Into a Proxmox VM.

Wszystko pod /usr/share należy do apt

Jedna zasada rozstrzyga każdy wybór poniżej. Plik zainstalowany przez pakiet jest plikiem pakietu. Edytujesz go na miejscu, a następna aktualizacja tego pakietu nadpisze twoją zmianę bez słowa, bo z punktu widzenia dpkg po prostu odkłada własny plik tam, gdzie go zostawił.

Każdy element marki musi więc mieszkać gdzieś, czego apt nie posiada. Węzeł Proxmoxa ma trzy takie miejsca, a każde kosztuje coś innego:

Gdzie mieszkaJak się tam dostajePrzetrwa aktualizacjęIle cię to kosztuje
Konfiguracja VM w /etc/pvesmbios1, a args do całej resztyTak, żaden pakiet nie dotyka konfiguracjiargs jest tylko dla roota i nie widać go w GUI
Plik, który dpkg ma polecone zostawić w spokojudpkg-divertTak, kopia pakietu trafia zamiast tego pod nazwę .distribAktualizacje nie docierają już do pliku, co ma znaczenie, gdy tym plikiem jest firmware
Twój własny katalog, poza drzewem pakietów/usr/local, wskazany z argsTak, żaden pakiet go nie posiadaMusisz go sam rozłożyć na każdy węzeł

Najjaśniej opisuje dywersję sam Debian: „a way of forcing dpkg not to install a file into its location, but to a diverted location”4. To załatwia interfejs WWW. Dla firmware’u to jedna z dwóch opcji, i to ta groźniejsza.

Obudowa to garść ciągów znaków i sprawdzenie uprawnień

SMBIOS to tabela, w której maszyna opisuje samą siebie: kto ją zrobił, jaki to model, jaki ma numer seryjny, jaka jest płyta i obudowa5. Czyta ją dmidecode, czyta ją każde narzędzie do inwentaryzacji, jakie kiedykolwiek puściłeś na sieć, czyta ją panel informacji o systemie w Fisher-Price OS (Windows), i czyta ją też większość kontroli licencyjnych, które decydują, czy dany program w ogóle uruchomi się na danej maszynie. Na VM pisze ją QEMU. Stąd QEMU i Standard PC w tabeli powyżej.

Typ 1 przez smbios1

Proxmox wystawia w konfiguracji VM jedną strukturę SMBIOS: typ 1, System Information, jako smbios16. Przyjmuje manufacturer, product, version, serial, sku, family i uuid.

Haczyk siedzi w qemu-server, nie w dokumentacji. Każde pole poza uuid musi pasować do wzorca base64, [A-Za-z0-9+\/]+={0,2}, więc zwykła wartość ze spacją jest odrzucana od razu. Prawdziwe ciągi koduje się w base64 z ustawionym base64=1, a qemu-server dekoduje je z powrotem, zanim zbuduje wiersz poleceń QEMU7. Edytor SMBIOS w GUI robi to przy każdym zapisie, z komentarzem „smbios values can be arbitrary, so encode and mark config as such”8. W wierszu poleceń to twoje zadanie:

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')"

Zwróć uwagę, że uuid wraca na miejsce. To tożsamość maszyny gościa, a cokolwiek przekażesz do --smbios1, zapisuje się jako cała opcja, więc najpierw ją odczytaj i zachowaj.

Brandinguj szablon, nie każdą VM osobno. Klon w Proxmoxie dostaje świeżo wygenerowany UUID i zachowuje każde inne pole smbios1, więc każdy klon wychodzi z własną tożsamością i twoimi ciągami9, z jednym wyjątkiem, opisanym niżej.

Typy 0, 2, 3 i 11 przez args

smbios1 kończy się na typie 1. Producent firmware’u, płyta główna, obudowa i ciągi OEM idą przez args, wiersz, który Proxmox przekazuje prosto do QEMU i który jego własna dokumentacja określa jako „for experts only”6. Opcja -smbios w QEMU przyjmuje pola dla każdego typu10:

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'

Po uruchomieniu w QEMU z tymi wierszami dmidecode w gościu odczytuje:

StrukturaPoleStandardowoZ marką
Typ 0VendorProxmox distribution of EDK IIExample Cloud Ltd
Typ 0Version4.2026.08-1EC-FW 1.0
Typ 1ManufacturerQEMUExample Cloud Ltd
Typ 1Product NameStandard PC (Q35 + ICH9, 2009)EC Compute Instance
Typ 1FamilynieokreśloneGeneral Purpose
Typ 2Manufacturerbrak strukturyExample Cloud Ltd
Typ 2Product Namebrak strukturyEC Virtual Board
Typ 3ManufacturerQEMUExample Cloud Ltd
Typ 3Asset TagnieokreśloneEC-ASSET-123
Typ 11String 1brak strukturyexample-cloud:instance=123

Po drodze wyszły cztery pułapki. Wszystkie cztery są ciche.

Podanie typu 0 usuwa „UEFI is supported”. OVMF zapisuje własny typ 0 tylko wtedy, gdy QEMU nie dostarczył swojego; pętla, która przechodzi po tabelach QEMU, ustawia NeedSmbiosType0 = FALSE w chwili, gdy natrafi na typ 011. Twój ciąg producenta zastępuje ten od Proxmoxa, i o to chodzi. Ale typ 0 od QEMU zastępuje też charakterystykę firmware’u z OVMF, i bez uefi=on wiersz „UEFI is supported” znika z dmidecode. Przywróć go przez uefi=on. Dla gości UEFI jest zresztą lepsze miejsce na ciąg producenta, w samym firmware, o czym dalej.

Typu obudowy nie da się ustawić. Typ 3 w QEMU przyjmuje manufacturer, version, serial, asset i sku, i nic więcej10. Zostaje Other.

Dwie definicje jednego typu się scalają, a wygrywa późniejsza. qemu-server wstawia swoje -smbios type=1 wcześnie w wierszu poleceń, a twoje args na sam koniec12, więc drugie -smbios type=1,manufacturer=… w args nie wyrzuca pierwszego: QEMU scalił je pole po polu, producent przyszedł z args, a UUID został tam, gdzie wstawił go smbios1. To ma znaczenie dla czwartej pułapki.

Obie połowy mają różnych właścicieli. qemu-server sprawdza uprawnienia opcja po opcji. smbios1 siedzi wśród opcji sprzętowych i wymaga VM.Config.HWType, a args spada do przypadku domyślnego na samym dole, który mówi „only root can set”13. Płyta, obudowa, producent firmware’u i ciągi OEM należą tylko do ciebie. Typ 1 nie. Każdy, komu dałeś uprawnienia do sprzętu, może go przepisać, a w produkcie hostowanym tym kimś może być klient. Jeśli ciąg producenta ma znaczenie, ustaw go także w args. Późniejsza definicja wygrywa.

Numer seryjny już jest w konfiguracji

Większość tego, co należy do typu 1, już leży w konfiguracji VM. Nazwa nadaje się na numer seryjny, bo qemu-server przyjmuje tam tylko nazwę DNS14: krótką, drukowalną, nigdy z przecinkiem, i to jedyną rzecz w VM, którą klient rozpozna.

Pole typu 1SkądDla VM z 4 rdzeniami i 16 GiB o nazwie web-01, z tagami production;web
Serial Numbernameweb-01
SKU Numbercores × sockets i memoryec-4c16g
Familypierwszy wpis w tagsproduction
UUIDUUID z smbios1, który już mabez zmian
Manufacturer, Producttwoje własne stałe ciągiExample Cloud Ltd, EC Compute Instance

Dwie rzeczy zostają poza tym. Węzeł zmienia się przy każdej migracji, a vmgenid ma się zmieniać: całe jego zadanie to powiedzieć gościowi, że został odtworzony ze snapshotu albo zbudowany z szablonu15. Żadne z nich nie jest tożsamością.

#!/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"

Wartości domyślne pochodzą od samego qemu-server, jeden rdzeń, jedno gniazdo i 512 MiB16, więc konfiguracja, która je pomija, i tak dostaje prawdziwe SKU. Puszczony na konfigurację z tabeli, z qm zastąpionym skryptem, który ją serwował, wiersz, który zapisał, trafił do QEMU zdekodowany tak, jak dekoduje go qemu-server, a dmidecode w gościu odczytał web-01, ec-4c16g, production i UUID, który już tam był. VM bez nazwy jest odrzucana, zamiast dostać pusty numer seryjny.

Oczywistym miejscem na to jest hookscript. To złe miejsce. qemu-server uruchamia hook pre-start wewnątrz blokady konfiguracji, którą wziął, żeby wystartować VM, a wiersz poleceń QEMU buduje z konfiguracji wczytanej, zanim hook się uruchomił17. Hook, który przepisuje numer seryjny, zmienia następny start, nie ten.

Uruchamiaj to więc z własnego provisioningu, w czterech momentach, w których zmieniają się dane wejściowe: utworzenie, klonowanie, zmiana nazwy i zmiana rozmiaru. To klonowanie gryzie. Klon zachowuje każde pole smbios1 poza UUID9, więc jeśli je pominiesz, każda VM zbudowana z web-template poda nazwę szablonu jako swój numer seryjny.

Logo startowe mieszka w dwóch różnych miejscach

To, które logo pokazuje gość, zależy od jego firmware’u. Dwa firmware’y, które dostarcza Proxmox, biorą je z zupełnie różnych miejsc:

SeaBIOS (bios: seabios, domyślny)OVMF (bios: ovmf, UEFI)
Skąd pochodzi logoJPEG, który QEMU przekazuje przy starciebitmapa wkompilowana w firmware
Plik Proxmoxa/usr/share/qemu-server/bootsplash.jpg, 640×480Logo.bmp, 400×120, 8 bitów, wbudowany w OVMF_CODE_4M*.fd
Pakiet-właścicielqemu-serverpve-edk2-firmware-ovmf
Zmiana per VMargs: -boot splash=…args wskazujące VM inny firmware
Zmiana bez przebudowy czegokolwiektaknie
Trafia do systemu gościa przez BGRTnietak

SeaBIOS: JPEG w wierszu poleceń

qemu-server dokłada tę samą opcję -boot do każdej VM, którą uruchamia, menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg18. Dokumentacja QEMU mówi, że obraz jest pokazywany „when option splash=sp_name is given and menu=on, If firmware/BIOS supports them. Currently Seabios for X86 system support it”10. OVMF nie bierze z tego nic poza splash-time, którego używa jako limitu czasu menu startowego, a w OvmfPkg nie ma nigdzie żadnego odwołania do pliku splash19.

Podmiana to jeden wiersz w konfiguracji VM:

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

Drugie -boot nie kłóci się z pierwszym. QEMU scala je tak samo jak -smbios, wygrywa późniejsza wartość, a przy dwóch podanych plikach splash zrzut ekranu pokazał drugi. /etc/pve to właściwe miejsce na ten plik, bo to klastrowy system plików i każdy węzeł widzi ten sam splash, a jego limit 1 MiB na plik jest daleko poza zasięgiem JPEG-a 640×48020.

Sam obraz musi spełnić trzy warunki, a pomyłka w którymkolwiek kosztuje cię logo albo jego kolory:

WarunekDlaczegoCo się dzieje w przeciwnym razie
JPEG albo 24-bitowy BMPQEMU sprawdza plik, zanim VM wystartujesplash file … format not recognized; must be JPEG or 24 bit BMP
JPEG baseline, chroma 4:2:0dekoder SeaBIOS nie obsługuje niczego innego21ERR_NOT_SEQUENTIAL_DCT albo ERR_NOT_YCBCR_221111 i pusty ekran
640×480, jak u samego ProxmoxaSeaBIOS prosi VGA BIOS o tryb dokładnie w rozmiarze obrazubrak pasującego trybu, brak splasha

Większość narzędzi graficznych domyślnie zapisuje baseline 4:2:0, więc zwykły sposób na utratę logo to jedna z opcji „zapisz dla sieci”, która po cichu włącza kodowanie progresywne, wygląda identycznie w każdej przeglądarce obrazów, jaką masz, i zostawia SeaBIOS, który nie rysuje zupełnie nic.

Pułapka z kolorami

Ta kosztowała całe popołudnie. Ten sam JPEG, wyrenderowany przez dwie kompilacje SeaBIOS 1.17.0, wychodzi w dwóch różnych kolorach:

Splash Example Cloud trzy razy: źródłowy JPEG z niebieskim kafelkiem logo, SeaBIOS w wersji dostarczanej przez Proxmoxa z tym samym niebieskim, i kompilacja SeaBIOS działająca w 32 bitach na piksel, w której niebieski zmienił się w złoty

Siedzi to w jpeg.c SeaBIOS. Procedura zapisu dla 24 bitów na piksel ma gałąź little-endian, która wstawia niebieski w pierwszy bajt każdego piksela, a procedura dla 32 bitów na piksel, PIC_32, takiej gałęzi nie ma i wstawia tam czerwony21. Na buforze ramki little-endian zamienia to czerwony z niebieskim. Niebieski wychodzi złoty, a pomarańczowy wyszedłby niebieski.

Która procedura się uruchomi, zależy od trybu wideo, jaki oferuje VGA BIOS:

FirmwareTryb VBE dla 640×480Bity na pikselKolory
Gotowy SeaBIOS 1.17.0 z upstreamu QEMU, tak jak dostarcza go pve-qemu-kvm 11.0.3-40x11116poprawne, skwantyzowane do 65 536
Własna kompilacja seabios 1.17.0-10 w Fedorze 440x14232czerwony z niebieskim zamienione

Numery trybów pochodzą z tabeli samego SeaBIOS22, a wiersz Proxmoxa sprawdzono na tych samych blobach, które są w pakiecie: bajt w bajt identycznych z gotowym rel-1.17.0-0-gb52ca86e094d od QEMU. Na Proxmoxie twoje kolory są więc poprawne, tylko że jest ich zaledwie 65 536, a subtelny gradient wyjdzie w pasy. A jeśli twoje logo kiedyś pojawi się w złych kolorach na jakimś innym hypervisorze, to nie wina twojego JPEG-a.

Logo UEFI jest wkompilowane w firmware

Goście UEFI to trudniejsza połowa, a na współczesnym Proxmoxie to większość gości.

Nie ma tu opcji splash do nadpisania. Logo to bitmapa wewnątrz obrazu firmware’u, a kompilacja Proxmoxa wstawia ją tam jednym wierszem w debian/rules:

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

To kopiuje ich Logo.bmp, 400×120, 8 bitów, w miejsce tego od TianoCore, zanim edk2 zostanie zbudowany23. Ten sam plik ustawia producenta firmware’u jako stałą czasu kompilacji, PcdFirmwareVendor=L"Proxmox distribution of EDK II", i stąd bierze się producent typu 0 z pierwszej tabeli23.

Nowe logo, nowy firmware. Żeby dostać taki, który zachowuje się dokładnie jak ten od Proxmoxa, trzeba go zbudować dokładnie tak jak Proxmox: ich drzewo na tagu odpowiadającym pakietowi, który dostarczają, ich łatki, ich flagi i jedna podmieniona bitmapa. pve-edk2-firmware 4.2026.08-1 przypina edk2 na 2970e56, czyli tagu upstreamu 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

Flagi są przepisane z debian/rules w stanie z tego commita. Uważaj na ciąg producenta: ich Makefile zapisuje go w podwójnych cudzysłowach, powłoka make je zdejmuje, a edk2 dostaje go gołego, więc tak właśnie jest tu przekazany, a ujęcie go w cudzysłów drugi raz kończy się błędem kompilacji. Zostaw bitmapę w 400×120 i 8 bitach jak u nich, a nic innego na ekranie startowym się nie przesunie.

Potrzebujesz obu obrazów. qemu-server uruchamia każdą VM Q35 z 4-megabajtowym dyskiem EFI na OVMF_CODE_4M.secboot.fd, kompilacji z wymaganym SMM, a zwykłego OVMF_CODE_4M.fd używa tylko dla i440fx24. Na obecnym Proxmoxie to obraz secboot uruchamia niemal każdy gość UEFI.

Zbudowany w ten sposób, bez żadnych zmian w drzewie Proxmoxa poza bitmapą i dwoma ciągami, obraz SMM startuje tak:

Ekran startowy gościa narysowany przez przebudowany obraz OVMF, z logo Example Cloud w miejscu, gdzie byłoby logo Proxmoxa

A to, jak gość widzi swój firmware, zmienia się razem z nim, bez ani jednej opcji -smbios w wierszu poleceń:

Odczytane w gościu4.2026.08-1 od ProxmoxaPrzebudowany z tego samego drzewa
Producent firmware’uProxmox distribution of EDK IIExample Cloud Ltd
Wersja firmware’u4.2026.08-14.2026.08-1+ec1
„UEFI is supported”jestjest
Tabele ACPIBGRT, WSMT i resztaten sam zestaw

To sprawia, że producent ustawiony przy kompilacji jest lepszą odpowiedzią dla gości UEFI. To własny typ 0 od OVMF, więc bit UEFI zostaje na miejscu i nikt nie musi pamiętać o uefi=on. Droga przez args dla typu 0 jest dla gości SeaBIOS i dla każdego, kto w ogóle nie przebudowuje firmware’u.

Dwa sposoby, żeby dać VM nowy firmware

qemu-server ma na sztywno wpisane, gdzie szuka firmware’u: OVMF.pm trzyma tabelę ścieżek pod /usr/share/pve-edk2-firmware/, z kluczem w postaci typu maszyny i opcji Secure Boot, i nigdzie w konfiguracji VM, w GUI ani w API nie ma opcji, która wybierałaby inny plik24. Zostają dwie drogi.

Budowa OVMF z marką i dwa sposoby, żeby dać go VMDrzewo Proxmoxapve-edk2-firmware 4.2026.08-1Twoja markaLogo.bmp + ciąg producentaTa sama kompilacja, te same flagiOVMF_CODE_4M.fd + .secboot.fdA: dywersja na każdym węźledostaje go każda VM UEFI,bez zmian w konfiguracji VMB: per VM przez argswłączasz VM po VM,pliki Proxmoxa nietknięteapt full-upgradenowy firmware Proxmoxa ląduje, twój zostaje staryhook Post-Invokewersje się różnią, przebuduj przed następnym startem
Jedna kompilacja, dwie drogi wejścia. Tak czy inaczej następna aktualizacja instaluje nowy firmware Proxmoxa obok twojego i zostawia twój bez zmian, i właśnie dlatego istnieje hook na dole.

Droga A: dywersja na każdym węźle. Powiedz dpkg, że dwa obrazy kodu Proxmoxa należą teraz gdzie indziej, i wstaw swoje tam, gdzie były:

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

Od następnego startu każda VM UEFI na węźle uruchamia twój firmware. Żadnych zmian w konfiguracji VM.

Droga B: wskaż go wybranym VM. Trzymaj obrazy we własnym katalogu i nadpisuj firmware po jednej VM. Od przejścia na -blockdev qemu-server dołącza obraz kodu jako węzeł blokowy o nazwie pflash0 i podaje go w -machine24, a QEMU scala drugie -machine tak samo jak -boot, więc args może dodać własny węzeł i skierować na niego pflash0:

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

Sprawdzono to okrężną drogą. Firmware secboot od Proxmoxa dołączono jako pflash0 dokładnie tak, jak robi to qemu-server, z włączonym SMM, potem dodano po nim ten wiersz args, a gość uruchomił obraz z marką, z logo i z ciągiem producenta, i stąd pochodzi zrzut ekranu powyżej.

Droga A, dywersjaDroga B, args per VM
Które VM go dostająkażda VM UEFI na węźletylko te, na których go ustawisz
Pliki Proxmoxaprzeniesione do .distribnietknięte
Konfiguracja VMbez zmianwiersz args, tylko root
Typ maszyny musi pasowaćzałatwione, oba obrazy są przekierowanetwoje zadanie: obraz secboot dla Q35
Cofnięciedpkg-divert --remove --renameusuń wiersz
Migracjawęzeł docelowy też musi mieć dywersjęwęzeł docelowy musi mieć plik

Obraz kodu ma około 3,5 MB, przy limicie 1 MiB na plik w pmxcfs20. W związku z tym nie może trafić do /etc/pve, i niezależnie od wybranej drogi musisz go rozłożyć na każdy węzeł. Zmigruj VM na węzeł, który go nie ma, a dostaniesz jeden z dwóch wyników, zależnie od drogi: przy drodze A z powrotem firmware i logo Proxmoxa, a przy drodze B VM, która w ogóle nie wystartuje, bo QEMU nie może otworzyć pliku, którego nie ma.

Aktualizacja, która zostawia cię w tyle

Dywersja to właściwe narzędzie do logo. Firmware to co innego.

Dywersja oznacza, że aktualizacje Proxmoxa nie docierają już do pliku. Dokładnie o to prosiłeś. To też dokładnie to, co zatrzymuje poprawki bezpieczeństwa edk2 w drodze do twoich gości: dziennik zmian Proxmoxa dla 4.2026.08-1 zaczyna się od „Besides many bug and security fixes” i dalej wymienia poprawkę CVE-2024-1374525, a kompilacja z marką z poprzedniego wydania nie ma z tego nic. Nic ci o tym nie powie.

To sprawdzono, a nie założono. W kontenerze z Debianem trixie i repozytorium Proxmoxa zainstalowano pve-edk2-firmware-ovmf 4.2025.05-3, oba obrazy kodu przekierowano, a pakiet zaktualizowano do 4.2026.08-1:

Po aktualizacjiWynik
dpkg-query -W pve-edk2-firmware-ovmf4.2026.08-1
Nowy obraz Proxmoxazainstalowany jako OVMF_CODE_4M.fd.distrib, hash się zmienił
Obraz z markąbez zmian, wciąż zbudowany z 4.2025.05-3
Cokolwiek na konsoli na ten tematnic, aż do hooka poniżej

Dodaj więc hook. apt uruchamia listę poleceń DPkg::Post-Invoke po każdym przebiegu dpkg26. Zapisz, z której wersji Proxmoxa budowałeś, i porównuj po każdym z nich:

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

Przy tej samej aktualizacji wypisał:

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.

Kończy się kodem 0 celowo. apt przerywa pracę, jeśli polecenie Post-Invoke zawiedzie26, a kontrola brandingu to żaden powód, żeby zostawić węzeł w pół aktualizacji. Głośne ostrzeżenie wystarczy.

Jeszcze jedno. Restarty. Gość podchwytuje nowy firmware dopiero wtedy, gdy restartuje się jego proces QEMU, więc przebudowa oznacza zatrzymanie i uruchomienie z poziomu Proxmoxa, a nie reboot z wnętrza gościa, i dokładnie tak samo aktualizacje firmware’u od Proxmoxa docierają do działającej VM. Tyle że one nie wymagają, żebyś najpierw pamiętał o przebudowie.

Albo zostaw firmware Proxmoxa w spokoju

Każda dotychczasowa droga do logo zmienia firmware, a poprzednia sekcja to rachunek za to. Jest jedna, która tego nie robi, i powstał jej prototyp na potrzeby tego wpisu.

Urządzenie PCI w QEMU może nieść option ROM, dowolny plik wskazany przez romfile=27, a OVMF uruchamia sterownik EFI, który tam znajdzie. Kompilacja Proxmoxa uruchamia go niezależnie od tego, czy jest podpisany: OVMF ustawia PcdOptionRomImageVerificationPolicy na 0x00, czyli zawsze wykonuj28. OVMF rysuje własne logo późno w fazie wyboru urządzenia startowego29, a BGRT buduje dopiero przy ReadyToBoot, tuż przed przekazaniem sterowania do programu rozruchowego. A sterownik BGRT z edk2 przyjmuje obraz zastępczy przez EDKII_BOOT_LOGO2_PROTOCOL i przebudowuje tabelę przy ReadyToBoot za każdym razem, gdy obraz się zmienił30.

To wszystko, czego trzeba. Sterownik czeka na ReadyToBoot na TPL_NOTIFY, który uruchamia się przed handlerem TPL_CALLBACK samego sterownika BGRT, czyści ekran, rysuje swoje logo i przekazuje ten sam obraz dalej. Po zbudowaniu to jeden plik o rozmiarze 8 KB, dołączany jednym wierszem:

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

Przy 8 KB mieści się z dużym zapasem w limicie 1 MiB pmxcfs20, więc w odróżnieniu od 3,5-megabajtowego obrazu firmware’u może mieszkać w /etc/pve i jechać za VM na każdy węzeł.

Przetestowano go na własnym firmware Proxmoxa, prosto z pve-edk2-firmware-ovmf 4.2026.08-1: OVMF_CODE_4M.secboot.fd z kluczami Microsoftu wstępnie zapisanymi w OVMF_VARS_4M.ms.fd, na Q35 z SMM, z uruchomieniem przez podpisany shim Fedory, tak żeby Secure Boot był włączony i egzekwowany:

Odczytane z gościaBez ROM-uZ ROM-em
Zmienna SecureBoot11
Na ekranielogo Proxmoxalogo Proxmoxa przez około 250 ms, potem twoje
Obraz BGRT, 400×120 w 440,340od Proxmoxa, SHA-256 be5afe4b…z ROM-u, SHA-256 6c494576…
Zmienione pliki firmware’użadneżadne

Obraz, który gość odczytał ze swojej tabeli BGRT z dołączonym option ROM: logo Example Cloud z podpisem, że narysował je option ROM

Ostatni wiersz to sedno. Firmware Proxmoxa jest nietknięty, więc ich następne wydanie z poprawkami bezpieczeństwa dociera do twoich gości przy następnym restarcie, a nic z poprzedniej sekcji nie ma zastosowania.

Nie jest to za darmo:

KosztDlaczego
Logo Proxmoxa widać przez mniej więcej ćwierć sekundyOVMF rysuje je, zanim jakikolwiek sterownik z option ROM dostanie ekran; uniknąć tego da się tylko przebudową
Gość widzi jedno urządzenie PCI więcej, bez sterownikaROM musi jechać na jakimś urządzeniu, a pci-testdev to urządzenie QEMU, które nic nie robi
Typ 0 nadal mówi Proxmoxciąg producenta jest wkompilowany; ustaw go przez args z uefi=on, jak wyżej
Tylko rootto wiersz args

A wniosek, który leży pod spodem, trzeba powiedzieć wprost. Niepodpisany sterownik uruchomił się w firmware gościa z zapisanymi kluczami Microsoftu i egzekwowanym Secure Boot, bo OVMF od Proxmoxa nie sprawdza option ROM-ów. Tutaj to się przydaje. Oznacza to też, że na tym firmware Secure Boot sprawdza programy rozruchowe, a nie to, co dołącza konfiguracja sprzętowa VM, a skoro args pisze tylko root, jest to pytanie o to, kto ma roota na twoich węzłach.

To prototyp. Działał na QEMU 10.2.2 z firmware Proxmoxa, jeszcze nie na węźle Proxmoxa, a to, co poniżej, to kod źródłowy, nie produkt:

github.com/damo2929/RebrandPCIRom: sterownik option ROM, konwerter logo i kompilacja w kontenerze.

Interfejs WWW to dwa pakiety

Logo w lewym górnym rogu interfejsu WWW nie jest w pve-manager. Workspace.js prosi o komponent proxmoxLogoSvg z prefiksem pwt, a ten mieszka w proxmox-widget-toolkit, który dzielą ze sobą Backup Server i Mail Gateway31. W pve-manager są tylko ikony kart:

CoPlikPakiet
Logo w nagłówku, rysowane w 200×35/usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svgproxmox-widget-toolkit
Ikona karty przeglądarki/usr/share/pve-manager/images/favicon.icopve-manager
Ikona 128×128, także ikona dotykowa/usr/share/pve-manager/images/logo-128.pngpve-manager

Wszystkie trzy to zwykłe pliki, więc to robota dla dpkg-divert, a koszt z poprzedniej sekcji w ogóle tu nie obowiązuje, bo logo nie ma poprawek bezpieczeństwa, które mogłyby go ominąć, i niczyj gość nie jest ani trochę mniej bezpieczny przez węzeł, który wciąż serwuje favicon z zeszłego miesiąca.

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

Przetestowane w tym samym kontenerze, na prawdziwych pakietach:

KrokWynik
Dywersja na proxmox-widget-toolkit 5.2.9, instalacja własnego SVGSVG Proxmoxa przemianowany na proxmox_logo.svg.distrib
Aktualizacja do 5.2.10własny SVG wciąż na miejscu, kopia 5.2.10 od Proxmoxa w .distrib
dpkg --verify proxmox-widget-toolkitbez zastrzeżeń, dpkg wie o dywersji
apt-get install --reinstall proxmox-widget-toolkitwłasny SVG wciąż na miejscu
dpkg-divert --remove --renameoryginał Proxmoxa z powrotem, bajt w bajt

Dwie rzeczy zostają przy Proxmoxie. Obraz w nagłówku jest rysowany w stałym polu 200×35, więc narysuj swój SVG w tym kształcie, inaczej zostanie ściśnięty. A tekst alt mówi Proxmox, a obraz linkuje do https://www.proxmox.com, i jedno, i drugie wpisane w komponent JavaScript, a nie w plik, który da się przekierować31. Zmiana tego oznacza łatanie zminifikowanego pakietu, który psuje się przy każdej aktualizacji. Nie warto dla tekstu alternatywnego.

Czego wymagają od ciebie licencja i znak towarowy Proxmoxa

Proxmox VE jest objęty licencją AGPL w wersji 332, a sekcja 13 tej licencji to klauzula sieciowa: „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. Czy podmiana trzech obrazów to modyfikacja Programu? To pytanie do prawnika. Tania odpowiedź to wystawić swoje obrazy i skrypt z dywersją gdzieś publicznie i podlinkować je ze strony logowania. Nie kosztuje to nic i zamyka temat.

Strona znaku towarowego jest jaśniejsza. Media kit Proxmoxa mówi: „Don’t alter the logo or incorporate the logo or symbol into your logo”34. Zastąp więc ich logo w całości własnym, nigdy przekolorowaną czy przerobioną jego wersją, i trzymaj Proxmoxa z dala od nazwy swojego produktu.

Twoja nazwa na produkcie to twoje utrzymanie

Branding VM jest tani. Garść ciągów SMBIOS, JPEG, bitmapa i trzy obrazy w interfejsie WWW: popołudnie pracy, w większości spędzone na ustalaniu, co gdzie mieszka.

Utrzymanie go to właściwa robota. To też ta część, którą się pomija.

Ciągi SMBIOS i splash pilnują się same, bo mieszkają w konfiguracji, której żaden pakiet nigdy nie dotknie, a logo interfejsu WWW pilnuje się samo, bo dpkg został o nim powiadomiony. Firmware nie. W dniu, w którym wkładasz swoje logo do obrazu firmware’u, przejmujesz kawałek cudzego procesu wydawniczego, a Proxmox buduje, testuje i wydaje nowy firmware z poprawkami bezpieczeństwa, które ich klienci dostają z następną aktualizacją, a twoi wtedy, kiedy zabierzesz się za przebudowę.

Taka wymiana jest w porządku, jeśli robisz ją świadomie. Firma hostingowa, której goście startują na firmware dwa wydania w tyle, bo logo liczyło się bardziej niż dziennik zmian, nie zbudowała produktu. Zbudowała naklejkę.

Jeśli twoja nazwa jest na ekranie startowym, to firmware za nią jest twój i ty masz go trzymać aktualnym, niezależnie od tego, kto go napisał. Nikt tego nie sprawdzi. Właśnie dlatego trzeba to zrobić.


  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”. Kopia archiwalna; strona na żywo zwraca 403 na zautomatyzowane zapytania. ↩︎

  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”; plymouth.spec Fedory ustawia bgrt jako motyw domyślny. ↩︎

  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 — typ 1 System Information, typ 2 płyta główna, typ 3 „the system’s mechanical enclosure(s)”, typ 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 — każde pole poza uuid ma wzorzec [A-Za-z0-9+\/]+={0,2}; wartości są dekodowane, gdy ustawione jest base64. ↩︎

  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”, pozostałe pola smbios1 są zachowywane. ↩︎ ↩︎

  10. QEMU, System Emulation, Invocation — pola -smbios dla każdego typu; -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 dodaje własny typ 0 tylko wtedy, gdy NeedSmbiosType0 jest nadal ustawione po przejściu przez tabele QEMU. ↩︎

  12. qemu-server, src/PVE/QemuServer.pm, custom args — args są dzielone i dokładane na koniec wiersza poleceń. ↩︎

  13. qemu-server, src/PVE/API2/Qemu.pm, config permission checks — smbios1 to opcja sprzętowa wymagająca VM.Config.HWType; przypadek domyślny „catches args, lock, etc.” i kończy się błędem „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 — pamięć default => 512; cores i sockets mają domyślnie 1 w QemuServer.pm. ↩︎

  17. qemu-server, src/PVE/QemuServer.pm, vm_start — lock_config w wierszu 5457, exec_hookscript($conf, $vmid, 'pre-start', 1) w 5581 i config_to_command w 5634 z tym samym $conf, bez ponownego wczytania pomiędzy. ↩︎

  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 czyta etc/boot-menu-wait, czyli wartość splash-time, i nic więcej z -boot. ↩︎

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

  21. SeaBIOS, src/jpeg.c — PIC zapisuje najpierw niebieski na little-endian, PIC_32 w wierszu 946 zapisuje najpierw czerwony, bez gałęzi zależnej od kolejności bajtów; ERR_NOT_SEQUENTIAL_DCT i ERR_NOT_YCBCR_221111 to jedyne odrzucane formaty. ↩︎ ↩︎

  22. SeaBIOS, vgasrc/svgamodes.c — tryb 0x111 to 640×480 w 16 bitach, 0x142 to 640×480 w 32. ↩︎

  23. pve-edk2-firmware, debian/rules at 4.2026.08-1 — cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp, ciąg PcdFirmwareVendor i flagi kompilacji OVMF. ↩︎ ↩︎ ↩︎

  24. qemu-server, src/PVE/QemuServer/OVMF.pm — wpisana na sztywno tabela firmware’u pod /usr/share/pve-edk2-firmware/, wybór SMM i węzeł blokowy 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), właściwość, którą ma każde urządzenie PCI. ↩︎

  28. edk2-stable202608, OvmfPkg/OvmfPkgIa32X64.dsc — gEfiSecurityPkgTokenSpaceGuid.PcdOptionRomImageVerificationPolicy|0x00, plik platformy, który buduje Proxmox. ↩︎

  29. edk2-stable202608, OvmfPkg/Library/PlatformBootManagerLib/BdsPlatform.c — BootLogoEnableLogo (), wywoływane z PlatformBootManagerAfterConsole. ↩︎

  30. edk2-stable202608, BootGraphicsResourceTableDxe.c — SetBootLogo2 w wierszu 239 kopiuje obraz; handler ReadyToBoot w 417 odinstalowuje i ponownie instaluje tabelę „If BGRT data change happens”. ↩︎

  31. proxmox-widget-toolkit, src/Logo.js — proxmoxLogoSvg, 200×35, alt: 'Proxmox', z linkiem do proxmox.com; używany z pve-manager Workspace.js z 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 — zacytowane w całości w tekście powyżej. ↩︎

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