othman.suseno/vtl-appliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Major VTL System Upgrade (Auth, Monitoring, CLI, Installer)

Browse Source 
- 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:
othman hendy suseno
2025-12-09 18:15:36 +00:00
parent 8a0523a265
commit 01080498af
53 changed files with 13399 additions and 425 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
docs/LIBRARY_FIX_REPORT.md Normal file
View File

@@ -0,0 +1,283 @@
# 🔍 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)