othman.suseno/atlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
atlas/docs/TUI.md
othman.suseno 507961716e
Some checks failed
CI / test-build (push) Failing after 2m26s
Details
add tui features
2025-12-15 01:08:17 +07:00

7.5 KiB
Raw Permalink Blame History

Terminal User Interface (TUI)

Overview

AtlasOS provides a Terminal User Interface (TUI) for managing the storage system from the command line. The TUI provides an interactive menu-driven interface that connects to the Atlas API.

Features

  • Interactive Menus: Navigate through system features with simple menus
  • Authentication: Secure login to the API
  • ZFS Management: View and manage pools, datasets, and ZVOLs
  • Storage Services: Manage SMB shares, NFS exports, and iSCSI targets
  • Snapshot Management: Create snapshots and manage policies
  • System Information: View system health and diagnostics
  • Backup & Restore: Manage configuration backups

Installation

Build the TUI binary:

go build ./cmd/atlas-tui

Or use the Makefile:

make build

This creates the atlas-tui binary.

Configuration

API URL

Set the API URL via environment variable:

export ATLAS_API_URL=http://localhost:8080
./atlas-tui

Default: http://localhost:8080

Usage

Starting the TUI

./atlas-tui

Authentication

On first run, you'll be prompted to login:

=== AtlasOS Login ===
Username: admin
Password: ****
Login successful!

Main Menu

=== AtlasOS Terminal Interface ===
1. ZFS Management
2. Storage Services
3. Snapshots
4. System Information
5. Backup & Restore
0. Exit

Menu Options

1. ZFS Management

Sub-menu:

  • List Pools
  • List Datasets
  • List ZVOLs
  • List Disks

Example - List Pools:

=== ZFS Pools ===
1. tank
   Size: 10TB
   Used: 2TB

2. Storage Services

Sub-menu:

  • SMB Shares
  • NFS Exports
  • iSCSI Targets

SMB Shares:

  • List Shares
  • Create Share

Example - Create SMB Share:

Share name: data-share
Dataset: tank/data
Path (optional, press Enter to auto-detect): 
Description (optional): Main data share
SMB share created successfully!
Share: data-share

NFS Exports:

  • List Exports
  • Create Export

Example - Create NFS Export:

Dataset: tank/data
Path (optional, press Enter to auto-detect): 
Clients (comma-separated, e.g., 192.168.1.0/24,*): 192.168.1.0/24
NFS export created successfully!
Export: /tank/data

iSCSI Targets:

  • List Targets
  • Create Target

Example - Create iSCSI Target:

IQN (e.g., iqn.2024-12.com.atlas:target1): iqn.2024-12.com.atlas:target1
iSCSI target created successfully!
Target: iqn.2024-12.com.atlas:target1

3. Snapshots

Sub-menu:

  • List Snapshots
  • Create Snapshot
  • List Snapshot Policies

Example - Create Snapshot:

Dataset name: tank/data
Snapshot name: backup-2024-12-20
Snapshot created successfully!
Snapshot: tank/data@backup-2024-12-20

4. System Information

Sub-menu:

  • System Info
  • Health Check
  • Dashboard

System Info:

=== System Information ===
Version: v0.1.0-dev
Uptime: 3600 seconds
Go Version: go1.21.0
Goroutines: 15

Services:
  smb: running
  nfs: running
  iscsi: stopped

Health Check:

=== Health Check ===
Status: healthy

Component Checks:
  zfs: healthy
  database: healthy
  smb: healthy
  nfs: healthy
  iscsi: stopped

Dashboard:

=== Dashboard ===
Pools: 2
Datasets: 10
SMB Shares: 5
NFS Exports: 3
iSCSI Targets: 2

5. Backup & Restore

Sub-menu:

  • List Backups
  • Create Backup
  • Restore Backup

Example - Create Backup:

Description (optional): Weekly backup
Backup created successfully!
Backup ID: backup-1703123456

Example - Restore Backup:

=== Backups ===
1. backup-1703123456
   Created: 2024-12-20T10:30:56Z
   Description: Weekly backup

Backup ID: backup-1703123456
Restore backup? This will overwrite current configuration. (yes/no): yes
Backup restored successfully!

Navigation

  • Select Option: Enter the number or letter corresponding to the menu option
  • Back: Enter 0 to go back to the previous menu
  • Exit: Enter 0, q, or exit to quit the application
  • Interrupt: Press Ctrl+C for graceful shutdown

Keyboard Shortcuts

  • Ctrl+C: Graceful shutdown
  • 0: Back/Exit
  • q: Exit
  • exit: Exit

Examples

Complete Workflow

# Start TUI
./atlas-tui

# Login
Username: admin
Password: admin

# Navigate to ZFS Management
Select option: 1

# List pools
Select option: 1

# Go back
Select option: 0

# Create SMB share
Select option: 2
Select option: 1
Select option: 2
Share name: myshare
Dataset: tank/data
...

# Exit
Select option: 0
Select option: 0

API Client

The TUI uses an HTTP client to communicate with the Atlas API:

  • Authentication: JWT token-based authentication
  • Error Handling: Clear error messages for API failures
  • Timeout: 30-second timeout for requests

Error Handling

The TUI handles errors gracefully:

  • Connection Errors: Clear messages when API is unreachable
  • Authentication Errors: Prompts for re-authentication
  • API Errors: Displays error messages from API responses
  • Invalid Input: Validates user input before sending requests

Configuration File

Future enhancement: Support for configuration file:

api_url: http://localhost:8080
username: admin
# Token can be stored (with appropriate security)

Security Considerations

  1. Password Input: Currently visible (future: hidden input)
  2. Token Storage: Token stored in memory only
  3. HTTPS: Use HTTPS for production API URLs
  4. Credentials: Never log credentials

Limitations

  • Password Visibility: Passwords are currently visible during input
  • No Token Persistence: Must login on each TUI start
  • Basic Interface: Text-based menus (not a full TUI library)
  • Limited Error Recovery: Some errors require restart

Future Enhancements

  1. Hidden Password Input: Use library to hide password input
  2. Token Persistence: Store token securely for session persistence
  3. Advanced TUI: Use Bubble Tea or similar for rich interface
  4. Command Mode: Support command-line arguments for non-interactive use
  5. Configuration File: Support for config file
  6. Auto-completion: Tab completion for commands
  7. History: Command history support
  8. Color Output: Colored output for better readability
  9. Progress Indicators: Show progress for long operations
  10. Batch Operations: Support for batch operations

Troubleshooting

Connection Errors

Error: request failed: dial tcp 127.0.0.1:8080: connect: connection refused

Solution: Ensure the API server is running:

./atlas-api

Authentication Errors

Error: login failed: invalid credentials

Solution: Check username and password. Default credentials:

  • Username: admin
  • Password: admin

API URL Configuration

If API is on a different host/port:

export ATLAS_API_URL=http://192.168.1.100:8080
./atlas-tui

Comparison with Web GUI

Feature TUI Web GUI
Access Local console Browser
Setup No browser needed Requires browser
Network Works offline (local) Requires network
Rich UI Text-based HTML/CSS/JS
Initial Setup Ideal for setup Better for daily use
Maintenance Good for maintenance Good for monitoring

Best Practices

  1. Use TUI for Initial Setup: TUI is ideal for initial system configuration
  2. Use Web GUI for Daily Operations: Web GUI provides better visualization
  3. Keep API Running: TUI requires the API server to be running
  4. Secure Credentials: Don't share credentials or tokens
  5. Use HTTPS in Production: Always use HTTPS for production API URLs