Skip to content

FAQ.md

Latest commit

 

History

History
314 lines (188 loc) · 16.2 KB

FAQ.md

File metadata and controls

314 lines (188 loc) · 16.2 KB
Raw

FAQ – System Monitoring Dashboard – Terminal User Interface (SMD-TUI)

This document addresses friction points, technical boundaries, and known failure modes of the SMD-TUI utility. It is not a marketing brochure; it is a defensive guide designed to prevent user frustration by setting clear expectations upfront.
Read it carefully before reporting problems or modifying the script.
If your workflow deviates from the strict requirements listed below, this script is likely not suitable for your system.

Table of Contents

Philosophy

Why does this script exist?

The Problem

Most system monitoring tools rely on heavy graphical frameworks (Python, Electron, Qt) or external daemons that introduce significant overhead, latency, and dependency hell. They often fail silently in minimal environments (SSH sessions, recovery consoles, TTY) where resources are scarce and stability is critical.

The Solution

SMD-TUI exists to provide a pure Bash, zero-dependency (beyond standard coreutils) telemetry stream. It is engineered for:

  1. Minimal Overhead
    No background daemons, no subshells for data gathering, no external GUI libraries.

  2. Maximum Portability
    Runs wherever bash 4.0+, awk, sed, and grep exist.

  3. Deterministic Output
    Uses strict printf formatting to prevent UI jitter during load spikes.

The Trade-off
By rejecting modern abstractions, this script sacrifices "ease of use" for "raw reliability." It assumes the user understands Linux internals (/proc, /sys, hwmon). If you expect a plug-and-play GUI, this tool will frustrate you.

Does this script support Windows or macOS?

Short Answer: No.

Technical Reality

This script relies exclusively on Linux-specific kernel interfaces and filesystem structures:

  • Kernel Interfaces
    Reads directly from /proc/stat, /proc/diskstats, /proc/pressure/memory, and /sys/class/hwmon. These paths do not exist on Windows or macOS.

  • Filesystem Layout
    Depends on the Linux FHS (Filesystem Hierarchy Standard) for device nodes (/dev/sd*, /media/, /run/media/).

  • Commands
    Uses iproute2 (ip), findmnt, acpi, and lm-sensors in ways specific to the Linux kernel API.

Workarounds?

None. While WSL (Windows Subsystem for Linux) might technically run the binary, sensor data (especially thermal and fan control) is often virtualized or inaccessible in WSL, leading to "unavailable" states. On macOS, the kernel APIs are fundamentally different; porting this script would require a complete rewrite, effectively creating a new tool.

Conclusion

Do not open issues regarding Windows/macOS compatibility. The project scope is strictly Linux-native.

Why is the display garbled or misaligned?

Root Cause

The TUI uses fixed-width character boxing and precise ANSI escape sequences. This requires:

  1. Monospaced Font
    Proportional fonts (e.g., default system fonts in some terminals) will destroy the grid alignment.

  2. Minimum Resolution
    The script enforces a minimum of 80 columns × 25 rows (2-column mode) or 40 columns × 45 rows (1-column mode). Below these thresholds, a warning banner is displayed and the dashboard is suppressed.

  3. UTF-8 Support
    The UI uses Unicode box-drawing characters (╭, ╮, │, ─) and block elements (▇, ❘). If your terminal locale is not UTF-8, these render as squares or question marks.

Risk

If you resize the terminal window dynamically, the script attempts to adapt via per-frame dimension reads, but rapid resizing can cause momentary "ghosting." The script does not support terminal emulators that fail to correctly report dimensions via tput.

Solution

  • Switch to a monospaced font (e.g., JetBrains Mono, Fira Code, Hack).
  • Ensure your terminal meets the minimum size requirements.
  • Set LC_ALL=en_US.UTF-8 or an equivalent UTF-8 locale in your environment.

Why do I see "unavailable" or "inactive" for sensors?

Root Cause

Modern Linux kernels and hardware manufacturers do not guarantee standardized sensor paths.

  • Thermal Sensors
    The script scans /sys/class/hwmon for specific driver names (k10temp, coretemp, zenpower). If your motherboard uses a proprietary or obscure controller, the path may not match the heuristic scan. The script also probes thermal_zone entries for x86_pkg_temp as a fallback.

  • Fans
    Many laptops hide fan control behind ACPI tables rather than exposing them in /sys/class/hwmon. A reading of 0 RPM is treated as "inactive" (fan off or passive cooling), not "broken."

  • Battery
    The BATTERY_ID defaults to BAT1. If your system uses BAT0 or a non-standard ID, the battery block will fail.

  • NVMe
    The script looks for an hwmon entry whose name contains "nvme" and reads temp1_input. Not all NVMe controllers expose this sysfs node.

Risk

Assuming a sensor is "broken" when it is simply "undiscovered" by the script's heuristics is a common user error. The script prioritizes safety: it displays "unavailable" rather than guessing and showing wrong data. A 3-second grace period (TEMP_ZERO_TIMEOUT) prevents flicker during transient 0 °C readings.

Solution

  • Inspect /sys/class/hwmon/ manually to find the correct sensor name and path.

  • Edit the CPU_TEMP_PATH or FAN_PATH variables at the top of the script if you know the exact path.

  • Change BATTERY_ID to match your system (ls /sys/class/power_supply/).

  • Verify that the lm-sensors and acpi packages are installed.

Why are external drives not showing up?

Root Cause

The script dynamically detects block devices using df -hP, filtering for sources starting with /dev/ while excluding /, /boot, /efi, and snap mount points. Re-detection occurs every 0.5 seconds to handle hot-plugging.
Storage detection (capacity, read/write I/O) is hardware-agnostic. NVMe, SATA HDDs, SATA SSDs, USB sticks, and SD cards are all treated identically — the script reads /proc/diskstats and df output, neither of which cares about the underlying bus interface. A mechanical SATA HDD will show capacity and I/O throughput just like an NVMe SSD.

Failure Nodes

  • Mount Point Mismatch
    If you mount a drive to a custom path that the df filter does not cover, it will be invisible. Network mounts (NFS, SMB) are excluded by design because they lack /dev/ block device sources.

  • Permission Issues
    Reading /proc/diskstats, /sys/class/ or /sys/block/ requires read permissions. Running as a standard user might restrict access to certain block devices. Running as a standard user might restrict access to certain block devices, causing I/O speeds to show 0.00.

  • Hot-plugging Latency
    The script re-scans mount points every 0.5 seconds. If a drive is inserted and ejected faster than this interval, it may be missed.

  • Terminal Height
    If the terminal is too short to accommodate additional drive boxes, drives are silently truncated and a warning banner is displayed.

Risk

Do not assume the script will "just work" with network mounts (NFS/SMB), encrypted volumes (LUKS) that are not yet unlocked, or RAID arrays with non-standard device naming. The script only tracks physical block devices exposed via /proc/diskstats.

Solution

  • Mount external drives to standard locations.
  • Run the script with sufficient permissions if I/O speeds show 0.00 (ensure read access to /sys/class/).
  • Use --no-drives to suppress external drive detection entirely if it causes issues.
  • Resize your terminal vertically to reveal hidden drives.

Why does my SATA HDD show no temperature?

Root Cause

Temperature monitoring in SMD-TUI is exclusively NVMe-specific. The script searches for an hwmon entry whose name contains "nvme" and reads its temp1_input node:

   nvme_hwmon_name=$(grep -il "nvme" /sys/class/hwmon/hwmon*/name 2>/dev/null | head -n 1)

There is no code path for SATA HDD or SATA SSD temperature monitoring. The script does not invoke smartctl, hddtemp, or any other tool that could read temperatures from ATA/SCSI devices. This is a deliberate scoping decision, not an oversight.

Scope Clarification

This limitation is not tied to the root drive. NVME_TEMP_PATH is a single global variable set once at startup — it locks onto the first NVMe hwmon entry found, regardless of whether that drive is the root device, a secondary internal drive, or anything else. The absence of SATA temperature support is systemic, not positional.

Risk

Users may conflate "my drive shows no temperature" with "my drive is not detected at all." These are separate systems: storage detection (capacity, I/O) works for all interfaces; temperature detection works only for NVMe controllers that expose hwmon. If your NVMe controller does not expose temp1_input, even NVMe temperature monitoring will fail silently and show "unavailable."

Solution

  • Accept the limitation. If SATA HDD temperature is critical to your workflow, this script is not the right tool.

  • For NVMe drives showing "unavailable": verify that cat /sys/class/hwmon/hwmon*/name contains an entry with nvme and that a corresponding temp1_input file exists.

  • Do not open issues requesting SATA/HDD temperature support. Adding it would require a new dependency (smartmontools or hddtemp), which violates the project's zero-overhead philosophy.

Why does the script crash or exit immediately?

Failure Nodes

  1. Missing Dependencies
    The script checks for mpstat, iostat, bc, and awk at startup. If any are missing, it exits with a clear error message and suggests the correct package manager command.

  2. Bash Version
    Requires Bash 4.0+ for associative arrays (used in stateful I/O tracking for external drives). Bash 3.x (found on legacy systems) will fail.

  3. Strict Mode
    set -euo pipefail is intentionally commented out by default to enable graceful degradation. Enabling it will cause immediate exit on any minor error (e.g., a missing sensor file), which contradicts the design philosophy.

Risk

Running this script on a minimal container (e.g., Alpine without bash or coreutils) will result in immediate failure. The dependency check at startup catches mpstat, iostat, bc, and awk, but does not verify every optional path (e.g., /proc/pressure/memory or power-profiles-daemon).

Solution

  • Verify Bash version: bash --version.
  • Install missing packages: sudo apt install sysstat bc gawk (or equivalent for your distro).
  • Run ./install.sh which checks and guides dependency installation.
  • Do not enable set -euo pipefail unless you have debugged every potential failure point in your specific environment.

Can I customize the update interval?

Limitation

The update interval is fixed at 0.5 seconds (hardcoded via read -r -t 0.5 -n 1 key).

Risk

Changing the update interval requires modifying the loop logic and will destabilize the delta calculations for I/O speeds. The * 2 multiplier in network and storage throughput math assumes a 0.5s interval.

Solution

To change the update rate, edit the read -r -t 0.5 line, but be aware that I/O delta math assumes a 0.5s interval. You must adjust the * 2 multiplier accordingly (e.g., for a 1.0s interval, change * 2 to * 1).

Can I customize the colors?

Limitation

Supported via --accent-color [C] (blue, cyan, gray, green, orange, purple, red). The default is no accent color. However, the alert colors (red/yellow/green for thresholds) are hardcoded to ensure visibility regardless of terminal theme.

Risk

Modifying the color logic manually can lead to poor contrast (e.g., yellow text on a white background) or loss of critical alert visibility. The current palette is chosen for maximum legibility in low-light terminal environments.

Solution

Use the --accent-color flag for theme customization.

Is this safe to run on a production server?

Assessment

  • CPU Overhead
    Negligible (<1% on modern CPUs). It uses native /proc and /sys reads, not heavy polling or subshells for critical-path data gathering.

  • Stability
    The script runs in a tight while true loop with a 0.5s sleep. If the terminal disconnects (SSH drop), the SIGINT/SIGTERM trap should terminate it cleanly, but orphaned processes are possible if the signal is not delivered.

  • Permissions
    It only reads public kernel stats. It does not write to any system files or modify system state.

  • Privacy
    No telemetry is sent anywhere. All data is local.

Risk

While safe, running any monitoring tool on a production server adds a variable. If the script enters an infinite loop due to an unhandled edge case, it could consume a small amount of CPU. Always test in a staging environment first.

Recommendation

Safe for production use, provided you accept the risk of running custom scripts. Do not run it as a systemd service unless you wrap it with a proper restart policy. For long-running sessions, consider running inside tmux or screen to survive SSH disconnects.

How do I report a bug correctly?

Incorrect Reports (will be closed)

  • "It doesn't work on Windows."
    See: Does this script support Windows or macOS?

  • "My fan speed is 0."
    Check your hardware documentation; many fans are not exposed to the OS or CPUs are passively cooled. Your operating system might run as a virtual machine.

  • "The colors look weird."
    Check your terminal font, palette, and background contrast.

  • "My SATA HDD has no temperature." (See: Why does my SATA HDD show no temperature? — this is by design.)

  • Screenshots without terminal logs or system specs.

Correct Report Format

  1. System Info
    Distribution, kernel version (uname -r), Bash version (bash --version).

  2. Hardware
    CPU model, motherboard model (crucial for sensor issues).

  3. Steps to Reproduce
    Exact command used, including flags.

  4. Logs
    Output of bash -x smd-tui (debug mode) if the script crashes.

  5. Expected vs. Actual
    Clear description of the discrepancy.

Final Note
This is a defensive tool. If your system behaves unexpectedly, the fault often lies in the hardware abstraction layer of your Linux distribution, not the script itself. Investigate your /sys and /proc trees before blaming the code.

Who is liable for data loss?

You are. This script is provided "as is" under the MIT License with no warranty whatsoever. As a user, you are solely responsible for your own data and, where applicable, for any customer or third-party data stored on the system this script manages.
If your system handles critical or regulated data, implement your own backup and redundancy strategy. See LICENSE and the DISCLAIMER section in README.md for the full legal text.

Can I modify the script?

Yes, under the terms of the MIT License. If you do, keep version numbers and build dates consistent across all files (see README.md — Version Metadata) to avoid breaking the test suite (test.sh).

Last updated: 22 August 2026 Author: RML Tec Dev