Skip to content

Linux Installation

Jump to bottom
Le Khanh Binh edited this page Sep 13, 2026 · 2 revisions

Linux Installation

ZenTune operates as a two-tier system on Linux: a root daemon managing hardware SMU states, power profiles, and sysfs interfaces, paired with a non-root Text User Interface (TUI) communicating over a local ZeroMQ IPC socket.

1. System requirements

Ensure the host environment meets the following specifications before installing:

  • Operating system: Linux kernel 5.10 or newer. A systemd-based distribution is recommended; the setup wizard automatically provisions and enables zentune.service. Non-systemd inits (OpenRC, runit, s6, musl/dinit) are supported via manual daemon execution or user-provided service scripts.
  • Privilege elevation: Administrator privileges via either sudo or systemd run0 (polkit). Minimal systems lacking sudo function natively with run0. When using run0, ensure polkitd and a Polkit authentication agent (graphical or console) are present.
  • Python: Python 3.10 or newer (python3 --version).
  • Hardware: AMD Ryzen processor (APU or desktop CPU). Intel processors are not supported. ZenTune interrogates hardware capabilities on first launch.
  • Terminal dimensions: Minimum window size of 50 columns by 25 rows. Smaller viewports display a terminal dimension warning.

Dependencies (pyzmq, textual, textual-plotext, and zenmaster) are isolated within /opt/zentune/venv via ensure_venv. System Python site-packages remain unmodified.

2. Install ryzen_smu (Secure Boot only)

Note

Systems with UEFI Secure Boot disabled communicate with the processor through direct PCI config space access and do not require ryzen_smu. Verify Secure Boot state:

mokutil --sb-state

If output reads SecureBoot disabled, proceed directly to Section 3: Install ZenTune. If SecureBoot enabled, install ryzen_smu below.

When Secure Boot is active, kernel lockdown policies prevent raw PCI config space writes from userspace. The ryzen_smu out-of-tree kernel module provides an authorized driver interface (/sys/kernel/ryzen_smu_drv/). Minimum supported version is 0.1.7.

2.1 Install build dependencies

DKMS automatically rebuilds ryzen_smu across distribution kernel upgrades.

Debian / Ubuntu / Linux Mint / Pop!_OS:

sudo apt update && sudo apt install cmake gcc g++ dkms openssl
# With run0:
run0 apt update && run0 apt install cmake gcc g++ dkms openssl

Fedora:

sudo dnf install cmake gcc gcc-c++ dkms openssl
# With run0:
run0 dnf install cmake gcc gcc-c++ dkms openssl

AlmaLinux / Rocky Linux 9 / RHEL 9:

sudo dnf install epel-release
sudo dnf install cmake gcc gcc-c++ dkms openssl

CentOS Stream 9:

sudo dnf config-manager --set-enabled crb
sudo dnf install epel-release
sudo dnf install cmake gcc gcc-c++ dkms openssl

Arch Linux / Manjaro / EndeavourOS:

sudo pacman -S cmake gcc dkms openssl
# With run0:
run0 pacman -S cmake gcc dkms openssl

openSUSE Tumbleweed / Leap:

sudo zypper install cmake gcc gcc-c++ dkms openssl
{{ ... }}

**Gentoo:**
```bash
sudo emerge --ask dev-build/cmake sys-kernel/dkms dev-libs/openssl

2.2 Build and install ryzen_smu via DKMS

Clone the repository and register the driver with DKMS:

git clone https://github.com/amkillam/ryzen_smu
cd ryzen_smu
sudo make dkms-install
# Or with run0:
# run0 make dkms-install

Load the module and verify detection:

sudo modprobe ryzen_smu
lsmod | grep ryzen_smu

If modprobe returns Operation not permitted or a verification error, enroll the DKMS Machine Owner Key (MOK) as detailed below.

2.3 Enroll the MOK signing key (Secure Boot)

DKMS generates a local key pair during compilation. Import the public certificate into the UEFI MOK database:

sudo mokutil --import /var/lib/dkms/mok.pub
# Or with run0:
# run0 mokutil --import /var/lib/dkms/mok.pub

Enter a temporary password when prompted, then restart the system:

sudo reboot

During reboot, the Shim UEFI key management utility launches:

  1. Select Enroll MOK.
  2. Select Continue, then confirm with Yes.
  3. Supply the temporary password configured during import.
  4. Select Reboot.

Once booted into Linux, confirm driver initialization:

sudo modprobe ryzen_smu
cat /sys/kernel/ryzen_smu_drv/drv_version

The version string must report 0.1.7 or higher.

3. Install ZenTune

Execute the automated installation script as a regular unprivileged user:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash

Do not run the script under root. install.sh requests elevation only when writing system directories.

3.1 Installer CLI options

The installation script accepts command-line flags to customize behavior:

Flag Description
--sudo Explicitly use sudo for privilege elevation.
--run0 Explicitly use systemd run0 --background= for privilege elevation.
--skip-deps Bypass package manager dependency installation.
--beta Download and install the latest rolling beta release.
--local Install directly from a local repository clone without downloading archives.
--uninstall Remove all ZenTune files, virtual environment, and systemd units.

Example using run0 and targeting the beta branch:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash -s -- --run0 --beta

3.2 Privilege detection logic

install.sh evaluates elevation tools in this order:

  1. Explicit CLI flags: --sudo sets PRIV_TOOL="sudo"; --run0 sets PRIV_TOOL="run0".
  2. Automatic discovery: checks for sudo in path; if absent, inspects run0 availability.
  3. Execution wrapper: sudo executes $SUDO -v for verification; run0 executes run0 --background= true.

3.3 What the installer configures

  1. Installs distribution packages (wget, unzip, curl, and python3 3.10+) via apt, dnf, pacman, or zypper.
  2. Deploys application source code to /opt/zentune/src/.
  3. Constructs an isolated virtual environment at /opt/zentune/venv/ via Python standard library ensurepip.
  4. Installs wheel dependencies (pyzmq, textual, textual-plotext, zenmaster) into the isolated venv.
  5. Deploys an executable wrapper script at /usr/local/bin/zentune.
  6. Sets ownership of /opt/zentune to the invoking user, allowing user-level config writes without elevated permissions.

4. First run & Polkit authorization

Launch the application from any terminal:

zentune

The initial run triggers the first-run configuration wizard:

Step 1: Welcome

Initializes default configuration settings and verifies terminal dimensions. Select Begin setup.

Step 2: Background daemon & Privilege elevation

Select Install / enable daemon. ZenTune interacts with your configured privilege elevation tool:

  • When using sudo: ZenTune opens SudoModal to capture your administrative password, invoking sudo -S -p "" -v in an isolated background thread to prime credentials.
  • When using run0: ZenTune displays Run0Modal. Authentication is delegated entirely to your system Polkit agent (e.g., polkit-gnome, lxpolkit, or a console TTY agent). No credentials pass through the ZenTune interface.
  • Privilege pre-check bypass: systemd.py recognizes run0 and bypasses preliminary credential checks because Polkit handles interactive authorization directly at execution time.
  • Unit activation: ZenTune writes /etc/systemd/system/zentune.service, reloads systemd units, and starts the service. Once active, the interface reports Daemon: running.

For non-systemd environments, the wizard outputs the standalone command to execute in another terminal:

sudo /opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py
# Or with run0:
run0 /opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py

Step 3: Hardware detection

ZenTune probes CPUID records, SMU registers, and platform capabilities via zenmaster. The detected CPU family (e.g., Family HawkPoint), architecture, and profile mapping appear on screen. Select Finish to enter the main dashboard.

5. Interface navigation

The TUI provides dedicated functional views accessible via keyboard shortcuts or mouse clicks:

Key Tab Function
h Home Live hardware telemetry graphs, frequency status, and sensor readouts.
1 Premade Instant application of preset profiles (Eco, Balanced, Performance, Extreme).
2 Custom Fine-grained parameter customization (Custom Presets).
3 Adaptive Dynamic curve adjustment responding to load and thermal metrics (Adaptive Mode).
4 Auto Automatic profile switching based on AC/Battery power events and resume hooks.
5 Info SMU tables, platform topology, cache domains, and hardware identifiers.
6 Status Daemon socket telemetry, operation receipts, and SMU return codes.
7 Settings Service management, elevation tool choice (auto, sudo, run0), and updates.
? About Version details, repository links, and update checks.
q Quit Terminate the TUI client (background daemon remains active).

To switch privilege elevation tools after installation, open Settings (7) -> Privilege escalation tool and select between Auto-detect, sudo, or run0.

6. Service architecture & IPC

The background daemon operates as a persistent system service:

6.1 Systemd service definition

The service unit is stored at /etc/systemd/system/zentune.service:

[Unit]
Description=ZenTune Power Management Daemon
After=multi-user.target

[Service]
Type=simple
ExecStart=/opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

6.2 IPC transport

Client-server communication runs over ZeroMQ:

  • Socket path: /run/zentune.sock (ipc:///run/zentune.sock)
  • Permissions: Mode 0o666 (world-writable) established by daemon.py on startup, allowing unprivileged TUI processes to transmit control messages.
  • Process lock: /run/zentune_daemon.lock prevents concurrent daemon instances.
  • Protocol: Request-reply (REQ/REP) message patterns exchanging structured JSON commands.

7. Updating ZenTune

When Software update is enabled, ZenTune inspects GitHub release feeds on launch. If a newer build is detected, the app offers automatic migration.

  • To initiate an update manually: Open About (?) -> Check updates, then select Update now (or Switch to beta).
  • To update from the command line, re-run the installer: 
    curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash

Updates preserve your custom definitions in /opt/zentune/src/Assets/custom.json and persistent preferences in config.ini.

8. Uninstalling

8.1 Automated removal

Pass the --uninstall flag to the installation script:

bash install.sh --uninstall
# Or in one command:
curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash -s -- --uninstall

To run non-interactively in automated scripts, export ZENTUNE_ASSUME_YES=1:

ZENTUNE_ASSUME_YES=1 bash install.sh --uninstall

8.2 In-app service deregistration

Navigate to Settings (7) -> Daemon service -> Uninstall. This halts, disables, and deletes /etc/systemd/system/zentune.service. Application code and custom preset configurations remain intact.

8.3 Manual cleanup

To remove all deployed artifacts manually:

# Stop and purge systemd unit
sudo systemctl disable --now zentune.service
# Or with run0: run0 systemctl disable --now zentune.service

sudo rm -f /etc/systemd/system/zentune.service
sudo systemctl daemon-reload

# Remove binaries, venv, and runtime files
sudo rm -f /usr/local/bin/zentune
sudo rm -rf /opt/zentune
sudo rm -f /run/zentune.sock /run/zentune_daemon.lock
rm -f /tmp/zentune_tui.lock

To purge ryzen_smu from DKMS:

cd ryzen_smu
sudo make dkms-uninstall
# Or with run0: run0 make dkms-uninstall

9. Manual installation from source

To audit source files before executing setup routines, clone the repository locally:

git clone https://github.com/HorizonUnix/ZenTune.git
cd ZenTune
./install.sh --local

To enforce run0 elevation during local setup:

./install.sh --local --run0

For non-systemd environments, write a supervisor unit (e.g., OpenRC runscript at /etc/init.d/zentune or runit run script) pointing ExecStart to /opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py.

Report an issue · Releases

Home

Getting started

Using the app

Internals

Clone this wiki locally