Re: [pve-devel] [PATCH manager v6 02/15] api: add resource map api endpoints for PCI and USB

["Fabian Grünbichler" <f.gruenbichler@proxmox.com>]

On June 14, 2023 10:46 am, Dominik Csapak wrote:
> this adds the typical section config crud API calls for
> USB and PCI resource mapping to /cluster/resource/{TYPE}
> 
> the only special thing that this series does is the list call
> for both has a special 'check-node' parameter that uses the
> 'proxyto_callback' to reroute the api call to the given node
> so that it can check the validity of the mapping for that node
> 
> in the future when we e.g. broadcast the lspci output via pmxcfs
> we drop the proxyto_callback and directly use the info from
> pmxcfs (or we drop the parameter and always check all nodes)
> 
> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
> ---
>  PVE/API2/Cluster.pm               |   8 +
>  PVE/API2/Cluster/Makefile         |   5 +
>  PVE/API2/Cluster/Mapping.pm       |  53 ++++++
>  PVE/API2/Cluster/Mapping/Makefile |  18 ++
>  PVE/API2/Cluster/Mapping/PCI.pm   | 300 ++++++++++++++++++++++++++++++
>  PVE/API2/Cluster/Mapping/USB.pm   | 295 +++++++++++++++++++++++++++++
>  PVE/API2/Hardware.pm              |   1 -
>  PVE/API2/Nodes.pm                 |   1 +
>  8 files changed, 680 insertions(+), 1 deletion(-)
>  create mode 100644 PVE/API2/Cluster/Mapping.pm
>  create mode 100644 PVE/API2/Cluster/Mapping/Makefile
>  create mode 100644 PVE/API2/Cluster/Mapping/PCI.pm
>  create mode 100644 PVE/API2/Cluster/Mapping/USB.pm

[..]

> diff --git a/PVE/API2/Cluster/Mapping/PCI.pm b/PVE/API2/Cluster/Mapping/PCI.pm
> new file mode 100644
> index 00000000..9fe20bea
> --- /dev/null
> +++ b/PVE/API2/Cluster/Mapping/PCI.pm
> @@ -0,0 +1,300 @@
> +package PVE::API2::Cluster::Mapping::PCI;
> +
> +use strict;
> +use warnings;
> +
> +use Storable qw(dclone);
> +
> +use PVE::Cluster qw(cfs_lock_file);
> +use PVE::Mapping::PCI;
> +use PVE::JSONSchema qw(get_standard_option);
> +use PVE::Tools qw(extract_param);
> +
> +use PVE::RESTHandler;
> +
> +use base qw(PVE::RESTHandler);
> +
> +__PACKAGE__->register_method ({
> +    name => 'index',
> +    path => '',
> +    method => 'GET',
> +    # only proxy if we give the 'check-node' parameter
> +    proxyto_callback => sub {
> +       my ($rpcenv, $proxyto, $param) = @_;
> +       return $param->{'check-node'} // 'localhost';
> +    },
> +    description => "List PCI Hardware Mapping",
> +    permissions => {
> +       description => "Only lists entries where you have 'Mapping.Modify', 'Mapping.Use' or".
> +           " 'Mapping.Audit' permissions on '/mapping/pci/<name>'.",

nit: the schema/parameters call it 'id', not 'name', repeated a few
times below..

if I create a mapping and then query this API endpoint with pvesh, I get
a wrong result:

$ pvesh ls /cluster/mapping/usb --output-format json
Use of uninitialized value $c in concatenation (.) or string at /usr/share/perl5/PVE/CLI/pvesh.pm line 364.
[{"capabilities":"Dr-c-","name":null}]

not sure whether the issue is with pvesh or here, but could be related
to

> +       user => 'all',
> +    },
> +    parameters => {
> +       additionalProperties => 0,
> +       properties => {
> +           'check-node' => get_standard_option('pve-node', {
> +               description => "If given, checks the configurations on the given node for ".
> +                   "correctness, and adds relevant errors to the devices.",
> +               optional => 1,
> +           }),
> +       },
> +    },
> +    returns => {
> +       type => 'array',
> +       items => {
> +           type => "object",
> +           properties => {
> +               id => {
> +                   type => 'string',
> +                   description => "The logical ID of the mapping."
> +               },
> +               map => {
> +                   type => 'array',
> +                   description => "The entries of the mapping.",
> +                   items => {
> +                       type => 'string',
> +                       description => "A mapping for a node.",
> +                   },
> +               },
> +               description => {
> +                   type => 'string',
> +                   description => "A description of the logical mapping.",
> +               },
> +               error => {
> +                   description => "A list of errors when 'check_node' is given.",
> +                   items => {
> +                       type => 'object',
> +                       properties => {
> +                           severity => {
> +                               type => "string",
> +                               description => "The severity of the error",
> +                           },
> +                           message => {
> +                               type => "string",
> +                               description => "The message of the error",
> +                           },
> +                       },
> +                   }
> +               },
> +           },
> +       },
> +       links => [ { rel => 'child', href => "{name}" } ],

this part here, where it tries to link children using 'name', although
the return value only contains 'id' as property..

> +    },
> +    code => sub {
> +       my ($param) = @_;
> +
> +       my $rpcenv = PVE::RPCEnvironment::get();
> +       my $authuser = $rpcenv->get_user();
> +       my $node = $param->{'check-node'};
> +
> +       die "Wrong node to check\n"
> +           if defined($node) && $node ne 'localhost' && $node ne PVE::INotify::nodename();
> +
> +       my $cfg = PVE::Mapping::PCI::config();
> +
> +       my $res = [];
> +
> +       my $privs = ['Mapping.Modify', 'Mapping.Use', 'Mapping.Audit'];
> +
> +       for my $id (keys $cfg->{ids}->%*) {
> +           next if !$rpcenv->check_full($authuser, "/mapping/pci/$id", $privs, 1, 1);
> +           next if !$cfg->{ids}->{$id};
> +
> +           my $entry = dclone($cfg->{ids}->{$id});
> +           $entry->{id} = $id;
> +           $entry->{digest} = $cfg->{digest};
> +
> +           if (defined($node)) {
> +               $entry->{errors} = [];
> +               if (my $mappings = PVE::Mapping::PCI::get_node_mapping($cfg, $id, $node)) {
> +                   if (!scalar($mappings->@*)) {
> +                       push $entry->{errors}->@*, {
> +                           severity => 'warning',
> +                           message => "No mapping for node $node.",
> +                       };
> +                   }
> +                   for my $mapping ($mappings->@*) {
> +                       eval {
> +                           PVE::Mapping::PCI::assert_valid($id, $mapping);
> +                       };
> +                       if (my $err = $@) {
> +                           push $entry->{errors}->@*, {
> +                               severity => 'error',
> +                               message => "Invalid configuration: $err",
> +                           };
> +                       }
> +                   }
> +               }
> +           }
> +
> +           push @$res, $entry;

this adds the full entry to the returned value, and the permission check
allows it with Mappings.*

> +       }
> +
> +       return $res;
> +    },
> +});
> +
> +__PACKAGE__->register_method ({
> +    name => 'get',
> +    protected => 1,
> +    path => '{id}',
> +    method => 'GET',
> +    description => "Get PCI Mapping.",
> +    permissions => {
> +       check =>['or',
> +           ['perm', '/mapping/pci/{name}', ['Mapping.Use']],
> +           ['perm', '/mapping/pci/{name}', ['Mapping.Modify']],

but this here doesn't allow Mapping.Audit?

either the index call needs to return a limited view, or this should be
allowed for Audit as well I think?

> +       ],
> +    },
> +    parameters => {
> +       additionalProperties => 0,
> +       properties => {
> +           id => {
> +               type => 'string',
> +               format => 'pve-configid',
> +           },
> +       }
> +    },
> +    returns => { type => 'object' },
> +    code => sub {
> +       my ($param) = @_;
> +
> +       my $cfg = PVE::Mapping::PCI::config();
> +       my $id = $param->{id};
> +
> +       my $entry = $cfg->{ids}->{$id};
> +       die "mapping '$param->{id}' not found\n" if !defined($entry);
> +
> +       my $data = dclone($entry);
> +
> +       $data->{digest} = $cfg->{digest};
> +
> +       return $data;
> +    }});
> +

> +__PACKAGE__->register_method ({
> +    name => 'create',
> +    protected => 1,
> +    path => '',
> +    method => 'POST',
> +    description => "Create a new hardware mapping.",
> +    permissions => {
> +	check => ['perm', '/mapping/pci/{name}', ['Mapping.Modify']],

we usually use the higher level path for creating (/mapping/pci) -
although the priv here is 'Modify' and not 'Allocate', we are still
creating a new entry ;)

> +    },
> +    # todo parameters

? ;)

> +    parameters => PVE::Mapping::PCI->createSchema(1),
> +    returns => {
> +	type => 'null',
> +    },
> +    code => sub {
> +	my ($param) = @_;
> +
> +	my $id = extract_param($param, 'id');
> +
> +	my $plugin = PVE::Mapping::PCI->lookup('pci');
> +	my $opts = $plugin->check_config($id, $param, 1, 1);
> +
> +	PVE::Mapping::PCI::lock_pci_config(sub {
> +	    my $cfg = PVE::Mapping::PCI::config();
> +
> +	    die "pci ID '$id' already defined\n" if defined($cfg->{ids}->{$id});
> +
> +	    $cfg->{ids}->{$id} = $opts;
> +
> +	    PVE::Mapping::PCI::write_pci_config($cfg);
> +
> +	}, "create hardware mapping failed");
> +
> +	return;
> +    },
> +});
> +
> +__PACKAGE__->register_method ({
> +    name => 'update',
> +    protected => 1,
> +    path => '{id}',
> +    method => 'PUT',
> +    description => "Update a hardware mapping.",
> +    permissions => {
> +	check => ['perm', '/mapping/pci/{id}', ['Mapping.Modify']],

this one is in line with our usual scheme

> +    },
> +    parameters => PVE::Mapping::PCI->updateSchema(),
> +    returns => {
> +	type => 'null',
> +    },
> +    code => sub {
> +	my ($param) = @_;
> +
> +	my $digest = extract_param($param, 'digest');
> +	my $delete = extract_param($param, 'delete');
> +	my $id = extract_param($param, 'id');
> +
> +	if ($delete) {
> +	    $delete = [ PVE::Tools::split_list($delete) ];
> +	}
> +
> +	PVE::Mapping::PCI::lock_pci_config(sub {
> +	    my $cfg = PVE::Mapping::PCI::config();
> +
> +	    PVE::Tools::assert_if_modified($cfg->{digest}, $digest) if defined($digest);
> +
> +	    die "pci ID '$id' does not exist\n" if !defined($cfg->{ids}->{$id});
> +
> +	    my $plugin = PVE::Mapping::PCI->lookup('pci');
> +	    my $opts = $plugin->check_config($id, $param, 1, 1);
> +
> +	    my $data = $cfg->{ids}->{$id};
> +
> +	    my $options = $plugin->private()->{options}->{pci};
> +	    PVE::SectionConfig::delete_from_config($data, $options, $opts, $delete);
> +
> +	    $data->{$_} = $opts->{$_} for keys $opts->%*;
> +
> +	    PVE::Mapping::PCI::write_pci_config($cfg);
> +
> +	}, "update hardware mapping failed");
> +
> +	return;
> +    },
> +});
> +
> +__PACKAGE__->register_method ({
> +    name => 'delete',
> +    protected => 1,
> +    path => '{id}',
> +    method => 'DELETE',
> +    description => "Remove Hardware Mapping.",
> +    permissions => {
> +	check => [ 'perm', '/mapping/pci/{id}', ['Mapping.Modify']],

this one should be changed if the create one is changed - they should
match..

> +    },
> +    parameters => {
> +	additionalProperties => 0,
> +	properties => {
> +	    id => {
> +		type => 'string',
> +		format => 'pve-configid',
> +	    },
> +	}
> +    },
> +    returns => { type => 'null' },
> +    code => sub {
> +	my ($param) = @_;
> +
> +	my $id = $param->{id};
> +
> +	PVE::Mapping::PCI::lock_pci_config(sub {
> +	    my $cfg = PVE::Mapping::PCI::config();
> +
> +	    if ($cfg->{ids}->{$id}) {
> +		delete $cfg->{ids}->{$id};
> +	    }
> +
> +	    PVE::Mapping::PCI::write_pci_config($cfg);
> +
> +	}, "delete pci mapping failed");
> +
> +	return;
> +    }
> +});
> +
> +1;
> diff --git a/PVE/API2/Cluster/Mapping/USB.pm b/PVE/API2/Cluster/Mapping/USB.pm

and pretty much everything mentioned above applies to this one as well
;)

> [..]