pihole-baremetal/README.md

pihole-baremetal

Introduction

Pi-hole is a network-wide ad-blocking DNS server that runs on a Raspberry Pi or other small computers. It blocks ads and trackers from your entire network, improving your privacy and reducing bandwidth usage.

Prerequisites

• A compatible operating system (Ubuntu, Debian, Fedora, Rocky, CentOS, Arch, openSUSE, etc.)
• Root or sudo access to the system
• Internet connectivity
• A static IP address (optional but recommended for stability)

Quick Install

Step-by-Step Installation

1. Open a Terminal: Access your terminal on the system where you want to install Pi-hole.

2. Run the Installer Script: Copy and paste the following command into your terminal and press Enter. This command downloads and executes the Pi-hole installation script.

   curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
     "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash
   

3. Follow the Prompts: The installer will guide you through the setup process. You can accept the default options or customize them according to your preferences.

Install Options

You can customize the installation by passing additional options to the installer script. Here are some common options:

• Fully Unattended: Installs Pi-hole with default settings without any prompts.

  curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
    "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --unattended
  

• Without Web Interface: Installs Pi-hole without the web interface (DNS only).

  curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
    "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --no-lighttpd
  

• Custom Upstream DNS: Specifies custom DNS servers.

  curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
    "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --dns1 8.8.8.8 --dns2 8.8.4.4
  

• Specify Interface and IP: Specifies the network interface and IP address.

  curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
    "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --interface eth0 --ipv4 192.168.1.10/24
  

• Force Install on Unsupported OS: Forces installation on unsupported operating systems.

  curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
    "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --skip-os-check --unattended
  

• Combine Options: You can combine multiple options as needed.

  curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
    "https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --unattended --dns1 9.9.9.9 --dns2 149.112.112.112
  

Advanced Configuration

Custom Blocklists

1. Open Admin Panel: Go to http://<your-pi-hole-ip>/admin and log in.
2. Group Management: Navigate to the "Group Management" section.
3. Adlists: Click on "Adlists" and add URLs of blocklists.
4. Update Gravity: Run pihole -g to update gravity.

Popular blocklist sources:

• Firebog (curated lists)
• StevenBlack/hosts

Custom DNS Records

Edit the /etc/pihole/custom.list file to add local DNS records.

Example:

192.168.1.100   mydevice.local

Firewall Rules

Pi-hole automatically sets up firewall rules using firewalld, ufw, or iptables. You can customize these rules as needed.

Example:

sudo ufw allow 53/tcp
sudo ufw allow 53/udp
sudo ufw allow 80/tcp
sudo ufw allow 4711/tcp

Logging

Pi-hole logs queries and FTL activity. You can view these logs using the following commands:

• Query Log: pihole -t
• FTL Log: tail -f /var/log/pihole/FTL.log
• Systemd Journal: journalctl -u pihole-FTL -f

Backup and Restore

Backup

Run the following command to create a backup:

pihole-manage backup

This will create a backup file in /etc/pihole/backups/.

Restore

To restore from a backup, place the backup file in /etc/pihole/backups/ and run:

pihole-manage restore <backup-file-name>

FAQ

Q: How do I reset the admin password?

A: Use the following command to reset the admin password:

pihole setpassword

Q: Why isn't DNS resolving?

A: Check if FTL is listening and test DNS resolution:

ss -tulpn | grep ':53'
dig @127.0.0.1 google.com

Restart DNS services if needed:

pihole restartdns

Q: Why isn't the web interface loading?

A: Check the status of the web server:

systemctl status lighttpd

Restart the web server if needed:

systemctl restart lighttpd

Contributing

We welcome contributions to improve Pi-hole Bare Metal. To contribute, follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them.
4. Push your changes to your fork.
5. Open a pull request to the main branch of the original repository.

Thank you for contributing!