ce5674cb6c
- Supports Ubuntu, Debian, Fedora, Rocky, CentOS, RHEL, Arch, openSUSE - Automatic OS detection and dependency installation - Automatic network interface and IP detection - Configurable upstream DNS servers - Firewall configuration (firewalld/ufw/iptables) - Management helper script (pihole-manage) - Unattended installation option - FreeBSD redirects to AdGuard Home alternative
213 lines
5.2 KiB
Markdown
213 lines
5.2 KiB
Markdown
# pihole-baremetal
|
|
|
|
One-command Pi-hole installation on bare metal - network-wide ad blocking DNS server.
|
|
|
|
## Quick Install
|
|
|
|
```bash
|
|
curl -fsSL -H "Authorization: token 77e3ddaf262bb94f6fa878ca449cc1aa1129a00d" \
|
|
"https://git.vish.gg/Vish/pihole-baremetal/raw/branch/main/install.sh" | sudo bash
|
|
```
|
|
|
|
### Install Options
|
|
|
|
```bash
|
|
# Fully unattended (no prompts, uses defaults)
|
|
curl ... | sudo bash -s -- --unattended
|
|
|
|
# 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
|
|
|
|
```bash
|
|
pihole -a -p
|
|
```
|
|
|
|
### Configure Clients
|
|
|
|
Set your devices or router's DNS server to your Pi-hole's IP address.
|
|
|
|
**Router (recommended):** Set Pi-hole IP as the primary DNS in your router's DHCP settings. All devices will automatically use Pi-hole.
|
|
|
|
**Individual devices:** Manually set DNS to Pi-hole IP in network settings.
|
|
|
|
### Add Custom Blocklists
|
|
|
|
1. Open Admin Panel → Group Management → Adlists
|
|
2. Add URLs of blocklists
|
|
3. Run `pihole -g` to update gravity
|
|
|
|
Popular blocklist sources:
|
|
- https://firebog.net/ (curated lists)
|
|
- https://github.com/StevenBlack/hosts
|
|
|
|
## Management Commands
|
|
|
|
### Native Pi-hole Commands
|
|
|
|
```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
|
|
```
|
|
|
|
### Helper Script Commands
|
|
|
|
```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
|
|
```
|
|
|
|
## File Locations
|
|
|
|
| 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 |
|
|
|
|
## Troubleshooting
|
|
|
|
### Check if Pi-hole is running
|
|
|
|
```bash
|
|
pihole status
|
|
systemctl status pihole-FTL
|
|
```
|
|
|
|
### DNS not resolving
|
|
|
|
```bash
|
|
# Check if FTL is listening
|
|
ss -tulpn | grep ':53'
|
|
|
|
# Test DNS resolution
|
|
dig @127.0.0.1 google.com
|
|
|
|
# Restart services
|
|
pihole restartdns
|
|
```
|
|
|
|
### Web interface not loading
|
|
|
|
```bash
|
|
# Check lighttpd status
|
|
systemctl status lighttpd
|
|
|
|
# Restart lighttpd
|
|
systemctl restart lighttpd
|
|
```
|
|
|
|
### View logs for errors
|
|
|
|
```bash
|
|
pihole -t # Tail query log
|
|
tail -f /var/log/pihole/FTL.log # FTL log
|
|
journalctl -u pihole-FTL -f # Systemd journal
|
|
```
|
|
|
|
### Reset admin password
|
|
|
|
```bash
|
|
pihole -a -p
|
|
```
|
|
|
|
## 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
|