feat: Major VTL System Upgrade (Auth, Monitoring, CLI, Installer)
- Web UI: - Added secure Authentication system (Login, 2 Roles: Admin/Viewer) - Added System Monitoring Dashboard (Health, Services, Power Mgmt) - Added User Management Interface (Create, Delete, Enable/Disable) - Added Device Mapping view in iSCSI tab (lsscsi output) - Backend: - Implemented secure session management (auth.php) - Added power management APIs (restart/shutdown appliance) - Added device mapping API - CLI: - Created global 'vtl' management tool - Added scripts for reliable startup (vtllibrary fix) - Installer: - Updated install.sh with new dependencies (tgt, sudoers, permissions) - Included all new components in build-installer.sh - Docs: - Consolidated documentation into docs/ folder
This commit is contained in:
586
docs/ISCSI_MANAGEMENT_GUIDE.md
Normal file
586
docs/ISCSI_MANAGEMENT_GUIDE.md
Normal file
@@ -0,0 +1,586 @@
|
||||
# 🔌 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 ✅
|
||||
Reference in New Issue
Block a user