# 🔍 MHVTL Library Detection Issue - Root Cause Analysis & Fix

## 📋 Problem Summary

**Issue:** Library (changer/robot) tidak terdeteksi di `lsscsi -g`, hanya tape drives yang muncul.

**Symptom:**
```bash
$ lsscsi -g
[0:0:0:0]    disk    QEMU     QEMU HARDDISK    2.5+  /dev/sda   /dev/sg0 
[2:0:0:0]    cd/dvd  QEMU     QEMU DVD-ROM     2.5+  /dev/sr0   /dev/sg1 
[3:0:1:0]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg2 
[3:0:2:0]    tape    HP       Ultrium 6-SCSI   0107  -          /dev/sg3 
[3:0:3:0]    tape    HP       Ultrium 6-SCSI   0107  -          /dev/sg4 
[3:0:4:0]    tape    HP       Ultrium 6-SCSI   0107  -          /dev/sg5
```

**Missing:** `mediumx` device (library/changer) yang seharusnya ada di `/dev/sg6`

---

## 🔎 Root Cause Analysis

### 1. **vtllibrary Process Tidak Berjalan**

Meskipun script `start-mhvtl.sh` mencoba menjalankan vtllibrary, processnya gagal start:

```bash
$ ps aux | grep vtllibrary
# No output - process not running!
```

Log menunjukkan:
```
Starting vtllibrary for library 10...
mhvtl started: 4 drives, 0 libraries  # <-- 0 libraries!
```

### 2. **Masalah #1: Drive ID Tidak Sesuai Konvensi MHVTL**

**Konfigurasi Awal (SALAH):**

`/etc/mhvtl/device.conf`:
```
Library: 10 CHANNEL: 00 TARGET: 00 LUN: 00
Drive: 00 CHANNEL: 00 TARGET: 01 LUN: 00  # ❌ SALAH!
Drive: 01 CHANNEL: 00 TARGET: 02 LUN: 00  # ❌ SALAH!
Drive: 02 CHANNEL: 00 TARGET: 03 LUN: 00  # ❌ SALAH!
Drive: 03 CHANNEL: 00 TARGET: 04 LUN: 00  # ❌ SALAH!
```

`/etc/mhvtl/library_contents.10`:
```
Drive 1: 1  # Mapping drive slot 1 ke drive ID 1
Drive 2: 2  # Tapi drive ID 1,2,3,4 tidak ada di device.conf!
Drive 3: 3
Drive 4: 4
```

**Konvensi MHVTL:**
- Drive ID harus mengikuti format: **Library_ID + Slot_Number**
- Untuk Library 10:
  - Slot 1 → Drive ID **11** (10 + 1)
  - Slot 2 → Drive ID **12** (10 + 2)
  - Slot 3 → Drive ID **13** (10 + 3)
  - Slot 4 → Drive ID **14** (10 + 4)

**Error yang Terjadi:**
```bash
$ /usr/bin/vtllibrary 10
error: Can not find entry for '0' in config file
```

vtllibrary mencari drive dengan ID yang dimapping di `library_contents.10`, tapi tidak menemukan drive dengan ID tersebut di `device.conf`.

### 3. **Masalah #2: Syntax Error di start-mhvtl.sh**

**Kode Awal (SALAH):**
```bash
/usr/bin/vtllibrary $library > /dev/null 2>&1 &
```

**Seharusnya:**
```bash
/usr/bin/vtllibrary -q $library > /dev/null 2>&1 &
```

vtllibrary memerlukan parameter `-q` untuk queue number:
```
Usage: /usr/bin/vtllibrary [OPTIONS] -q <Q-number>
```

---

## ✅ Solutions Applied

### Fix #1: Update Drive IDs di device.conf

**File:** `/etc/mhvtl/device.conf`

**Changes:**
```diff
 Library: 10 CHANNEL: 00 TARGET: 00 LUN: 00
-Drive: 00 CHANNEL: 00 TARGET: 01 LUN: 00
-Drive: 01 CHANNEL: 00 TARGET: 02 LUN: 00
-Drive: 02 CHANNEL: 00 TARGET: 03 LUN: 00
-Drive: 03 CHANNEL: 00 TARGET: 04 LUN: 00
+Drive: 11 CHANNEL: 00 TARGET: 01 LUN: 00
+Drive: 12 CHANNEL: 00 TARGET: 02 LUN: 00
+Drive: 13 CHANNEL: 00 TARGET: 03 LUN: 00
+Drive: 14 CHANNEL: 00 TARGET: 04 LUN: 00
```

### Fix #2: Update Drive Mapping di library_contents.10

**File:** `/etc/mhvtl/library_contents.10`

**Changes:**
```diff
 VERSION: 2

-Drive 1: 1
-Drive 2: 2
-Drive 3: 3
-Drive 4: 4
+Drive 1: 11
+Drive 2: 12
+Drive 3: 13
+Drive 4: 14

 Picker 1:
```

### Fix #3: Update start-mhvtl.sh Script

**File:** `/builder/adastra-vtl/scripts/start-mhvtl.sh`

**Changes:**
```diff
 for library in $LIBRARY_NUMS; do
     if ! pgrep -f "vtllibrary.*$library" > /dev/null; then
         echo "Starting vtllibrary for library $library..."
-        /usr/bin/vtllibrary $library > /dev/null 2>&1 &
+        /usr/bin/vtllibrary -q $library > /dev/null 2>&1 &
     else
         echo "vtllibrary for library $library is already running"
     fi
 done
```

---

## 🎯 Verification

### After Fix:

```bash
$ lsscsi -g
[0:0:0:0]    disk    QEMU     QEMU HARDDISK    2.5+  /dev/sda   /dev/sg0 
[2:0:0:0]    cd/dvd  QEMU     QEMU DVD-ROM     2.5+  /dev/sr0   /dev/sg1 
[3:0:0:0]    mediumx ADASTRA  HEPHAESTUS-V     0107  -          /dev/sg6  ✅ LIBRARY DETECTED!
[3:0:1:0]    tape    IBM      ULT3580-TD8      0107  -          /dev/sg2 
[3:0:2:0]    tape    HP       Ultrium 6-SCSI   0107  -          /dev/sg3 
[3:0:3:0]    tape    HP       Ultrium 6-SCSI   0107  -          /dev/sg4 
[3:0:4:0]    tape    HP       Ultrium 6-SCSI   0107  -          /dev/sg5
```

```bash
$ ps aux | grep -E "(vtltape|vtllibrary)" | grep -v grep
root   65804  0.0  0.0  5368  3888 ?  Ss  17:10  0:00 /usr/bin/vtltape -q 11
root   65808  0.0  0.0  5368  3760 ?  Ss  17:10  0:00 /usr/bin/vtltape -q 12
root   65812  0.0  0.0  5368  3760 ?  Ss  17:10  0:00 /usr/bin/vtltape -q 13
root   65816  0.0  0.0  5368  3888 ?  Ss  17:10  0:00 /usr/bin/vtltape -q 14
root   66102  0.0  0.0  3932  2776 ?  Ss  17:11  0:00 /usr/bin/vtllibrary -q 10  ✅
```

```bash
$ /proc/scsi/scsi
Attached devices:
Host: scsi0 Channel: 00 Id: 00 Lun: 00
  Vendor: QEMU     Model: QEMU HARDDISK    Rev: 2.5+
  Type:   Direct-Access                    ANSI  SCSI revision: 05
Host: scsi2 Channel: 00 Id: 00 Lun: 00
  Vendor: QEMU     Model: QEMU DVD-ROM     Rev: 2.5+
  Type:   CD-ROM                           ANSI  SCSI revision: 05
Host: scsi3 Channel: 00 Id: 00 Lun: 00
  Vendor: ADASTRA  Model: HEPHAESTUS-V     Rev: 0107
  Type:   Medium Changer                   ANSI  SCSI revision: 05  ✅
Host: scsi3 Channel: 00 Id: 01 Lun: 00
  Vendor: IBM      Model: ULT3580-TD8      Rev: 0107
  Type:   Sequential-Access                ANSI  SCSI revision: 05
Host: scsi3 Channel: 00 Id: 02 Lun: 00
  Vendor: HP       Model: Ultrium 6-SCSI   Rev: 0107
  Type:   Sequential-Access                ANSI  SCSI revision: 05
Host: scsi3 Channel: 00 Id: 03 Lun: 00
  Vendor: HP       Model: Ultrium 6-SCSI   Rev: 0107
  Type:   Sequential-Access                ANSI  SCSI revision: 05
Host: scsi3 Channel: 00 Id: 04 Lun: 00
  Vendor: HP       Model: Ultrium 6-SCSI   Rev: 0107
  Type:   Sequential-Access                ANSI  SCSI revision: 05
```

---

## 📝 Key Learnings

### MHVTL Drive ID Convention

**Rule:** Drive ID = Library ID (tens digit) + Slot Number (ones digit)

**Examples:**

| Library ID | Slot | Drive ID | Format |
|------------|------|----------|--------|
| 10 | 1 | **11** | 10 + 1 |
| 10 | 2 | **12** | 10 + 2 |
| 10 | 3 | **13** | 10 + 3 |
| 10 | 4 | **14** | 10 + 4 |
| 30 | 1 | **31** | 30 + 1 |
| 30 | 2 | **32** | 30 + 2 |

### vtllibrary Command Syntax

**Correct:**
```bash
/usr/bin/vtllibrary -q <library_id>
```

**Wrong:**
```bash
/usr/bin/vtllibrary <library_id>  # Missing -q parameter!
```

### Configuration File Relationship

```
device.conf          library_contents.10
─────────────        ───────────────────
Library: 10     ←──→ VERSION: 2
Drive: 11       ←──→ Drive 1: 11
Drive: 12       ←──→ Drive 2: 12
Drive: 13       ←──→ Drive 3: 13
Drive: 14       ←──→ Drive 4: 14
```

Both files must reference the **same drive IDs** for vtllibrary to work correctly.

---

## 🚀 Quick Fix Script

A script has been created to automatically fix this issue:

**Location:** `/builder/adastra-vtl/scripts/fix-mhvtl-config.sh`

**Usage:**
```bash
sudo bash /builder/adastra-vtl/scripts/fix-mhvtl-config.sh
```

This script will:
1. Stop mhvtl service
2. Backup current configuration
3. Update drive IDs in device.conf (00→11, 01→12, 02→13, 03→14)
4. Update drive mappings in library_contents.10
5. Restart mhvtl service
6. Verify library is detected

---

## 📚 References

- [MHVTL Documentation](https://github.com/markh794/mhvtl)
- MHVTL iSCSI Binding Guide: `/builder/adastra-vtl/MHVTL_ISCSI_BINDING_GUIDE.md`
- Device Configuration: `/etc/mhvtl/device.conf`
- Library Contents: `/etc/mhvtl/library_contents.10`

---

**Status:** ✅ **RESOLVED**  
**Date:** December 9, 2025  
**Tested On:** Ubuntu 24.04.3 LTS, Kernel 6.8.0-88  
**MHVTL Version:** 1.7.2 (commit: 8ef9703)