Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ryzalain/hagezi-dns-api

Quick and Easy DNS Configuration w/ The Best Blocklists by HaGeZi
https://github.com/ryzalain/hagezi-dns-api

dns docker hagezi pi-hole-blocklists rust security

Last synced: 20 days ago
JSON representation

Quick and Easy DNS Configuration w/ The Best Blocklists by HaGeZi

Awesome Lists containing this project

README 

          
# 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](#quick-start)

- [API Endpoints](#api-endpoints)

- [Configuration](#configuration)

- [Docker Deployment](#docker-deployment)

- [Pi-hole Integration](#pi-hole-integration)

- [Development](#development)

- [Contributing](#contributing)



## 🏃 Quick Start



### Using Docker (Recommended)



```bash

# Clone the repository

git clone 

cd hagezi-api



# Start with Docker Compose

docker-compose up -d



# Check if the API is running

curl http://localhost:3000/health

```



### Manual Installation



```bash

# Install Rust (if not already installed)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh



# Clone and build

git clone 

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`:



```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:



```bash

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



```bash

# Start all services

docker-compose up -d



# View logs

docker-compose logs -f hagezi-api



# Stop services

docker-compose down

```



### Standalone Docker



```bash

# 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:



```bash

# 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:



```bash

# 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



```bash

# Clone the repository

git clone 

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



```bash

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

```



### Get Pro Level Blocklist in Hosts Format



```bash

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

```



### Check API Status



```bash

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

```



Response:

```json

{

  "status": "healthy",

  "version": "1.0.0",

  "uptime": 3600,

  "cache_stats": {

    "entries": 5,

    "hit_rate": 0.85

  }

}

```



### Pi-hole Optimized Endpoint



```bash

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

```



## 🔧 Troubleshooting



### Common Issues



1. **Port already in use**

   ```bash

   # Change port in config or environment

   export HAGEZI_SERVER_PORT=3001

   ```



2. **SSL/TLS errors**

   ```bash

   # Install SSL development libraries

   sudo apt-get install libssl-dev pkg-config

   ```



3. **Permission denied (Docker)**

   ```bash

   # Add user to docker group

   sudo usermod -aG docker $USER

   # Log out and back in

   ```



### Logging



Enable debug logging:

```bash

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](LICENSE) file for details.



## 🙏 Acknowledgments



- [HaGeZi](https://github.com/hagezi/dns-blocklists) for providing excellent DNS blocklists

- [Pi-hole](https://pi-hole.net/) 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**