你的虚拟机启动时,客户看到的是什么
你以自己的名义出售虚拟机。 客户开机,屏幕上出现的第一样东西却是别人的 logo。
这就是一台原装的 Proxmox 虚拟机。 什么都没坏,Proxmox 也没做错任何事:这是他们的产品、他们的名字,固件和显示它的界面都是他们写的,他们完全有权把名字放在那里,就像服务器厂商把自家铭牌钉在机箱正面一样。 只是那不是你的。
logo 只是开始。
下面是一台原装 UEFI 客户机在 Proxmox 当前固件 pve-edk2-firmware 4.2026.08-1 上报告的内容,在客户机内部用 dmidecode 读出:
| 客户机看的地方 | 读到的内容 | 谁的名字 |
|---|---|---|
| 启动画面 | Proxmox 的 logo | Proxmox |
| 固件厂商(SMBIOS 类型 0) | Proxmox distribution of EDK II | Proxmox |
| 固件版本 | 4.2026.08-1 | Proxmox 的软件包版本 |
| 系统制造商(类型 1) | QEMU | QEMU |
| 产品名(类型 1) | Standard PC (Q35 + ICH9, 2009) | QEMU |
| 机箱制造商(类型 3) | QEMU | QEMU |
| 主板(类型 2) | 根本不存在 | 谁都不是 |
| 管理 Web 界面 | 左上角的 Proxmox logo | Proxmox |
启动 logo 也不止于固件。 UEFI 固件会通过一张叫 BGRT(Boot Graphics Resource Table,启动图形资源表)的 ACPI 表,把它画过的图像交给操作系统,这张表存在的目的就是说明“an image was drawn on the screen during boot”1,然后操作系统会在它自己的启动画面上再画一遍。 Fisher-Price OS (Windows) 把它放在转圈动画的上方,Microsoft 称 BGRT 为“the standard interface that Windows uses to access the logo”2。 Fedora 默认的 Plymouth 主题在 Linux 上也这么做3。 所以,一台跑在 Proxmox 固件上的客户机,在任何人登录之前就把 Proxmox 的 logo 显示了两遍。
这些改起来都不难。
难的是让它保持改过的样子。
下一次 apt full-upgrade 会悄悄把其中一半放回去,而它没放回去的那一半,才是你应该担心的那一半,本文大部分篇幅讲的就是这个。
交接过程中的那张 MSDM 表根本不是品牌。 它装的是许可证密钥,把它搬进虚拟机另有一篇文章:Moving an OEM Licence Into a Proxmox VM。
/usr/share 下的一切都归 apt 所有
一条规则决定了下面的每一个选择。 软件包安装的文件就是软件包的文件。 你就地修改它,下一次这个软件包升级就会一声不吭地覆盖你的修改,因为在 dpkg 看来,它只是把自己的文件放回原处而已。
所以每一处品牌都必须放在 apt 不拥有的地方。 一个 Proxmox 节点上有三个这样的地方,各有各的代价:
| 放在哪里 | 怎么放进去 | 升级后是否还在 | 你付出的代价 |
|---|---|---|---|
/etc/pve 里的虚拟机配置 | smbios1,其他一切用 args | 是,配置从不会被软件包碰 | args 只有 root 能设,而且 GUI 里不显示 |
| 一个已告诉 dpkg 别动的文件 | dpkg-divert | 是,软件包的那份改装到一个 .distrib 名字下 | 升级再也到不了这个文件,而当这个文件是固件时,这就要紧了 |
| 你自己的目录,在软件包目录树之外 | /usr/local,从 args 引用 | 是,没有软件包拥有它 | 得你自己放到每个节点上 |
Debian 自己对 diversion 的描述最清楚:“a way of forcing dpkg not to install a file into its location, but to a diverted location”4。 Web 界面就靠它解决。 对固件来说,它是两个选项之一,而且是更危险的那个。
机箱不过是几个字符串加一道权限检查
SMBIOS 是一台机器用来描述自己的表:谁造的,什么型号,序列号,主板和机箱是什么5。
dmidecode 读它,你在网络上用过的每一个资产盘点工具都读它,Fisher-Price OS (Windows) 的系统信息面板读它,大多数决定某个软件能不能在某台机器上运行的许可证检查也读它。
在虚拟机上,写它的是 QEMU。
所以上表里才是 QEMU 和 Standard PC。
类型 1 走 smbios1
Proxmox 在虚拟机配置里暴露了一个 SMBIOS 结构:类型 1,System Information,即 smbios16。
它接受 manufacturer、product、version、serial、sku、family 和 uuid。
坑在 qemu-server 里,不在文档里。
除了 uuid,每个字段都必须匹配一个 base64 模式 [A-Za-z0-9+\/]+={0,2},所以一个带空格的普通值会被直接拒绝。
真正的字符串要做 base64 编码,并设上 base64=1,qemu-server 在构造 QEMU 命令行之前会再把它们解码回来7。
GUI 的 SMBIOS 编辑器每次保存都这么做,代码注释写着“smbios values can be arbitrary, so encode and mark config as such”8。
在命令行上,这就是你的活了:
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')"
注意 uuid 被放了回去。
它是客户机的机器身份,而你传给 --smbios1 的东西会作为整个选项保存下来,所以要先读出来并保留。
给模板打品牌,而不是给每台虚拟机打。
Proxmox 克隆会生成一个新的 UUID,并保留 smbios1 的其他所有字段,所以每个克隆出来都有自己的身份和你的字符串9,只有一个例外,见下文。
类型 0、2、3 和 11 走 args
smbios1 止步于类型 1。
固件厂商、主板、机箱和 OEM 字符串都要走 args,也就是 Proxmox 原样传给 QEMU 的那一行,Proxmox 自己的文档称之为“for experts only”6。
QEMU 的 -smbios 选项接受每种类型的字段10:
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'
在 QEMU 上带着这些行启动后,客户机的 dmidecode 读到:
| 结构 | 字段 | 原装 | 打品牌后 |
|---|---|---|---|
| 类型 0 | Vendor | Proxmox distribution of EDK II | Example Cloud Ltd |
| 类型 0 | Version | 4.2026.08-1 | EC-FW 1.0 |
| 类型 1 | Manufacturer | QEMU | Example Cloud Ltd |
| 类型 1 | Product Name | Standard PC (Q35 + ICH9, 2009) | EC Compute Instance |
| 类型 1 | Family | 未指定 | General Purpose |
| 类型 2 | Manufacturer | 没有这个结构 | Example Cloud Ltd |
| 类型 2 | Product Name | 没有这个结构 | EC Virtual Board |
| 类型 3 | Manufacturer | QEMU | Example Cloud Ltd |
| 类型 3 | Asset Tag | 未指定 | EC-ASSET-123 |
| 类型 11 | String 1 | 没有这个结构 | example-cloud:instance=123 |
一路上冒出了四个陷阱。四个都悄无声息。
提供类型 0 会让“UEFI is supported”消失。
只有当 QEMU 没有提供类型 0 时,OVMF 才写它自己的类型 0;遍历 QEMU 表的那个循环一遇到类型 0 就把 NeedSmbiosType0 = FALSE 设上11。
你的厂商字符串替换了 Proxmox 的,这正是目的。
但 QEMU 的类型 0 也替换了 OVMF 的固件特性,没有 uefi=on 的话,“UEFI is supported”这一行就从 dmidecode 里消失了。
用 uefi=on 把它加回来。
对 UEFI 客户机,厂商字符串反正有个更好的去处,就在固件本身里面,后文会讲。
机箱类型设不了。
QEMU 的类型 3 只接受 manufacturer、version、serial、asset 和 sku,别的都不接受10。
它会一直是 Other。
同一类型的两份定义会合并,后面的胜出。
qemu-server 把它的 -smbios type=1 放在命令行靠前的位置,把你的 args 放在最末尾12,所以 args 里的第二个 -smbios type=1,manufacturer=… 并不会把第一个扔掉:QEMU 逐字段合并它们,manufacturer 来自 args,UUID 还是 smbios1 设的那个。
这一点对第四个陷阱很要紧。
两半的主人不同。
qemu-server 逐个选项检查权限。
smbios1 归在硬件选项里,需要 VM.Config.HWType,而 args 落到最底下那个兜底分支,写着“only root can set”13。
主板、机箱、固件厂商和 OEM 字符串只有你能改。
类型 1 不是。
任何你给过硬件权限的人都能改写它,而在托管产品上,这个人很可能就是客户。
如果制造商字符串要紧,就在 args 里也设一遍。后面的定义胜出。
序列号早就在配置里了
类型 1 里该放的东西,大部分已经躺在虚拟机配置里了。 名字是个很好的序列号,因为 qemu-server 在那里只接受 DNS 名14:短,可打印,绝不含逗号,而且是这台虚拟机上客户唯一认得的东西。
| 类型 1 字段 | 取自 | 对一台名为 web-01、标签 production;web 的 4 核 16 GiB 虚拟机 |
|---|---|---|
| Serial Number | name | web-01 |
| SKU Number | cores × sockets,以及 memory | ec-4c16g |
| Family | tags 里的第一项 | production |
| UUID | 它已有的 smbios1 UUID | 不变 |
| Manufacturer、Product | 你自己的固定字符串 | Example Cloud Ltd、EC Compute Instance |
有两样东西不放进去。
节点每次迁移都会变,而 vmgenid 本来就该变:它全部的工作就是告诉客户机,它是从快照恢复的,或者是从模板构建的15。
两者都不是身份。
#!/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"
默认值用的是 qemu-server 自己的,一个核、一个插槽、512 MiB16,所以一份省略了它们的配置照样得到正确的 SKU。
用上表里的配置去跑它,qm 换成一个供出这份配置的脚本,它写出的那一行按 qemu-server 的方式解码后交给 QEMU,客户机的 dmidecode 读回了 web-01、ec-4c16g、production 和它原有的 UUID。
没有名字的虚拟机会被拒绝,而不是给一个空序列号。
最显而易见的去处是 hookscript。
那是错的去处。
qemu-server 在为启动虚拟机而拿到的配置锁里运行 pre-start 钩子,并且用钩子运行之前加载的配置来构造 QEMU 命令行17。
一个改写序列号的钩子改变的是下一次启动,不是这一次。
所以要从你的开通流程里运行它,在它的输入会变化的四个时刻:创建、克隆、重命名和调整规格。
咬人的是克隆。
克隆保留 smbios1 除 UUID 以外的每个字段9,所以漏掉这一步,每台从 web-template 构建的虚拟机都会把模板的名字报告成自己的序列号。
启动 logo 住在两个不同的地方
客户机显示哪个 logo,取决于它的固件。 Proxmox 自带的两种固件,从完全不同的地方拿 logo:
SeaBIOS(bios: seabios,默认) | OVMF(bios: ovmf,UEFI) | |
|---|---|---|
| logo 从哪里来 | QEMU 在启动时交过去的一张 JPEG | 编译进固件里的一张位图 |
| Proxmox 的文件 | /usr/share/qemu-server/bootsplash.jpg,640×480 | Logo.bmp,400×120,8 位,编译进 OVMF_CODE_4M*.fd |
| 所属软件包 | qemu-server | pve-edk2-firmware-ovmf |
| 按虚拟机修改 | args: -boot splash=… | 用 args 让虚拟机指向别的固件 |
| 不重新构建任何东西就能改 | 能 | 不能 |
| 通过 BGRT 到达客户机操作系统 | 否 | 是 |
SeaBIOS:命令行上的一张 JPEG
qemu-server 给它启动的每台虚拟机都加上同一个 -boot 选项:menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg18。
QEMU 的文档说,这张图会在“when option splash=sp_name is given and menu=on, If firmware/BIOS supports them. Currently Seabios for X86 system support it”时显示10。
OVMF 从中只拿 splash-time,用作启动菜单的超时,OvmfPkg 里没有任何地方引用这个 splash 文件19。
替换它只需在虚拟机配置里加一行:
args: -boot splash=/etc/pve/branding/splash.jpg
第二个 -boot 不会和第一个打架。
QEMU 用合并 -smbios 的同样方式合并它,后面的值胜出;给两个 splash 文件时,截图显示的是第二个。
/etc/pve 是放这个文件的正确位置,因为它是集群文件系统,每个节点看到的都是同一张 splash,而它每个文件 1 MiB 的上限,离一张 640×480 的 JPEG 还远着呢20。
图像本身必须满足三个条件,任何一个弄错,你就会丢掉 logo 或者它的颜色:
| 条件 | 为什么 | 否则会怎样 |
|---|---|---|
| JPEG 或 24 位 BMP | QEMU 在虚拟机启动前检查文件 | splash file … format not recognized; must be JPEG or 24 bit BMP |
| Baseline JPEG,4:2:0 色度 | SeaBIOS 的解码器别的都处理不了21 | ERR_NOT_SEQUENTIAL_DCT 或 ERR_NOT_YCBCR_221111,外加一块黑屏 |
| 640×480,和 Proxmox 自己的一样 | SeaBIOS 向 VGA BIOS 要一个和图片尺寸完全一致的模式 | 没有匹配的模式,就没有 splash |
大多数图像工具默认写 baseline 4:2:0,所以丢掉 logo 的常见方式,是某个“存储为 Web 格式”之类的选项悄悄打开了渐进式编码,在你所有的图片查看器里看起来一模一样,而 SeaBIOS 却什么都画不出来。
颜色陷阱
这个花了我一个下午。 同一张 JPEG,用两个 SeaBIOS 1.17.0 构建渲染,出来是两种不同的颜色:

问题在 SeaBIOS 的 jpeg.c 里。
每像素 24 位的写入函数有一个小端分支,把蓝色放在每个像素的第一个字节,而每像素 32 位的写入函数 PIC_32 没有这个分支,在那里写的是红色21。
在小端的帧缓冲上,这就把红和蓝对调了。
蓝色出来是金色,橙色出来会是蓝色。
运行哪个写入函数,取决于 VGA BIOS 提供的视频模式:
| 固件 | 640×480 的 VBE 模式 | 每像素位数 | 颜色 |
|---|---|---|---|
QEMU 上游预编译的 SeaBIOS 1.17.0,即 pve-qemu-kvm 11.0.3-4 自带的 | 0x111 | 16 | 正确,量化到 65,536 色 |
Fedora 44 自己构建的 seabios 1.17.0-10 | 0x142 | 32 | 红蓝对调 |
模式编号来自 SeaBIOS 自己的表22,Proxmox 那一行是对照软件包里的二进制本身核对过的:和 QEMU 预编译的 rel-1.17.0-0-gb52ca86e094d 逐字节相同。
所以在 Proxmox 上你的颜色是对的,只是只有 65,536 种,细腻的渐变会出现色带。
而如果你的 logo 哪天在别的 hypervisor 上颜色不对,那不是你 JPEG 的问题。
UEFI logo 是编译进固件里的
UEFI 客户机是更难的那一半,而在如今的 Proxmox 上,大多数客户机都是 UEFI。
没有 splash 选项可以覆盖。
logo 是固件镜像里的一张位图,Proxmox 的构建用 debian/rules 里的一行把它放进去:
debian/setup-build-stamp:
cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp
这会在 edk2 构建之前,把他们那张 400×120、8 位的 Logo.bmp 覆盖到 TianoCore 的那张上23。
同一个文件还把固件厂商设成一个构建时常量 PcdFirmwareVendor=L"Proxmox distribution of EDK II",第一张表里的类型 0 厂商就是从这里来的23。
新 logo,就是新固件。
要得到一个行为和 Proxmox 完全一样的固件,办法就是完全照 Proxmox 的方式构建:他们的源码树,签出与他们所发布软件包相对应的标签,他们的补丁,他们的标志,只换一张位图。
pve-edk2-firmware 4.2026.08-1 把 edk2 固定在 2970e56,也就是上游的 edk2-stable202608 标签23。
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
这些标志取自该提交下的 debian/rules。
注意厂商字符串:他们的 Makefile 用双引号写它,make 的 shell 把引号剥掉,edk2 收到的是不带引号的,所以这里就这样传,再加一层引号会导致构建错误。
位图保持和他们一样的 400×120、8 位,启动画面上其他东西就都不会挪位。
两个镜像你都需要。
qemu-server 用 OVMF_CODE_4M.secboot.fd(要求 SMM 的那个构建)启动任何带 4M EFI 磁盘的 Q35 虚拟机,普通的 OVMF_CODE_4M.fd 只用于 i440fx24。
在当前的 Proxmox 上,几乎每台 UEFI 客户机跑的都是 secboot 那个。
这样构建,与 Proxmox 的源码树相比只改了位图和两个字符串,SMM 镜像启动起来是这样的:

客户机对自身固件的认知也随之改变,命令行上一个 -smbios 选项都不用:
| 在客户机内部读到的 | Proxmox 的 4.2026.08-1 | 用同一源码树重新构建 |
|---|---|---|
| 固件厂商 | Proxmox distribution of EDK II | Example Cloud Ltd |
| 固件版本 | 4.2026.08-1 | 4.2026.08-1+ec1 |
| “UEFI is supported” | 列出 | 列出 |
| ACPI 表 | BGRT、WSMT 等等 | 同一组 |
这让构建时设定的厂商成为 UEFI 客户机更好的答案。
它是 OVMF 自己的类型 0,所以 UEFI 那一位原地不动,谁都不用记着 uefi=on。
类型 0 走 args 的那条路,是给 SeaBIOS 客户机的,以及给根本不重建固件的人的。
把新固件交给虚拟机的两种方式
qemu-server 把它找固件的位置写死了:OVMF.pm 里有一张 /usr/share/pve-edk2-firmware/ 下的路径表,按机器类型和 Secure Boot 选项索引,而虚拟机配置、GUI 或 API 里没有任何一个选项能选别的文件24。
剩下两条路。
路线 A:在每个节点上 divert。 告诉 dpkg,Proxmox 的两个代码镜像现在归到别处,然后把你的放到它们原来的位置:
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
从下一次启动起,这个节点上的每台 UEFI 虚拟机都用你的固件启动。 虚拟机配置一点都不用改。
路线 B:让选定的虚拟机指向它。
把镜像放在你自己的目录里,一次一台虚拟机地覆盖固件。
改用 -blockdev 之后,qemu-server 把代码镜像作为一个叫 pflash0 的块节点挂上,并在 -machine 里指名它24,而 QEMU 合并第二个 -machine 的方式和合并 -boot 一样,所以 args 可以加一个自己的节点,让 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
这是绕远路测试过的。
先把 Proxmox 的 secboot 固件完全按 qemu-server 的方式挂成 pflash0,开着 SMM,然后在后面加上那行 args,客户机启动的是品牌化的镜像,logo 和厂商字符串都在,上面那张截图就是这么来的。
| 路线 A,divert | 路线 B,按虚拟机加 args | |
|---|---|---|
| 哪些虚拟机得到它 | 节点上的每台 UEFI 虚拟机 | 只有你设置了的虚拟机 |
| Proxmox 的文件 | 移到 .distrib | 不动 |
| 虚拟机配置 | 不变 | 一行 args,只有 root 能设 |
| 机器类型必须匹配 | 已处理,两个镜像都 divert 了 | 你的事:Q35 用 secboot 镜像 |
| 撤销 | dpkg-divert --remove --rename | 删掉那一行 |
| 迁移 | 目标节点也必须 divert | 目标节点必须有这个文件 |
代码镜像大约 3.5 MB,而 pmxcfs 每个文件的上限是 1 MiB20。
所以它放不进 /etc/pve,无论走哪条路,都得放到每个节点上。
把虚拟机迁到一个没有它的节点上,根据路线不同会有两种结果之一:路线 A 下,Proxmox 自己的固件和 logo 又回来了;路线 B 下,虚拟机根本启动不了,因为 QEMU 打不开一个不存在的文件。
把你甩在后面的升级
diversion 是对付 logo 的正确工具。 固件不一样。
diversion 意味着 Proxmox 的升级再也到不了这个文件。 这正是你要的。 这也正是让 edk2 安全修复到不了你客户机的原因:Proxmox 4.2026.08-1 的变更日志开头就是“Besides many bug and security fixes”,接着列出了 CVE-2024-13745 的修复25,而一个基于上一版构建的品牌化固件,这些一样都没有。 没有任何东西告诉你。
这是测试过的,不是假设的。
在一个配了 Proxmox 软件源的 Debian trixie 容器里,装上 pve-edk2-firmware-ovmf 4.2025.05-3,两个代码镜像都 divert,然后把软件包升级到 4.2026.08-1:
| 升级之后 | 结果 |
|---|---|
dpkg-query -W pve-edk2-firmware-ovmf | 4.2026.08-1 |
| Proxmox 的新镜像 | 装成了 OVMF_CODE_4M.fd.distrib,哈希变了 |
| 品牌化镜像 | 没变,仍然基于 4.2025.05-3 构建 |
| 控制台上关于此事的任何提示 | 什么都没有,直到加上下面这个钩子 |
所以加个钩子。
apt 在每次 dpkg 运行之后执行一串 DPkg::Post-Invoke 命令26。
记下你基于哪个 Proxmox 版本构建,每次之后比较一下:
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
在同一次升级上,它打印出:
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.
它故意以 0 退出。
Post-Invoke 命令失败的话 apt 会中止26,而一个品牌检查不值得让节点停在升级到一半的状态。
一句响亮的警告就够了。
还有一件事。 重启。 客户机只有在它的 QEMU 进程重启时才会用上新固件,所以重新构建之后,需要从 Proxmox 停机再启动,而不是从客户机内部重启,Proxmox 自己的固件更新到达运行中的虚拟机也正是这样。 只不过它们不需要你先记着去重新构建。
或者,别碰 Proxmox 的固件
到目前为止,每一种换 logo 的路线都要改固件,上一节就是这样做的账单。 有一种不用改,为了这篇文章做了原型。
QEMU 里的 PCI 设备可以带一个 option ROM,就是你用 romfile= 指定的任何文件27,OVMF 会运行它在里面找到的 EFI 驱动。
Proxmox 的构建不管它有没有签名都会运行:OVMF 把 PcdOptionRomImageVerificationPolicy 设成 0x00,也就是总是执行28。
OVMF 在启动设备选择的后期才画它自己的 logo29,并且只在 ReadyToBoot 时,也就是交给引导程序之前的那一刻,才构建 BGRT。
而 edk2 的 BGRT 驱动通过 EDKII_BOOT_LOGO2_PROTOCOL 接收替换图像,只要图像变了,就在 ReadyToBoot 时重建这张表30。
需要的就这么多。
驱动在 TPL_NOTIFY 上等待 ReadyToBoot,这比 BGRT 驱动自己的 TPL_CALLBACK 处理程序先运行,它清屏,画上自己的 logo,再把同一张图交过去。
构建出来是一个 8 KB 的文件,一行就挂上:
args: -device pci-testdev,romfile=/etc/pve/branding/brandrom.rom
8 KB 远在 pmxcfs 的 1 MiB 上限之内20,所以和 3.5 MB 的固件镜像不同,它可以放在 /etc/pve 里,跟着虚拟机去每一个节点。
它是对着 Proxmox 自己的固件测试的,直接取自 pve-edk2-firmware-ovmf 4.2026.08-1:OVMF_CODE_4M.secboot.fd,OVMF_VARS_4M.ms.fd 里预先注册了 Microsoft 的密钥,Q35 加 SMM,通过 Fedora 签名的 shim 启动,这样 Secure Boot 是开着的并且在强制执行:
| 从客户机里读到的 | 不挂 ROM | 挂上 ROM |
|---|---|---|
SecureBoot 变量 | 1 | 1 |
| 屏幕上 | Proxmox 的 logo | Proxmox 的约 250 毫秒,然后是你的 |
| BGRT 图像,400×120,位于 440,340 | Proxmox 的,SHA-256 be5afe4b… | ROM 的,SHA-256 6c494576… |
| 改动的固件文件 | 无 | 无 |

关键在最后一行。 Proxmox 的固件没被动过,所以他们下一个安全版本会在下一次重启时到达你的客户机,上一节的事一件都不适用。
这不是免费的:
| 代价 | 原因 |
|---|---|
| Proxmox 的 logo 会显示大约四分之一秒 | OVMF 在任何 option ROM 驱动拿到屏幕之前就把它画了;只有重新构建才能避免 |
| 客户机多看到一个 PCI 设备,没有驱动 | ROM 必须挂在某个设备上,而 pci-testdev 是 QEMU 那个什么都不做的设备 |
| 类型 0 仍然写着 Proxmox | 厂商字符串是编译进去的;像上面那样,在 uefi=on 下通过 args 设置 |
| 只有 root 能做 | 这是一行 args |
而它底下的那个发现需要直说。
一个未签名的驱动,在一台注册了 Microsoft 密钥、强制执行 Secure Boot 的客户机上,在固件里运行了,因为 Proxmox 的 OVMF 不检查 option ROM。
在这里这是有用的。
但它也意味着,在这个固件上,Secure Boot 检查的是引导程序,而不是虚拟机硬件配置挂上去的随便什么东西。既然只有 root 能写 args,这就成了一个谁在你的节点上握有 root 的问题。
这是一个原型。 它在 QEMU 10.2.2 加 Proxmox 的固件上跑过,还没在 Proxmox 节点上跑过,下面给的是源代码,不是产品:
github.com/damo2929/RebrandPCIRom:option ROM 驱动、logo 转换器和容器构建。
Web 界面是两个软件包
Web 界面左上角的 logo 不在 pve-manager 里。
Workspace.js 请求的是一个前缀为 pwt 的 proxmoxLogoSvg 组件,它在 proxmox-widget-toolkit 里,Backup Server 和 Mail Gateway 也共用这个包31。
只有标签页图标在 pve-manager 里:
| 什么 | 文件 | 软件包 |
|---|---|---|
| 页头 logo,按 200×35 绘制 | /usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svg | proxmox-widget-toolkit |
| 浏览器标签页图标 | /usr/share/pve-manager/images/favicon.ico | pve-manager |
| 128×128 图标,也用作触摸图标 | /usr/share/pve-manager/images/logo-128.png | pve-manager |
三个都是普通文件,所以这是 dpkg-divert 的活儿,而且上一节的代价在这里完全不适用,因为 logo 没有安全修复可错过,一个节点还在提供上个月的 favicon,也不会让任何人的客户机更不安全。
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
在同一个容器里,对着真实的软件包测试过:
| 步骤 | 结果 |
|---|---|
在 proxmox-widget-toolkit 5.2.9 上 divert,装上自己的 SVG | Proxmox 的 SVG 被改名为 proxmox_logo.svg.distrib |
| 升级到 5.2.10 | 自己的 SVG 仍在原处,Proxmox 的 5.2.10 版本在 .distrib 里 |
dpkg --verify proxmox-widget-toolkit | 没有报错,dpkg 知道这个 diversion |
apt-get install --reinstall proxmox-widget-toolkit | 自己的 SVG 仍在原处 |
dpkg-divert --remove --rename | Proxmox 的原件回来了,逐字节一致 |
有两样仍然是 Proxmox 的。
页头图像画在一个固定的 200×35 框里,所以你的 SVG 要按这个形状画,否则会被挤扁。
另外 alt 文本写的是 Proxmox,图像链接到 https://www.proxmox.com,这两样都写在 JavaScript 组件里,而不是一个你能 divert 的文件里31。
要改它们,就得给一个压缩过的 bundle 打补丁,而它每次升级都会坏。
为了 alt 文本,不值得。
Proxmox 的许可证和商标对你有什么要求
Proxmox VE 采用 AGPL 第 3 版许可32,该许可证第 13 条是网络条款:“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。 换掉三张图片算不算修改了程序? 那得问律师。 省事的答案是把你的图片和 divert 脚本放到公开的地方,在登录页上放个链接。 一分钱都不花,问题也就了结了。
商标这边更清楚。 Proxmox 的媒体资料包写着“Don’t alter the logo or incorporate the logo or symbol into your logo”34。 所以用你自己的 logo 把他们的整个换掉,绝不要用他们 logo 的改色版或改造版,也别让 Proxmox 出现在你产品的名字里。
写上你的名字,就意味着由你来维护
给虚拟机打品牌很便宜。 几个 SMBIOS 字符串、一张 JPEG、一张位图、Web 界面里的三张图片:一个下午的活儿,大部分时间花在弄清楚东西都放在哪里。
维持住它才是真正的工作。 也正是常被跳过的那部分。
SMBIOS 字符串和启动画面会自己照顾自己,因为它们住在任何软件包都不会碰的配置里;Web 界面的 logo 也会自己照顾自己,因为 dpkg 已经被告知了它的存在。 固件不会。 从你把 logo 放进固件镜像的那天起,你就接管了别人发布流程中的一部分。Proxmox 构建、测试并发布带有安全修复的新固件,他们的客户在下一次升级时就能拿到,而你的客户要等你抽出空来重新构建才能拿到。
明知如此做出这个取舍,没问题。 一家托管公司,客户机启动的固件落后两个版本,因为 logo 比变更日志更重要,那它造出来的不是产品。 是一张贴纸。
如果启动画面上是你的名字,那它背后的固件就该由你保持最新,不管是谁写的。 没人会检查。 正因如此,才必须去做。
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”。存档副本;在线页面对自动请求返回 403。 ↩︎
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”;Fedora 的 plymouth.spec 把
bgrt设为默认主题。 ↩︎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 — 类型 1 系统信息,类型 2 主板,类型 3 “the system’s mechanical enclosure(s)",类型 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 — 除uuid外的每个字段都匹配模式[A-Za-z0-9+\/]+={0,2};设置了base64时值会被解码。 ↩︎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”,smbios1的其他字段保留。 ↩︎ ↩︎QEMU, System Emulation, Invocation — 各类型的
-smbios字段;-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— 只有在遍历完 QEMU 的表之后NeedSmbiosType0仍然置位时,OVMF 才会添加它自己的类型 0。 ↩︎qemu-server,
src/PVE/QemuServer.pm, custom args —args被拆分后追加到命令行末尾。 ↩︎qemu-server,
src/PVE/API2/Qemu.pm, config permission checks —smbios1是硬件类选项,需要VM.Config.HWType;兜底分支 “catches args, lock, etc.",并以 “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— 内存default => 512;QemuServer.pm里cores和sockets默认为 1。 ↩︎qemu-server,
src/PVE/QemuServer.pm,vm_start— 第 5457 行lock_config,第 5581 行exec_hookscript($conf, $vmid, 'pre-start', 1),第 5634 行config_to_command用的是同一个$conf,中间没有重新加载。 ↩︎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 只从-boot读取etc/boot-menu-wait,即splash-time的值,别的都不读。 ↩︎pve-cluster,
src/pmxcfs/memdb.h—#define MEMDB_MAX_FILE_SIZE (1024 * 1024) // 1 MiB。 ↩︎ ↩︎ ↩︎SeaBIOS,
src/jpeg.c— 在小端机器上PIC先写蓝色,第 946 行的PIC_32先写红色且没有字节序分支;ERR_NOT_SEQUENTIAL_DCT和ERR_NOT_YCBCR_221111是仅有的两种被拒绝的格式。 ↩︎ ↩︎SeaBIOS,
vgasrc/svgamodes.c— 模式0x111是 640×480、16 位,0x142是 640×480、32 位。 ↩︎pve-edk2-firmware,
debian/rulesat 4.2026.08-1 —cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp、PcdFirmwareVendor字符串以及 OVMF 的构建标志。 ↩︎ ↩︎ ↩︎qemu-server,
src/PVE/QemuServer/OVMF.pm—/usr/share/pve-edk2-firmware/下写死的固件表、SMM 的选择,以及pflash0块节点。 ↩︎ ↩︎ ↩︎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),每个 PCI 设备都有的属性。 ↩︎edk2-stable202608,
OvmfPkg/OvmfPkgIa32X64.dsc—gEfiSecurityPkgTokenSpaceGuid.PcdOptionRomImageVerificationPolicy|0x00,Proxmox 构建所用的平台文件。 ↩︎edk2-stable202608,
OvmfPkg/Library/PlatformBootManagerLib/BdsPlatform.c—BootLogoEnableLogo (),从PlatformBootManagerAfterConsole调用。 ↩︎edk2-stable202608,
BootGraphicsResourceTableDxe.c— 第 239 行的SetBootLogo2复制图像;第 417 行的 ReadyToBoot 处理程序 “If BGRT data change happens” 就卸载并重新安装这张表。 ↩︎proxmox-widget-toolkit,
src/Logo.js—proxmoxLogoSvg,200×35,alt: 'Proxmox',链接到 proxmox.com;由 pve-managerWorkspace.js以prefix: '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 — 正文中已完整引用。 ↩︎
Proxmox, Media kit — “Don’t alter the logo or incorporate the logo or symbol into your logo.” ↩︎