Raspberry Pi Zero 2 W - Pi-hole DNS Server Scripts & Configurations

This repository contains all automation scripts, optimizations, and configurations for a high-performance Pi-hole DNS server running on Raspberry Pi Zero 2 W.

🏗️ Repository Structure

├── scripts/
│   ├── automation/          # Automated maintenance scripts
│   ├── optimization/        # Performance optimization scripts
│   └── management/          # Management and utility scripts
├── configs/
│   ├── pihole/             # Pi-hole specific configurations
│   ├── system/             # Systemd services and timers
│   └── unbound/            # Unbound DNS resolver configs
├── docs/                   # Documentation and guides
├── backups/               # Configuration backups
└── deploy/                # Deployment scripts

📦 What's Included

Automation Scripts

• Pi-hole Gravity Updates: Weekly automated blocklist updates with health checks
• System Updates: Automated OS security and package updates
• Performance Monitoring: System resource monitoring and alerting

Optimization Scripts

• Pi-hole Performance: DNS cache optimization for limited RAM (416MB)
• System Performance: Kernel parameter tuning for DNS workloads
• Unbound Optimization: DNS resolver tuning for Pi Zero 2 W hardware

Management Tools

• Backup & Restore: Complete configuration backup and rollback procedures
• Health Monitoring: Service status checking and performance validation
• Update Management: Selective update controls (security-only vs full updates)

🚀 Quick Start

Prerequisites

• Raspberry Pi Zero 2 W (or similar low-resource Pi)
• Raspberry Pi OS (Debian-based)
• Pi-hole installed and configured
• Unbound DNS resolver (optional but recommended)

Deployment

1. Clone this repository:

   git clone <repository-url>
   cd pi-scripts-backup

2. Run the deployment script:

   sudo ./deploy/install.sh

3. Verify services are running:

   ./scripts/management/system-health-check.sh

🔧 Configuration

Automated Updates

• Pi-hole Gravity: Weekly updates on Sundays at 3:00 AM
• System Updates: Weekly updates on Saturdays at 2:00 AM
• Randomization: Up to 30-60 minutes delay to distribute load

Performance Optimizations

• DNS Cache: Optimized for 416MB RAM system
• Memory Management: Reduced swap usage and memory pressure
• Network Tuning: UDP buffer optimizations for DNS workloads

📊 Performance Results

Before Optimization

• DNS Query Time: 4ms average
• Available RAM: 268MB
• Swap Usage: 69MB
• System Load: 0.29

After Optimization

• DNS Query Time: 0ms (cached), 4ms (uncached)
• Available RAM: 299MB (+30MB improvement)
• Swap Usage: 43MB (-26MB improvement)
• System Load: 0.17 (-41% improvement)

🛡️ Backup & Recovery

Automatic Backups

All configurations are automatically backed up before any changes:

• Pi-hole configs: /home/pi/pihole-backups/
• System configs: /home/pi/system-backups/
• Unbound configs: /home/pi/unbound-backups/

Rollback Procedures

Complete rollback available via:

sudo /home/pi/scripts/rollback-optimizations.sh

📋 Management Commands

Pi-hole Management

# Check Pi-hole status and next update
./scripts/management/pihole-gravity-manager.sh status

# Manual gravity update
./scripts/management/pihole-gravity-manager.sh run

# View update logs
./scripts/management/pihole-gravity-manager.sh logs

System Management

# Check system status and available updates
./scripts/management/raspi-update-manager.sh summary

# Run security updates only
./scripts/management/raspi-update-manager.sh security

# Full system update
./scripts/management/raspi-update-manager.sh run

🔍 Monitoring & Logs

Log Locations

• Pi-hole Updates: /var/log/pihole-scripts/
• System Updates: /var/log/system-update/
• Service Logs: journalctl -u <service-name>

Health Checks

• DNS resolution testing
• Service availability monitoring
• Resource usage validation
• Network connectivity verification

⚙️ Hardware Specifications

Target Hardware

• Model: Raspberry Pi Zero 2 W
• RAM: 512MB (416MB available to OS)
• CPU: Quad-core ARM Cortex-A53 @ 1GHz
• Storage: MicroSD (minimum 16GB recommended)

Resource Usage (Optimized)

• RAM Usage: ~117MB for system + Pi-hole + Unbound
• CPU Usage: ~5% average with DNS queries
• Disk Usage: ~2.6GB for OS + applications + logs

🤝 Contributing

Feel free to submit issues, feature requests, or improvements via GitHub issues and pull requests.

📜 License

This project is open source and available under the MIT License.

⚠️ Disclaimer

These scripts are optimized for Raspberry Pi Zero 2 W hardware constraints. Adjust configurations as needed for different hardware specifications.

---

Last Updated: July 2025
Compatible with: Raspberry Pi OS (Debian 12 "Bookworm"), Pi-hole v5.x+, Unbound 1.17+