50%

AtlasOS_SRS_v1.md

@@ -0,0 +1,185 @@
+SOFTWARE REQUIREMENTS SPECIFICATION (SRS)
+AtlasOS – Storage Controller Operating System (v1)
+
+==================================================
+
+1. INTRODUCTION
+--------------------------------------------------
+1.1 Purpose
+This document defines the functional and non-functional requirements for AtlasOS v1,
+a storage controller operating system built on Linux with ZFS as the core storage engine.
+It serves as the authoritative reference for development scope, validation, and acceptance.
+
+1.2 Scope
+AtlasOS v1 provides:
+- ZFS pool, dataset, and ZVOL management
+- Storage services: SMB, NFS, iSCSI (ZVOL-backed)
+- Virtual Tape Library (VTL) with mhvtl for tape emulation
+- Automated snapshot management
+- Role-Based Access Control (RBAC) and audit logging
+- Web-based GUI and local TUI
+- Monitoring and Prometheus-compatible metrics
+
+The following are explicitly out of scope for v1:
+- High Availability (HA) or clustering
+- Multi-node replication
+- Object storage (S3)
+- Active Directory / LDAP integration
+
+1.3 Definitions
+Dataset  : ZFS filesystem
+ZVOL     : ZFS block device
+LUN      : Logical Unit Number exposed via iSCSI
+Job      : Asynchronous long-running operation
+Desired State : Configuration stored in DB and applied atomically to system
+
+==================================================
+
+2. SYSTEM OVERVIEW
+--------------------------------------------------
+AtlasOS consists of:
+- Base OS      : Minimal Linux (Ubuntu/Debian)
+- Data Plane  : ZFS and storage services
+- Control Plane: Go backend with HTMX-based UI
+- Interfaces  : Web GUI, TUI, Metrics endpoint
+
+==================================================
+
+3. USER CLASSES
+--------------------------------------------------
+Administrator : Full system and storage control
+Operator      : Storage and service operations
+Viewer        : Read-only access
+
+==================================================
+
+4. FUNCTIONAL REQUIREMENTS
+--------------------------------------------------
+
+4.1 Authentication & Authorization
+- System SHALL require authentication for all management access
+- System SHALL enforce RBAC with predefined roles
+- Access SHALL be denied by default
+
+4.2 ZFS Management
+- System SHALL list available disks (read-only)
+- System SHALL create, import, and export ZFS pools
+- System SHALL report pool health status
+- System SHALL create and manage datasets
+- System SHALL create ZVOLs for block storage
+- System SHALL support scrub operations with progress monitoring
+
+4.3 Snapshot Management
+- System SHALL support manual snapshot creation
+- System SHALL support automated snapshot policies
+- System SHALL allow per-dataset snapshot enable/disable
+- System SHALL prune snapshots based on retention policy
+
+4.4 SMB Service
+- System SHALL create SMB shares mapped to datasets
+- System SHALL manage share permissions
+- System SHALL apply configuration atomically
+- System SHALL reload service safely
+
+4.5 NFS Service
+- System SHALL create NFS exports per dataset
+- System SHALL support RW/RO and client restrictions
+- System SHALL regenerate exports from desired state
+- System SHALL reload NFS exports safely
+
+4.6 iSCSI Block Storage
+- System SHALL provision ZVOL-backed LUNs
+- System SHALL create iSCSI targets with IQN
+- System SHALL map LUNs to targets
+- System SHALL configure initiator ACLs
+- System SHALL expose connection instructions
+
+4.6.1 Virtual Tape Library (VTL)
+- System SHALL manage mhvtl service (start, stop, restart)
+- System SHALL create and manage virtual tape libraries (media changers)
+- System SHALL create and manage virtual tape drives (LTO-5 through LTO-8)
+- System SHALL create and manage virtual tape cartridges
+- System SHALL support tape operations (load, eject, read, write)
+- System SHALL manage library_contents files for tape inventory
+- System SHALL validate drive ID conflicts to prevent device path collisions
+- System SHALL automatically restart mhvtl service after configuration changes
+- System SHALL support multiple vendors (IBM, HP, Quantum, Tandberg, Overland)
+- System SHALL enforce RBAC for VTL operations (Administrator and Operator only)
+
+4.7 Job Management
+- System SHALL execute long-running operations as jobs
+- System SHALL track job status and progress
+- System SHALL persist job history
+- Failed jobs SHALL not leave system inconsistent
+
+4.8 Audit Logging
+- System SHALL log all mutating operations
+- Audit log SHALL record actor, action, resource, and timestamp
+- Audit log SHALL be immutable from the UI
+
+4.9 Web GUI
+- System SHALL provide a web-based management interface
+- GUI SHALL support partial updates
+- GUI SHALL display system health and alerts
+- Destructive actions SHALL require confirmation
+
+4.10 TUI
+- System SHALL provide a local console interface
+- TUI SHALL support initial system setup
+- TUI SHALL allow monitoring and maintenance operations
+- TUI SHALL function without web UI availability
+
+4.11 Monitoring & Metrics
+- System SHALL expose /metrics in Prometheus format
+- System SHALL expose pool health and capacity metrics
+- System SHALL expose job failure metrics
+- GUI SHALL present a metrics summary
+
+4.12 Update & Maintenance
+- System SHALL support safe update mechanisms
+- Configuration SHALL be backed up prior to updates
+- Maintenance mode SHALL disable user operations
+
+==================================================
+
+5. NON-FUNCTIONAL REQUIREMENTS
+--------------------------------------------------
+
+5.1 Reliability
+- Storage operations SHALL be transactional where possible
+- System SHALL recover gracefully from partial failures
+
+5.2 Performance
+- Management UI read operations SHOULD respond within 500ms
+- Background jobs SHALL not block UI responsiveness
+
+5.3 Security
+- HTTPS SHALL be enforced for the web UI
+- Secrets SHALL NOT be logged in plaintext
+- Least-privilege access SHALL be enforced
+
+5.4 Maintainability
+- Configuration SHALL be declarative
+- System SHALL provide diagnostic information for support
+
+==================================================
+
+6. CONSTRAINTS & ASSUMPTIONS
+--------------------------------------------------
+- Single-node controller
+- Linux kernel with ZFS support
+- Local storage only
+
+==================================================
+
+7. ACCEPTANCE CRITERIA (v1)
+--------------------------------------------------
+AtlasOS v1 is accepted when:
+- ZFS pool, dataset, share, and LUN lifecycle works end-to-end
+- Snapshot policies are active and observable
+- RBAC and audit logging are enforced
+- GUI, TUI, and metrics endpoints are functional
+- No manual configuration file edits are required
+
+==================================================
+END OF DOCUMENT