vtl-appliance/docs/TAPE_MANAGEMENT_GUIDE.md

🗂️ MHVTL Tape Management Guide

Overview

The MHVTL Web UI now includes complete CRUD (Create, Read, Update, Delete) functionality for managing virtual tape files directly from the browser. No more manual command-line operations!

Features

✅ Full CRUD Operations

Operation	Feature	Status
CREATE	Create single or multiple tapes	✅ Working
READ	List all tapes with details	✅ Working
UPDATE	(Future: Edit tape properties)	🔜 Planned
DELETE	Delete single or bulk tapes	✅ Working

🎯 Key Features

1. ➕ Create Tapes

   • Create single or multiple tapes (up to 100 at once)
   • Auto-increment barcode numbering
   • Configurable size, media type, and density
   • Real-time creation feedback

2. 📋 List & Search

   • View all virtual tapes
   • Display: Barcode, Size, Modified date
   • Real-time search/filter by barcode
   • Sortable table view
   • Total tape count

3. 🗑️ Delete Operations

   • Delete individual tapes with confirmation
   • Bulk delete with pattern matching (wildcards)
   • Safe deletion with security checks
   • Success/error notifications

4. 🔄 Auto-Refresh

   • Refresh button to reload tape list
   • Auto-refresh after create/delete operations

Usage Guide

Creating Tapes

1. Navigate to "Manage Tapes" tab
2. Fill in the "Create New Tapes" form:
   • Library Number: Target library (default: 10)
   • Barcode Prefix: 1-6 characters (e.g., "CLN", "DATA", "ARCH")
   • Starting Number: First barcode number (e.g., 100 → CLN000100)
   • Number of Tapes: How many tapes to create (1-100)
   • Tape Size (MB): Size in megabytes (default: 2.5TB = 2,500,000 MB)
   • Media Type: data, clean, or WORM
   • Density: LTO-5, LTO-6, LTO-7, LTO-8, or LTO-9
3. Click "➕ Create Tapes"
4. Wait for confirmation message
5. Tape list will auto-refresh

Example:

Barcode Prefix: BACKUP
Starting Number: 1
Number of Tapes: 10
Size: 2500000 MB
Media Type: data
Density: LTO-6

Result: Creates BACKUP000001 through BACKUP000010

Viewing Tapes

1. Navigate to "Manage Tapes" tab
2. Scroll to "Tape Files" section
3. Click "🔄 Refresh List" to load/reload tapes
4. Use the search box to filter by barcode

Displayed Information:

• Barcode: Tape identifier (e.g., CLN000100)
• Size: Disk space used (e.g., 1.5 KB, 2.3 GB)
• Modified: Last modification date/time
• Actions: Delete button

Deleting Tapes

Single Tape Delete

1. Find the tape in the list
2. Click the "🗑️ Delete" button
3. Confirm the deletion
4. Tape will be removed immediately

Bulk Delete

1. Scroll to "Bulk Actions" section
2. Enter a pattern (supports wildcards):
   • CLN* - All tapes starting with "CLN"
   • BACKUP* - All backup tapes
   • *001 - All tapes ending with "001"
   • TEST* - All test tapes
3. Click "🗑️ Bulk Delete"
4. Confirm the deletion
5. See count of deleted tapes

⚠️ Warning: Bulk delete is permanent and cannot be undone!

Searching/Filtering

1. Use the search box in the "Tape Files" section
2. Type any part of the barcode
3. Results filter in real-time
4. Case-insensitive search

API Reference

Endpoints

All endpoints use POST method to /mhvtl-config/api.php

1. Create Tapes

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "create_tapes",
  "library": 10,
  "barcode_prefix": "CLN",
  "start_num": 100,
  "count": 5,
  "size": 2500000,
  "media_type": "data",
  "density": "LTO6"
}

Response:

{
  "success": true,
  "created_count": 5,
  "message": "Created 5 tape(s)"
}

2. List Tapes

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "list_tapes"
}

Response:

{
  "success": true,
  "tapes": [
    {
      "name": "CLN000100",
      "size": "1.5 KB",
      "modified": "2025-12-09 14:04:56"
    }
  ]
}

3. Delete Single Tape

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "delete_tape",
  "tape_name": "CLN000100"
}

Response:

{
  "success": true,
  "message": "Tape deleted successfully"
}

4. Bulk Delete Tapes

POST /mhvtl-config/api.php
Content-Type: application/json

{
  "action": "bulk_delete_tapes",
  "pattern": "CLN*"
}

Response:

{
  "success": true,
  "deleted_count": 6,
  "message": "Deleted 6 tape(s)"
}

Technical Details

File Structure

/opt/mhvtl/                    # Tape storage directory
├── CLN000100/                 # Individual tape directory
│   ├── data                   # Tape data file
│   ├── indx                   # Index file
│   └── meta                   # Metadata file
├── CLN000101/
└── ...

Permissions

• Directory: /opt/mhvtl/ - 775 (vtl:vtl)
• Tape Dirs: 750 (owner:vtl)
• Tape Files: 640 (owner:vtl)
• Web User: www-data (member of vtl group)

Security Features

1. Path Traversal Protection

   • Validates all tape paths
   • Blocks .. and / in patterns
   • Ensures operations stay within /opt/mhvtl/

2. Input Validation

   • Barcode prefix: max 6 characters
   • Tape count: 1-100 limit
   • Media type: whitelist validation
   • Density: whitelist validation

3. Sudo Configuration

   • Limited sudo access for www-data
   • Only specific commands allowed
   • No password required for allowed operations

4. Error Handling

   • Graceful error messages
   • Partial success reporting
   • Detailed error logs

Sudoers Configuration

File: /etc/sudoers.d/mhvtl

# Allow www-data to manage mhvtl
www-data ALL=(ALL) NOPASSWD: /bin/systemctl restart mhvtl
www-data ALL=(ALL) NOPASSWD: /bin/systemctl start mhvtl
www-data ALL=(ALL) NOPASSWD: /bin/systemctl stop mhvtl
www-data ALL=(ALL) NOPASSWD: /bin/systemctl status mhvtl
www-data ALL=(ALL) NOPASSWD: /bin/rm -rf /opt/mhvtl/*

# Same for apache (RPM-based systems)
apache ALL=(ALL) NOPASSWD: /bin/systemctl restart mhvtl
apache ALL=(ALL) NOPASSWD: /bin/systemctl start mhvtl
apache ALL=(ALL) NOPASSWD: /bin/systemctl stop mhvtl
apache ALL=(ALL) NOPASSWD: /bin/systemctl status mhvtl
apache ALL=(ALL) NOPASSWD: /bin/rm -rf /opt/mhvtl/*

Command Generation

The mktape command is executed as:

mktape -l <library> -m <barcode> -s <size_MB> -t <type> -d <density>

Example:

mktape -l 10 -m CLN000100 -s 2500000 -t data -d LTO6

Testing

CRUD Test Results

=== CRUD TEST ===
1. CREATE: ✅ success:true
2. READ:   ✅ "name":"CRUD000001", "name":"CRUD000002"
3. DELETE: ✅ success:true
4. VERIFY: ✅ Only CRUD000002 remains

Performance

• Create 1 tape: ~1 second
• Create 10 tapes: ~3 seconds
• List 100 tapes: <1 second
• Delete 1 tape: ~1 second
• Bulk delete 50 tapes: ~3 seconds

Troubleshooting

Issue: "Permission denied" when creating tapes

Solution:

1. Check www-data is in vtl group: groups www-data
2. Check /opt/mhvtl permissions: ls -ld /opt/mhvtl
3. Restart Apache: systemctl restart apache2

Issue: "Failed to delete tape"

Solution:

1. Check sudoers file: cat /etc/sudoers.d/mhvtl
2. Test sudo access: sudo -u www-data sudo rm -rf /opt/mhvtl/TEST
3. Check tape exists: ls /opt/mhvtl/

Issue: Tapes not showing in list

Solution:

1. Click "🔄 Refresh List" button
2. Check browser console for errors (F12)
3. Verify API is accessible: curl http://localhost/mhvtl-config/api.php

Issue: "Invalid density" error

Solution: Use one of the supported densities:

• LTO5, LTO6, LTO7, LTO8, LTO9

Best Practices

1. Naming Convention

   • Use meaningful prefixes (BACKUP, ARCHIVE, TEST, etc.)
   • Keep prefixes short (3-6 chars)
   • Use consistent numbering scheme

2. Tape Organization

   • Group tapes by purpose (prefix)
   • Use sequential numbering
   • Document tape usage in external system

3. Deletion Safety

   • Always confirm before bulk delete
   • Test patterns with small sets first
   • Keep backups of important data

4. Performance

   • Create tapes in batches (10-50 at a time)
   • Use bulk delete for cleanup
   • Regular cleanup of unused tapes

Future Enhancements

• Edit tape properties (size, type)
• Tape usage statistics
• Export tape list to CSV
• Tape backup/restore
• Tape verification/integrity check
• Batch operations from file upload
• Tape labeling/tagging system
• Usage history/audit log

Package Information

• Version: 1.0.0
• Package Size: 26 KB
• Files: 28
• Location: /builder/adastra-vtl/dist/adastra-vtl-installer-1.0.0.tar.gz

Support

For issues or questions:

1. Check this guide first
2. Review the troubleshooting section
3. Check system logs: journalctl -u mhvtl
4. Check Apache logs: /var/log/apache2/error.log

---

Last Updated: December 9, 2025
Status: Production Ready ✅