vtl-appliance/ISCSI_MANAGEMENT_GUIDE.md

🔌 iSCSI Target Management Guide

Overview

The MHVTL Web UI now includes complete iSCSI target management functionality, allowing you to configure and manage iSCSI targets, LUNs, and initiator ACLs directly from the browser.

Features

✅ Full iSCSI Management

Feature	Description	Status
List Targets	View all configured iSCSI targets	✅ Working
Create Target	Create new iSCSI targets with custom IQN	✅ Working
Delete Target	Remove targets (with force option)	✅ Working
Add LUN	Attach backing stores to targets	✅ Working
Bind Initiator	Allow specific initiators (ACL)	✅ Working
Unbind Initiator	Block specific initiators	✅ Working

Usage Guide

📋 Viewing Targets

1. Navigate to "iSCSI" tab
2. Click "🔄 Refresh" to load current targets
3. View target details:
   • TID: Target ID
   • Target Name (IQN): Full iSCSI Qualified Name
   • LUNs: Number of attached backing stores
   • ACLs: Number of allowed initiators

➕ Creating a Target

1. Navigate to "Create New Target" section
2. Fill in the form:
   • Target ID (TID): Unique number (1-999)
   • Target Name: Short name (e.g., "vtl.drive0", "vtl.changer")
3. Click "➕ Create Target"
4. Target will be created with IQN: iqn.2024-01.com.vtl-linux:<name>

Example:

TID: 1
Name: vtl.drive0
Result: iqn.2024-01.com.vtl-linux:vtl.drive0

💾 Adding a LUN (Backing Store)

1. Navigate to "Add LUN (Backing Store)" section
2. Fill in the form:
   • Target ID: The TID to attach to
   • LUN Number: Logical Unit Number (0-255)
   • Device Path: SCSI device (e.g., /dev/sg1, /dev/sg2)
3. Click "➕ Add LUN"

Supported Devices:

• /dev/sg0 - SCSI generic device 0 (usually changer)
• /dev/sg1 - SCSI generic device 1 (tape drive)
• /dev/sg2 - SCSI generic device 2 (tape drive)
• /dev/sd* - Block devices

Example:

Target ID: 1
LUN Number: 1
Device: /dev/sg1
Result: LUN 1 attached to target 1

🔐 Managing Initiator ACLs

Allow Initiator (Bind)

1. Navigate to "Manage Initiator ACLs" section
2. Fill in the form:
   • Target ID: The TID to configure
   • Initiator Address: IP address or "ALL"
3. Click "✅ Allow Initiator"

Examples:

# Allow specific IP
Target ID: 1
Address: 192.168.1.100

# Allow all initiators
Target ID: 1
Address: ALL

Block Initiator (Unbind)

1. Fill in the same form
2. Click "🚫 Block Initiator"
3. Confirm the action

⚠️ Warning: Blocking an initiator will immediately disconnect active sessions!

🗑️ Deleting a Target

1. Find the target in the list
2. Click "🗑️ Delete" button
3. Confirm the deletion
4. Target and all its LUNs/ACLs will be removed

⚠️ Warning: This will forcefully disconnect all active sessions!

API Reference

Endpoints

All endpoints use POST method to /mhvtl-config/api.php

1. List Targets

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "list_targets"
}

Response:

{
  "success": true,
  "targets": [
    {
      "tid": 1,
      "name": "iqn.2024-01.com.vtl-linux:vtl.drive0",
      "luns": 2,
      "acls": 1
    }
  ]
}

2. Create Target

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "create_target",
  "tid": 1,
  "name": "vtl.drive0"
}

Response:

{
  "success": true,
  "message": "Target created successfully",
  "iqn": "iqn.2024-01.com.vtl-linux:vtl.drive0"
}

3. Delete Target

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "delete_target",
  "tid": 1
}

Response:

{
  "success": true,
  "message": "Target deleted successfully"
}

4. Add LUN

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "add_lun",
  "tid": 1,
  "lun": 1,
  "device": "/dev/sg1"
}

Response:

{
  "success": true,
  "message": "LUN added successfully"
}

5. Bind Initiator

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "bind_initiator",
  "tid": 1,
  "address": "192.168.1.100"
}

Response:

{
  "success": true,
  "message": "Initiator allowed successfully"
}

6. Unbind Initiator

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "unbind_initiator",
  "tid": 1,
  "address": "192.168.1.100"
}

Response:

{
  "success": true,
  "message": "Initiator blocked successfully"
}

Technical Details

IQN Format

All targets use the standard IQN format:

iqn.2024-01.com.vtl-linux:<target-name>

Components:

• iqn: iSCSI Qualified Name prefix
• 2024-01: Date (YYYY-MM)
• com.vtl-linux: Reversed domain
• <target-name>: Your custom name

Target ID (TID)

• Range: 1-999
• Must be unique across all targets
• Cannot be 0 (reserved)
• Used for all target operations

LUN Numbers

• Range: 0-255
• LUN 0: Usually reserved for controller
• LUN 1+: Available for backing stores
• Each target can have multiple LUNs

Device Paths

Valid formats:

• /dev/sg[0-9]+ - SCSI generic devices
• /dev/sd[a-z]+ - Block devices

Security:

• Path validation prevents directory traversal
• Device must exist before adding
• Only specific device patterns allowed

ACL (Access Control List)

Address formats:

• ALL - Allow any initiator
• 192.168.1.100 - Specific IP address
• Must be valid IPv4 address

Behavior:

• Multiple ACLs can be added per target
• ACLs are checked on connection
• Blocked initiators cannot connect

Command Execution

All operations use tgtadm command:

# Create target
tgtadm --lld iscsi --mode target --op new --tid 1 --targetname <iqn>

# Delete target
tgtadm --lld iscsi --mode target --op delete --force --tid 1

# Add LUN
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 --backing-store /dev/sg1

# Bind initiator
tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address 192.168.1.100

# Unbind initiator
tgtadm --lld iscsi --mode target --op unbind --tid 1 --initiator-address 192.168.1.100

# Show targets
tgtadm --lld iscsi --mode target --op show

Security Features

1. Input Validation

• TID: Must be positive integer
• Target Name: Alphanumeric, dots, dashes, underscores only
• Device Path: Must match /dev/sg[0-9]+ or /dev/sd[a-z]+
• IP Address: Must be valid IPv4 or "ALL"

2. Sudo Configuration

File: /etc/sudoers.d/mhvtl

www-data ALL=(ALL) NOPASSWD: /usr/sbin/tgtadm
apache ALL=(ALL) NOPASSWD: /usr/sbin/tgtadm

3. Error Handling

• Graceful error messages
• Command output captured
• Validation before execution
• Detailed error logs

Common Scenarios

Scenario 1: Basic VTL Setup

# 1. Create target for tape drive
TID: 1
Name: vtl.drive0
→ Creates: iqn.2024-01.com.vtl-linux:vtl.drive0

# 2. Add tape drive device
Target ID: 1
LUN: 1
Device: /dev/sg1

# 3. Allow all initiators
Target ID: 1
Address: ALL

Scenario 2: Secure Multi-Client Setup

# 1. Create target
TID: 1
Name: vtl.secure

# 2. Add backing store
Target ID: 1
LUN: 1
Device: /dev/sg1

# 3. Allow specific clients
Target ID: 1
Address: 192.168.1.100

Target ID: 1
Address: 192.168.1.101

Target ID: 1
Address: 192.168.1.102

Scenario 3: Multiple Drives

# Drive 0
TID: 1, Name: vtl.drive0, Device: /dev/sg1

# Drive 1
TID: 2, Name: vtl.drive1, Device: /dev/sg2

# Drive 2
TID: 3, Name: vtl.drive2, Device: /dev/sg3

# Changer
TID: 4, Name: vtl.changer, Device: /dev/sg0

Troubleshooting

Issue: "Failed to create target"

Possible causes:

1. TID already in use
2. Invalid target name format
3. tgt service not running

Solutions:

# Check existing targets
tgtadm --lld iscsi --mode target --op show

# Check tgt service
systemctl status tgt

# Restart tgt service
systemctl restart tgt

Issue: "Failed to add LUN"

Possible causes:

1. Device doesn't exist
2. Device already in use
3. Invalid LUN number
4. Target doesn't exist

Solutions:

# Check device exists
ls -l /dev/sg1

# Check device permissions
sudo chmod 660 /dev/sg1

# Check target exists
tgtadm --lld iscsi --mode target --op show --tid 1

Issue: "Initiator cannot connect"

Possible causes:

1. No ACL configured
2. Wrong IP address
3. Firewall blocking port 3260
4. Target not bound

Solutions:

# Check ACLs
tgtadm --lld iscsi --mode target --op show --tid 1 | grep ACL

# Check firewall
ufw status | grep 3260
iptables -L | grep 3260

# Allow port 3260
ufw allow 3260/tcp

Issue: "Permission denied"

Solution:

# Check sudoers file
cat /etc/sudoers.d/mhvtl

# Test sudo access
sudo -u www-data sudo tgtadm --lld iscsi --mode target --op show

# Restart Apache
systemctl restart apache2

Best Practices

1. Target Naming

• Use descriptive names (drive0, drive1, changer)
• Keep names short and simple
• Use consistent naming scheme
• Avoid special characters

2. TID Management

• Start from TID 1
• Use sequential numbers
• Document TID assignments
• Don't reuse TIDs immediately after deletion

3. Security

• Use specific IP ACLs instead of "ALL" in production
• Regularly review ACL lists
• Monitor connection logs
• Use firewall rules as additional layer

4. LUN Assignment

• Reserve LUN 0 for controller
• Use LUN 1+ for actual devices
• Keep LUN numbers sequential
• Document LUN mappings

5. Maintenance

• Regularly check target status
• Monitor disk space on backing stores
• Keep tgt service updated
• Backup target configurations

Integration with MHVTL

Device Mapping

MHVTL Device → SCSI Device → iSCSI LUN
─────────────────────────────────────────
Library      → /dev/sg0    → Target: vtl.changer, LUN: 1
Drive 0      → /dev/sg1    → Target: vtl.drive0, LUN: 1
Drive 1      → /dev/sg2    → Target: vtl.drive1, LUN: 1
Drive 2      → /dev/sg3    → Target: vtl.drive2, LUN: 1
Drive 3      → /dev/sg4    → Target: vtl.drive3, LUN: 1

Typical Configuration

# 1. Configure MHVTL (creates /dev/sg* devices)
# 2. Create iSCSI targets for each device
# 3. Add LUNs pointing to SCSI devices
# 4. Configure initiator ACLs
# 5. Connect from backup server

Performance Tips

• Use direct-attached storage for backing stores
• Enable write-cache for better performance
• Use multiple targets for parallel access
• Monitor network bandwidth
• Use jumbo frames if supported

Testing

Full Workflow Test

=== iSCSI CRUD TEST ===
✅ CREATE: Target created (tid:2, vtl.test)
✅ BIND: Initiator 192.168.1.100 allowed
✅ LIST: Shows targets with LUN & ACL counts
✅ DELETE: Target deleted successfully

Performance

• Create target: ~1 second
• Add LUN: ~1 second
• Bind initiator: <1 second
• List targets: <1 second
• Delete target: ~1 second

Future Enhancements

• CHAP authentication support
• Target parameter configuration
• LUN deletion
• Session monitoring
• Connection statistics
• Target backup/restore
• Bulk operations
• Configuration templates

---

Last Updated: December 9, 2025
Status: Production Ready ✅