From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id D8CE61FF0E1 for ; Mon, 16 Nov 2026 02:25:45 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 7EF262189A; Mon, 16 Nov 2026 02:24:34 +0100 (CET) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH v5 storage 14/36] api: add endpoints for the cluster-wide multipath configuration Date: Mon, 16 Nov 2026 02:23:23 +0100 Message-ID: <20261116012355.3187417-15-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261116012355.3187417-1-t.lamprecht@proxmox.com> References: <20261116012355.3187417-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794792242038 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.060 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: D7OXJNBEURB4EWCO3BH3UPSOA6QSJYL3 X-Message-ID-Hash: D7OXJNBEURB4EWCO3BH3UPSOA6QSJYL3 X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Add the API module for /cluster/multipath with the explicit LUN entries (list, read, add, update, delete) and the overrides file (read, write), so that the web UI and API clients can edit the configuration. Reading needs Sys.Audit and writing Sys.Modify on '/', and a digest protects against concurrent edits. An alias that is the alias or WWID of another entry is refused, as multipathd drops one of two maps that claim the same name. So is a 'multipaths' section in the overrides, as the entries generate it. Signed-off-by: Thomas Lamprecht --- src/PVE/API2/Makefile | 1 + src/PVE/API2/Multipath.pm | 360 ++++++++++++++++++++++++++++ src/PVE/Multipath/Config.pm | 27 +++ src/test/run_multipath_api_tests.pl | 36 +++ 4 files changed, 424 insertions(+) create mode 100644 src/PVE/API2/Multipath.pm diff --git a/src/PVE/API2/Makefile b/src/PVE/API2/Makefile index fe316c52..002a3bd4 100644 --- a/src/PVE/API2/Makefile +++ b/src/PVE/API2/Makefile @@ -3,5 +3,6 @@ .PHONY: install install: install -D -m 0644 Disks.pm ${DESTDIR}${PERLDIR}/PVE/API2/Disks.pm + install -D -m 0644 Multipath.pm ${DESTDIR}${PERLDIR}/PVE/API2/Multipath.pm make -C Storage install make -C Disks install diff --git a/src/PVE/API2/Multipath.pm b/src/PVE/API2/Multipath.pm new file mode 100644 index 00000000..4951b1d7 --- /dev/null +++ b/src/PVE/API2/Multipath.pm @@ -0,0 +1,360 @@ +package PVE::API2::Multipath; + +use v5.36; + +use HTTP::Status qw(:constants); + +use PVE::Exception qw(raise raise_param_exc); +use PVE::JSONSchema qw(get_standard_option); +use PVE::RESTHandler; +use PVE::Tools qw(extract_param); + +use PVE::Multipath::Config; + +use base qw(PVE::RESTHandler); + +my sub assert_map_name_free($cfg, $wwid, $name) { + for my $other (sort keys $cfg->{ids}->%*) { + next if $other eq $wwid; + my $section = $cfg->{ids}->{$other}; + die "'$name' is already the map name of WWID '$other'\n" + if $other eq $name || (defined($section->{alias}) && $section->{alias} eq $name); + } +} + +my sub apply_section_update($section, $param, $delete) { + eval { PVE::Multipath::Config::apply_section_update($section, $param, $delete) }; + raise_param_exc({ delete => $@ }) if $@; +} + +my sub edit_config_locked($digest, $errmsg, $code) { + PVE::Multipath::Config::lock_config( + sub { + my $cfg = PVE::Multipath::Config::read_config(); + PVE::Tools::assert_if_modified($cfg->{digest}, $digest); + $code->($cfg); + PVE::Multipath::Config::write_cluster_config($cfg); + }, + $errmsg, + ); +} + +__PACKAGE__->register_method({ + name => 'index', + path => '', + method => 'GET', + description => "Directory index.", + permissions => { user => 'all' }, + parameters => { + additionalProperties => 0, + properties => {}, + }, + returns => { + type => 'array', + items => { + type => 'object', + properties => { + name => { type => 'string' }, + }, + }, + links => [{ rel => 'child', href => "{name}" }], + }, + code => sub { + return [map { +{ name => $_ } } qw(overrides wwid)]; + }, +}); + +__PACKAGE__->register_method({ + name => 'read_overrides', + path => 'overrides', + method => 'GET', + description => "Read the verbatim multipath.conf override sections.", + permissions => { + check => ['perm', '/', ['Sys.Audit']], + }, + parameters => { + additionalProperties => 0, + properties => {}, + }, + returns => { + type => 'object', + properties => { + overrides => { + type => 'string', + description => 'Verbatim override sections.', + optional => 1, + }, + digest => get_standard_option('pve-config-digest'), + }, + }, + code => sub { + my $overrides = PVE::Multipath::Config::read_overrides(); + return { + digest => PVE::Multipath::Config::overrides_digest($overrides), + defined($overrides) && length($overrides) ? (overrides => $overrides) : (), + }; + }, +}); + +__PACKAGE__->register_method({ + name => 'set_overrides', + path => 'overrides', + method => 'PUT', + protected => 1, + description => "Set the verbatim multipath.conf sections for hardware-specific settings:" + . " 'devices', 'overrides', 'defaults', 'blacklist' and 'blacklist_exceptions' blocks," + . " for example 'devices { device { ... } }'.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + overrides => { + type => 'string', + description => 'Verbatim override sections. Omit to clear them.', + maxLength => 128 * 1024, + optional => 1, + }, + digest => get_standard_option('pve-config-digest'), + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $overrides = $param->{overrides}; + my $digest = extract_param($param, 'digest'); + eval { PVE::Multipath::Config::check_overrides($overrides) }; + raise_param_exc({ overrides => $@ }) if $@; + + PVE::Multipath::Config::lock_overrides( + sub { + my $current = PVE::Multipath::Config::read_overrides(); + PVE::Tools::assert_if_modified( + PVE::Multipath::Config::overrides_digest($current), $digest, + ); + PVE::Multipath::Config::write_overrides($overrides // ''); + }, + "updating multipath overrides failed", + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'wwid_index', + path => 'wwid', + method => 'GET', + description => "List the explicit multipath entries with their alias and per-LUN" + . " multipathd settings.", + permissions => { + check => ['perm', '/', ['Sys.Audit']], + }, + parameters => { + additionalProperties => 0, + properties => {}, + }, + returns => { + type => 'array', + items => { + type => 'object', + properties => { + wwid => { type => 'string', description => 'The LUN WWID.' }, + PVE::Multipath::Config::wwid_api_schema()->%*, + }, + }, + links => [{ rel => 'child', href => '{wwid}' }], + }, + code => sub { + my $cfg = PVE::Multipath::Config::read_config(); + my $sections = PVE::Multipath::Config::wwid_sections($cfg); + return [map { { wwid => $_, $sections->{$_}->%* } } sort keys %$sections]; + }, +}); + +__PACKAGE__->register_method({ + name => 'read_wwid', + path => 'wwid/{wwid}', + method => 'GET', + description => "Read the explicit multipath entry of a WWID, with the digest of the" + . " configuration it was read from.", + permissions => { + check => ['perm', '/', ['Sys.Audit']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID to read.', + pattern => $PVE::Multipath::Config::WWID_PATTERN, + maxLength => 128, + }, + }, + }, + returns => { + type => 'object', + properties => { + wwid => { type => 'string', description => 'The LUN WWID.' }, + PVE::Multipath::Config::wwid_api_schema()->%*, + digest => get_standard_option('pve-config-digest'), + }, + }, + code => sub { + my ($param) = @_; + + my $wwid = $param->{wwid}; + + my $cfg = PVE::Multipath::Config::read_config(); + my $entry = PVE::Multipath::Config::wwid_sections($cfg)->{$wwid} + or raise("WWID '$wwid' is not explicitly allow-listed\n", code => HTTP_NOT_FOUND); + return { wwid => $wwid, $entry->%*, digest => $cfg->{digest} }; + }, +}); + +__PACKAGE__->register_method({ + name => 'add_wwid', + path => 'wwid', + method => 'POST', + protected => 1, + description => "Add an explicit multipath entry for a LUN, with an optional alias, node" + . " restriction, and multipathd settings. For a LUN of an iSCSI storage with multipath" + . " enabled, an entry is only needed to set an alias or per-LUN settings. The entry" + . " keeps the LUN managed even if the storage's 'managed-multipath' option is disabled.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID of the LUN to manage via multipath.', + pattern => $PVE::Multipath::Config::WWID_PATTERN, + maxLength => 128, + }, + PVE::Multipath::Config::wwid_api_schema()->%*, + digest => get_standard_option('pve-config-digest'), + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = extract_param($param, 'wwid'); + my $digest = extract_param($param, 'digest'); + + edit_config_locked( + $digest, + "adding WWID '$wwid' failed", + sub { + my ($cfg) = @_; + raise_param_exc({ wwid => "WWID '$wwid' is already allow-listed" }) + if $cfg->{ids}->{$wwid}; + assert_map_name_free($cfg, $wwid, $wwid); + assert_map_name_free($cfg, $wwid, $param->{alias}) if defined($param->{alias}); + my $section = $cfg->{ids}->{$wwid} = { type => 'wwid' }; + apply_section_update($section, $param, undef); + }, + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'update_wwid', + path => 'wwid/{wwid}', + method => 'PUT', + protected => 1, + description => "Update the alias, node restriction, and multipathd settings of an" + . " explicit multipath entry.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID to update.', + pattern => $PVE::Multipath::Config::WWID_PATTERN, + maxLength => 128, + }, + PVE::Multipath::Config::wwid_api_schema()->%*, + delete => { + type => 'string', + format => 'pve-configid-list', + description => 'Comma-separated list of settings to unset.', + optional => 1, + }, + digest => get_standard_option('pve-config-digest'), + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = extract_param($param, 'wwid'); + my $delete = extract_param($param, 'delete'); + my $digest = extract_param($param, 'digest'); + + edit_config_locked( + $digest, + "updating WWID '$wwid' failed", + sub { + my ($cfg) = @_; + my $section = $cfg->{ids}->{$wwid} + or die "WWID '$wwid' is not explicitly allow-listed, add it first\n"; + assert_map_name_free($cfg, $wwid, $param->{alias}) if defined($param->{alias}); + apply_section_update($section, $param, $delete); + }, + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'remove_wwid', + path => 'wwid/{wwid}', + method => 'DELETE', + protected => 1, + description => "Remove an explicit multipath entry without changing node allow-lists.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID to remove.', + pattern => $PVE::Multipath::Config::WWID_PATTERN, + maxLength => 128, + }, + digest => get_standard_option('pve-config-digest'), + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = $param->{wwid}; + my $digest = extract_param($param, 'digest'); + + edit_config_locked( + $digest, + "removing WWID '$wwid' failed", + sub { + my ($cfg) = @_; + die "WWID '$wwid' is not explicitly allow-listed - a LUN of a multipath-enabled" + . " storage is managed through that storage's 'managed-multipath' option\n" + if !$cfg->{ids}->{$wwid}; + delete $cfg->{ids}->{$wwid}; + }, + ); + return undef; + }, +}); + +1; diff --git a/src/PVE/Multipath/Config.pm b/src/PVE/Multipath/Config.pm index 667ad2b8..dd2e4dda 100644 --- a/src/PVE/Multipath/Config.pm +++ b/src/PVE/Multipath/Config.pm @@ -2,6 +2,8 @@ package PVE::Multipath::Config; use v5.36; +use Digest::SHA qw(sha1_hex); + use PVE::Cluster qw(cfs_register_file cfs_read_file cfs_write_file cfs_lock_file); use PVE::JSONSchema qw(get_standard_option); use PVE::SectionConfig; @@ -134,6 +136,7 @@ sub read_config() { return cfs_read_file('multipath.cfg') } sub write_cluster_config($cfg) { cfs_write_file('multipath.cfg', $cfg) } sub read_overrides() { return cfs_read_file('multipath-overrides.conf') } sub write_overrides($text) { cfs_write_file('multipath-overrides.conf', $text) } +sub overrides_digest($text) { return sha1_hex($text // '') } sub lock_config($code, $errmsg = undef) { cfs_lock_file('multipath.cfg', undef, $code); @@ -162,6 +165,18 @@ sub wwids_for_node($cfg, $node) { wwid_list($cfg)->@*]; } +sub wwid_sections($cfg) { + my $res = {}; + for my $wwid (wwid_list($cfg)->@*) { + my $section = $cfg->{ids}->{$wwid}; + my $entry = { map { $_ => $section->{$_} } grep { $_ ne 'type' } keys %$section }; + $entry->{nodes} = __PACKAGE__->encode_value('wwid', 'nodes', $entry->{nodes}) + if $entry->{nodes}; + $res->{$wwid} = $entry; + } + return $res; +} + sub build_multipaths_block($cfg, $node) { my $out = "# Managed by Proxmox VE.\nmultipaths {\n"; for my $wwid (wwids_for_node($cfg, $node)->@*) { @@ -175,4 +190,16 @@ sub build_multipaths_block($cfg, $node) { return "$out}\n"; } +sub apply_section_update($section, $param, $delete) { + for my $key (sort keys %$param) { + $section->{$key} = __PACKAGE__->decode_value($section->{type}, $key, $param->{$key}); + } + PVE::SectionConfig::delete_from_config( + $section, + $properties, + $param, + [PVE::Tools::split_list($delete // '')], + ); +} + 1; diff --git a/src/test/run_multipath_api_tests.pl b/src/test/run_multipath_api_tests.pl index 025f04a1..9a668905 100755 --- a/src/test/run_multipath_api_tests.pl +++ b/src/test/run_multipath_api_tests.pl @@ -9,11 +9,47 @@ BEGIN { use lib ('.', '..'); use File::Temp qw(tempdir); use JSON qw(decode_json); +use Storable qw(dclone); use Test::More; use Test::MockModule; +use PVE::API2::Multipath; use PVE::Multipath::Generator; use PVE::Storage; +subtest 'explicit entries are ordinary configuration writes' => sub { + my $cfg = { ids => {}, digest => 'a' x 40 }; + my $config = Test::MockModule->new('PVE::Multipath::Config'); + $config->mock(read_config => sub { dclone($cfg) }); + $config->mock(lock_config => sub { $_[0]->() }); + $config->mock(write_cluster_config => sub { $cfg = $_[0] }); + PVE::API2::Multipath->add_wwid({ wwid => '3600a', alias => 'data' }); + is( + $cfg->{ids}->{'3600a'}->{alias}, + 'data', + 'entry can be added without node reports or tools', + ); + eval { PVE::API2::Multipath->add_wwid({ wwid => '3600b', alias => 'data' }) }; + like($@, qr/already|used|alias/, 'duplicate alias refused'); + PVE::API2::Multipath->update_wwid({ wwid => '3600a', 'no-path-retry' => 'fail' }); + is($cfg->{ids}->{'3600a'}->{'no-path-retry'}, 'fail', 'per-LUN setting updated'); + eval { PVE::API2::Multipath->update_wwid({ wwid => '3600a', digest => 'b' x 40 }) }; + like($@, qr/modified/, 'digest checked'); + PVE::API2::Multipath->remove_wwid({ wwid => '3600a' }); + is_deeply($cfg->{ids}, {}, 'entry removed without local device commands'); + + for my $name (qw(read_wwid add_wwid update_wwid remove_wwid)) { + my $schema = PVE::API2::Multipath->map_method_by_name($name)->{parameters}; + eval { PVE::JSONSchema::validate({ wwid => '8:16' }, $schema) }; + like($@, qr/wwid: value does not match/, + "$name refuses an ambiguous WWID as parameter"); + } + is_deeply( + PVE::API2::Multipath->index({}), + [map { { name => $_ } } qw(overrides wwid)], + 'index', + ); +}; + subtest 'add-only generation and failed reload throttle' => sub { my $dir = tempdir('multipath-test-XXXX', DIR => '.', CLEANUP => 1); local $PVE::Multipath::Generator::DEFAULTS_DROPIN = "$dir/defaults";