BAMS/ARCHITECTURE.md

BAMS Architecture

Overview

BAMS (Backup Appliance Management System) is a comprehensive management platform for backup appliances, providing unified control over storage, tape libraries, iSCSI targets, and Bacula integration.

System Architecture

┌─────────────────────────────────────────────────────────┐
│                    Cockpit Web UI                        │
│                  (Cockpit Plugin)                        │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP/REST API
                       │
┌──────────────────────▼──────────────────────────────────┐
│              BAMS Backend Service (Go)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐│
│  │   Disk   │  │   Tape   │  │   iSCSI   │  │ Bacula  ││
│  │ Service  │  │ Service  │  │  Service │  │ Service ││
│  └────┬─────┘  └────┬─────┘  └────┬──────┘  └────┬────┘│
└───────┼─────────────┼──────────────┼──────────────┼─────┘
        │             │              │              │
┌───────▼─────┐ ┌─────▼─────┐ ┌─────▼──────┐ ┌─────▼─────┐
│    LVM      │ │   mtx     │ │    SCST    │ │  systemd  │
│    ZFS      │ │  sg_lib   │ │   iSCSI    │ │  bacula-sd│
└─────────────┘ └───────────┘ └────────────┘ └───────────┘

Components

1. Backend Service (Go)

Location: backend/

Structure:

• main.go - Entry point, HTTP server setup
• internal/api/ - REST API handlers and routing
• internal/services/ - Business logic services
  • disk/ - Disk repository management (LVM/ZFS)
  • tape/ - Tape library management
  • iscsi/ - iSCSI target management (SCST)
  • bacula/ - Bacula integration
  • logs/ - Logging and diagnostics
  • audit/ - Audit logging
• internal/config/ - Configuration management
• internal/logger/ - Logging utilities
• internal/utils/ - Helper functions

Key Features:

• RESTful API with JSON responses
• Graceful shutdown handling
• Request validation
• Error recovery middleware
• CORS support

2. Cockpit Plugin (Frontend)

Location: cockpit/

Files:

• manifest.json - Plugin metadata
• index.html - Main UI structure
• bams.js - JavaScript application logic

Features:

• Dashboard with real-time monitoring
• Storage repository management
• Tape library operations
• iSCSI target configuration
• Bacula status and control
• Log viewer

3. Configuration

Location: configs/

Files:

• bams.service - Systemd service file
• config.yaml.example - Configuration template
• polkit.rules - Polkit authorization rules

Data Flow

Disk Repository Creation

1. User creates repository via UI
2. Frontend sends POST to /api/v1/disk/repositories
3. Backend validates input
4. Disk service creates LVM volume or ZFS zvol
5. Repository metadata stored
6. Response returned to UI

Tape Operations

1. User triggers inventory/load/unload
2. Frontend sends request to API
3. Tape service executes mtx commands
4. Results parsed and returned
5. UI updates display

iSCSI Target Management

1. User creates/updates target
2. Backend validates IQN, portals, initiators
3. SCST configuration generated
4. Configuration applied via scstadmin
5. Status returned to UI

Security

• Authentication: PAM/system users via Cockpit
• Authorization: Polkit rules for privileged operations
• Audit Logging: All configuration changes logged
• Input Validation: All user input validated
• Error Handling: Panic recovery middleware

API Endpoints

Dashboard

• GET /api/v1/dashboard - System overview

Disk Repositories

• GET /api/v1/disk/repositories - List repositories
• POST /api/v1/disk/repositories - Create repository
• GET /api/v1/disk/repositories/{id} - Get repository
• DELETE /api/v1/disk/repositories/{id} - Delete repository

Tape Library

• GET /api/v1/tape/library - Library status
• POST /api/v1/tape/inventory - Run inventory
• GET /api/v1/tape/drives - List drives
• POST /api/v1/tape/drives/{id}/load - Load tape
• POST /api/v1/tape/drives/{id}/unload - Unload tape
• GET /api/v1/tape/slots - List slots

iSCSI Targets

• GET /api/v1/iscsi/targets - List targets
• POST /api/v1/iscsi/targets - Create target
• GET /api/v1/iscsi/targets/{id} - Get target
• PUT /api/v1/iscsi/targets/{id} - Update target
• DELETE /api/v1/iscsi/targets/{id} - Delete target
• POST /api/v1/iscsi/targets/{id}/apply - Apply configuration
• POST /api/v1/iscsi/targets/{id}/luns - Add LUN
• DELETE /api/v1/iscsi/targets/{id}/luns/{lun} - Remove LUN
• GET /api/v1/iscsi/sessions - List sessions

Bacula

• GET /api/v1/bacula/status - SD status
• GET /api/v1/bacula/config - Get config
• POST /api/v1/bacula/config - Generate config
• POST /api/v1/bacula/inventory - Run inventory
• POST /api/v1/bacula/restart - Restart SD

Logs & Diagnostics

• GET /api/v1/logs/{service} - Get logs
• GET /api/v1/logs/{service}/stream - Stream logs (WebSocket)
• GET /api/v1/diagnostics/bundle - Download support bundle

Deployment

1. Build backend: make build
2. Install service: make install
3. Configure: Edit /etc/bams/config.yaml
4. Start service: systemctl start bams
5. Access via Cockpit web interface

Dependencies

• Go 1.21+
• Cockpit 300+
• SCST (iSCSI target framework)
• mtx (tape library control)
• LVM tools (for LVM repositories)
• ZFS tools (for ZFS repositories, optional)
• Bacula (for backup integration)

Future Enhancements

• WebSocket support for real-time log streaming
• Multi-tenant support
• High Availability
• Tape encryption management
• Cloud tiering
• Policy-based tape lifecycle