🐧 SmartLinux

SmartLinux is a modern, high-performance desktop application for storage drive health diagnostics, telemetry inspection, and S.M.A.R.T. attribute monitoring across local drives (SATA, NVMe, USB) and remote SSH Homelab servers (Linux, macOS, BSD).

Designed with an on-demand philosophy, SmartLinux avoids unnecessary drive spin-ups and disk wear by only scanning when explicitly requested.

---

✨ Key Features

• ⚡ Pure On-Demand Diagnostics:
  Zero background spin-ups and zero unnecessary wear on standby HDDs. Storage devices and remote servers are listed immediately in an unscanned state; S.M.A.R.T. telemetry is read only when you click Scan Now.
• 🔌 Real-Time USB Hotplug Auto-Detection:
  Zero-overhead Linux kernel Netlink uevent listener automatically detects plugged or removed USB drives in real time without requiring manual refreshes.
• ⏏️ Safely Eject USB Storage:
  Safely unmounts and powers off external USB storage devices directly from the UI or right-click context menu.
• 🌐 Remote Homelab Monitoring via SSH:
  Connect seamlessly to remote servers (e.g., ZimaOS, Proxmox, TrueNAS, Raspberry Pi, Ubuntu Server, Debian, macOS) using Password or Private Key authentication with automatic sudo elevation.
• 📄 Multi-Format Diagnostic Reports:
  Export comprehensive diagnostic reports with multi-drive selection and custom directory browsing:
  • 📝 Markdown (.md): Clean GitHub-Flavored Markdown tables.
  • 📕 PDF Document (.pdf): Styled high-DPI report with telemetry metric boxes and colored status badges.
  • 📘 Word Document (.doc): Formatted Microsoft Word / LibreOffice Writer report.
  • 📊 Excel Spreadsheet (.xls): Multi-sheet Excel workbook with per-attribute columns.
• 📈 On-Demand S.M.A.R.T. History Log:
  Persists health snapshots on every manual scan into a lightweight, non-database JSON Lines file (~/.local/share/smartlinux/history.jsonl). An interactive Historial tab computes delta comparisons against previous scans, instantly flagging worsening sectors or error counts in red.
• 🩺 Native Drive Self-Test (Short & Long):
  Trigger internal drive self-tests (smartctl -t short or -t long) directly from the diagnostic panel for both local and remote SSH drives, with asynchronous background polling and human-readable completion timing ("X hours/days ago").
• 🛡️ Hardened SSH Security & System Keyring:
  Replaces permissive auto-add policies with strict known_hosts cryptographic verification, protecting Homelab hosts from Man-in-the-Middle (MITM) attacks with interactive fingerprint approval modals. SSH passwords are saved securely in the system keyring (gnome-keyring / SecretService) with defensive 0600 / 0700 file permissions.
• 🤖 Standalone Ansible & ntfy Monitor:
  Includes scripts/ansible_smart_check.py, a standalone zero-dependency Python script designed for headless automation (e.g. Ansible / Semaphore). Evaluates exact ATA/NVMe thresholds and fires immediate push alerts to a self-hosted ntfy instance (NTFY_URL) on WARNING or FAILED status.
• 🎨 Modern High-Contrast Dark UI:
  Crisp typography (+15px readable scale), responsive telemetry cards (Temperature, Power-On Hours, Power Cycles), and full ATA / NVMe SMART attribute tables.
• 🪄 1-Click Dependency Auto-Configuration:
  If smartctl is missing or lacks non-root SUID permissions, SmartLinux presents a single-click auto-setup modal that installs packages and sets permissions via system authorization (pkexec).

---

🛠️ System Requirements

• Operating System: Linux (Ubuntu, Debian, Fedora, Arch, Linux Mint, Pop!_OS, etc.) or macOS.
• Python: Python 3.10 or higher.
• smartmontools: smartctl utility installed on the system.

Installing Dependencies

Ubuntu / Debian / Linux Mint / Pop!_OS:

sudo apt update
sudo apt install python3 python3-pip python3-venv smartmontools libxcb-cursor0

Fedora / RHEL / Nobara:

sudo dnf install python3 python3-pip smartmontools

Arch Linux / Manjaro:

sudo pacman -S python python-pip smartmontools

macOS (Homebrew):

brew install python smartmontools

---

🔒 Permission Setup (Local SUID)

To allow SmartLinux to read local raw disk health without prompting for root passwords on every startup, set the SUID bit on smartctl:

# Ubuntu / Debian / Fedora / Pop!_OS:
sudo chmod u+s /usr/sbin/smartctl

# Arch Linux / Omarchy / Manjaro:
sudo chmod u+s /usr/bin/smartctl

(Alternatively, let SmartLinux's built-in 1-click auto-setup modal handle this automatically upon initial launch).

---

🪟 Tiling Window Managers (Hyprland / Omarchy / Sway)

SmartLinux features a high-density diagnostic dashboard layout designed for a native window size of 1180x750. To prevent tiling window managers from auto-tiling or stretching the dashboard across ultra-wide monitors, add a floating rule:

Omarchy (~/.config/hypr/hyprland.lua):

o.window("smartlinux", { float = true, center = true, size = { 1180, 750 } })

Standard Hyprland (~/.config/hypr/hyprland.conf):

windowrulev2 = float, class:^(smartlinux)$
windowrulev2 = size 1180 750, class:^(smartlinux)$
windowrulev2 = center, class:^(smartlinux)$

---

🚀 Installation & Quick Start

Option 1: Desktop Integration (1-Click Installer)

To install SmartLinux into your system's Application Menu with its official commercial icon:

git clone https://github.com/juniorbarchini-oss/smartlinux.git
cd smartlinux
chmod +x install.sh
./install.sh

Option 2: Run Directly (Development Mode)

git clone https://github.com/juniorbarchini-oss/smartlinux.git
cd smartlinux
chmod +x smartlinux.sh
./smartlinux.sh

Option 3: Compile Standalone Portable Package

To bundle SmartLinux into a standalone portable folder suitable for USB flash drives:

chmod +x build_portable.sh
./build_portable.sh

The compiled standalone binary will be generated in dist/SmartLinux/.

---

📂 Project Architecture

smartlinux/
├── scripts/
│   └── ansible_smart_check.py  # Standalone headless SMART monitor with ntfy push alerts
├── smartlinux/
│   ├── core/
│   │   ├── models.py           # Data models (DiskInfo, SmartAttribute, ServerConfig)
│   │   ├── detector.py         # Local disk discovery and safe ejection
│   │   ├── history_manager.py  # On-demand JSON Lines health snapshot log (~/.local/share/)
│   │   ├── smart_parser.py     # ATA/SATA and NVMe SMART JSON parser & threshold evaluator
│   │   ├── ssh_client.py       # Hardened SSH client with strict known_hosts verification
│   │   ├── watcher.py          # Netlink kernel uevent hotplug watcher
│   │   ├── exporter.py         # Multi-format report exporter (.md, .pdf, .doc, .xls)
│   │   └── config_manager.py   # Secure server persistence with system keyring integration
│   ├── ui/
│   │   ├── theme.py            # Dark theme stylesheet (QSS)
│   │   ├── main_window.py      # Main window & background worker orchestration
│   │   ├── sidebar.py          # Device tree with health badges and context menus
│   │   ├── detail_panel.py     # Telemetry metric cards, self-test actions and attribute table
│   │   ├── history_tab.py      # Historical SMART attribute delta and degradation viewer
│   │   ├── server_dialog.py    # Remote SSH server configuration & host key approval modal
│   │   ├── export_dialog.py    # Multi-disk and multi-format export dialog
│   │   └── setup_dialog.py     # 1-click dependency & SUID installer modal
│   ├── assets/
│   │   ├── icon.svg            # Vector application icon
│   │   └── icon.png            # High-resolution raster application icon
│   ├── __init__.py
│   └── main.py                 # Application entry point
├── tests/
│   ├── test_security.py        # Automated tests for known_hosts, keyring, and permissions
│   └── test_ansible_smart_check.py # Automated tests for ATA/NVMe thresholds and ntfy alerts
├── smartlinux.sh               # One-click launcher script
├── install.sh                  # System desktop & icon installer
├── build_portable.sh           # Standalone binary compiler (PyInstaller)
├── smartlinux.desktop          # Linux desktop entry specification
├── requirements.txt            # Python dependencies (PySide6, paramiko, keyring)
└── README.md                   # Documentation

---

👥 Credits

• Concept, Design & Development: Humberto Barchini (HB) & Antigravity (AGY)
• License: Open Source under the MIT License.

---

🌟 Support & Donations

If you find SmartLinux useful for managing your storage hardware and Homelab servers, feel free to support the project: