all lists on lists.proxmox.com
 help / color / mirror / Atom feed
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');




  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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal