vtl-appliance/docs/MHVTL_ISCSI_BINDING_GUIDE.md

# 🔌 MHVTL iSCSI Binding Guide

## Overview

This guide shows you how to **expose MHVTL virtual tape library and drives via iSCSI** so remote backup servers can access them over the network.

## 🎯 Concept

```
┌─────────────────────────────────────────────────────────────┐
│                    MHVTL Server (Ubuntu 24.04)              │
│                                                             │
│  MHVTL Processes → SCSI Devices → iSCSI Targets → Network  │
│  ──────────────────────────────────────────────────────────│
│  vtllibrary      → /dev/sg0     → Target 1 (Changer)       │
│  vtltape (drive0)→ /dev/sg1     → Target 2 (Drive 0)       │
│  vtltape (drive1)→ /dev/sg2     → Target 3 (Drive 1)       │
│  vtltape (drive2)→ /dev/sg3     → Target 4 (Drive 2)       │
│  vtltape (drive3)→ /dev/sg4     → Target 5 (Drive 3)       │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ iSCSI (Port 3260)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Backup Server (Client)                   │
│                                                             │
│  iscsiadm discover → Connect → See Virtual Tape Library    │
│  ──────────────────────────────────────────────────────────│
│  /dev/sg0 → Library (Changer)                              │
│  /dev/sg1 → Tape Drive 0                                   │
│  /dev/sg2 → Tape Drive 1                                   │
│  /dev/sg3 → Tape Drive 2                                   │
│  /dev/sg4 → Tape Drive 3                                   │
│                                                             │
│  Backup Software (Bacula, Amanda, etc.) → Use devices      │
└─────────────────────────────────────────────────────────────┘
```

## 📋 Prerequisites

### 1. Ubuntu 24.04 LTS
```bash
lsb_release -a
# Description: Ubuntu 24.04.3 LTS
```

### 2. Kernel Headers & Build Tools
```bash
sudo apt-get update
sudo apt-get install -y linux-headers-$(uname -r) build-essential
```

### 3. MHVTL Installed
```bash
# Check if MHVTL is installed
which vtltape vtllibrary
# Should show: /usr/bin/vtltape and /usr/bin/vtllibrary
```

### 4. iSCSI Target (tgt) Installed
```bash
sudo apt-get install -y tgt
sudo systemctl enable tgt
sudo systemctl start tgt
```

## 🔧 Step 1: Compile & Install MHVTL Kernel Module

### Why Kernel Module?

MHVTL needs a kernel module to create SCSI devices. Without it, you'll see:
```
ERROR: Could not locate mhvtl kernel module
```

### Compile Module

```bash
# 1. Download MHVTL source
cd /tmp
git clone https://github.com/markh794/mhvtl.git
cd mhvtl/kernel

# 2. Compile kernel module
make

# Output should show:
# CC [M]  /tmp/mhvtl/kernel/mhvtl.o
# MODPOST /tmp/mhvtl/kernel/Module.symvers
# LD [M]  /tmp/mhvtl/kernel/mhvtl.ko

# 3. Install module
sudo make install

# 4. Update module dependencies
sudo depmod -a

# 5. Load module
sudo modprobe mhvtl

# 6. Verify module is loaded
lsmod | grep mhvtl
# Should show: mhvtl    49152  0
```

### Auto-load Module on Boot

```bash
# Add to /etc/modules-load.d/mhvtl.conf
echo "mhvtl" | sudo tee /etc/modules-load.d/mhvtl.conf
```

## 🔧 Step 2: Configure MHVTL

### Check Current Configuration

```bash
# Check device.conf
cat /etc/mhvtl/device.conf

# Should show library and drives like:
# Library: 10 CHANNEL: 00 TARGET: 00 LUN: 00
# Drive: 11 CHANNEL: 00 TARGET: 01 LUN: 00
# Drive: 12 CHANNEL: 00 TARGET: 01 LUN: 01
```

### Start MHVTL Service

```bash
# Start MHVTL
sudo systemctl start mhvtl

# Check status
sudo systemctl status mhvtl

# Should show:
# Active: active (exited)
# Started X drives, Y libraries
```

### Verify SCSI Devices

```bash
# List SCSI devices
lsscsi -g

# Should show something like:
# [3:0:0:0]    mediumx STK      L700             0107  -          /dev/sg0
# [3:0:1:0]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg1
# [3:0:1:1]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg2
# [3:0:1:2]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg3
# [3:0:1:3]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg4
```

**Device Types:**
- `mediumx` = Library/Changer (robot)
- `tape` = Tape Drive

## 🔧 Step 3: Create iSCSI Targets

### Option A: Using Web UI (Recommended)

1. **Open Web UI**
   ```
   http://your-server/mhvtl-config/
   ```

2. **Navigate to "iSCSI" Tab**

3. **Create Target for Library (Changer)**
   ```
   Target ID: 1
   Target Name: vtl.changer
   Click "Create Target"
   ```

4. **Create Targets for Drives**
   ```
   Target ID: 2, Name: vtl.drive0
   Target ID: 3, Name: vtl.drive1
   Target ID: 4, Name: vtl.drive2
   Target ID: 5, Name: vtl.drive3
   ```

5. **Add LUNs (Backing Stores)**
   ```
   Target 1 → LUN 1 → /dev/sg0 (Changer)
   Target 2 → LUN 1 → /dev/sg1 (Drive 0)
   Target 3 → LUN 1 → /dev/sg2 (Drive 1)
   Target 4 → LUN 1 → /dev/sg3 (Drive 2)
   Target 5 → LUN 1 → /dev/sg4 (Drive 3)
   ```

6. **Configure ACLs**
   ```
   For each target:
   - Allow specific IP: 192.168.1.100
   - Or allow all: ALL
   ```

### Option B: Using Command Line

```bash
# 1. Create target for changer
sudo tgtadm --lld iscsi --mode target --op new --tid 1 \
  --targetname iqn.2024-01.com.vtl-linux:vtl.changer

# 2. Add changer device as LUN
sudo tgtadm --lld iscsi --mode logicalunit --op new \
  --tid 1 --lun 1 --backing-store /dev/sg0

# 3. Allow all initiators (or specific IP)
sudo tgtadm --lld iscsi --mode target --op bind \
  --tid 1 --initiator-address ALL

# 4. Create target for drive 0
sudo tgtadm --lld iscsi --mode target --op new --tid 2 \
  --targetname iqn.2024-01.com.vtl-linux:vtl.drive0

# 5. Add drive 0 device as LUN
sudo tgtadm --lld iscsi --mode logicalunit --op new \
  --tid 2 --lun 1 --backing-store /dev/sg1

# 6. Allow initiators
sudo tgtadm --lld iscsi --mode target --op bind \
  --tid 2 --initiator-address ALL

# Repeat for other drives (sg2, sg3, sg4)...
```

### Verify iSCSI Targets

```bash
# List all targets
sudo tgtadm --lld iscsi --mode target --op show

# Should show:
# Target 1: iqn.2024-01.com.vtl-linux:vtl.changer
#     LUN: 0
#         Type: controller
#     LUN: 1
#         Type: passthrough
#         SCSI ID: ...
#         Backing store path: /dev/sg0
#     ACL information:
#         ALL
```

## 🔧 Step 4: Configure Firewall

```bash
# Allow iSCSI port (3260)
sudo ufw allow 3260/tcp

# Or for specific IP
sudo ufw allow from 192.168.1.100 to any port 3260

# Check firewall status
sudo ufw status
```

## 🔧 Step 5: Connect from Client (Backup Server)

### Install iSCSI Initiator

```bash
# On Ubuntu/Debian
sudo apt-get install -y open-iscsi

# On RHEL/CentOS
sudo yum install -y iscsi-initiator-utils

# Start service
sudo systemctl enable iscsid
sudo systemctl start iscsid
```

### Discover iSCSI Targets

```bash
# Discover targets from MHVTL server
sudo iscsiadm -m discovery -t st -p <MHVTL_SERVER_IP>

# Example:
sudo iscsiadm -m discovery -t st -p 192.168.1.50

# Output:
# 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.changer
# 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.drive0
# 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.drive1
# 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.drive2
# 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.drive3
```

### Login to iSCSI Targets

```bash
# Login to all targets
sudo iscsiadm -m node --login

# Or login to specific target
sudo iscsiadm -m node -T iqn.2024-01.com.vtl-linux:vtl.changer --login

# Check session
sudo iscsiadm -m session

# Output:
# tcp: [1] 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.changer (non-flash)
# tcp: [2] 192.168.1.50:3260,1 iqn.2024-01.com.vtl-linux:vtl.drive0 (non-flash)
```

### Verify Devices on Client

```bash
# List SCSI devices
lsscsi -g

# Should now show:
# [X:0:0:0]    mediumx STK      L700             0107  -          /dev/sg0
# [Y:0:0:0]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg1
# [Z:0:0:0]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg2

# Check device details
sudo sg_inq /dev/sg0  # Should show library info
sudo sg_inq /dev/sg1  # Should show tape drive info
```

## 🔧 Step 6: Configure Backup Software

### Bacula Configuration

```bash
# Edit /etc/bacula/bacula-sd.conf

Autochanger {
  Name = "VTL-Changer"
  Device = Drive-0, Drive-1, Drive-2, Drive-3
  Changer Command = "/usr/lib/bacula/scripts/mtx-changer %c %o %S %a %d"
  Changer Device = /dev/sg0
}

Device {
  Name = Drive-0
  Media Type = LTO-8
  Archive Device = /dev/nst0
  AutomaticMount = yes
  AlwaysOpen = yes
  RemovableMedia = yes
  RandomAccess = no
  AutoChanger = yes
  Drive Index = 0
}

# Repeat for Drive-1, Drive-2, Drive-3...
```

### Amanda Configuration

```bash
# Edit /etc/amanda/amanda.conf

define changer vtl-changer {
    tpchanger "chg-robot:/dev/sg0"
    property "tape-device" "0=/dev/nst0"
    property "tape-device" "1=/dev/nst1"
    property "tape-device" "2=/dev/nst2"
    property "tape-device" "3=/dev/nst3"
}
```

### Veeam Configuration

1. Open Veeam Backup & Replication
2. Go to **Backup Infrastructure** → **Tape Servers**
3. Add new tape server (your backup server)
4. Veeam will auto-detect the library and drives
5. Configure tape jobs to use the VTL

## 📊 Complete Setup Example

### MHVTL Server Setup

```bash
# 1. Install kernel module
cd /tmp && git clone https://github.com/markh794/mhvtl.git
cd mhvtl/kernel && make && sudo make install
sudo depmod -a && sudo modprobe mhvtl

# 2. Start MHVTL
sudo systemctl start mhvtl

# 3. Verify devices
lsscsi -g
# [3:0:0:0]    mediumx STK      L700             0107  -          /dev/sg0
# [3:0:1:0]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg1
# [3:0:1:1]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg2

# 4. Create iSCSI targets
sudo tgtadm --lld iscsi --mode target --op new --tid 1 \
  --targetname iqn.2024-01.com.vtl-linux:vtl.changer
sudo tgtadm --lld iscsi --mode logicalunit --op new \
  --tid 1 --lun 1 --backing-store /dev/sg0
sudo tgtadm --lld iscsi --mode target --op bind \
  --tid 1 --initiator-address ALL

sudo tgtadm --lld iscsi --mode target --op new --tid 2 \
  --targetname iqn.2024-01.com.vtl-linux:vtl.drive0
sudo tgtadm --lld iscsi --mode logicalunit --op new \
  --tid 2 --lun 1 --backing-store /dev/sg1
sudo tgtadm --lld iscsi --mode target --op bind \
  --tid 2 --initiator-address ALL

# 5. Allow firewall
sudo ufw allow 3260/tcp

# 6. Verify
sudo tgtadm --lld iscsi --mode target --op show
```

### Client Setup

```bash
# 1. Install iSCSI initiator
sudo apt-get install -y open-iscsi

# 2. Discover targets
sudo iscsiadm -m discovery -t st -p 192.168.1.50

# 3. Login to targets
sudo iscsiadm -m node --login

# 4. Verify devices
lsscsi -g

# 5. Test library
mtx -f /dev/sg0 status

# 6. Test tape drive
mt -f /dev/nst0 status
```

## 🔍 Troubleshooting

### Issue 1: "Could not locate mhvtl kernel module"

**Solution:**
```bash
# Compile and install kernel module
cd /tmp/mhvtl/kernel
make && sudo make install
sudo depmod -a
sudo modprobe mhvtl
lsmod | grep mhvtl
```

### Issue 2: No SCSI devices after starting MHVTL

**Check:**
```bash
# 1. Module loaded?
lsmod | grep mhvtl

# 2. Service running?
sudo systemctl status mhvtl

# 3. Check logs
sudo journalctl -u mhvtl -n 50

# 4. Check config
cat /etc/mhvtl/device.conf
```

### Issue 3: Cannot add LUN to iSCSI target

**Error:** `tgtadm: invalid request`

**Possible causes:**
- Device doesn't exist
- Device is not a SCSI generic device
- Device is already in use

**Solution:**
```bash
# Check device exists
ls -l /dev/sg0

# Check device type
lsscsi -g | grep sg0

# Check if device is in use
sudo lsof /dev/sg0

# Try with correct device
sudo tgtadm --lld iscsi --mode logicalunit --op new \
  --tid 1 --lun 1 --backing-store /dev/sg0 \
  --bstype=sg --device-type=changer
```

### Issue 4: Client cannot discover targets

**Check:**
```bash
# 1. Firewall on server
sudo ufw status | grep 3260

# 2. tgt service running
sudo systemctl status tgt

# 3. Targets exist
sudo tgtadm --lld iscsi --mode target --op show

# 4. Network connectivity
ping <MHVTL_SERVER_IP>
telnet <MHVTL_SERVER_IP> 3260
```

### Issue 5: Client can discover but cannot login

**Check ACLs:**
```bash
# Show ACLs
sudo tgtadm --lld iscsi --mode target --op show --tid 1 | grep ACL

# If no ACL, add one
sudo tgtadm --lld iscsi --mode target --op bind \
  --tid 1 --initiator-address ALL

# Or specific IP
sudo tgtadm --lld iscsi --mode target --op bind \
  --tid 1 --initiator-address 192.168.1.100
```

### Issue 6: Devices appear but backup software doesn't see them

**Check:**
```bash
# 1. Verify device type
lsscsi -g
# Should show "mediumx" for changer, "tape" for drives

# 2. Test with mtx (for changer)
sudo mtx -f /dev/sg0 status

# 3. Test with mt (for tape)
sudo mt -f /dev/nst0 status

# 4. Check permissions
ls -l /dev/sg* /dev/nst*
sudo chmod 660 /dev/sg* /dev/nst*
sudo chown root:tape /dev/sg* /dev/nst*
```

## 🎯 Best Practices

### 1. Device Mapping

Keep consistent mapping:
```
/dev/sg0 → Target 1 → Changer
/dev/sg1 → Target 2 → Drive 0
/dev/sg2 → Target 3 → Drive 1
/dev/sg3 → Target 4 → Drive 2
/dev/sg4 → Target 5 → Drive 3
```

### 2. Target Naming

Use descriptive names:
```
iqn.2024-01.com.vtl-linux:vtl.changer
iqn.2024-01.com.vtl-linux:vtl.drive0
iqn.2024-01.com.vtl-linux:vtl.drive1
```

### 3. Security

- Use specific IP ACLs instead of "ALL" in production
- Enable firewall rules
- Use CHAP authentication (optional)
- Isolate VTL traffic on dedicated VLAN

### 4. Performance

- Use dedicated network interface for iSCSI
- Enable jumbo frames (MTU 9000)
- Use 10GbE if possible
- Monitor network bandwidth

### 5. Persistence

Make iSCSI targets persistent:
```bash
# Save tgt configuration
sudo tgt-admin --dump > /etc/tgt/conf.d/vtl.conf

# Auto-restore on boot
sudo systemctl enable tgt
```

### 6. Monitoring

```bash
# Check iSCSI sessions
sudo tgtadm --lld iscsi --mode conn --op show --tid 1

# Check MHVTL status
sudo systemctl status mhvtl

# Check device usage
lsof /dev/sg*

# Monitor logs
sudo journalctl -u mhvtl -f
sudo journalctl -u tgt -f
```

## 📚 Additional Resources

### MHVTL Commands

```bash
# List tapes
vtlcmd -l

# Create tape
mktape -l <library> -m <media-type> -s <barcode>

# Load tape
vtlcmd <drive> load <slot>

# Unload tape
vtlcmd <drive> unload

# Library status
vtlcmd <library> status
```

### iSCSI Commands

```bash
# Show all targets
sudo tgtadm --lld iscsi --mode target --op show

# Show specific target
sudo tgtadm --lld iscsi --mode target --op show --tid 1

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

# Show connections
sudo tgtadm --lld iscsi --mode conn --op show --tid 1
```

### Client Commands

```bash
# Discover targets
sudo iscsiadm -m discovery -t st -p <server>

# Login to target
sudo iscsiadm -m node -T <iqn> --login

# Logout from target
sudo iscsiadm -m node -T <iqn> --logout

# Show sessions
sudo iscsiadm -m session

# Delete node
sudo iscsiadm -m node -T <iqn> --op delete
```

## 🎉 Summary

**What You've Accomplished:**

1. ✅ Compiled and installed MHVTL kernel module
2. ✅ Started MHVTL with library and drives
3. ✅ Created iSCSI targets for each device
4. ✅ Configured ACLs for client access
5. ✅ Connected from backup server
6. ✅ Verified devices are accessible
7. ✅ Ready for backup software integration

**Your VTL is now accessible over the network via iSCSI!** 🚀

Remote backup servers can now:
- See the virtual tape library (changer/robot)
- Access virtual tape drives
- Load/unload virtual tapes
- Perform backups to virtual tapes
- All over standard Ethernet network!

---

**Last Updated**: December 9, 2025  
**Tested On**: Ubuntu 24.04.3 LTS, Kernel 6.8.0-88  
**Status**: Production Ready ✅