atlas/PlutoOS_SRS_v1.md

SOFTWARE REQUIREMENTS SPECIFICATION (SRS)
PlutoOS – Storage Controller Operating System (v1)

==================================================

1. INTRODUCTION
--------------------------------------------------
1.1 Purpose
This document defines the functional and non-functional requirements for PlutoOS 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
PlutoOS v1 provides:
- ZFS pool, dataset, and ZVOL management
- Storage services: SMB, NFS, iSCSI (ZVOL-backed)
- 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
--------------------------------------------------
PlutoOS 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.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)
--------------------------------------------------
PlutoOS 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