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 odczytuje | Czyja nazwa |
|---|---|---|
| Ekran startowy | logo Proxmoxa | Proxmox |
| Producent firmware’u (SMBIOS typ 0) | Proxmox distribution of EDK II | Proxmox |
| Wersja firmware’u | 4.2026.08-1 | wersja pakietu Proxmoxa |
| Producent systemu (typ 1) | QEMU | QEMU |
| Nazwa produktu (typ 1) | Standard PC (Q35 + ICH9, 2009) | QEMU |
| Producent obudowy (typ 3) | QEMU | QEMU |
| Płyta główna (typ 2) | w ogóle jej nie ma | niczyja |
| Webowy interfejs zarządzania | logo Proxmoxa, w lewym górnym rogu | Proxmox |
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.
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 mieszka | Jak się tam dostaje | Przetrwa aktualizację | Ile cię to kosztuje |
|---|---|---|---|
Konfiguracja VM w /etc/pve | smbios1, a args do całej reszty | Tak, żaden pakiet nie dotyka konfiguracji | args jest tylko dla roota i nie widać go w GUI |
| Plik, który dpkg ma polecone zostawić w spokoju | dpkg-divert | Tak, kopia pakietu trafia zamiast tego pod nazwę .distrib | Aktualizacje 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 args | Tak, żaden pakiet go nie posiada | Musisz 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:
| Struktura | Pole | Standardowo | Z marką |
|---|---|---|---|
| Typ 0 | Vendor | Proxmox distribution of EDK II | Example Cloud Ltd |
| Typ 0 | Version | 4.2026.08-1 | EC-FW 1.0 |
| Typ 1 | Manufacturer | QEMU | Example Cloud Ltd |
| Typ 1 | Product Name | Standard PC (Q35 + ICH9, 2009) | EC Compute Instance |
| Typ 1 | Family | nieokreślone | General Purpose |
| Typ 2 | Manufacturer | brak struktury | Example Cloud Ltd |
| Typ 2 | Product Name | brak struktury | EC Virtual Board |
| Typ 3 | Manufacturer | QEMU | Example Cloud Ltd |
| Typ 3 | Asset Tag | nieokreślone | EC-ASSET-123 |
| Typ 11 | String 1 | brak struktury | example-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 1 | Skąd | Dla VM z 4 rdzeniami i 16 GiB o nazwie web-01, z tagami production;web |
|---|---|---|
| Serial Number | name | web-01 |
| SKU Number | cores × sockets i memory | ec-4c16g |
| Family | pierwszy wpis w tags | production |
| UUID | UUID z smbios1, który już ma | bez zmian |
| Manufacturer, Product | twoje własne stałe ciągi | Example 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 logo | JPEG, który QEMU przekazuje przy starcie | bitmapa wkompilowana w firmware |
| Plik Proxmoxa | /usr/share/qemu-server/bootsplash.jpg, 640×480 | Logo.bmp, 400×120, 8 bitów, wbudowany w OVMF_CODE_4M*.fd |
| Pakiet-właściciel | qemu-server | pve-edk2-firmware-ovmf |
| Zmiana per VM | args: -boot splash=… | args wskazujące VM inny firmware |
| Zmiana bez przebudowy czegokolwiek | tak | nie |
| Trafia do systemu gościa przez BGRT | nie | tak |
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:
| Warunek | Dlaczego | Co się dzieje w przeciwnym razie |
|---|---|---|
| JPEG albo 24-bitowy BMP | QEMU sprawdza plik, zanim VM wystartuje | splash file … format not recognized; must be JPEG or 24 bit BMP |
| JPEG baseline, chroma 4:2:0 | dekoder SeaBIOS nie obsługuje niczego innego21 | ERR_NOT_SEQUENTIAL_DCT albo ERR_NOT_YCBCR_221111 i pusty ekran |
| 640×480, jak u samego Proxmoxa | SeaBIOS prosi VGA BIOS o tryb dokładnie w rozmiarze obrazu | brak 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:

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:
| Firmware | Tryb VBE dla 640×480 | Bity na piksel | Kolory |
|---|---|---|---|
Gotowy SeaBIOS 1.17.0 z upstreamu QEMU, tak jak dostarcza go pve-qemu-kvm 11.0.3-4 | 0x111 | 16 | poprawne, skwantyzowane do 65 536 |
Własna kompilacja seabios 1.17.0-10 w Fedorze 44 | 0x142 | 32 | czerwony 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:

A to, jak gość widzi swój firmware, zmienia się razem z nim, bez ani jednej opcji -smbios w wierszu poleceń:
| Odczytane w gościu | 4.2026.08-1 od Proxmoxa | Przebudowany z tego samego drzewa |
|---|---|---|
| Producent firmware’u | Proxmox distribution of EDK II | Example Cloud Ltd |
| Wersja firmware’u | 4.2026.08-1 | 4.2026.08-1+ec1 |
| „UEFI is supported” | jest | jest |
| Tabele ACPI | BGRT, WSMT i reszta | ten 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.
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, dywersja | Droga B, args per VM | |
|---|---|---|
| Które VM go dostają | każda VM UEFI na węźle | tylko te, na których go ustawisz |
| Pliki Proxmoxa | przeniesione do .distrib | nietknięte |
| Konfiguracja VM | bez zmian | wiersz args, tylko root |
| Typ maszyny musi pasować | załatwione, oba obrazy są przekierowane | twoje zadanie: obraz secboot dla Q35 |
| Cofnięcie | dpkg-divert --remove --rename | usuń wiersz |
| Migracja | wę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 aktualizacji | Wynik |
|---|---|
dpkg-query -W pve-edk2-firmware-ovmf | 4.2026.08-1 |
| Nowy obraz Proxmoxa | zainstalowany 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 temat | nic, 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ścia | Bez ROM-u | Z ROM-em |
|---|---|---|
Zmienna SecureBoot | 1 | 1 |
| Na ekranie | logo Proxmoxa | logo Proxmoxa przez około 250 ms, potem twoje |
| Obraz BGRT, 400×120 w 440,340 | od Proxmoxa, SHA-256 be5afe4b… | z ROM-u, SHA-256 6c494576… |
| Zmienione pliki firmware’u | żadne | żadne |

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:
| Koszt | Dlaczego |
|---|---|
| Logo Proxmoxa widać przez mniej więcej ćwierć sekundy | OVMF 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 sterownika | ROM musi jechać na jakimś urządzeniu, a pci-testdev to urządzenie QEMU, które nic nie robi |
| Typ 0 nadal mówi Proxmox | ciąg producenta jest wkompilowany; ustaw go przez args z uefi=on, jak wyżej |
| Tylko root | to 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:
| Co | Plik | Pakiet |
|---|---|---|
| Logo w nagłówku, rysowane w 200×35 | /usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svg | proxmox-widget-toolkit |
| Ikona karty przeglądarki | /usr/share/pve-manager/images/favicon.ico | pve-manager |
| Ikona 128×128, także ikona dotykowa | /usr/share/pve-manager/images/logo-128.png | pve-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:
| Krok | Wynik |
|---|---|
Dywersja na proxmox-widget-toolkit 5.2.9, instalacja własnego SVG | SVG Proxmoxa przemianowany na proxmox_logo.svg.distrib |
| Aktualizacja do 5.2.10 | własny SVG wciąż na miejscu, kopia 5.2.10 od Proxmoxa w .distrib |
dpkg --verify proxmox-widget-toolkit | bez zastrzeżeń, dpkg wie o dywersji |
apt-get install --reinstall proxmox-widget-toolkit | własny SVG wciąż na miejscu |
dpkg-divert --remove --rename | oryginał 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ć.
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. ↩︎
Microsoft Learn, Boot screen components — „This is the standard interface that Windows uses to access the logo.” ↩︎
Fedora Project, Changes/FlickerFreeBoot — „a new plymouth theme which incorporates the firmware’s bootsplash image”; plymouth.spec Fedory ustawia
bgrtjako motyw domyślny. ↩︎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.” ↩︎
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”. ↩︎
Proxmox VE, qm.conf(5) —
smbios1: „Specify SMBIOS type 1 fields”;args: „Arbitrary arguments passed to kvm … this option is for experts only.” ↩︎ ↩︎qemu-server,
src/PVE/QemuServer.pm, thesmbios1format and command-line builder — każde pole pozauuidma wzorzec[A-Za-z0-9+\/]+={0,2}; wartości są dekodowane, gdy ustawione jestbase64. ↩︎pve-manager,
www/manager6/Parser.js,printQemuSmbios1— „smbios values can be arbitrary, so encode and mark config as such”. ↩︎qemu-server,
src/PVE/API2/Qemu.pm, clone — „auto generate a new uuid”, pozostałe polasmbios1są zachowywane. ↩︎ ↩︎QEMU, System Emulation, Invocation — pola
-smbiosdla 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.” ↩︎ ↩︎ ↩︎edk2-stable202608,
OvmfPkg/SmbiosPlatformDxe/SmbiosPlatformDxe.c— OVMF dodaje własny typ 0 tylko wtedy, gdyNeedSmbiosType0jest nadal ustawione po przejściu przez tabele QEMU. ↩︎qemu-server,
src/PVE/QemuServer.pm, custom args —argssą dzielone i dokładane na koniec wiersza poleceń. ↩︎qemu-server,
src/PVE/API2/Qemu.pm, config permission checks —smbios1to opcja sprzętowa wymagającaVM.Config.HWType; przypadek domyślny „catches args, lock, etc.” i kończy się błędem „only root can set”. ↩︎qemu-server,
src/PVE/QemuServer.pm, thenameoption —format => 'dns-name'. ↩︎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)”. ↩︎qemu-server,
src/PVE/QemuServer/Memory.pm— pamięćdefault => 512;coresisocketsmają domyślnie 1 wQemuServer.pm. ↩︎qemu-server,
src/PVE/QemuServer.pm,vm_start—lock_configw wierszu 5457,exec_hookscript($conf, $vmid, 'pre-start', 1)w 5581 iconfig_to_commandw 5634 z tym samym$conf, bez ponownego wczytania pomiędzy. ↩︎qemu-server,
src/PVE/QemuServer.pm,-boot—menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg. ↩︎edk2-stable202608,
OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c— OVMF czytaetc/boot-menu-wait, czyli wartośćsplash-time, i nic więcej z-boot. ↩︎pve-cluster,
src/pmxcfs/memdb.h—#define MEMDB_MAX_FILE_SIZE (1024 * 1024) // 1 MiB. ↩︎ ↩︎ ↩︎SeaBIOS,
src/jpeg.c—PICzapisuje najpierw niebieski na little-endian,PIC_32w wierszu 946 zapisuje najpierw czerwony, bez gałęzi zależnej od kolejności bajtów;ERR_NOT_SEQUENTIAL_DCTiERR_NOT_YCBCR_221111to jedyne odrzucane formaty. ↩︎ ↩︎SeaBIOS,
vgasrc/svgamodes.c— tryb0x111to 640×480 w 16 bitach,0x142to 640×480 w 32. ↩︎pve-edk2-firmware,
debian/rulesat 4.2026.08-1 —cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp, ciągPcdFirmwareVendori flagi kompilacji OVMF. ↩︎ ↩︎ ↩︎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ł blokowypflash0. ↩︎ ↩︎ ↩︎pve-edk2-firmware,
debian/changelog— 4.2026.08-1: „Besides many bug and security fixes … fix CVE-2024-13745”. ↩︎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.” ↩︎ ↩︎
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. ↩︎edk2-stable202608,
OvmfPkg/OvmfPkgIa32X64.dsc—gEfiSecurityPkgTokenSpaceGuid.PcdOptionRomImageVerificationPolicy|0x00, plik platformy, który buduje Proxmox. ↩︎edk2-stable202608,
OvmfPkg/Library/PlatformBootManagerLib/BdsPlatform.c—BootLogoEnableLogo (), wywoływane zPlatformBootManagerAfterConsole. ↩︎edk2-stable202608,
BootGraphicsResourceTableDxe.c—SetBootLogo2w wierszu 239 kopiuje obraz; handler ReadyToBoot w 417 odinstalowuje i ponownie instaluje tabelę „If BGRT data change happens”. ↩︎proxmox-widget-toolkit,
src/Logo.js—proxmoxLogoSvg, 200×35,alt: 'Proxmox', z linkiem do proxmox.com; używany z pve-managerWorkspace.jszprefix: 'pwt'. ↩︎ ↩︎Proxmox VE wiki, FAQ — „Proxmox VE code is licensed under the GNU Affero General Public License, version 3.” ↩︎
GNU Affero General Public License v3, §13 Remote Network Interaction — zacytowane w całości w tekście powyżej. ↩︎
Proxmox, Media kit — „Don’t alter the logo or incorporate the logo or symbol into your logo.” ↩︎