HaGeZi DNS Blocklist API

A high-performance Rust API backend for serving HaGeZi DNS blocklists with Pi-hole and Docker integration.

🚀 Features

• Fast & Efficient: Built with Rust and Axum for maximum performance
• Multiple Formats: Support for domains, hosts, adblock, dnsmasq, wildcard, and RPZ formats
• Intelligent Caching: Built-in caching with TTL and size limits
• Pi-hole Integration: Direct integration with Pi-hole through API endpoints and scripts
• Docker Ready: Complete Docker and Docker Compose setup
• RESTful API: Clean REST API with comprehensive endpoints
• Configurable: Flexible configuration through files and environment variables

📋 Table of Contents

• Quick Start
• API Endpoints
• Configuration
• Docker Deployment
• Pi-hole Integration
• Development
• Contributing

🏃 Quick Start

Using Docker (Recommended)

# Clone the repository
git clone <repository-url>
cd hagezi-api

# Start with Docker Compose
docker-compose up -d

# Check if the API is running
curl http://localhost:3000/health

Manual Installation

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone <repository-url>
cd hagezi-api
cargo build --release

# Run the application
./target/release/hagezi-api

🔌 API Endpoints

Health & Status

• GET /health - Health check endpoint
• GET /api/status - API status and information

Blocklist Endpoints

• GET /api/blocklist/{level} - Get blocklist by level

  • Levels: light, normal, pro, proplus, ultimate
  • Query parameters:
    • format: domains, hosts, adblock, dnsmasq, wildcard, rpz
    • level: Override the URL level parameter

• POST /api/compile - Compile custom blocklist

  • Body: JSON with compilation parameters

Pi-hole Integration

• GET /api/pihole/blocklist/{level} - Pi-hole optimized blocklist
• POST /api/pihole/update - Trigger Pi-hole update
• GET /api/pihole/status - Pi-hole integration status

Cache Management

• GET /api/cache/stats - Cache statistics
• POST /api/cache/clear - Clear cache

⚙️ Configuration

Configuration File

Create config/config.toml:

[server]
host = "0.0.0.0"
port = 3000

[cache]
ttl_hours = 24
max_size = 100

[fetcher]
timeout_seconds = 30
user_agent = "HaGeZi-API/1.0"

[blocklists]
base_url = "https://raw.githubusercontent.com/hagezi/dns-blocklists/main"

[pihole]
enabled = true
update_interval_hours = 6

Environment Variables

All configuration options can be overridden with environment variables using the HAGEZI_ prefix:

export HAGEZI_SERVER_HOST=0.0.0.0
export HAGEZI_SERVER_PORT=3000
export HAGEZI_CACHE_TTL_HOURS=24
export HAGEZI_CACHE_MAX_SIZE=100
export HAGEZI_FETCHER_TIMEOUT_SECONDS=30
export HAGEZI_FETCHER_USER_AGENT="HaGeZi-API/1.0"

🐳 Docker Deployment

Docker Compose (Recommended)

The included docker-compose.yml provides a complete setup with:

• HaGeZi API service
• Pi-hole integration
• Optional Redis for advanced caching

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f hagezi-api

# Stop services
docker-compose down

Standalone Docker

# Build the image
docker build -t hagezi-api .

# Run the container
docker run -d \
  --name hagezi-api \
  -p 3000:3000 \
  -e HAGEZI_SERVER_HOST=0.0.0.0 \
  -e HAGEZI_SERVER_PORT=3000 \
  hagezi-api

🥧 Pi-hole Integration

Automatic Updates

Use the provided script to automatically update Pi-hole with HaGeZi blocklists:

# Make the script executable
chmod +x scripts/pihole-update.sh

# Run with default settings (normal level, domains format)
./scripts/pihole-update.sh

# Run with custom settings
./scripts/pihole-update.sh --level pro --format domains --api-url http://localhost:3000

Cron Job Setup

Add to your crontab for automatic updates:

# Update Pi-hole with HaGeZi blocklists every 6 hours
0 */6 * * * /path/to/hagezi-api/scripts/pihole-update.sh

Manual Pi-hole Configuration

1. Access Pi-hole admin interface
2. Go to Group Management > Adlists
3. Add the HaGeZi API endpoint:

   http://localhost:3000/api/pihole/blocklist/normal
   

4. Update gravity: pihole -g

🛠️ Development

Prerequisites

• Rust 1.70+ (latest stable recommended)
• OpenSSL development libraries

Building from Source

# Clone the repository
git clone <repository-url>
cd hagezi-api

# Install dependencies (Ubuntu/Debian)
sudo apt-get install pkg-config libssl-dev

# Build in development mode
cargo build

# Run with debug logging
RUST_LOG=debug cargo run

# Run tests
cargo test

# Format code
cargo fmt

# Lint code
cargo clippy

Project Structure

hagezi-api/
├── src/
│   ├── api/           # API handlers and routes
│   ├── blocklist/     # Blocklist management
│   ├── config/        # Configuration handling
│   ├── error/         # Error types and handling
│   ├── models/        # Data models
│   └── main.rs        # Application entry point
├── config/            # Configuration files
├── scripts/           # Integration scripts
├── Dockerfile         # Docker configuration
├── docker-compose.yml # Docker Compose setup
└── README.md          # This file

📊 API Examples

Get Normal Level Blocklist in Domains Format

curl "http://localhost:3000/api/blocklist/normal?format=domains"

Get Pro Level Blocklist in Hosts Format

curl "http://localhost:3000/api/blocklist/pro?format=hosts"

Check API Status

curl http://localhost:3000/api/status

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "cache_stats": {
    "entries": 5,
    "hit_rate": 0.85
  }
}

Pi-hole Optimized Endpoint

curl "http://localhost:3000/api/pihole/blocklist/normal"

🔧 Troubleshooting

Common Issues

1. Port already in use

   # Change port in config or environment
   export HAGEZI_SERVER_PORT=3001

2. SSL/TLS errors

   # Install SSL development libraries
   sudo apt-get install libssl-dev pkg-config

3. Permission denied (Docker)

   # Add user to docker group
   sudo usermod -aG docker $USER
   # Log out and back in

Logging

Enable debug logging:

export RUST_LOG=hagezi_api=debug,tower_http=debug

Health Checks

The API provides several health check endpoints:

• /health - Basic health check
• /api/status - Detailed status information

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Code Style

• Use cargo fmt for formatting
• Use cargo clippy for linting
• Write tests for new functionality
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• HaGeZi for providing excellent DNS blocklists
• Pi-hole for the amazing network-wide ad blocking
• The Rust community for excellent crates and tools

📞 Support

• Create an issue for bug reports or feature requests
• Check existing issues before creating new ones
• Provide detailed information for faster resolution

---

Made with ❤️ and Rust