From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH v5 storage 18/36] api: add node-level iSCSI status
Date: Mon, 16 Nov 2026 02:23:27 +0100 [thread overview]
Message-ID: <20261116012355.3187417-19-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261116012355.3187417-1-t.lamprecht@proxmox.com>
From: Dietmar Maurer <dietmar@proxmox.com>
Activating an iSCSI storage logs in on its own, but looking at the
sessions of a node needs iscsiadm on a shell. Add the API module for
/nodes/{node}/iscsi with a read-only view: the initiator name and
alias, and the targets with their portals, session state, block
devices and the storage of the target. Node records without a session
are listed too, so a target that is not connected stays visible.
Reading needs Sys.Audit on the node or Datastore.Allocate on
/storage.
Signed-off-by: Dietmar Maurer <dietmar@proxmox.com>
[TL: keep it read-only, without rescan and node record removal;
report the initiator name and alias as top-level fields; move the
iscsiadm helpers into the plugin]
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
src/PVE/API2/ISCSI.pm | 166 +++++++++++++++++++++++++++++++++
src/PVE/API2/Makefile | 1 +
src/PVE/ISCSI/Topology.pm | 19 ++++
src/PVE/Storage/ISCSIPlugin.pm | 27 ++++++
src/test/run_san_api_tests.pl | 56 ++++++++++-
5 files changed, 268 insertions(+), 1 deletion(-)
create mode 100644 src/PVE/API2/ISCSI.pm
diff --git a/src/PVE/API2/ISCSI.pm b/src/PVE/API2/ISCSI.pm
new file mode 100644
index 00000000..005e6809
--- /dev/null
+++ b/src/PVE/API2/ISCSI.pm
@@ -0,0 +1,166 @@
+package PVE::API2::ISCSI;
+
+use v5.36;
+
+use PVE::JSONSchema qw(get_standard_option);
+use PVE::RESTHandler;
+
+use PVE::ISCSI::Topology;
+use PVE::Storage;
+use PVE::Storage::ISCSIPlugin;
+
+use base qw(PVE::RESTHandler);
+
+my $read_permissions = {
+ check => [
+ 'or',
+ ['perm', '/nodes/{node}', ['Sys.Audit']],
+ ['perm', '/storage', ['Datastore.Allocate']],
+ ],
+};
+
+__PACKAGE__->register_method({
+ name => 'index',
+ path => '',
+ method => 'GET',
+ proxyto => 'node',
+ permissions => { user => 'all' },
+ description => 'Node iSCSI index.',
+ parameters =>
+ { additionalProperties => 0, properties => { node => get_standard_option('pve-node') } },
+ returns => {
+ type => 'array',
+ items => { type => 'object', properties => { name => { type => 'string' } } },
+ links => [{ rel => 'child', href => '{name}' }],
+ },
+ code => sub { return [{ name => 'status' }, { name => 'target' }] },
+});
+
+__PACKAGE__->register_method({
+ name => 'status',
+ path => 'status',
+ method => 'GET',
+ protected => 1,
+ proxyto => 'node',
+ description => 'Report the iSCSI initiator identity and availability.',
+ permissions => $read_permissions,
+ parameters =>
+ { additionalProperties => 0, properties => { node => get_standard_option('pve-node') } },
+ returns => {
+ type => 'object',
+ properties => {
+ supported =>
+ { type => 'boolean', description => 'Whether open-iscsi is installed.' },
+ 'initiator-name' =>
+ { type => 'string', optional => 1, description => 'The initiator IQN.' },
+ 'initiator-alias' =>
+ { type => 'string', optional => 1, description => 'The initiator alias.' },
+ },
+ },
+ code => sub {
+ my $res = { supported => PVE::Storage::ISCSIPlugin::iscsi_supported() };
+ my $info = PVE::Storage::ISCSIPlugin::read_initiator_info() // {};
+ $res->{'initiator-name'} = $info->{name} if defined($info->{name});
+ $res->{'initiator-alias'} = $info->{alias} if defined($info->{alias});
+ return $res;
+ },
+});
+
+__PACKAGE__->register_method({
+ name => 'targets',
+ path => 'target',
+ method => 'GET',
+ protected => 1,
+ proxyto => 'node',
+ description => 'List iSCSI targets and their sessions and devices.',
+ permissions => $read_permissions,
+ parameters =>
+ { additionalProperties => 0, properties => { node => get_standard_option('pve-node') } },
+ returns => {
+ type => 'array',
+ items => {
+ type => 'object',
+ properties => {
+ target => { type => 'string', description => 'The target IQN.' },
+ portal => { type => 'string', description => 'The portal address and port.' },
+ 'session-id' =>
+ { type => 'integer', optional => 1, description => 'The kernel session ID.' },
+ state => {
+ type => 'string',
+ enum => ['logged-in', 'recovering', 'failed', 'not-connected', 'unknown'],
+ description => 'The connection state.',
+ },
+ 'kernel-state' =>
+ { type => 'string', optional => 1, description => 'The kernel session state.' },
+ 'used-by-storage' => {
+ type => 'string',
+ optional => 1,
+ description => 'An iSCSI storage using the target.',
+ },
+ devices => {
+ type => 'array',
+ description => 'The block devices of the session.',
+ items => {
+ type => 'object',
+ properties => {
+ devpath =>
+ { type => 'string', description => 'The block device path.' },
+ lun => { type => 'integer', description => 'The LUN number.' },
+ },
+ },
+ },
+ },
+ },
+ },
+ code => sub {
+ my $sessions = PVE::ISCSI::Topology::sessions();
+ my $cfg = PVE::Storage::config();
+ my %owners;
+ for my $sid (sort keys $cfg->{ids}->%*) {
+ my $scfg = $cfg->{ids}->{$sid};
+ $owners{ $scfg->{target} } //= $sid if $scfg->{type} eq 'iscsi' && $scfg->{target};
+ }
+ my (@rows, %seen);
+ for my $sid (sort { $a <=> $b } keys %$sessions) {
+ my $session = $sessions->{$sid};
+ my $state = $session->{state};
+ my $row = {
+ target => $session->{target},
+ portal => $session->{portal},
+ 'session-id' => int($sid),
+ state => $state eq 'LOGGED_IN' ? 'logged-in'
+ : $state eq 'FAILED' ? 'recovering'
+ : $state eq 'FREE' ? 'failed'
+ : 'unknown',
+ 'kernel-state' => $state,
+ devices => [
+ sort { $a->{lun} <=> $b->{lun} || $a->{devpath} cmp $b->{devpath} }
+ map { { devpath => "/dev/$_", lun => $session->{devices}->{$_}->{lun} } }
+ keys $session->{devices}->%*
+ ],
+ };
+ push @rows, $row;
+ $seen{"$row->{target}\0$row->{portal}"} = 1;
+ }
+ if (PVE::Storage::ISCSIPlugin::iscsi_supported()) {
+ for my $record (PVE::Storage::ISCSIPlugin::iscsi_node_list()->@*) {
+ my $portal = PVE::ISCSI::Topology::normalize_portal($record->{portal});
+ next if $seen{"$record->{target}\0$portal"}++;
+ push @rows,
+ {
+ target => $record->{target},
+ portal => $portal,
+ state => 'not-connected',
+ devices => [],
+ };
+ }
+ }
+ for my $row (@rows) {
+ $row->{'used-by-storage'} = $owners{ $row->{target} }
+ if defined($owners{ $row->{target} });
+ }
+ return [sort { $a->{target} cmp $b->{target} || $a->{portal} cmp $b->{portal} } @rows];
+ },
+});
+
+1;
diff --git a/src/PVE/API2/Makefile b/src/PVE/API2/Makefile
index 002a3bd4..9ab978b0 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 ISCSI.pm ${DESTDIR}${PERLDIR}/PVE/API2/ISCSI.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/ISCSI/Topology.pm b/src/PVE/ISCSI/Topology.pm
index 52467864..146bda98 100644
--- a/src/PVE/ISCSI/Topology.pm
+++ b/src/PVE/ISCSI/Topology.pm
@@ -33,8 +33,18 @@ sub sessions($sysfs = undef) {
my $target = file_read_firstline("$dir/targetname") // return;
my $session = {
target => $target,
+ state => file_read_firstline("$dir/state") // '',
+ portal => '',
devices => {},
};
+ my (undef, $conn) = dir_glob_regex("$dir/device", '(connection\d+:\d+)');
+ if (defined($conn)) {
+ my $cdir = "$dir/device/$conn/iscsi_connection/$conn";
+ my $address = file_read_firstline("$cdir/persistent_address") // '';
+ my $port = file_read_firstline("$cdir/persistent_port") // '';
+ $address = "[$address]" if $address =~ m/:/;
+ $session->{portal} = normalize_portal("$address:$port");
+ }
foreach_session_lun(
"$dir/device",
sub($devdir, $channel, $id, $lun) {
@@ -64,4 +74,13 @@ sub device_map($sysfs = undef) {
return $res;
}
+sub normalize_portal($portal) {
+ return $portal if $portal !~ m/^(.+):(\d+)$/;
+ my ($addr, $port) = ($1, $2);
+ $addr =~ s/^\[(.*)\]$/$1/;
+ $addr =~ s/^::ffff:(\d+\.\d+\.\d+\.\d+)$/$1/i;
+ $addr = "[$addr]" if $addr =~ m/:/;
+ return "$addr:$port";
+}
+
1;
diff --git a/src/PVE/Storage/ISCSIPlugin.pm b/src/PVE/Storage/ISCSIPlugin.pm
index e117f39f..89cfc944 100644
--- a/src/PVE/Storage/ISCSIPlugin.pm
+++ b/src/PVE/Storage/ISCSIPlugin.pm
@@ -84,6 +84,33 @@ sub iscsi_session_list {
return $res;
}
+sub iscsi_node_list {
+ assert_iscsi_support();
+
+ my $res = [];
+ eval {
+ run_command(
+ [$ISCSIADM, '--mode', 'node'],
+ errmsg => 'iscsi node record scan failed',
+ outfunc => sub {
+ my $line = shift;
+ if ($line =~ $ISCSI_TARGET_RE) {
+ push @$res, { portal => $1, target => $2 };
+ }
+ },
+ );
+ };
+ if (my $err = $@) {
+ die $err if $err !~ m/: No records found/i;
+ }
+
+ return $res;
+}
+
+sub iscsi_supported {
+ return -x $ISCSIADM ? 1 : 0;
+}
+
sub iscsi_test_session {
my ($sid) = @_;
diff --git a/src/test/run_san_api_tests.pl b/src/test/run_san_api_tests.pl
index f3846ba4..a051350d 100755
--- a/src/test/run_san_api_tests.pl
+++ b/src/test/run_san_api_tests.pl
@@ -5,9 +5,58 @@ use warnings;
use Test::MockModule;
use Test::More;
use lib qw(. ..);
+use PVE::API2::ISCSI;
use PVE::API2::Storage::Scan;
-for my $case (['PVE::API2::Storage::Scan', 'sanlunscan']) {
+my $plugin = Test::MockModule->new('PVE::Storage::ISCSIPlugin');
+my $topology = Test::MockModule->new('PVE::ISCSI::Topology');
+my $storage = Test::MockModule->new('PVE::Storage');
+$plugin->mock(iscsi_supported => sub { 1 });
+$plugin->mock(read_initiator_info => sub { { name => 'iqn.test', alias => 'test' } });
+$plugin->mock(iscsi_node_list => sub { [{ target => 'iqn.target', portal => '192.0.2.2:3260' }] });
+$storage->mock(config => sub { { ids => { san => { type => 'iscsi', target => 'iqn.target' } } } });
+my $state = 'LOGGED_IN';
+$topology->mock(
+ sessions => sub {
+ return {
+ 7 => {
+ target => 'iqn.target',
+ portal => '192.0.2.1:3260',
+ state => $state,
+ devices => { sda => { lun => 1 }, sdb => { lun => 0 } },
+ },
+ };
+ },
+);
+my $status = PVE::API2::ISCSI->map_method_by_name('status');
+is_deeply(
+ $status->{code}->({ node => 'test' }),
+ { supported => 1, 'initiator-name' => 'iqn.test', 'initiator-alias' => 'test' },
+ 'initiator identity',
+);
+my $targets = PVE::API2::ISCSI->map_method_by_name('targets');
+for my $case (
+ ['LOGGED_IN', 'logged-in'],
+ ['FAILED', 'recovering'],
+ ['FREE', 'failed'],
+ ['', 'unknown'],
+) {
+ $state = $case->[0];
+ my $rows = $targets->{code}->({ node => 'test' });
+ is($rows->[0]->{state}, $case->[1], "session state $state");
+ is_deeply(
+ $rows->[0]->{devices},
+ [{ devpath => '/dev/sdb', lun => 0 }, { devpath => '/dev/sda', lun => 1 }],
+ 'session devices ordered by LUN',
+ );
+ is($rows->[1]->{state}, 'not-connected', 'node record without a session');
+ is($rows->[0]->{'used-by-storage'}, 'san', 'target storage attribution');
+ eval { PVE::JSONSchema::validate($rows, $targets->{returns}) };
+ is($@, '', 'rows satisfy the schema');
+}
+for my $case (
+ ['PVE::API2::ISCSI', qw(status targets)], ['PVE::API2::Storage::Scan', 'sanlunscan'],
+) {
my ($class, @names) = @$case;
for my $name (@names) {
is_deeply(
@@ -21,6 +70,11 @@ for my $case (['PVE::API2::Storage::Scan', 'sanlunscan']) {
);
}
}
+is_deeply(
+ PVE::API2::ISCSI->map_method_by_name('index')->{code}->({}),
+ [{ name => 'status' }, { name => 'target' }],
+ 'only read-only children',
+);
require PVE::CLI::pvesm;
my $formatter = Test::MockModule->new('PVE::CLIFormatter');
next prev parent reply other threads:[~2026-11-16 1:27 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-16 1:23 [PATCH v5 cluster,storage,docs,manager 00/36] SAN: cluster-wide multipath, SAN views and a guided setup for shared LVM Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 cluster 01/36] cfs: observe the multipath configuration files Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 02/36] diskmanage: collect disk transport type from lsblk Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 03/36] diskmanage: qualify NVMe over fabrics transport Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 04/36] diskmanage: optionally include iSCSI session devices in disk enumeration Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 05/36] diskmanage: collect native NVMe multipath path state Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 06/36] iscsi: factor out session device map from device list Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 07/36] multipath: add a library around multipathd Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 08/36] diskmanage: add helper to list multipath devices Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 09/36] multipath: add a cluster-wide configuration Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 10/36] iscsi: add an option to manage storage LUNs with multipath Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 11/36] lvm: activate a missing base volume before using the volume group Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 12/36] multipath: apply the configuration on every node Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 13/36] multipath: publish per-node status Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 14/36] api: add endpoints for the cluster-wide multipath configuration Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 15/36] api: multipath: add the cluster-wide health status Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 16/36] api: scan: add a SAN LUN inventory Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 17/36] pvesm: expose the " Thomas Lamprecht
2026-11-16 1:23 ` Thomas Lamprecht [this message]
2026-11-16 1:23 ` [PATCH v5 storage 19/36] disks: lvm: drop unused imports Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 20/36] disks: lvm: allow volume groups on SAN LUNs and multipath maps Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 21/36] disks: lvm: refuse to destroy the volume group of a shared storage Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 storage 22/36] disks: allow wiping a SAN LUN that no storage uses Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 docs 23/36] storage: document the cluster-wide multipath management Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 24/36] pvestatd: apply the multipath configuration and report the node status Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 25/36] report: add the managed multipath configuration Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 26/36] api: cluster: add the multipath endpoints Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 27/36] api: nodes: expose the iSCSI status Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 28/36] ui: dc: add a SAN view Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 29/36] ui: storage: iscsi: add the multipath option Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 30/36] ui: lvm: enable shared when a base storage is selected Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 31/36] ui: node: add SAN LUNs panel Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 32/36] ui: node: san: wipe a LUN that no storage uses Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 33/36] ui: node: san: show iSCSI targets and sessions Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 34/36] ui: dc: san: add a guided setup for shared LVM on iSCSI Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 35/36] ui: dc: san: add a guided setup for shared LVM on Fibre Channel Thomas Lamprecht
2026-11-16 1:23 ` [PATCH v5 manager 36/36] ui: storage: point the iSCSI and LVM add dialogs to the SAN view Thomas Lamprecht
2026-11-18 8:11 ` superseded: [PATCH v5 cluster,storage,docs,manager 00/36] SAN: cluster-wide multipath, SAN views and a guided setup for shared LVM Thomas Lamprecht
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261116012355.3187417-19-t.lamprecht@proxmox.com \
--to=t.lamprecht@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox