vtl-appliance/dist/adastra-vtl-installer/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

lsb_release -a
# Description: Ubuntu 24.04.3 LTS

2. Kernel Headers & Build Tools

sudo apt-get update
sudo apt-get install -y linux-headers-$(uname -r) build-essential

3. MHVTL Installed

# Check if MHVTL is installed
which vtltape vtllibrary
# Should show: /usr/bin/vtltape and /usr/bin/vtllibrary

4. iSCSI Target (tgt) Installed

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# Save tgt configuration
sudo tgt-admin --dump > /etc/tgt/conf.d/vtl.conf

# Auto-restore on boot
sudo systemctl enable tgt

6. Monitoring

# 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

# 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

# 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

# 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 ✅