public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH v7 storage 20/43] api: add node-level iSCSI status
Date: Wed, 18 Nov 2026 21:26:03 +0100	[thread overview]
Message-ID: <20261118202646.3017286-21-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261118202646.3017286-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 bb52a93f..c3066fa0 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 4ebfaccd..f975f94f 100644
--- a/src/PVE/ISCSI/Topology.pm
+++ b/src/PVE/ISCSI/Topology.pm
@@ -35,8 +35,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) {
@@ -66,4 +76,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 5cc0ad7e..565d2b15 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 9f8e2d7d..c16d2bf2 100755
--- a/src/test/run_san_api_tests.pl
+++ b/src/test/run_san_api_tests.pl
@@ -5,10 +5,59 @@ use warnings;
 use Test::MockModule;
 use Test::More;
 use lib qw(. ..);
+use PVE::API2::ISCSI;
 use PVE::API2::Storage::Scan;
 use PVE::CLI::pvesm;
 
-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(
@@ -22,6 +71,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',
+);
 
 my $formatter = Test::MockModule->new('PVE::CLIFormatter');
 my $data = [{ wwid => '3600abc', devpath => '/dev/sda', serial => 'S1' }];




  parent reply	other threads:[~2026-11-18 20:31 UTC|newest]

Thread overview: 45+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-18 20:25 [PATCH v7 cluster,storage,docs,manager 00/43] SAN: cluster-wide multipath, SAN views and a guided setup for shared LVM Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 cluster 01/43] cfs: observe the multipath configuration files Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 02/43] diskmanage: collect disk transport type from lsblk Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 03/43] diskmanage: qualify NVMe over Fabrics transport Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 04/43] diskmanage: optionally include iSCSI session devices in disk enumeration Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 05/43] diskmanage: collect native NVMe multipath path state Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 06/43] iscsi: factor out session device map from device list Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 07/43] multipath: add a library around multipathd Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 08/43] diskmanage: add helper to list multipath devices Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 09/43] multipath: add a cluster-wide configuration Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 10/43] iscsi: add an option to manage storage LUNs with multipath Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 11/43] lvm: activate a missing base volume before using the volume group Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 12/43] multipath: apply the configuration on every node Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 13/43] multipath: publish per-node status Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 14/43] api: add endpoints for the cluster-wide multipath configuration Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 15/43] api: multipath: add the cluster-wide health status Thomas Lamprecht
2026-11-18 20:25 ` [PATCH v7 storage 16/43] diskmanage: look up the requested disks by name Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 17/43] diskmanage: read the udev data of all disks with one call Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 18/43] api: scan: add a SAN LUN inventory Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 19/43] pvesm: expose the " Thomas Lamprecht
2026-11-18 20:26 ` Thomas Lamprecht [this message]
2026-11-18 20:26 ` [PATCH v7 storage 21/43] api: scan: name the portal of an iSCSI path Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 22/43] disks: lvm: drop unused imports Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 23/43] disks: lvm: allow volume groups on SAN LUNs and multipath maps Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 24/43] disks: lvm: refuse to destroy the volume group of a shared storage Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 25/43] disks: allow wiping a SAN LUN that no storage uses Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 storage 26/43] api: scan: report the process that has a SAN LUN open Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 docs 27/43] storage: document the cluster-wide multipath management Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 docs 28/43] storage: multipath: describe the use shown for an open LUN Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 29/43] pvestatd: apply the multipath configuration and report the node status Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 30/43] report: add the managed multipath configuration Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 31/43] api: cluster: add the multipath endpoints Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 32/43] api: nodes: expose the iSCSI status Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 33/43] ui: dc: add a SAN view Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 34/43] ui: storage: iscsi: add the multipath option Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 35/43] ui: lvm: enable shared when a base storage is selected Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 36/43] ui: node: add SAN LUNs panel Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 37/43] ui: node: san: wipe a LUN that no storage uses Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 38/43] ui: node: san: show iSCSI targets and sessions Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 39/43] ui: dc: san: add a guided setup for shared LVM on iSCSI Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 40/43] ui: dc: san: add a guided setup for shared LVM on Fibre Channel Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 41/43] ui: storage: point the iSCSI and LVM add dialogs to the SAN view Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 42/43] ui: san: show the guest or process that has a LUN open Thomas Lamprecht
2026-11-18 20:26 ` [PATCH v7 manager 43/43] ui: node: san: add a column for the target or subsystem of a LUN Thomas Lamprecht
2026-11-19 19:49 ` superseded: [PATCH v7 cluster,storage,docs,manager 00/43] 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=20261118202646.3017286-21-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
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal