vtl-appliance/docs/AUTO_START_CONFIGURATION.md

# 🚀 VTL Auto-Start Configuration

## 📋 Overview

All critical VTL system components are now configured to **automatically start on boot**, ensuring the system is fully operational after every restart.

---

## ✅ Auto-Start Services

### 1. **MHVTL Service** ✅ ENABLED

**Service:** `mhvtl.service`  
**Status:** Enabled (auto-start on boot)  
**Description:** Virtual Tape Library core service

**What it does:**
- Loads mhvtl kernel module
- Starts vtltape processes for each drive
- Starts vtllibrary process for the changer/robot
- Creates SCSI devices (/dev/sg*)

**Verify:**
```bash
systemctl is-enabled mhvtl
# Output: enabled

systemctl status mhvtl
# Should show: Active: active (running)
```

---

### 2. **Apache Web Server** ✅ ENABLED

**Service:** `apache2.service`  
**Status:** Enabled (auto-start on boot)  
**Description:** Web server for MHVTL Web UI

**What it does:**
- Serves Web UI at `http://localhost/mhvtl-config/`
- Provides REST API for configuration management
- Enables remote management of VTL

**Verify:**
```bash
systemctl is-enabled apache2
# Output: enabled

systemctl status apache2
# Should show: Active: active (running)

# Check web UI access
curl -I http://localhost/mhvtl-config/
# Should return: HTTP/1.1 200 OK
```

---

### 3. **TGT iSCSI Target** ✅ ENABLED

**Service:** `tgt.service`  
**Status:** Enabled (auto-start on boot)  
**Description:** iSCSI target service for network access

**What it does:**
- Provides iSCSI target functionality
- Allows remote clients to access VTL over network
- Manages iSCSI targets, LUNs, and ACLs

**Verify:**
```bash
systemctl is-enabled tgt
# Output: enabled

systemctl status tgt
# Should show: Active: active (running)

# List iSCSI targets
tgtadm --lld iscsi --mode target --op show
```

---

## 🔄 Boot Sequence

### What Happens on System Boot:

1. **Kernel Module Loading**
   - `mhvtl` kernel module is loaded
   - Creates SCSI host adapter

2. **MHVTL Service Start** (via systemd)
   - Executes `/opt/adastra-vtl/scripts/start-mhvtl.sh`
   - Starts vtltape processes (drives 11, 12, 13, 14)
   - Starts vtllibrary process (library 10)
   - Creates SCSI devices

3. **Apache Web Server Start**
   - Starts Apache HTTP server
   - Web UI becomes accessible

4. **TGT iSCSI Service Start**
   - Starts iSCSI target daemon
   - Loads saved target configurations (if any)

---

## 📊 Verification Script

A comprehensive verification script has been created to check all components:

**Location:** `/builder/adastra-vtl/scripts/verify-vtl-startup.sh`

**Usage:**
```bash
sudo /builder/adastra-vtl/scripts/verify-vtl-startup.sh
```

**What it checks:**

### 1. Service Status
- ✅ MHVTL service running
- ✅ Apache web server running
- ✅ TGT iSCSI service running

### 2. Auto-Start Configuration
- ✅ MHVTL enabled for boot
- ✅ Apache enabled for boot
- ✅ TGT enabled for boot

### 3. MHVTL Components
- ✅ vtltape processes (4 drives)
- ✅ vtllibrary process (1 library)

### 4. SCSI Devices
- ✅ Library/changer detected
- ✅ Tape drives detected (4 drives)

### 5. Web UI Access
- ✅ Web UI files installed
- ✅ Web server listening on port 80

### 6. iSCSI Targets
- ℹ️  Lists configured targets (if any)

### 7. Configuration Files
- ✅ device.conf present
- ✅ library_contents.* present

**Output Example:**
```
==========================================
VTL System Startup Verification
==========================================

1. Service Status Check
✅ MHVTL (Virtual Tape Library) - Running
✅ Apache Web Server (Web UI) - Running
✅ TGT (iSCSI Target) - Running

2. Auto-Start Configuration
✅ MHVTL Service - Enabled (auto-start on boot)
✅ Apache Web Server - Enabled (auto-start on boot)
✅ TGT iSCSI Target - Enabled (auto-start on boot)

...

Summary
Status: 10/10 checks passed

✅ ALL SYSTEMS OPERATIONAL

VTL system is fully functional and will auto-start on boot!
```

---

## 🛠️ Manual Service Management

### Start Services
```bash
sudo systemctl start mhvtl
sudo systemctl start apache2
sudo systemctl start tgt
```

### Stop Services
```bash
sudo systemctl stop mhvtl
sudo systemctl stop apache2
sudo systemctl stop tgt
```

### Restart Services
```bash
sudo systemctl restart mhvtl
sudo systemctl restart apache2
sudo systemctl restart tgt
```

### Check Status
```bash
sudo systemctl status mhvtl
sudo systemctl status apache2
sudo systemctl status tgt
```

### Enable Auto-Start (Already Done)
```bash
sudo systemctl enable mhvtl
sudo systemctl enable apache2
sudo systemctl enable tgt
```

### Disable Auto-Start (If Needed)
```bash
sudo systemctl disable mhvtl
sudo systemctl disable apache2
sudo systemctl disable tgt
```

---

## 📁 Service Files

### MHVTL Service
**File:** `/etc/systemd/system/mhvtl.service`

```ini
[Unit]
Description=mhvtl Virtual Tape Library
Documentation=man:vtltape(1) man:vtllibrary(1)
After=network.target

[Service]
Type=forking
ExecStart=/opt/adastra-vtl/scripts/start-mhvtl.sh
ExecStop=/opt/adastra-vtl/scripts/stop-mhvtl.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

### Apache Service
**File:** `/lib/systemd/system/apache2.service` (system default)

### TGT Service
**File:** `/lib/systemd/system/tgt.service` (system default)

---

## 🔍 Troubleshooting

### MHVTL Not Starting on Boot

**Check:**
```bash
# Verify service is enabled
systemctl is-enabled mhvtl

# Check service status
systemctl status mhvtl

# Check logs
journalctl -u mhvtl -n 50
```

**Fix:**
```bash
# Enable service
sudo systemctl enable mhvtl

# Start service
sudo systemctl start mhvtl
```

### Web UI Not Accessible

**Check:**
```bash
# Verify Apache is running
systemctl status apache2

# Check if port 80 is listening
sudo netstat -tuln | grep :80
# or
sudo ss -tuln | grep :80

# Check web UI files
ls -la /var/www/html/mhvtl-config/
```

**Fix:**
```bash
# Start Apache
sudo systemctl start apache2

# Enable Apache
sudo systemctl enable apache2
```

### Devices Not Appearing

**Check:**
```bash
# Check if kernel module is loaded
lsmod | grep mhvtl

# Check SCSI devices
lsscsi -g

# Check processes
ps aux | grep vtl
```

**Fix:**
```bash
# Reload kernel module
sudo rmmod mhvtl
sudo modprobe mhvtl

# Restart mhvtl service
sudo systemctl restart mhvtl
```

---

## 🎯 Post-Reboot Checklist

After every reboot, the system should automatically:

1. ✅ Load mhvtl kernel module
2. ✅ Start MHVTL service
3. ✅ Create 4 tape drives + 1 library
4. ✅ Start Apache web server
5. ✅ Make Web UI accessible
6. ✅ Start TGT iSCSI service
7. ✅ Load iSCSI target configurations

**Quick Verification:**
```bash
# Run verification script
sudo /builder/adastra-vtl/scripts/verify-vtl-startup.sh

# Or manual check
lsscsi -g
systemctl status mhvtl apache2 tgt
```

---

## 📚 Related Scripts

1. **`verify-vtl-startup.sh`** - Comprehensive system verification
2. **`start-mhvtl.sh`** - MHVTL startup script (called by systemd)
3. **`stop-mhvtl.sh`** - MHVTL shutdown script (called by systemd)
4. **`clean-reboot-mhvtl.sh`** - Clean reboot with verification
5. **`fix-mhvtl-config.sh`** - Fix drive ID configuration

---

## ✅ Summary

### Current Status:

| Component | Auto-Start | Status |
|-----------|-----------|--------|
| MHVTL Service | ✅ Enabled | Will start on boot |
| Apache Web Server | ✅ Enabled | Will start on boot |
| TGT iSCSI Target | ✅ Enabled | Will start on boot |
| Web UI | ✅ Ready | Accessible after boot |
| Kernel Module | ✅ Auto-load | Loaded on boot |

### What This Means:

🎉 **System is fully configured for automatic operation!**

After every reboot:
- VTL will be fully operational
- Web UI will be accessible
- iSCSI targets will be available
- No manual intervention required

---

**Status:** ✅ **FULLY CONFIGURED**  
**Date:** December 9, 2025  
**Tested On:** Ubuntu 24.04.3 LTS  
**Auto-Start:** All services enabled