[Share] Pi-hole Ultra Script: A System Optimizer & Maintenance Tool for Debian

[waelisa]

Hello Pi-hole Community,

Pi-hole Debian Ultra Script - Complete Overview

What Is This Script?

A comprehensive system optimization tool for Debian-based systems running Pi-hole. It safely cleans, optimizes, and maintains your system with enterprise-grade safety features and rollback capability.

---

Core Functionality

1. System Optimization

• Removes orphaned packages - Identifies and removes unnecessary packages

• Disables non-essential services - Frees up system resources

• Cleans temporary files - Safe cleanup with process checking

• Updates system packages - Keeps your system current

• Optimizes Pi-hole - Updates gravity and Pi-hole itself

2. Safety & Recovery

• System Snapshots - Full backups before any changes

• Rollback Capability - Restore to any previous state

• Dry Run Mode - Preview changes without applying them

• Log Export - Save dry run results for review

3. Hardware-Specific Optimizations

• Raspberry Pi Detection - Auto-detects Pi hardware

• Smart Boot Config - Finds the active boot partition

• Pi-Specific Tweaks - GPU memory, boot delay, splash screen

• WiFi Power Saving - Optional WiFi disable for Ethernet users

4. Network Safety

• Connection Detection - Identifies if using WiFi vs Ethernet

• WiFi Warning - Warns before disabling active WiFi

• Confirmation Prompts - Never makes changes without asking

5. Maintenance

• Auto-Snapshot Cleanup - Removes snapshots older than 14 days

• Manual Snapshot Management - Delete individual or all snapshots

• Log Rotation - Manages system logs

---

Complete Menu Options

Option 1: Run Full Optimization

The all-in-one solution that:

• Auto-cleans old snapshots (>14 days)

• Creates a new system snapshot

• Shows orphaned packages for review

• Asks before removing anything

• Disables unnecessary services (with WiFi safety check)

• Applies Raspberry Pi optimizations (if detected)

• Cleans temporary files (with process check)

• Updates all system packages

• Optimizes Pi-hole

• Shows summary of changes

• Auto-reboots after 60 seconds unless cancelled

Option 2: Dry Run with Log Export

Safe preview mode that:

• Shows everything that WOULD be removed/changed

• Saves complete report to /tmp/pihole-dryrun-TIMESTAMP.txt

• Lists orphaned packages

• Shows services that would be disabled

• Displays WiFi warnings

• Lists Raspberry Pi packages to install

• Checks for processes using /tmp

• Asks if you want to view the log

• Makes NO actual changes

Option 3: Create System Snapshot

Manual backup that saves:

• Complete package list

• Pi-hole configurations

• dnsmasq configurations

• Boot config and full boot partition

• Service states

• Kernel version

• Distribution info

• Hardware model

• Network config

• Running processes

• Mount points

Option 4: Rollback System

Restore from any snapshot:

• Shows all available snapshots with sizes and dates

• Select which snapshot to restore

• Requires confirmation

• Restores package states

• Restores all configurations

• Restores boot partition

• Auto-reboots after 60 seconds

Option 5: Verify/Fix D-Bus Issues

Diagnoses and repairs D-Bus:

• Checks current D-Bus status

• Attempts to restart D-Bus

• Emergency fix if needed

• Verifies D-Bus is running

Option 6: Reinstall Raspberry Pi Components

For Pi hardware only:

• Reinstalls Raspberry Pi kernel

• Reinstalls bootloader

• Reinstalls firmware

• Reinstalls VideoCore libraries

• Updates EEPROM

• Reconfigures raspi-config

• Auto-reboots after 60 seconds

Option 7: Verify/Install Critical Packages

Checks for essential packages:

• Lists missing critical packages

• Includes Pi-specific packages when on Pi

• Option to install missing packages

• Verifies all core dependencies

Option 8: Setup Automated Pi-hole Updates

Configure automatic updates:

• Daily (3 AM)

• Weekly (Sundays 3 AM)

• Monthly (1st 3 AM)

• Custom cron schedule

• Disable automated updates

• Logs to /var/log/pihole-auto-update.log

Option 9: Quick System Info

Shows essential system information:

• Hostname and OS version

• Kernel version

• Uptime

• Memory usage

• Disk usage

• Network interface

• CPU temperature (on Pi)

• Pi-hole status and version

• D-Bus status

• Failed services count

• Snapshot count and size

• Processes using /tmp

Option 10: View System Health

Detailed health report:

• D-Bus status

• Failed services list

• Recent system errors

• Disk health

• Processes using /tmp

• Raspberry Pi specific (temp, throttling, voltage)

• Pi-hole status and query stats

Option 11: Cleanup Only

Safe, minimal cleanup:

• Removes orphaned packages

• Cleans APT cache

• Vacuums system journals (7 days)

• Safely cleans /tmp and /var/tmp (with process check)

• Shows before/after disk space

Option 12: Cleanup Old Snapshots

Manual snapshot management:

• Lists all snapshots with sizes

• Options to:

  • Remove all snapshots

  • Remove >30 days old

  • Keep only most recent

  • Select specific snapshots

  • Cancel

Option 13: DELETE ALL SNAPSHOTS

Dangerous but sometimes necessary:

• Shows ALL snapshots with sizes

• Requires typing "DELETE ALL" to confirm

• Immediate permanent deletion

• Use with extreme caution

---

Safety Features

Pre-Flight Checks

Every run verifies:

• Root privileges

• Available disk space (500MB minimum)

• Available memory (256MB recommended)

• Internet connectivity

• DNS resolution

• Backup directory writable

• Package manager working

• Pi-hole installation (if present)

Smart Detection

Automatically detects:

• Debian version (10, 11, 12)

• Raspberry Pi hardware

• Active network interface (WiFi vs Ethernet)

• Active boot partition (smart config detection)

• Processes using /tmp

Confirmation Prompts

Always asks before:

• Removing orphaned packages

• Disabling WiFi services

• Disabling WiFi hardware

• Creating snapshots when low on space

• Force cleanup when processes use /tmp

• Rollback operations

• Deleting snapshots

Recovery Options

If something goes wrong:

• Option 3 - Create manual snapshots anytime

• Option 4 - Rollback to any previous state

• Logs - Complete logs at /var/log/pihole-ultra.log

• Dry Run logs - Preview logs at /tmp/pihole-dryrun-*.txt

---

What Makes This Script "Production Grade"

1. Non-Destructive by Design - Always creates snapshots first

2. Full Audit Trail - Everything logged

3. Preview Before Action - Dry run shows everything

4. Recovery Built-In - Rollback to any point

5. Auto-Maintenance - Self-cleaning snapshots

6. Hardware-Aware - Smart detection for Pi

7. Network-Safe - Won't disconnect you accidentally

8. Process-Safe - Checks running processes before cleanup

9. Timeout Protection - Auto-reboot prevents half-finished states

10. Complete Transparency - Shows exactly what changed

---

Supported Systems

• Debian 10 (Buster)

• Debian 11 (Bullseye)

• Debian 12 (Bookworm)

• Raspberry Pi OS (all versions)

• Raspbian (all versions)

• Ubuntu 20.04 LTS

• Ubuntu 22.04 LTS

• Any Debian-based distribution

---

The Philosophy

"A stable Pi-hole keeps the internet peaceful!"

This script follows three core principles:

1. Safety First - Never make changes without a way back

2. Transparency - Show exactly what will happen before it happens

3. Automation - Handle maintenance automatically so you don't have to think about it

---

File Locations

Item	Location
Main Log	/var/log/pihole-ultra.log
Snapshots	/root/pihole-system-backups/
Dry Run Logs	/tmp/pihole-dryrun-*.txt
Auto-Update Log	/var/log/pihole-auto-update.log
Boot Config	Auto-detected (/boot/config.txt or /boot/firmware/config.txt)

---

Quick Start

bash

# Download the script
wget https://raw.githubusercontent.com/waelisa/Raspberry-Pi-Pi-hole-Debian-Ultra-Script/main/pihole-ultra.sh

# Make it executable
chmod +x pihole-ultra.sh

# Run as root
sudo ./pihole-ultra.sh

Then:

1. Option 2 first - Dry run to see what will change

2. Review the log at /tmp/pihole-dryrun-*.txt

3. Option 1 - Run full optimization when ready

4. If anything goes wrong, Option 4 to rollback

Best regards,

Wael Isa

[jockesve]

First of all: Thanks!

Any plans to create a ‘Trixie’ version of this?

Unfortunately I updated my RPi’s to Trixie a while back…

[robgill]

Your deletion of everything in /tmp and /var/tmp seems a little heavy handed and maybe shouldn't be described as "safe".

It could cause any manner of problems for running tasks relying on files in either of those directories. It's safe to delete files created by tasks that have completed though.

[buntspexxt]

Plus:

rm -f /run/dbus/system_bus_socket

Never delete a socket file!

[waelisa]

Trixie !
sure will be in next update for all Debian,
now i’m work for Pi-hole + DNSCrypt-Proxy + Unbound: Ultimate Masterpiece Edition full auto install and everything ready with ease, config for privacy, and install everything.
I’ll write post here when script ready soon today maybe

[waelisa]

what task you mean?

[waelisa]

I’ll update the script to work with all Debian and fix this too, today.

[robgill]

I mean any task that is still executing.

sudo ps x for a list

Any of those may still be relying upon files present in /tmp.

[waelisa]

v2.1.5 - Final Production Release

What's New in this Version:

1. Professional Banner & Branding

   • Clean ASCII art banner

   • Consistent styling throughout

2. Enhanced Information Display

   • Shows supported Debian versions

   • Clear safety features list

   • Snapshot count in menu

3. Improved Rollback Function

   • Added auto-reboot timeout (same as optimization)

   • Better date formatting for snapshots

   • Emergency backup preservation

4. Better System Health View

   • Added Pi-hole query statistics

   • Raspberry Pi voltage monitoring

   • More detailed system info

5. Enhanced Cleanup Functions

   • Shows before/after disk space

   • Counts removed snapshots

   • Better user feedback

6. Production-Ready Features

   • Auto-cleanup of old snapshots (14 days)

   • 60-second reboot timeout

   • WiFi safety detection

   • Complete rollback capability

   • Comprehensive logging

The Script is Now:

Safe - Creates snapshots before any changes
Reliable - Auto-reboot prevents half-finished states
Maintainable - Auto-cleans old snapshots
Transparent - Dry-run mode shows exactly what will change
Recoverable - Full rollback capability
Informative - Shows summary of all changes
Universal - Works on all Debian-based systems
Pi-Optimized - Special handling for Raspberry Pi

Conclusion:

You can now run this script with complete confidence. It includes every safety feature imaginable:

• Pre-flight checks

• Automatic snapshots

• Snapshot retention policy

• WiFi connection detection

• Confirmation prompts

• Dry-run mode

• Rollback capability

• Auto-reboot timeout

• Comprehensive logging

If anything goes wrong (which is highly unlikely), you have:

• Option 3 to create manual snapshots anytime

• Option 4 to rollback to any previous state

• Full logs at /var/log/pihole-ultra.log

[waelisa]

What's New in v2.1.6:

1. Process Checking for /tmp Cleanup

• Added check_tmp_processes() function that uses lsof to find processes using /tmp

• Shows warning if any processes are relying on temporary files

• Prevents cleaning /tmp if it might crash running services

• Added lsof to required tools

2. Safe Cleanup with Confirmation

• New safe_cleanup() function with process checking

• If processes are using /tmp, shows the list and asks for confirmation

• Option to view full process list before proceeding

• Prevents accidental crashes

3. DELETE ALL SNAPSHOTS Option (Dangerous)

• New Option 13 in main menu: "DELETE ALL SNAPSHOTS (dangerous)"

• New delete_all_snapshots() function

• Shows list of all snapshots with sizes before deletion

• Requires typing "DELETE ALL" to confirm (extra safety)

• Also available in the cleanup snapshots menu as option 5

4. Enhanced System Information

• Shows number of processes using /tmp in the menu

• Added to quick system info

• Added to optimization summary

• Shows warning if processes still using /tmp after optimization

5. Better Safety Features

• Process checking integrated into full optimization (Step 6)

• Added to cleanup-only mode

• Dry run now shows warning about /tmp processes

• Added to system health view

6. Improved Error Handling

• All cleanup operations now check for running processes

• Confirmation prompts for dangerous operations

• Better feedback about system state

Final Status:

The script is now COMPLETE and PRODUCTION-READY with:

Full Safety: Pre-flight checks, snapshots, rollback
Process Safety: Checks for processes using /tmp before cleanup
Snapshot Management: Auto-cleanup (14 days), manual cleanup, DANGEROUS delete all
Network Safety: WiFi detection to prevent disconnection
Preview Mode: Dry run shows exactly what will change
Visual Feedback: Summary of all changes made
Auto-Reboot: 60-second countdown with cancel option
Comprehensive Logging: Everything logged to /var/log/pihole-ultra.log

You can now run this script with 100% confidence that it won't break your running system by cleaning files that are in use.

[waelisa]

What's New in v2.1.7:

1. Smart Boot Config Detection (detect_boot_config())

• Checks mounted boot partitions first (most accurate)

• Falls back to standard paths if needed

• Handles ambiguous cases (both files present) by asking user

• Stores both path and mount point for complete backup/restore

2. Enhanced Boot Partition Backup

• Backs up the entire boot partition when possible

• Stores mount point info in snapshots

• Restores to the correct location automatically

3. Better Raspberry Pi Support

• Shows active boot config in menu and system info

• Optimizes the correct config file every time

• Handles all Raspberry Pi OS versions (old and new)

4. Improved Safety

• Never guesses which config file to use

• Always uses the actually mounted boot partition

• User confirmation if ambiguous

5. Complete Integration

• Pre-flight checks now detect boot config

• Snapshots include full boot partition

• Rollback restores to correct location

• Optimization uses correct config file

Why This Matters:

On some Raspberry Pi OS versions, both /boot/config.txt and /boot/firmware/config.txt exist, but only one is actually used by the system. Before v2.1.7, the script might have edited the wrong one. Now it:

1. Checks what's actually mounted via mount | grep /boot

2. Finds the real active config file

3. Backs up the entire boot partition for safety

4. Restores to the exact same location

The Script is Now:

100% Accurate - Always edits the right config file
Universal - Works on all Raspberry Pi OS versions
Safe - Full boot partition backups
Smart - Handles ambiguous cases gracefully
Complete - Every feature now uses smart detection

This is the final, production-ready version. It will work perfectly on any Debian-based system, with special attention to Raspberry Pi's sometimes-tricky boot configuration.

[waelisa]

What's New in v2.1.8:

1. Dry Run Log Export (DRY_RUN_LOG variable)

• Automatically saves dry run output to /tmp/pihole-dryrun-YYYYMMDD-HHMMSS.txt

• Timestamped filename for easy identification

• Complete report of everything that would be removed/changed

2. Enhanced Dry Run Output

• Screen display still shows everything in real-time

• Log file contains the same information plus:

  • System information header

  • Timestamp

  • Complete list of orphaned packages

  • Services that would be disabled

  • WiFi warnings

  • Raspberry Pi packages to install

  • Process list if using /tmp

3. Post-Dry Run Options

• After dry run completes, asks if you want to view the log

• Uses less for easy scrolling through long lists

• Log persists after script exits for later review

4. Menu Enhancement

• Option 2 now says: "Dry Run (Preview with log export)"

• Exit message mentions dry run logs location

5. Information Screen Updated

• Added "Dry Run logs at: /tmp/pihole-dryrun-*.txt" to info

• Added to safety features list

Why This Matters:

Before v2.1.8, if you had 50+ orphaned packages, they'd scroll off the screen and you'd lose the list. Now:

1. Run Option 2 - See everything on screen AND saved to file

2. Review the log at your leisure with cat /tmp/pihole-dryrun-*.txt

3. Check for custom drivers that deborphan might have flagged

4. Be 100% confident before running Option 1

The Script is Now COMPLETE:

Full Safety: Pre-flight checks, snapshots, rollback
Process Safety: Checks for processes using /tmp before cleanup
Snapshot Management: Auto-cleanup (14 days), manual cleanup, dangerous delete all
Network Safety: WiFi detection to prevent disconnection
Preview Mode: Dry run with log export for complete review
Boot Config: Smart detection of active boot partition
Visual Feedback: Summary of all changes made
Auto-Reboot: 60-second countdown with cancel option
Comprehensive Logging: Everything logged to multiple locations

This is the final production version. It's been through 8 iterations and includes every safety feature imaginable. You can run this on any Debian-based system with complete confidence.

[waelisa]

I upload info about last 4 ver, review the code, now more safe.

[waelisa]

Key Improvements in v2.2.1:

1. Removed all deborphan references - No more installation attempts or errors

2. New cleanup_system() function - Standardized cleanup using native apt tools

3. Updated orphan detection - Uses apt-mark, apt-cache rdepends, and apt-get autoremove --dry-run

4. Added menu option 15 - Quick "Standard System Cleanup" using the new function

5. Updated documentation - Mentions native apt orphan detection for Debian 13+

6. Faster execution - Native tools are significantly faster than deborphan

This version will work perfectly on Debian 13 (Trixie) and all older versions without any errors about missing packages.

[rdwebdesign]

@waelisa

Suggestion:

Maybe it would be better if you create a CHANGELOG file on your repository and keep here only the discussion with other users. You could still post "New version XXXX - check the changes" with a link to your repo.

Your posts are long and I think users will find it hard to follow the questions/suggestions/comments about the script.