Skip to content

0x556c79/install_ugreen_leds_controller

BranchesTags

Repository files navigation

Ugreen LED Controller Installer

Small, single-file Bash installer for the ugreen_leds_controller project. It clones, installs the kernel module, copies helper scripts and a systemd unit, and enables the service.

Quick install

Always validate what the script does before running

Run the following command to install:

curl -sf https://raw.githubusercontent.com/0x556c79/install_ugreen_leds_controller/main/install_ugreen_leds_controller.sh -o install_ugreen_leds_controller.sh ; sudo bash install_ugreen_leds_controller.sh

Compatibility

This installer has been confirmed working on the following models. For general module compatibility (other OS/distros), refer to the upstream project.

Model Notes Reference
UGREEN DX4600+ Tested with TrueNAS SCALE 25.04.2.6 #20
UGREEN DXP2800 #12
UGREEN DXP3800 Plus Tested with TrueNAS SCALE 25.10.3 #18
UGREEN DXP4700 Tested with TrueNAS SCALE 25.10.4 —
UGREEN DXP4800 Tested with TrueNAS SCALE 25.04.2.5, script v1.0 #6
UGREEN NASync DXP4800 Pro Customization configuration also tested #24
UGREEN DXP6800 Pro Tested with TrueNAS SCALE 25.10.3 #17
UGREEN DXP8800 Plus Developed & tested on this model —
UGREEN NASync iDX6011 Pro Experimental support; different LED protocol, interim TrueNAS modules built from the iDX fork #23

If you've confirmed the script works on another model, feel free to open an issue or pull request!

iDX6011/iDX6012 Controller Source

The iDX6011/iDX6012 series uses a different LED protocol than the DX/DXP models. The installer defaults to --controller-source auto, which checks the DMI product name and selects the iDX profile only for iDX6011 or iDX6012.

sudo bash install_ugreen_leds_controller.sh --controller-source auto
sudo bash install_ugreen_leds_controller.sh --controller-source idx6011  # force iDX profile
sudo bash install_ugreen_leds_controller.sh --controller-source upstream # force DX/DXP upstream profile

Until iDX support is merged upstream, the iDX profile expects TrueNAS kernel modules built from klein0r/ugreen_leds_controller and published on the temporary idx6011-kmods artifact branch in this repository. The build-idx6011-truenas-kmods GitHub Actions workflow builds missing artifacts for the supported TrueNAS SCALE trains (24.04, 24.10, 25.04, and 25.10) from pinned source commit 480f114bae69ec2bb7003df5d9c13f788ca6ace6. When upstream publishes compatible artifacts, only the profile constants in the installer should need to change.

For iDX network LEDs, the installed monitor auto-detects network_stat and network_stat2. Optional overrides can be set in /etc/ugreen-leds.conf:

NETDEV_LED_NAMES="network_stat network_stat2"
NETDEV_INTERFACE_NAMES="enp1s0 enp2s0"

TrueNAS Scale Read-Only Filesystem Support

NEW: The installer now supports TrueNAS Scale systems with read-only root filesystems (common when Nvidia drivers are installed).

Key Features

  • ✅ Persistent Storage: Stores kernel module and scripts on a writable ZFS pool location
  • ✅ Version Tracking: Only downloads kernel modules when TrueNAS version changes
  • ✅ Smart Reuse: Reuses existing files on subsequent boots (no re-download)
  • ✅ Auto-Recovery: Survives TrueNAS updates when configured as Init Script
  • ✅ Config Preservation: Your /etc/ugreen-leds.conf settings always persist

Installation Options

Important: Script Location Requirements

⚠️ The script MUST be run from a location under /mnt/ (on a ZFS pool) to ensure persistence across reboots on TrueNAS Scale. The script will abort if run from outside /mnt/.

Automatic Detection

The script intelligently detects the persistent directory location:

  1. Script in leds_controller/ directory: If the script is already located in a folder named leds_controller, this folder is used as the persistent directory.

    # Example: Script is at /mnt/tank/apps/leds_controller/install_ugreen_leds_controller.sh
cd /mnt/tank/apps/leds_controller
sudo bash install_ugreen_leds_controller.sh --yes

  2. Existing leds_controller/ at same level: If a leds_controller directory exists at the same level as the script, it will be reused.

    # Example: Script is at /mnt/tank/apps/install_ugreen_leds_controller.sh
# and /mnt/tank/apps/leds_controller/ already exists
cd /mnt/tank/apps
sudo bash install_ugreen_leds_controller.sh --yes

  3. New installation: If neither condition above is met, the script creates a new leds_controller/ directory.

Manual Installation Options

Option 1: Interactive (Recommended for first-time setup)

cd /mnt/<POOL>/<DATASET>/<FOLDER>
sudo bash install_ugreen_leds_controller.sh

The installer will prompt you to choose a persistent storage location.

Option 2: Use Current Directory

cd /mnt/<POOL>/<DATASET>/<FOLDER>
sudo bash install_ugreen_leds_controller.sh --use-current-dir

Creates leds_controller/ in your current directory.

Option 3: Specify Pool Path

sudo bash install_ugreen_leds_controller.sh --pool-path <POOL>/<DATASET>/<FOLDER>

Example: --pool-path tank/apps/ugreen

Option 4: Explicit Persistent Directory

sudo bash install_ugreen_leds_controller.sh --persist-dir /mnt/<POOL>/<PATH>/leds_controller

TrueNAS UI Integration (Automatic Startup)

To ensure LED controller starts after every reboot:

  1. Copy the installer to the persistent directory (if not already there):

    cp install_ugreen_leds_controller.sh /mnt/<POOL>/<PATH>/leds_controller/

  2. Navigate to System Settings → Advanced → Init/Shutdown Scripts

  3. Click Add

  4. Configure:

    • Description: UGREEN LED Controller
    • Type: Command
    • Command: /bin/bash /mnt/<POOL>/<PATH>/leds_controller/install_ugreen_leds_controller.sh --yes
    • When: Post Init
    • Enabled: ✓ (checked)
    • Timeout: 10 seconds

  5. Click Save

Why this works:

  • The script detects it's running from inside the leds_controller/ directory
  • It uses that directory as the persistent storage location
  • The --yes flag enables non-interactive mode for automated execution
  • Version tracking ensures fast subsequent boots (~3-5 seconds, no re-download)

Persistent Directory Structure

The installer creates the following structure:

/mnt/<POOL>/<PATH>/leds_controller/
├── .version                                    # TrueNAS version tracker
├── led-ugreen.ko                               # Kernel module
├── install_ugreen_leds_controller.sh          # Installer copy for reuse
├── ugreen_leds_controller/                    # Cloned repository
│   └── scripts/
└── scripts/                                    # Installed scripts
    ├── ugreen-diskiomon
    ├── ugreen-netdevmon
    ├── ugreen-probe-leds
    └── ugreen-power-led

/etc/ugreen-leds.conf                          # Your configuration (writable)

Configuration Priority

The installer automatically handles configuration in the following priority order:

  1. Existing persistent config: Uses ${PERSIST_DIR}/ugreen-leds.conf if it exists
  2. Existing system config: Migrates /etc/ugreen-leds.conf to persistent directory (preserves your settings)
  3. Template config: Uses repository template for new installations

Migration Note: If you have an existing /etc/ugreen-leds.conf from a standard installation, it will be automatically detected and copied to your persistent directory on first run, preserving all your custom settings.

Command-Line Options

Options:
  -h                    Print help message
  -v <version>          Use specific TrueNAS version (e.g., 24.10.0)

  --persist-dir <path>  Specify custom persistent storage directory
  --use-current-dir     Use current working directory for leds_controller/ folder
  --pool-path <path>    Specify ZFS pool path under /mnt/
  --controller-source <auto|upstream|idx6011>
                        Select controller source profile (default: auto)

  --uninstall           Fully uninstall: stop services, unload modules, remove files
  --dry-run             Show actions without making changes
  --yes                 Non-interactive mode (assume yes to all prompts)
  --force               Allow destructive actions

Uninstalling

To preview the uninstall (no changes made):

sudo bash install_ugreen_leds_controller.sh --uninstall --dry-run

To fully uninstall:

sudo bash install_ugreen_leds_controller.sh --uninstall

For non-interactive uninstall (skips confirmation prompts):

sudo bash install_ugreen_leds_controller.sh --uninstall --yes

The uninstaller reverses all installation steps: stops services, removes service files, unloads kernel modules, removes configs, scripts, and optionally deletes the persistent directory. No internet access is required.

How It Works

  1. First Run: Downloads kernel module, installs scripts, copies installer
  2. Subsequent Runs: Checks version tracker, reuses existing files if version matches
  3. Version Change: Automatically downloads new kernel module when TrueNAS updates
  4. Read-Only Detection: Automatically adapts to read-only /usr filesystem

Troubleshooting

Check service status:

systemctl status ugreen-diskiomon.service
systemctl status ugreen-netdevmon@<interface>.service

View installer logs:

ls -lh /mnt/<POOL>/<PATH>/leds_controller/
cat /mnt/<POOL>/<PATH>/leds_controller/.version

Force module re-download:

rm /mnt/<POOL>/<PATH>/leds_controller/.version
/mnt/<POOL>/<PATH>/leds_controller/install_ugreen_leds_controller.sh --yes

Verify module is loaded:

lsmod | grep led_ugreen

Check persistent directory paths in services:

grep ExecStart /etc/systemd/system/ugreen-*.service

Migration from Standard Installation

If you have existing installation in system directories:

  1. Run the adapted installer with your preferred persistent directory option
  2. The script will automatically migrate your /etc/ugreen-leds.conf to the persistent directory
  3. Service files are updated to reference the new persistent directory paths
  4. Old files in /usr/bin remain but are unused
  5. Optionally remove old files: rm -f /usr/bin/ugreen-* /lib/modules/*/extra/led-ugreen.ko

Your configuration is preserved: The installer detects existing /etc/ugreen-leds.conf and copies it to the persistent directory automatically.

Additional Notes

  • Full usage, configuration details, and troubleshooting: project Wiki
  • Use --dry-run to preview actions without changing the system
  • Configuration changes in /etc/ugreen-leds.conf persist across reboots

Disclaimer

Use at your own risk. The author is not responsible for any damage caused by running this script.

About

Simple bash script to install ugreen_leds_controller from https://github.com/miskcoo/ugreen_leds_controller

Topics

truenas-scale ugreen-nas

Resources

Readme

License

GPL-3.0 license
Activity

Stars

93 stars

Watchers

11 watching

Forks

10 forks
Report repository

Releases 6

install_ugreen_leds_controller v2.0.9 Latest
Apr 18, 2026
+ 5 releases

Contributors

Languages