Pi-hole Control

# Pi-hole Skill

Control your Pi-hole DNS ad blocker via the Pi-hole v6 API.

## Setup

Set your Pi-hole API configuration in Clawdbot config:

```yaml skills: entries: pihole: apiUrl: "https://pi-hole.local/api" # v6 API path apiToken: "your-app-password-here" # Get from Pi-hole Admin insecure: false # Set to true for self-signed certs ```

Alternatively, set environment variables: ```bash export PIHOLE_API_URL="https://pi-hole.local/api" export PIHOLE_API_TOKEN="your-app-password-here" export PIHOLE_INSECURE="false" ```

### Getting API Credentials

1. Open Pi-hole Admin at `http://pi-hole.local/admin` 2. Navigate to **Settings** > **API** 3. Generate an app password 4. Use that password as `apiToken`

## Capabilities

### Status - Get current Pi-hole status (enabled/disabled) - View stats: queries blocked, queries today, domains being blocked, active clients - See recent query activity

### Controls - **Enable/Disable**: Turn Pi-hole on or off - **Disable for 5 minutes**: Temporarily disable ad blocking for a short period - **Disable for custom duration**: Set specific disable time (in minutes)

### Block Analysis - **Check blocked domains**: See what domains were blocked in a time window - **Show top blocked**: Most frequently blocked domains

## Usage Examples

``` # Check Pi-hole status "pihole status"

# Turn off ad blocking "pihole off"

# Turn on ad blocking "pihole on"

# Disable for 5 minutes (for a site that needs ads) "pihole disable 5m"

# Disable for 30 minutes "pihole disable 30"

# See what was blocked in the last 30 minutes "pihole blocked"

# See blocked domains in last 10 minutes (600 seconds) "pihole blocked 600"

# Show statistics "pihole stats" ```

## API Endpoints (Pi-hole v6)

### Authentication ``` POST /api/auth Content-Type: application/json {"password":"your-app-password"}

Response: { "session": { "sid": "session-token-here", "validity": 1800 } } ```

### Status ``` GET /api/dns/blocking Headers: sid: <session-token>

Response: { "blocking": "enabled" | "disabled", "timer": 30 // seconds until re-enable (if disabled with timer) } ```

### Enable/Disable ``` POST /api/dns/blocking Headers: sid: <session-token> Content-Type: application/json

Enable: {"blocking":true}

Disable: {"blocking":false}

Disable with timer (seconds): {"blocking":false,"timer":300} ```

### Stats ``` GET /api/stats/summary Headers: sid: <session-token>

Response: { "queries": { "total": 233512, "blocked": 23496, "percent_blocked": 10.06 }, "gravity": { "domains_being_blocked": 165606 }, "clients": { "active": 45 } } ```

### Queries ``` GET /api/queries?start=-<seconds> Headers: sid: <session-token>

Response: { "queries": [ { "domain": "example.com", "status": "GRAVITY", "time": 1768363900, "type": "A" } ] } ```

## v5 vs v6 API Changes

Pi-hole v6 introduced significant API changes:

| Feature | v5 API | v6 API | |---------|----------|----------| | Base URL | `/admin/api.php` | `/api` | | Auth | Token in URL/headers | Session-based | | Status | `?status` | `/api/dns/blocking` | | Stats | `?summaryRaw` | `/api/stats/summary` | | Queries | `?recentBlocked` | `/api/queries` | | Whitelist | Supported via API | **Not available via API** |

**Important:** Domain whitelisting is no longer available via the v6 API. You must whitelist domains through the Pi-hole Admin UI.

## SSL Certificates

### Production (Valid Cert) ```yaml { "apiUrl": "https://pi-hole.example.com/api", "apiToken": "...", "insecure": false } ```

### Self-Signed/Local Cert ```yaml { "apiUrl": "https://pi-hole.local/api", "apiToken": "...", "insecure": true } ```

The `insecure` flag adds the `-k` option to curl to bypass certificate validation.

## Security Notes

- Session tokens expire after 30 minutes (1800 seconds) - API password is sent in JSON body, not URL - All requests have a 30-second timeout - Token is not visible in process list (passed via environment)

## Troubleshooting

### "Failed to authenticate" - Check that `apiToken` matches your Pi-hole app password - Verify `apiUrl` is correct (must end in `/api`) - Ensure Pi-hole is accessible from your network

### "Could not determine status" - Check API URL is reachable - If using HTTPS with self-signed cert, set `insecure: true` - Verify API password is correct

### Network Errors - Ensure clawdbot's machine can reach the Pi-hole - Check firewall rules allow API access - Verify URL scheme (http vs https)

## Requirements

- Pi-hole v6 or later - App password generated in Pi-hole Admin - Network access to Pi-hole API - `curl`, `jq` (installed on most Unix systems)