From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 60F671FF0C0 for ; Wed, 18 Nov 2026 21:29:20 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 5B29321878; Wed, 18 Nov 2026 21:28:00 +0100 (CET) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH v7 storage 14/43] api: add endpoints for the cluster-wide multipath configuration Date: Wed, 18 Nov 2026 21:25:57 +0100 Message-ID: <20261118202646.3017286-15-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261118202646.3017286-1-t.lamprecht@proxmox.com> References: <20261118202646.3017286-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: 1795033611884 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.017 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: TJQ4KO2SLNCBWC26ZTTUYXGJEPORAQZY X-Message-ID-Hash: TJQ4KO2SLNCBWC26ZTTUYXGJEPORAQZY 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 | 349 ++++++++++++++++++++++++++++ src/PVE/Multipath/Config.pm | 27 +++ src/test/run_multipath_api_tests.pl | 36 +++ 4 files changed, 413 insertions(+) create mode 100644 src/PVE/API2/Multipath.pm diff --git a/src/PVE/API2/Makefile b/src/PVE/API2/Makefile index 01b7b28f..bb52a93f 100644 --- a/src/PVE/API2/Makefile +++ b/src/PVE/API2/Makefile @@ -3,6 +3,7 @@ .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 make -C Plugins install diff --git a/src/PVE/API2/Multipath.pm b/src/PVE/API2/Multipath.pm new file mode 100644 index 00000000..efd56c75 --- /dev/null +++ b/src/PVE/API2/Multipath.pm @@ -0,0 +1,349 @@ +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 a 'devices' section with 'device' subsections.", + 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($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 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($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' has no explicit multipath entry\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 per-LUN 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($param) { + my $wwid = extract_param($param, 'wwid'); + my $digest = extract_param($param, 'digest'); + + edit_config_locked( + $digest, + "adding WWID '$wwid' failed", + sub($cfg) { + raise_param_exc({ + wwid => "WWID '$wwid' already has an explicit multipath entry" }) + 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 per-LUN 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($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($cfg) { + my $section = $cfg->{ids}->{$wwid} + or die "WWID '$wwid' has no explicit multipath entry, 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($param) { + my $wwid = $param->{wwid}; + my $digest = extract_param($param, 'digest'); + + edit_config_locked( + $digest, + "removing WWID '$wwid' failed", + sub($cfg) { + if (!$cfg->{ids}->{$wwid}) { + die "WWID '$wwid' has no explicit multipath entry - a LUN of a" + . " multipath-enabled storage is managed through that storage's" + . " 'managed-multipath' option\n"; + } + delete $cfg->{ids}->{$wwid}; + }, + ); + return undef; + }, +}); + +1; diff --git a/src/PVE/Multipath/Config.pm b/src/PVE/Multipath/Config.pm index 1111a8a7..88073465 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; @@ -138,6 +140,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); @@ -166,6 +169,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)->@*) { @@ -179,4 +194,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 37588f99..36b85761 100755 --- a/src/test/run_multipath_api_tests.pl +++ b/src/test/run_multipath_api_tests.pl @@ -10,11 +10,47 @@ BEGIN { use lib ('.', '..'); use File::Temp qw(tempdir); use JSON qw(encode_json 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";