vtl-appliance/docs/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

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

{
  "action": "list_targets"
}
```

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

#### 2. Create Target

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

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

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

#### 3. Delete Target

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

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

**Response:**
```json
{
  "success": true,
  "message": "Target deleted successfully"
}
```

#### 4. Add LUN

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

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

**Response:**
```json
{
  "success": true,
  "message": "LUN added successfully"
}
```

#### 5. Bind Initiator

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

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

**Response:**
```json
{
  "success": true,
  "message": "Initiator allowed successfully"
}
```

#### 6. Unbind Initiator

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

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

**Response:**
```json
{
  "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:

```bash
# 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`

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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

```bash
# 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

```bash
=== 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 ✅