# AtlasOS – Calypso  
## SCST + MHVTL Integration Blueprint  
### (Single Source – Engineering Grade)

Version: 1.0  
Status: Baseline Blueprint  
Target OS: Ubuntu Server 24.04 LTS  
Scope: Virtual Tape Library (MHVTL) + Physical Tape Bridging via SCST iSCSI  
Date: 2025

---

## 1. Purpose

Dokumen ini mendefinisikan **blueprint integrasi resmi** antara:

- **MHVTL** sebagai Virtual Tape Library provider  
- **SCST** sebagai satu-satunya iSCSI target framework  
- **AtlasOS – Calypso** sebagai orchestration & control plane  

Blueprint ini berlaku untuk:
- Virtual Tape Library (VTL)
- Bridging physical tape library (SAS / FC)
- iSCSI presentation ke **backup software apa pun** (vendor-agnostic)

Dokumen ini bersifat **authoritative** untuk implementasi.

---

## 2. Fundamental Design Principles

### 2.1 Ownership Model
- **MHVTL** → producer perangkat SCSI virtual  
- **Physical tape library** → producer perangkat SCSI fisik  
- **SCST** → exporter perangkat ke iSCSI  
- **Backup software** → iSCSI initiator (consumer)

Tidak boleh ada dua framework yang mengelola device yang sama.

---

### 2.2 Mandatory Rules

1. SCST adalah **satu-satunya iSCSI target framework**
2. Semua tape (physical & virtual) wajib diexport via SCST
3. Mapping tape device:
   - LUN 0 → Medium Changer
   - LUN 1..N → Tape Drives (maks 8)
4. Tape target **single-initiator only**
5. Tidak ada backup-software-specific logic di core
6. Semua operasi destructive / privileged:
   - async
   - auditable
   - guarded

---

## 3. High-Level Integration Architecture

### 3.1 Data Plane

Backup Software
|
iSCSI
|
SCST
|
+------------------+
| Backend Device |
+------------------+
| |
MHVTL Physical Tape
|
Disk Backing Store


### 3.2 Control Plane
- Calypso API mengontrol:
  - lifecycle MHVTL
  - SCST config generation & apply
  - device discovery
  - state & policy enforcement
- UI hanya berbicara ke API
- Tidak ada direct shell access

---

## 4. Device Model

### 4.1 Virtual Tape Library (MHVTL)
MHVTL menyediakan:
- Medium changer device
- Tape drive devices
- Slot & barcode emulation
- Tape image files (disk-backed)

Device yang dihasilkan:
- `/dev/sgX` (generic SCSI)
- `/dev/stX` / `/dev/nstX` (tape)
- `/dev/schX` (changer)

---

### 4.2 Physical Tape Library
Physical library menyediakan:
- Medium changer (SAS / FC)
- Tape drives (LTO-8)
- Slots & barcodes

Device yang dihasilkan:
- `/dev/sgX`
- `/dev/stX` / `/dev/nstX`
- `/dev/schX`

---

## 5. Stable Device Naming (Critical)

### Problem
Nama `/dev/sg*`, `/dev/st*`, `/dev/sch*` **tidak stabil** antar reboot.

### Blueprint Solution
1. Discover device via:
   - `lsscsi -g`
   - `sg_inq`
2. Ambil:
   - vendor
   - model
   - serial
   - device type
3. Generate udev rules → symlink stabil

### Recommended Symlink Layout

/dev/calypso/
vtl/
<library_name>/
changer
drive1
drive2
physical/
<library_serial>/
changer
drive1
drive2


SCST **hanya** boleh mereferensikan path stabil ini.

---

## 6. SCST Backend Strategy

### 6.1 Handler Selection
Karena variasi build SCST, Calypso wajib melakukan **capability detection**.

Supported modes:
- Native tape handler (jika tersedia)
- Generic SCSI passthrough (`sg` based)

### 6.2 Recommended Default
- **Changer** → SCSI generic passthrough
- **Drive** → tape char device (`nst`) atau sg fallback

Handler mode dipilih **per target**, disimpan di DB.

---

## 7. iSCSI Target Model

### 7.1 Target Naming


iqn.<year>.atlasos.calypso:vtl.<name>
iqn.<year>.atlasos.calypso:tape.physical.<name>



### 7.2 LUN Mapping (Mandatory)
| LUN | Device |
|----|-------|
| 0  | Medium Changer |
| 1  | Tape Drive 1 |
| 2  | Tape Drive 2 |
| …  | … (max 8) |

### 7.3 ACL Policy
- Allow only explicit initiator IQN
- Tape targets: **single initiator enforced**

---

## 8. Workflow: Create & Export VTL

### Step 1 — Prepare Backing Store
- Allocate disk path for tape images:


/var/lib/calypso/vtl/<lib>/tapes


### Step 2 — Create MHVTL Library
Calypso invokes MHVTL tools to:
- create changer
- create drives (1–8)
- define slots
- enable barcode

Result:
- Device nodes appear
- MHVTL config persisted

---

### Step 3 — Device Discovery
- Run `lsscsi -g`
- Match new devices
- Persist mapping in DB
- Generate udev rules

---

### Step 4 — Generate SCST Config
- Define target IQN
- Define LUN mappings
- Define ACL

Config generated to:

/etc/calypso/scst/generated.conf


---

### Step 5 — Apply SCST (Safe Mode)
1. Validate config
2. Apply via `scstadmin`
3. Verify target visibility
4. On failure → rollback to last-known-good

---

### Step 6 — Initiator Validation
Calypso provides validation profile:
- Linux initiator test
- Windows initiator hints
- Confirm:
  - changer visible
  - drives visible
  - basic SCSI ops OK

---

## 9. Guardrails & Safety Rules

### Hard Blocks
- No SCST apply while:
  - drive busy
  - tape loaded & writing
- No delete library with:
  - active initiator
  - loaded tape

### Soft Alerts
- Multiple initiators → CRITICAL alert
- Backing store nearly full → WARNING / CRITICAL

---

## 10. Observability Requirements

Calypso must monitor:
- SCST target state
- iSCSI sessions
- MHVTL status:
  - drives count
  - slots usage
  - error logs
- Disk usage (tape images)

Events pushed via WebSocket to UI.

---

## 11. Persisted State

### PostgreSQL
- vtl_libraries
- vtl_drives
- vtl_tapes
- iscsi_targets
- lun_mappings
- tasks
- audit_log
- alerts

### Filesystem

/etc/calypso/
scst/
generated.conf
last-known-good.conf
udev/

/var/lib/calypso/
vtl/
state/


---

## 12. Example Mapping (Conceptual)

**Library:** `vtl01`  
**Target IQN:** `iqn.2025.atlasos.calypso:vtl.vtl01`

| LUN | Device Path |
|----|------------|
| 0 | /dev/calypso/vtl/vtl01/changer |
| 1 | /dev/calypso/vtl/vtl01/drive1 |
| 2 | /dev/calypso/vtl/vtl01/drive2 |

---

## 13. Required Adapters in Calypso

1. **MHVTL Adapter**
   - create/delete library
   - manage tapes
   - status & logs

2. **SCST Adapter**
   - config generation
   - apply / rollback
   - session listing

3. **Discovery Adapter**
   - lsscsi mapping
   - sg_inq identification
   - udev rule generation

4. **Policy Engine**
   - single-initiator enforcement
   - safe-apply checks

---

## 14. Final Authority

Dokumen ini adalah **blueprint resmi integrasi SCST + MHVTL**.

Jika ada konflik:
- Blueprint ini
- CURSOR.md
- SRS

maka **Blueprint ini menang untuk domain SCST + MHVTL**.

AtlasOS – Calypso diperlakukan sebagai **enterprise tape & VTL appliance**, bukan sekadar lab tool.

---

