From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id F07FF1FF14C for ; Fri, 26 Jun 2026 14:10:40 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 9D1F0EFEC; Fri, 26 Jun 2026 14:10:23 +0200 (CEST) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH storage 03/13] api: multipath: add cluster-wide configuration endpoints Date: Fri, 26 Jun 2026 14:07:33 +0200 Message-ID: <20260626121000.2095591-4-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260626121000.2095591-1-t.lamprecht@proxmox.com> References: <20260626121000.2095591-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: 1782475801334 X-SPAM-LEVEL: Spam detection results: 0 AWL -0.145 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment 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 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: VCSGDYE5HJVB6OCWU7C3A4UHMI3T6UX3 X-Message-ID-Hash: VCSGDYE5HJVB6OCWU7C3A4UHMI3T6UX3 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 a CRUD API over the cluster-wide multipath.cfg, mounted by pve-manager at /cluster/multipath: read the effective configuration, manage the WWID allow-list, set the global defaults and the per-LUN knobs and aliases, and replace the verbatim override sections. Updates take the settable knobs straight from the section schema, with the schema 'default' stripped so omitting a knob leaves it unchanged rather than resetting it; 'delete' is guarded to the settable properties so it cannot strip a section's type and corrupt the file. Applying the result on each node is handled separately by pvestatd via the generator. Signed-off-by: Thomas Lamprecht --- src/PVE/API2/Makefile | 1 + src/PVE/API2/Multipath.pm | 422 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 423 insertions(+) create mode 100644 src/PVE/API2/Multipath.pm diff --git a/src/PVE/API2/Makefile b/src/PVE/API2/Makefile index fe316c5..002a3bd 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 0000000..6a165d5 --- /dev/null +++ b/src/PVE/API2/Multipath.pm @@ -0,0 +1,422 @@ +package PVE::API2::Multipath; + +use strict; +use warnings; + +use PVE::Exception qw(raise_param_exc); +use PVE::Storage; +use PVE::Tools qw(extract_param); + +use PVE::Multipath::Config; +use PVE::Multipath::ClusterConfig; + +use PVE::RESTHandler; + +use base qw(PVE::RESTHandler); + +# WWID as exported by /dev/disk/by-id/dm-uuid-mpath-; keep validation lenient, multipathd is +# the authority on what is valid. +my $WWID_RE = qr/^[a-zA-Z0-9._:-]+$/; + +# Map each multipath WWID to the storage that consumes it, read from the cluster-wide storage config +# so the answer is identical on every node. +my sub multipath_consumers { + my $consumers = {}; + + my $cfg = eval { PVE::Storage::config() }; + return $consumers if !$cfg; + + my $ids = $cfg->{ids} // {}; + for my $storeid (sort keys %$ids) { + my $scfg = $ids->{$storeid}; + next if ($scfg->{type} // '') ne 'lvm' || !defined($scfg->{base}); + + my ($baseid, $wwid) = eval { PVE::Storage::parse_volume_id($scfg->{base}, 1) }; + next if !defined($baseid) || !defined($wwid); + + my $basecfg = $ids->{$baseid}; + next if !$basecfg || ($basecfg->{type} // '') ne 'multipath'; + + $consumers->{$wwid} = $storeid; + } + + return $consumers; +} + +# multipathd resolves an alias to a map name, so two WWIDs sharing one alias makes it drop a map +# (the loser is order-dependent and only logged at level 1). Reject a collision up front. +my sub assert_alias_free { + my ($cfg, $wwid, $alias) = @_; + + for my $other (keys $cfg->{ids}->%*) { + next if $other eq $wwid; + my $section = $cfg->{ids}->{$other}; + next if ($section->{type} // '') ne 'wwid'; + die "alias '$alias' is already assigned to WWID '$other'\n" + if defined($section->{alias}) && $section->{alias} eq $alias; + } +} + +# Apply a section update: set the given properties, then unset those named in $delete. Guard $delete +# to the settable options and never set and delete the same key, so a stray 'delete=type' cannot +# strip the section type and corrupt the file (as PVE::API2::Storage::Config guards it too). +my sub apply_section_update { + my ($section, $param, $delete, $settable) = @_; + + my @delete = split(/,/, $delete // ''); + for my $key (@delete) { + raise_param_exc({ delete => "'$key' is not a settable property" }) if !$settable->{$key}; + raise_param_exc({ $key => "cannot set and delete a property at the same time" }) + if defined($param->{$key}); + } + $section->{$_} = $param->{$_} for keys %$param; + delete $section->{$_} for @delete; +} + +__PACKAGE__->register_method({ + name => 'read', + path => '', + method => 'GET', + description => "Read the cluster-wide multipath configuration.", + permissions => { + check => ['perm', '/', ['Sys.Audit']], + }, + parameters => { + additionalProperties => 0, + properties => {}, + }, + returns => { + type => 'object', + properties => { + defaults => { + type => 'object', + description => 'Effective global multipathd knobs.', + additionalProperties => 1, + }, + wwids => { + type => 'array', + description => 'The multipath WWID allow-list.', + items => { type => 'string' }, + }, + aliases => { + type => 'object', + description => 'Per-WWID human-readable aliases.', + additionalProperties => { type => 'string' }, + }, + overrides => { + type => 'string', + description => 'Verbatim multipath.conf override sections.', + optional => 1, + }, + }, + }, + code => sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + my $overrides = PVE::Multipath::ClusterConfig::read_overrides(); + return { + defaults => PVE::Multipath::Config::effective_defaults($cfg), + wwids => PVE::Multipath::Config::wwid_list($cfg), + aliases => PVE::Multipath::Config::aliases($cfg), + defined($overrides) && length($overrides) ? (overrides => $overrides) : (), + }; + }, +}); + +__PACKAGE__->register_method({ + name => 'set_overrides', + path => '', + method => 'PUT', + protected => 1, + description => "Set the verbatim multipath.conf override sections, such as " + . "hardware-specific 'device {}' or 'overrides {}' blocks.", + 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, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $overrides = $param->{overrides}; + eval { PVE::Multipath::Config::check_overrides($overrides) }; + raise_param_exc({ overrides => $@ }) if $@; + + PVE::Multipath::ClusterConfig::write_overrides($overrides // ''); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'set_defaults', + path => 'defaults', + method => 'PUT', + protected => 1, + description => "Set the global multipathd defaults applied on every node.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + PVE::Multipath::Config::defaults_api_schema()->%*, + delete => { + type => 'string', + description => 'A list of settings to reset to their default, comma-separated.', + optional => 1, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $delete = extract_param($param, 'delete'); + my $settable = PVE::Multipath::Config::defaults_api_schema(); + + PVE::Multipath::ClusterConfig::lock_config( + sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + my $section = $cfg->{ids}->{defaults} //= { type => 'defaults' }; + apply_section_update($section, $param, $delete, $settable); + PVE::Multipath::ClusterConfig::write_config($cfg); + }, + "updating multipath defaults failed", + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'add_wwid', + path => 'wwid', + method => 'POST', + protected => 1, + description => "Add a WWID to the multipath allow-list.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID of the LUN to manage via multipath.', + maxLength => 128, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = $param->{wwid}; + raise_param_exc({ wwid => "does not look like a valid WWID" }) + if $wwid !~ $WWID_RE; + + PVE::Multipath::ClusterConfig::lock_config( + sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + return if $cfg->{ids}->{$wwid}; + $cfg->{ids}->{$wwid} = { type => 'wwid' }; + PVE::Multipath::ClusterConfig::write_config($cfg); + }, + "adding WWID '$wwid' failed", + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'update_wwid', + path => 'wwid/{wwid}', + method => 'PUT', + protected => 1, + description => "Set the alias and per-LUN multipathd knobs for an allow-listed WWID.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID to update.', + maxLength => 128, + }, + PVE::Multipath::Config::wwid_api_schema()->%*, + delete => { + type => 'string', + description => 'A list of settings to unset, comma-separated.', + optional => 1, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = extract_param($param, 'wwid'); + my $delete = extract_param($param, 'delete'); + my $settable = PVE::Multipath::Config::wwid_api_schema(); + + PVE::Multipath::ClusterConfig::lock_config( + sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + my $section = $cfg->{ids}->{$wwid}; + die "WWID '$wwid' is not on the allow-list, add it first\n" if !$section; + + assert_alias_free($cfg, $wwid, $param->{alias}) if defined($param->{alias}); + + apply_section_update($section, $param, $delete, $settable); + PVE::Multipath::ClusterConfig::write_config($cfg); + }, + "updating WWID '$wwid' failed", + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'remove_wwid', + path => 'wwid/{wwid}', + method => 'DELETE', + protected => 1, + description => "Remove a WWID from the multipath allow-list.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID to remove.', + maxLength => 128, + }, + force => { + type => 'boolean', + description => 'Remove even while a storage still consumes the LUN.', + optional => 1, + default => 0, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = $param->{wwid}; + + # dropping a consumed WWID flushes its map on the next sync, so the backing storage loses + # the device; refuse unless explicitly forced + if (!$param->{force}) { + my $storeid = multipath_consumers()->{$wwid}; + die "WWID '$wwid' is still used by storage '$storeid', remove that" + . " storage first or pass 'force' to override\n" + if defined($storeid); + } + + PVE::Multipath::ClusterConfig::lock_config( + sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + delete $cfg->{ids}->{$wwid}; + PVE::Multipath::ClusterConfig::write_config($cfg); + }, + "removing WWID '$wwid' failed", + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'set_alias', + path => 'alias', + method => 'POST', + protected => 1, + description => "Set or replace the human-readable alias for an allow-listed WWID." + . " The alias becomes the dm-multipath map name on every node.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID to label.', + maxLength => 128, + }, + alias => PVE::Multipath::Config::wwid_api_schema()->{alias}, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = $param->{wwid}; + my $alias = $param->{alias}; + raise_param_exc({ wwid => "does not look like a valid WWID" }) + if $wwid !~ $WWID_RE; + + PVE::Multipath::ClusterConfig::lock_config( + sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + die "WWID '$wwid' is not on the allow-list, add it first\n" + if !$cfg->{ids}->{$wwid}; + assert_alias_free($cfg, $wwid, $alias); + $cfg->{ids}->{$wwid}->{alias} = $alias; + PVE::Multipath::ClusterConfig::write_config($cfg); + }, + "setting alias for WWID '$wwid' failed", + ); + return undef; + }, +}); + +__PACKAGE__->register_method({ + name => 'remove_alias', + path => 'alias/{wwid}', + method => 'DELETE', + protected => 1, + description => "Remove the alias for a multipath WWID.", + permissions => { + check => ['perm', '/', ['Sys.Modify']], + }, + parameters => { + additionalProperties => 0, + properties => { + wwid => { + type => 'string', + description => 'The WWID whose alias to remove.', + maxLength => 128, + }, + }, + }, + returns => { type => 'null' }, + code => sub { + my ($param) = @_; + + my $wwid = $param->{wwid}; + PVE::Multipath::ClusterConfig::lock_config( + sub { + my $cfg = PVE::Multipath::ClusterConfig::read_config(); + delete $cfg->{ids}->{$wwid}->{alias} if $cfg->{ids}->{$wwid}; + PVE::Multipath::ClusterConfig::write_config($cfg); + }, + "removing alias for WWID '$wwid' failed", + ); + return undef; + }, +}); + +1; -- 2.47.3