# mhVTL Installation and Configuration Guide for Ubuntu 24.04

This document provides comprehensive instructions for installing, configuring, and managing mhVTL (Virtual Tape Library) on Ubuntu 24.04.

## Overview

mhVTL is a virtual tape library implementation that simulates tape drives and tape library hardware. It's useful for:
- Backup software testing and development
- Training environments
- iSCSI tape target implementations
- Storage system demonstrations

## Prerequisites

- Ubuntu 24.04 LTS
- Root or sudo access
- Internet connection for downloading packages and source code
- Kernel headers matching your running kernel
- Build tools (gcc, make)

## Installation Steps

### 1. Check Kernel Version

Verify your kernel version:

```bash
uname -r
```

Expected output: `6.8.0-90-generic` (or similar for Ubuntu 24.04)

### 2. Install Dependencies

Install required packages:

```bash
sudo apt update
sudo apt install -y build-essential linux-headers-$(uname -r) git \
    lsscsi mt-st mtx sg3-utils zlib1g-dev
```

Package descriptions:
- `build-essential`: GCC compiler and make
- `linux-headers`: Kernel headers for module compilation
- `git`: Version control for source code
- `lsscsi`: List SCSI devices utility
- `mt-st`: Magnetic tape control
- `mtx`: Media changer control
- `sg3-utils`: SCSI utilities
- `zlib1g-dev`: Compression library development files

### 3. Clone mhVTL Source Code

Download the mhVTL source:

```bash
cd /tmp
git clone https://github.com/markh794/mhvtl.git
cd mhvtl
```

### 4. Build mhVTL Kernel Module

Build the kernel module:

```bash
cd /tmp/mhvtl/kernel
make
sudo make install
```

This installs the mhvtl.ko kernel module to `/lib/modules/$(uname -r)/kernel/drivers/scsi/`

### 5. Build and Install User-Space Components

Build the user-space utilities and daemons:

```bash
cd /tmp/mhvtl
make
sudo make install
```

This process:
- Compiles vtltape (tape drive daemon)
- Compiles vtllibrary (tape library daemon)
- Installs utilities: vtlcmd, mktape, dump_tape, edit_tape
- Creates systemd service files
- Generates default configuration in `/etc/mhvtl/`
- Creates virtual tape media in `/opt/mhvtl/`

Build time: approximately 2-3 minutes

### 6. Load mhVTL Kernel Module

Load the kernel module:

```bash
sudo modprobe mhvtl
```

Verify module is loaded:

```bash
lsmod | grep mhvtl
```

Expected output:
```
mhvtl                  49152  0
```

### 7. Configure Automatic Module Loading

Create configuration to load mhVTL on boot:

```bash
sudo bash -c 'echo "mhvtl" >> /etc/modules-load.d/mhvtl.conf'
```

### 8. Reload Systemd and Start Services

```bash
sudo systemctl daemon-reload
sudo systemctl enable mhvtl.target
sudo systemctl start mhvtl.target
```

### 9. Verify Installation

Check service status:

```bash
sudo systemctl status mhvtl.target
```

Verify tape devices:

```bash
lsscsi
```

Expected output includes tape libraries and drives:
```
[3:0:0:0]    mediumx STK      L700             0107  /dev/sch0
[3:0:1:0]    tape    IBM      ULT3580-TD8      0107  /dev/st0
...
```

Check library status:

```bash
mtx -f /dev/sch0 status
```

Verify processes are running:

```bash
ps -ef | grep vtl | grep -v grep
```

## Configuration Files

### Main Configuration File

`/etc/mhvtl/device.conf` - Main device configuration

### Library Contents

- `/etc/mhvtl/library_contents.10` - Library 10 tape inventory
- `/etc/mhvtl/library_contents.30` - Library 30 tape inventory

### Virtual Tape Storage

`/opt/mhvtl/` - Directory containing virtual tape data files

### Systemd Service Files

- `/usr/lib/systemd/system/mhvtl.target` - Main target
- `/usr/lib/systemd/system/vtltape@.service` - Tape drive service template
- `/usr/lib/systemd/system/vtllibrary@.service` - Library service template
- `/usr/lib/systemd/system/mhvtl-load-modules.service` - Module loading service

## Managing mhVTL

### Changing Tape Drive Models

To change tape drive vendor and model, edit `/etc/mhvtl/device.conf`:

1. Stop mhVTL services:
```bash
sudo systemctl stop mhvtl.target
```

2. Backup configuration:
```bash
sudo cp /etc/mhvtl/device.conf /etc/mhvtl/device.conf.backup
```

3. Edit the drive configuration. Find the drive section (example):
```
Drive: 11 CHANNEL: 00 TARGET: 01 LUN: 00
 Library ID: 10 Slot: 01
 Vendor identification: IBM
 Product identification: ULT3580-TD8
 Unit serial number: XYZZY_A1
 NAA: 10:22:33:44:ab:00:01:00
 Compression: factor 1 enabled 1
 Compression type: lzo
 Backoff: 400
```

4. Change the vendor and product identification. Common LTO-8 options:

**IBM LTO-8:**
```
 Vendor identification: IBM
 Product identification: ULT3580-TD8
```

**Quantum LTO-8:**
```
 Vendor identification: QUANTUM
 Product identification: ULTRIUM-HH8
```

**HPE LTO-8:**
```
 Vendor identification: HP
 Product identification: Ultrium 8-SCSI
```

5. Using sed for bulk changes (all drives to Quantum LTO-8):
```bash
sudo sed -i 's/Vendor identification: IBM/Vendor identification: QUANTUM/g' /etc/mhvtl/device.conf
sudo sed -i 's/Product identification: ULT3580-TD8/Product identification: ULTRIUM-HH8/g' /etc/mhvtl/device.conf
```

6. Restart services:
```bash
sudo systemctl start mhvtl.target
```

7. Verify changes:
```bash
lsscsi | grep tape
```

### Available Tape Drive Models

mhVTL supports these tape drive types:

**LTO Drives:**
- `ULTRIUM-TD1` / `ULTRIUM-HH1` - LTO-1
- `ULTRIUM-TD2` / `ULTRIUM-HH2` - LTO-2
- `ULTRIUM-TD3` / `ULTRIUM-HH3` - LTO-3
- `ULTRIUM-TD4` / `ULTRIUM-HH4` - LTO-4
- `ULTRIUM-TD5` / `ULTRIUM-HH5` - LTO-5
- `ULTRIUM-TD6` / `ULTRIUM-HH6` - LTO-6
- `ULTRIUM-TD7` / `ULTRIUM-HH7` - LTO-7
- `ULTRIUM-TD8` / `ULTRIUM-HH8` - LTO-8

**Other Drives:**
- `T10000A`, `T10000B`, `T10000C`, `T10000D` - STK/Oracle T10000 series
- `SDLT320`, `SDLT600` - SDLT drives
- `AIT1`, `AIT2`, `AIT3`, `AIT4` - AIT drives

Note: TD = Tabletop Drive, HH = Half-Height

### Changing Tape Library Models

To change library vendor and model:

1. Stop services:
```bash
sudo systemctl stop mhvtl.target
```

2. Backup configuration:
```bash
sudo cp /etc/mhvtl/device.conf /etc/mhvtl/device.conf.backup
```

3. Edit library section in `/etc/mhvtl/device.conf`:
```
Library: 10 CHANNEL: 00 TARGET: 00 LUN: 00
 Vendor identification: STK
 Product identification: L700
 Unit serial number: XYZZY_A
 NAA: 10:22:33:44:ab:00:00:00
 Home directory: /opt/mhvtl
 PERSIST: False
 Backoff: 400
```

4. Common library configurations:

**Quantum Scalar i500:**
```
 Vendor identification: QUANTUM
 Product identification: Scalar i500
```

**Quantum Scalar i40:**
```
 Vendor identification: QUANTUM
 Product identification: Scalar i40
```

**IBM TS3500:**
```
 Vendor identification: IBM
 Product identification: 03584L32
```

**STK L700:**
```
 Vendor identification: STK
 Product identification: L700
```

5. Using sed to change libraries:
```bash
# Change Library 10 to Quantum Scalar i500
sudo sed -i '/^Library: 10/,/^$/{s/Vendor identification: STK/Vendor identification: QUANTUM/}' /etc/mhvtl/device.conf
sudo sed -i '/^Library: 10/,/^$/{s/Product identification: L700/Product identification: Scalar i500/}' /etc/mhvtl/device.conf
```

6. Restart services:
```bash
sudo systemctl start mhvtl.target
```

7. Verify:
```bash
lsscsi | grep mediumx
```

### Adding a New Tape Drive

To add a new tape drive to an existing library:

1. Stop services:
```bash
sudo systemctl stop mhvtl.target
```

2. Edit `/etc/mhvtl/device.conf` and add a new drive section:
```
Drive: 15 CHANNEL: 00 TARGET: 05 LUN: 00
 Library ID: 10 Slot: 05
 Vendor identification: QUANTUM
 Product identification: ULTRIUM-HH8
 Unit serial number: XYZZY_A5
 NAA: 10:22:33:44:ab:00:05:00
 Compression: factor 1 enabled 1
 Compression type: lzo
 Backoff: 400
```

Important fields:
- `Drive:` - Unique drive number (must be unique)
- `TARGET:` - SCSI target ID (must be unique)
- `Library ID:` - Must match an existing library number (10 or 30)
- `Slot:` - Physical slot in library (must be unique in that library)
- `Unit serial number:` - Unique serial number
- `NAA:` - Unique NAA identifier

3. Restart services:
```bash
sudo systemctl daemon-reload
sudo systemctl start mhvtl.target
```

4. Verify:
```bash
lsscsi | grep tape
```

### Deleting a Tape Drive

To remove a tape drive:

1. Stop services:
```bash
sudo systemctl stop mhvtl.target
```

2. Edit `/etc/mhvtl/device.conf` and remove the entire drive section (from `Drive: XX` to the blank line)

3. Restart services:
```bash
sudo systemctl start mhvtl.target
```

### Adding a New Tape Library

To add a completely new tape library:

1. Stop services:
```bash
sudo systemctl stop mhvtl.target
```

2. Edit `/etc/mhvtl/device.conf` and add a new library section:
```
Library: 40 CHANNEL: 00 TARGET: 16 LUN: 00
 Vendor identification: QUANTUM
 Product identification: Scalar i40
 Unit serial number: XYZZY_C
 NAA: 40:22:33:44:ab:00:16:00
 Home directory: /opt/mhvtl
 PERSIST: False
 Backoff: 400
```

Important fields:
- `Library:` - Unique library number (e.g., 40)
- `TARGET:` - SCSI target ID (must be unique)
- `Unit serial number:` - Unique serial number
- `NAA:` - Unique NAA identifier

3. Add drives for this library (change `Library ID: 40`):
```
Drive: 41 CHANNEL: 00 TARGET: 17 LUN: 00
 Library ID: 40 Slot: 01
 Vendor identification: QUANTUM
 Product identification: ULTRIUM-HH8
 Unit serial number: XYZZY_C1
 NAA: 40:22:33:44:ab:00:17:00
 Compression: factor 1 enabled 1
 Compression type: lzo
 Backoff: 400
```

4. Create library contents file:
```bash
sudo cp /etc/mhvtl/library_contents.10 /etc/mhvtl/library_contents.40
```

5. Edit `/etc/mhvtl/library_contents.40` to match your library configuration

6. Create media for the new library:
```bash
sudo /usr/bin/make_vtl_media --config-dir=/etc/mhvtl --home-dir=/opt/mhvtl
```

7. Restart services:
```bash
sudo systemctl daemon-reload
sudo systemctl start mhvtl.target
```

8. Verify:
```bash
lsscsi
mtx -f /dev/sch2 status
```

### Deleting a Tape Library

To remove a tape library:

1. Stop services:
```bash
sudo systemctl stop mhvtl.target
```

2. Edit `/etc/mhvtl/device.conf`:
   - Remove the library section (from `Library: XX` to blank line)
   - Remove all associated drive sections (where `Library ID: XX` matches)

3. Remove library contents file:
```bash
sudo rm /etc/mhvtl/library_contents.XX
```

4. Optionally remove media files:
```bash
# Be careful - this deletes all virtual tapes
sudo rm -rf /opt/mhvtl/
```

5. Restart services:
```bash
sudo systemctl daemon-reload
sudo systemctl start mhvtl.target
```

## Creating Virtual Tape Media

To create additional virtual tape media:

```bash
# Create a single LTO-8 tape
sudo mktape -m /opt/mhvtl/TAPE001L8 -s 12000000 -t LTO8 -d 12345678

# Create media using make_vtl_media
sudo /usr/bin/make_vtl_media --config-dir=/etc/mhvtl --home-dir=/opt/mhvtl
```

Media parameters:
- `-m` - Path to media file
- `-s` - Size in kilobytes (12000000 = ~12GB)
- `-t` - Tape type (LTO1-LTO8, etc.)
- `-d` - Density code

## Managing Services

### Start/Stop Services

```bash
# Stop all mhVTL services
sudo systemctl stop mhvtl.target

# Start all mhVTL services
sudo systemctl start mhvtl.target

# Restart all services
sudo systemctl restart mhvtl.target

# Check status
sudo systemctl status mhvtl.target
```

### Individual Drive/Library Control

```bash
# Stop specific tape drive (drive 11)
sudo systemctl stop vtltape@11

# Start specific tape drive
sudo systemctl start vtltape@11

# Stop specific library (library 10)
sudo systemctl stop vtllibrary@10

# Start specific library
sudo systemctl start vtllibrary@10
```

## Troubleshooting

### Kernel Module Not Loading

Check kernel logs:
```bash
sudo dmesg | grep mhvtl
```

Verify module exists:
```bash
ls -l /lib/modules/$(uname -r)/kernel/drivers/scsi/mhvtl.ko
```

Try manual load with verbose output:
```bash
sudo modprobe -v mhvtl
```

### Services Not Starting

Check service logs:
```bash
sudo journalctl -u vtltape@11 -n 50
sudo journalctl -u vtllibrary@10 -n 50
```

Verify configuration file syntax:
```bash
sudo /usr/bin/vtltape -f /etc/mhvtl/device.conf -q 11 -v 9
```

### Devices Not Appearing

Rescan SCSI bus:
```bash
sudo rescan-scsi-bus.sh
```

Or:
```bash
echo "- - -" | sudo tee /sys/class/scsi_host/host*/scan
```

### Permission Issues

Ensure correct permissions:
```bash
sudo chown -R root:root /etc/mhvtl
sudo chmod 755 /etc/mhvtl
sudo chmod 644 /etc/mhvtl/*

sudo chown -R root:root /opt/mhvtl
sudo chmod 755 /opt/mhvtl
```

### Rebuilding After Kernel Update

After a kernel update, rebuild the kernel module:

```bash
cd /tmp/mhvtl/kernel
make clean
make
sudo make install
sudo modprobe -r mhvtl
sudo modprobe mhvtl
sudo systemctl restart mhvtl.target
```

## Useful Commands

### View Tape Library Status

```bash
# List all libraries
lsscsi | grep mediumx

# Show library inventory
mtx -f /dev/sch0 status

# List tape drives
lsscsi | grep tape
```

### Tape Operations

```bash
# Rewind tape
mt -f /dev/st0 rewind

# Get tape status
mt -f /dev/st0 status

# Eject tape
mt -f /dev/st0 eject
```

### Library Operations

```bash
# Load tape from slot 1 to drive 0
mtx -f /dev/sch0 load 1 0

# Unload tape from drive 0 to slot 1
mtx -f /dev/sch0 unload 1 0

# Transfer tape from slot 1 to slot 2
mtx -f /dev/sch0 transfer 1 2
```

### Check mhVTL Processes

```bash
ps -ef | grep vtl | grep -v grep
```

### View Configuration

```bash
# Show device configuration
cat /etc/mhvtl/device.conf

# Show library contents
cat /etc/mhvtl/library_contents.10
```

## Uninstallation

To completely remove mhVTL:

```bash
# Stop services
sudo systemctl stop mhvtl.target
sudo systemctl disable mhvtl.target

# Remove kernel module
sudo modprobe -r mhvtl
sudo rm /lib/modules/$(uname -r)/kernel/drivers/scsi/mhvtl.ko
sudo depmod -a

# Remove binaries
sudo rm /usr/bin/vtltape
sudo rm /usr/bin/vtllibrary
sudo rm /usr/bin/vtlcmd
sudo rm /usr/bin/mktape
sudo rm /usr/bin/dump_tape
sudo rm /usr/bin/edit_tape
sudo rm /usr/bin/preload_tape
sudo rm /usr/lib/libvtlscsi.so
sudo rm /usr/lib/libvtlcart.so

# Remove systemd files
sudo rm /usr/lib/systemd/system/vtltape@.service
sudo rm /usr/lib/systemd/system/vtllibrary@.service
sudo rm /usr/lib/systemd/system/mhvtl.target
sudo rm /usr/lib/systemd/system/mhvtl-load-modules.service
sudo rm /usr/lib/systemd/system-generators/mhvtl-device-conf-generator
sudo systemctl daemon-reload

# Remove configuration and data
sudo rm -rf /etc/mhvtl
sudo rm -rf /opt/mhvtl

# Remove module load configuration
sudo rm /etc/modules-load.d/mhvtl.conf
```

## References

- mhVTL Project: https://github.com/markh794/mhvtl
- Documentation: https://sites.google.com/site/mhvtl/
- SCSI Commands Reference: http://www.t10.org/

## Version Information

- Document Version: 1.0
- mhVTL Version: Latest from GitHub (as of installation date)
- Ubuntu Version: 24.04 LTS (Noble Numbat)
- Kernel Version: 6.8.0-90-generic
- Last Updated: 2025-12-24
