[PATCH pve-manager v2 10/17] api: Add CRUD handlers for custom CPU models

Arthur Bied-Charreton
2026-04-01T08:02:43Z

Add CRUD endpoints for custom CPU models, allowing to interact with
/etc/pve/virtual-guest/cpu-models.conf [0] programmatically.

The `custom-` prefix is not required from the consumers for the
`cputype` parameter, rather the handlers normalize it such that `foo`
evaluates to the same custom model as `custom-foo`.

[0] https://pve.proxmox.com/wiki/Manual:_cpu-models.conf

Based on & adapted from the following patches by Stefan Reiter:
https://lore.proxmox.com/pve-devel/20211028114150.3245864-4-s.reiter@proxmox.com/
https://lore.proxmox.com/pve-devel/20211028114150.3245864-5-s.reiter@proxmox.com/

Signed-off-by: Arthur Bied-Charreton <a.bied-charreton@proxmox.com>
---
PVE/API2/Cluster/Qemu.pm | 8 +-
PVE/API2/Cluster/Qemu/CustomCPUModels.pm | 211 +++++++++++++++++++++++
PVE/API2/Cluster/Qemu/Makefile | 5 +-
3 files changed, 221 insertions(+), 3 deletions(-)
create mode 100644 PVE/API2/Cluster/Qemu/CustomCPUModels.pm

diff --git a/PVE/API2/Cluster/Qemu.pm b/PVE/API2/Cluster/Qemu.pm
index ed37fd20..5acef731 100644
--- a/PVE/API2/Cluster/Qemu.pm
+++ b/PVE/API2/Cluster/Qemu.pm
@@ -3,6 +3,7 @@ package PVE::API2::Cluster::Qemu;
use v5.36;

use PVE::API2::Cluster::Qemu::CPUFlags;
+use PVE::API2::Cluster::Qemu::CustomCPUModels;

use base qw(PVE::RESTHandler);

@@ -11,6 +12,11 @@ __PACKAGE__->register_method({
path => "cpu-flags",
});

+__PACKAGE__->register_method({
+ subclass => "PVE::API2::Cluster::Qemu::CustomCPUModels",
+ path => "custom-cpu-models",
+});
+
__PACKAGE__->register_method({
name => 'index',
path => '',
@@ -33,7 +39,7 @@ __PACKAGE__->register_method({
my ($param) = @_;

return [
- { name => 'cpu-flags' },
+ { name => 'cpu-flags' }, { name => 'custom-cpu-models' },
];
},
});
diff --git a/PVE/API2/Cluster/Qemu/CustomCPUModels.pm b/PVE/API2/Cluster/Qemu/CustomCPUModels.pm
new file mode 100644
index 00000000..8c2bd724
--- /dev/null
+++ b/PVE/API2/Cluster/Qemu/CustomCPUModels.pm
@@ -0,0 +1,211 @@
+package PVE::API2::Cluster::Qemu::CustomCPUModels;
+
+use v5.36;
+
+use PVE::JSONSchema qw(get_standard_option);
+use PVE::RPCEnvironment;
+use PVE::RESTHandler;
+use PVE::Tools qw(extract_param);
+
+use PVE::QemuServer::CPUConfig;
+
+use base qw(PVE::RESTHandler);
+
+__PACKAGE__->register_method({
+ name => 'config',
+ path => '',
+ method => 'GET',
+ description => 'Read all custom CPU models definitions',
+ permissions => {
+ check => ['perm', '/nodes', ['Sys.Audit']],
+ },
+ parameters => {
+ additionalProperties => 0,
+ },
+ returns => {
+ type => 'array',
+ items => {
+ type => 'object',
+ properties => get_standard_option('pve-qemu-cpu'),
+ },
+ },
+ code => sub {
+ my $conf = PVE::QemuServer::CPUConfig::load_custom_model_conf();
+ delete $conf->{order};
+ my $ids = [];
+ foreach my $id (keys %{ $conf->{ids} }) {
+ delete $conf->{ids}->{$id}->{type};
+ push @$ids, $conf->{ids}->{$id};
+ }
+ return $ids;
+ },
+});
+
+__PACKAGE__->register_method({
+ name => 'create',
+ path => '',
+ method => 'POST',
+ protected => 1,
+ description => 'Add a custom CPU model definition',
+ permissions => {
+ check => ['perm', '/nodes', ['Sys.Console']],
+ },
+ parameters => {
+ additionalProperties => 0,
+ properties => PVE::QemuServer::CPUConfig::add_cpu_json_properties({
+ digest => get_standard_option('pve-config-digest'),
+ }),
+ },
+ returns => { type => 'null' },
+ code => sub {
+ my ($param) = @_;
+
+ my $digest = extract_param($param, 'digest');
+
+ (my $name = $param->{cputype}) =~ s/^custom-//;
+ $param->{cputype} = "custom-$name";
+
+ PVE::QemuServer::CPUConfig::lock_cpu_config(sub {
+ my $conf = PVE::QemuServer::CPUConfig::load_custom_model_conf();
+ PVE::SectionConfig::assert_if_modified($conf, $digest);
+
+ die "custom CPU model '$name' already exists\n"
+ if defined($conf->{ids}->{$name});
+ $conf->{ids}->{$name} = $param;
+
+ PVE::QemuServer::CPUConfig::write_custom_model_conf($conf);
+ });
+ },
+});
+
+__PACKAGE__->register_method({
+ name => 'delete',
+ path => '{cputype}',
+ method => 'DELETE',
+ protected => 1,
+ description => 'Delete a custom CPU model definition',
+ permissions => {
+ check => ['perm', '/nodes', ['Sys.Console']],
+ },
+ parameters => {
+ additionalProperties => 0,
+ properties => {
+ digest => get_standard_option('pve-config-digest'),
+ cputype => {
+ type => 'string',
+ description => "The custom model to delete.",
+ },
+ },
+ },
+ returns => { type => 'null' },
+ code => sub {
+ my ($param) = @_;
+
+ my $digest = extract_param($param, 'digest');
+
+ (my $name = $param->{cputype}) =~ s/^custom-//;
+
+ PVE::QemuServer::CPUConfig::lock_cpu_config(sub {
+ my $conf = PVE::QemuServer::CPUConfig::load_custom_model_conf();
+ PVE::SectionConfig::assert_if_modified($conf, $digest);
+
+ die "custom CPU model '$name' does not exist\n"
+ if !defined($conf->{ids}->{$name});
+ delete $conf->{ids}->{$name};
+
+ PVE::QemuServer::CPUConfig::write_custom_model_conf($conf);
+ });
+ },
+});
+
+__PACKAGE__->register_method({
+ name => 'update',
+ path => '{cputype}',
+ method => 'PUT',
+ protected => 1,
+ description => "Update a custom CPU model definition.",
+ permissions => {
+ check => ['perm', '/nodes', ['Sys.Console']],
+ },
+ parameters => {
+ additionalProperties => 0,
+ properties => PVE::QemuServer::CPUConfig::add_cpu_json_properties({
+ digest => get_standard_option('pve-config-digest'),
+ delete => {
+ type => 'string',
+ format => 'pve-configid-list',
+ description => "A list of properties to delete.",
+ optional => 1,
+ },
+ }),
+ },
+ returns => { type => 'null' },
+ code => sub {
+ my ($param) = @_;
+
+ my $digest = extract_param($param, 'digest');
+ my $delete = extract_param($param, 'delete') // '';
+ my %delete_hash = map { $_ => 1 } PVE::Tools::split_list($delete);
+
+ (my $name = $param->{cputype}) =~ s/^custom-//;
+ $param->{cputype} = "custom-$name";
+
+ PVE::QemuServer::CPUConfig::lock_cpu_config(sub {
+ my $conf = PVE::QemuServer::CPUConfig::load_custom_model_conf();
+
+ PVE::SectionConfig::assert_if_modified($conf, $digest);
+
+ my $model = $conf->{ids}->{$name};
+ die "custom CPU model '$name' does not exist\n" if !defined($model);
+
+ my $props = PVE::QemuServer::CPUConfig::add_cpu_json_properties({});
+ for my $p (keys %$props) {
+ if ($delete_hash{$p}) {
+ die "cannot delete 'cputype' property\n" if $p eq 'cputype';
+ die "cannot set and delete property '$p' at once\n" if $param->{$p};
+ delete $model->{$p};
+ } elsif (defined($param->{$p})) {
+ $model->{$p} = $param->{$p};
+ }
+ }
+
+ PVE::QemuServer::CPUConfig::write_custom_model_conf($conf);
+ });
+ },
+});
+
+__PACKAGE__->register_method({
+ name => 'info',
+ path => '{cputype}',
+ method => 'GET',
+ description => 'Retrieve details about a specific custom CPU model',
+ permissions => {
+ check => ['perm', '/nodes', ['Sys.Audit']],
+ },
+ parameters => {
+ additionalProperties => 0,
+ properties => {
+ cputype => {
+ type => 'string',
+ description => "Name of the CPU model to query.",
+ },
+ },
+ },
+ returns => {
+ type => 'object',
+ properties => PVE::QemuServer::CPUConfig::add_cpu_json_properties({
+ digest => get_standard_option('pve-config-digest'),
+ }),
+ },
+ code => sub {
+ my ($param) = @_;
+ (my $name = $param->{cputype}) =~ s/^custom-//;
+ my $conf = PVE::QemuServer::CPUConfig::load_custom_model_conf();
+ my $digest = $conf->{digest};
+ my $retval = PVE::QemuServer::CPUConfig::get_custom_model($name);
+ $retval->{digest} = $digest;
+ return $retval;
+ },
+});
+
+1;
diff --git a/PVE/API2/Cluster/Qemu/Makefile b/PVE/API2/Cluster/Qemu/Makefile
index 2ab3e0b1..76b661db 100644
--- a/PVE/API2/Cluster/Qemu/Makefile
+++ b/PVE/API2/Cluster/Qemu/Makefile
@@ -2,8 +2,9 @@ include ../../../../defines.mk

# for node independent, cluster-wide applicable, API endpoints
# ensure we do not conflict with files shipped by pve-cluster!!
-PERLSOURCE= \
- CPUFlags.pm
+PERLSOURCE= \
+ CPUFlags.pm \
+ CustomCPUModels.pm

all:

--
2.47.3