Unix Server Tech Knowledge Base

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Advanced iSCSI Procedures ======

This article covers non-trivial iSCSI procedures that require careful execution to avoid data loss or service disruption.

===== Resizing an iSCSI Target =====

==== Overview ====

When an iSCSI target needs to be expanded, the process varies depending on the underlying storage technology. This guide covers both LVM2 and ZFS-based targets.

==== General Approach (LVM2) ====

For LVM2-backed exports:
  - Unmount and disconnect the target on all initiators
  - Expand the logical volume on the target server
  - Restart the iSCSI target service (recommended for consistency)
  - Reconnect initiators and resize the filesystem

==== ZFS-Based Targets (FreeBSD) ====

The following procedure assumes:
  * **Target:** FreeBSD with ZFS volumes (zvols)
  * **Initiator:** Debian/Devuan-based Linux systems

<WRAP center round alert 60%>
**⚠ Warning:** Ensure no applications or services are accessing the target volume during this process. Options:
  * **Minimum:** Stop all services using the target
  * **Recommended:** Logout from the target on all initiators before making changes
</WRAP>

=== Step 1: Expand the ZFS Volume (Target Server) ===

<code bash>
# Set the new size on the ZFS volume
# Example: storage/iscsi/target is the zvol path
# newsize format: 500G, 2T, etc.
zfs set volsize=500G storage/iscsi/target

# Notify ctld of the configuration change
# 'reload' may work instead of 'restart' if supported
service ctld restart
</code>

=== Step 2: Rescan from Initiator (Linux) ===

After expanding the target, initiators must rescan to detect the new size.

**Option A: Rescan all sessions (not recommended for production)**
<code bash>
# Rescans ALL iSCSI sessions - use with caution in production
iscsiadm -m session --rescan
</code>

**Option B: Rescan specific target only (recommended)**

<code bash>
# Method 1: Find the Session ID (SID) for your specific target
# Replace 'thing1' with a unique substring from your target name
SID=$(iscsiadm -m session -P 0 | grep thing1 | cut -d'[' -f2 | cut -d']' -f1)

# Rescan only that specific session
iscsiadm --mode session --sid=$SID --rescan

# Alternatively, manually find SID and run directly:
# iscsiadm -m session          # Lists all sessions with SIDs
# iscsiadm --mode session --sid=15 --rescan

# Verify the new size has been detected
fdisk -l /dev/disk/by-path/ip-<target-ip>:3260-iscsi-<iqn>-lun-<num>
# Or use lsblk for a cleaner view
lsblk /dev/disk/by-path/ip-<target-ip>*
</code>

=== Step 3: Resize the Filesystem ===

After the initiator recognizes the new size, expand the filesystem:

**For ext4:**
<code bash>
resize2fs /dev/sdX
</code>

**For XFS:**
<code bash>
xfs_growfs /mount/point
</code>

**For LVM:**
<code bash>
pvresize /dev/sdX
lvextend -l +100%FREE /dev/vg_name/lv_name
resize2fs /dev/vg_name/lv_name  # for ext4
</code>

**For virtual machines:** Consider booting from [[https://gparted.org/download.php|GParted Live CD]] to safely resize partitions without mounting them.

===== Removing an iSCSI Target =====

==== Overview ====

Removing an iSCSI target requires cleanup on both the target server and all initiators. The initiator maintains a local database of discovered targets that must be explicitly cleaned.

<WRAP center round important 60%>
**Critical:** Always logout from the target BEFORE removing it from the database. Failure to do so may cause issues.
</WRAP>

==== Procedure: Remove a Single Target ====

<code bash>
# Step 1: Logout from the iSCSI session
# Replace with your actual target IQN and portal address
iscsiadm -m node \
  --target='iqn.2005-03.org.example:storage.target1' \
  --portal "192.168.1.100:3260" \
  --logout

# Step 2: Remove the target from the local database
iscsiadm -m node \
  --target='iqn.2005-03.org.example:storage.target1' \
  --portal "192.168.1.100:3260" \
  -o delete

# Verify removal
iscsiadm -m node
</code>

==== Procedure: Remove All Targets (Complete Cleanup) ====

When decommissioning an entire iSCSI infrastructure or target server:

=== Method 1: Service Shutdown and Manual Cleanup ===

<code bash>
# Stop the iSCSI initiator service
# sysV (Devuan, other good Linux systems)
service start iscsiadm
service stop open-iscis # or iscsid on some systems

# systemd (RedHat, other Linux systems which have drunk the Kool-aid)
systemctl stop iscsiadm
systemctl stop open-iscsi    # or iscsid on some systems

# Remove iSCSI configuration databases
# Debian/Ubuntu location:
rm -rf /etc/iscsi/send_targets/*
rm -rf /etc/iscsi/nodes/*

# RHEL/CentOS/Rocky location:
rm -rf /var/lib/iscsi/send_targets/*
rm -rf /var/lib/iscsi/nodes/*

# Restart the service
service start open-iscis # sysV
systemctl start open-iscsi # systemd
</code>

=== Method 2: Programmatic Logout ===

<code bash>
# Logout from all active sessions
iscsiadm -m node --logoutall=all

# Remove all node records
iscsiadm -m node -o delete

# Verify all targets are removed
iscsiadm -m node
</code>

==== Distribution-Specific Notes ====

^ Distribution ^ Configuration Path ^
| Debian/Ubuntu/Devuan | ''/etc/iscsi/nodes/'' and ''/etc/iscsi/send_targets/'' |
| RHEL/CentOS/Rocky/Fedora | ''/var/lib/iscsi/nodes/'' and ''/var/lib/iscsi/send_targets/'' |
| SUSE | ''/var/lib/iscsi/nodes/'' and ''/var/lib/iscsi/send_targets/'' |

===== Additional Resources =====

  * [[https://linux.die.net/man/8/iscsiadm|iscsiadm man page]]
  * [[https://docs.freebsd.org/en/books/handbook/network-iscsi/|FreeBSD iSCSI Handbook]]
  * [[https://groups.google.com/forum/#!topic/open-iscsi/7x28lO6-Rho|Open-iSCSI Google Group Discussion]]

===== Best Practices =====

  * Always test resize operations in a non-production environment first
  * Maintain backups before performing any resize operations
  * Document your target IQNs and portal addresses
  * Use ''by-path'' device naming for consistency across reboots
  * Monitor initiator logs (''/var/log/syslog'' or ''journalctl'') during operations

----

//Last updated: February 2, 2026//