Vish/pihole-baremetal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md with improved documentation #1

Merged
Vish merged 1 commits from update-readme-documentation into main 2026-02-01 22:28:03 -08:00
Conversation 1 Commits 1 Files Changed 1 +127 -157
1 changed files with 127 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

286
README.md
View File

@@ -1,216 +1,186 @@
# pihole-baremetal
One-command Pi-hole installation on bare metal - network-wide ad blocking DNS server.
## 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.
```bash
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
```bash
# Fully unattended (no prompts, uses defaults)
curl ... | sudo bash -s -- --unattended
You can customize the installation by passing additional options to the installer script. Here are some common options:
# Without web interface (DNS only)
curl ... | sudo bash -s -- --no-lighttpd
# Custom upstream DNS
curl ... | sudo bash -s -- --dns1 8.8.8.8 --dns2 8.8.4.4
# Specify interface and IP
curl ... | sudo bash -s -- --interface eth0 --ipv4 192.168.1.10/24
# Force install on unsupported OS
curl ... | sudo bash -s -- --skip-os-check --unattended
# Combine options
curl ... | sudo bash -s -- --unattended --dns1 9.9.9.9 --dns2 149.112.112.112
```
## What It Does
**Zero intervention required.** The installer automatically:
- Detects your OS (Ubuntu, Debian, Fedora, Rocky, CentOS, Arch, openSUSE)
- Installs all required dependencies
- Detects your network interface and IP address
- Configures Pi-hole with sensible defaults
- Sets up firewall rules (firewalld/ufw/iptables)
- Creates a management helper script
**Run one command, wait 2-3 minutes, done.**
## Supported Systems
| OS | Version | Status |
|----|---------|--------|
| Ubuntu | 20.04, 22.04, 24.04+ | ✅ Official |
| Debian | 10, 11, 12+ | ✅ Official |
| Raspberry Pi OS | All | ✅ Official |
| Fedora | 38+ | ✅ Official |
| CentOS / RHEL | 8, 9+ | ✅ Official |
| Rocky Linux | 8, 9+ | ✅ Official |
| AlmaLinux | 8, 9+ | ✅ Official |
| Linux Mint | 20, 21, 22+ | ✅ Works |
| Pop!_OS | 22.04+ | ✅ Works |
| Arch Linux | Rolling | ⚠️ Experimental |
| Manjaro | Rolling | ⚠️ Experimental |
| openSUSE | Leap/Tumbleweed | ⚠️ Experimental |
| FreeBSD | - | ❌ Use AdGuard Home |
## Services & Ports
| Service | Port | Description |
|---------|------|-------------|
| DNS | 53/tcp, 53/udp | DNS resolver |
| Web Admin | 80/tcp | Admin interface |
| FTL | 4711/tcp | Pi-hole FTL API |
## Post-Install Configuration
### Set Admin Password
- **Fully Unattended**: Installs Pi-hole with default settings without any prompts.
```bash
# Pi-hole v6+
pihole setpassword
# Pi-hole v5 (legacy)
pihole -a -p
curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
"https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --unattended
```
### Configure Clients
- **Without Web Interface**: Installs Pi-hole without the web interface (DNS only).
Set your devices or router's DNS server to your Pi-hole's IP address.
```bash
curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
"https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash -s -- --no-lighttpd
```
**Router (recommended):** Set Pi-hole IP as the primary DNS in your router's DHCP settings. All devices will automatically use Pi-hole.
- **Custom Upstream DNS**: Specifies custom DNS servers.
**Individual devices:** Manually set DNS to Pi-hole IP in network settings.
```bash
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
```
### Add Custom Blocklists
- **Specify Interface and IP**: Specifies the network interface and IP address.
1. Open Admin Panel → Group Management → Adlists
2. Add URLs of blocklists
3. Run `pihole -g` to update gravity
```bash
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.
```bash
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.
```bash
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:
- https://firebog.net/ (curated lists)
- https://github.com/StevenBlack/hosts
- [Firebog](https://firebog.net/) (curated lists)
- [StevenBlack/hosts](https://github.com/StevenBlack/hosts)
## Management Commands
### Custom DNS Records
### Native Pi-hole Commands
Edit the `/etc/pihole/custom.list` file to add local DNS records.
```bash
pihole status # Show status
pihole -c # Console dashboard (live)
pihole -up # Update Pi-hole
pihole -g # Update blocklists (gravity)
pihole -q example.com # Query logs for domain
pihole -w example.com # Whitelist domain
pihole -b example.com # Blacklist domain
pihole enable # Enable blocking
pihole disable # Disable blocking
pihole disable 5m # Disable for 5 minutes
pihole restartdns # Restart DNS resolver
pihole -a -p # Change admin password
pihole -t # Tail the log
Example:
```
192.168.1.100 mydevice.local
```
### Helper Script Commands
### Firewall Rules
Pi-hole automatically sets up firewall rules using `firewalld`, `ufw`, or `iptables`. You can customize these rules as needed.
Example:
```bash
pihole-manage status # Show Pi-hole and service status
pihole-manage logs # Tail Pi-hole log
pihole-manage ftl-logs # Tail FTL log
pihole-manage stats # Show statistics
pihole-manage top-ads # Show top blocked domains
pihole-manage gravity # Update blocklists
pihole-manage backup # Create backup
pihole-manage password # Change admin password
sudo ufw allow 53/tcp
sudo ufw allow 53/udp
sudo ufw allow 80/tcp
sudo ufw allow 4711/tcp
```
## File Locations
### Logging
| Path | Description |
|------|-------------|
| `/etc/pihole/` | Pi-hole configuration |
| `/etc/pihole/setupVars.conf` | Installation settings |
| `/etc/pihole/custom.list` | Local DNS records |
| `/etc/dnsmasq.d/` | Dnsmasq configuration |
| `/var/log/pihole/` | Log files |
| `/var/log/pihole/pihole.log` | Query log |
| `/var/log/pihole/FTL.log` | FTL engine log |
| `/opt/pihole/` | Pi-hole scripts |
Pi-hole logs queries and FTL activity. You can view these logs using the following commands:
## Troubleshooting
- **Query Log**: `pihole -t`
- **FTL Log**: `tail -f /var/log/pihole/FTL.log`
- **Systemd Journal**: `journalctl -u pihole-FTL -f`
### Check if Pi-hole is running
### Backup and Restore
#### Backup
Run the following command to create a backup:
```bash
pihole status
systemctl status pihole-FTL
pihole-manage backup
```
### DNS not resolving
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:
```bash
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:
```bash
pihole setpassword
```
### Q: Why isn't DNS resolving?
**A**: Check if FTL is listening and test DNS resolution:
```bash
# Check if FTL is listening
ss -tulpn | grep ':53'
# Test DNS resolution
dig @127.0.0.1 google.com
```
# Restart services
Restart DNS services if needed:
```bash
pihole restartdns
```
### Web interface not loading
### Q: Why isn't the web interface loading?
**A**: Check the status of the web server:
```bash
# Check lighttpd status
systemctl status lighttpd
```
# Restart lighttpd
Restart the web server if needed:
```bash
systemctl restart lighttpd
```
### View logs for errors
## Contributing
```bash
pihole -t # Tail query log
tail -f /var/log/pihole/FTL.log # FTL log
journalctl -u pihole-FTL -f # Systemd journal
```
We welcome contributions to improve Pi-hole Bare Metal. To contribute, follow these steps:
### Reset admin password
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.
```bash
pihole setpassword
```
## Uninstall
```bash
pihole uninstall
```
This will remove Pi-hole and optionally its dependencies.
## Upstream DNS Options
| Provider | DNS 1 | DNS 2 |
|----------|-------|-------|
| Cloudflare | 1.1.1.1 | 1.0.0.1 |
| Google | 8.8.8.8 | 8.8.4.4 |
| Quad9 | 9.9.9.9 | 149.112.112.112 |
| OpenDNS | 208.67.222.222 | 208.67.220.220 |
| Cloudflare (malware) | 1.1.1.2 | 1.0.0.2 |
| Cloudflare (family) | 1.1.1.3 | 1.0.0.3 |
## License
MIT
Thank you for contributing!