Pi-hole DNS Control

Control your Pi-hole DNS ad blocker via the Pi-hole v6 API. This skill enables you to manage ad blocking, view statistics, check blocked domains, and temporarily disable blocking through natural language commands.

Setup Instructions

Configure your Pi-hole API credentials in one of two ways:

**Option 1: Configuration File**

```yaml

skills:

entries:

pihole:

apiUrl: "https://pi-hole.local/api"

apiToken: "your-app-password-here"

insecure: false

```

**Option 2: 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. Navigate to Pi-hole Admin interface at `http://pi-hole.local/admin`

2. Go to **Settings** > **API**

3. Generate an application password

4. Use the generated password as your `apiToken`

**Note:** This skill requires Pi-hole v6 or later.

Capabilities

When the user requests Pi-hole operations, you should:

Status Checking

Blocking Controls

Analysis & Monitoring

Implementation Steps

1. Authentication

Before making any API calls, authenticate with Pi-hole:

```bash

Authenticate and get session token

session_response=$(curl -s -X POST "${PIHOLE_API_URL}/auth" \

-H "Content-Type: application/json" \

-d "{\"password\":\"${PIHOLE_API_TOKEN}\"}")

Extract session ID

sid=$(echo "$session_response" | jq -r '.session.sid')

```

Add `-k` flag to curl if `insecure: true` is set (for self-signed certificates).

2. Check Status

```bash

Get blocking status

curl -s "${PIHOLE_API_URL}/dns/blocking" \

-H "sid: ${sid}" | jq

```

Response format:

```json

{

"blocking": "enabled",

"timer": 0

}

```

3. Get Statistics

```bash

Fetch summary statistics

curl -s "${PIHOLE_API_URL}/stats/summary" \

-H "sid: ${sid}" | jq

```

Response includes:

4. Enable/Disable Blocking

**Enable blocking:**

```bash

curl -s -X POST "${PIHOLE_API_URL}/dns/blocking" \

-H "sid: ${sid}" \

-H "Content-Type: application/json" \

-d '{"blocking":true}'

```

**Disable blocking permanently:**

```bash

curl -s -X POST "${PIHOLE_API_URL}/dns/blocking" \

-H "sid: ${sid}" \

-H "Content-Type: application/json" \

-d '{"blocking":false}'

```

**Disable blocking with timer (in seconds):**

```bash

Disable for 5 minutes (300 seconds)

curl -s -X POST "${PIHOLE_API_URL}/dns/blocking" \

-H "sid: ${sid}" \

-H "Content-Type: application/json" \

-d '{"blocking":false,"timer":300}'

```

5. Query Blocked Domains

```bash

Get queries from last N seconds

Example: Last 30 minutes = 1800 seconds

curl -s "${PIHOLE_API_URL}/queries?start=-1800" \

-H "sid: ${sid}" | jq '.queries[] | select(.status == "GRAVITY")'

```

Filter for `"status": "GRAVITY"` to show only blocked queries.

Usage Examples

Present the following patterns to users:

```

"Check Pi-hole status"

→ Show current blocking status and basic stats

"Turn off Pi-hole"

→ Disable ad blocking completely

"Turn on Pi-hole"

→ Enable ad blocking

"Disable Pi-hole for 5 minutes"

→ Temporarily disable blocking with auto-restore

"Disable Pi-hole for 30 minutes"

→ Longer temporary disable

"Show blocked domains in the last 30 minutes"

→ Display recently blocked domains

"Pi-hole statistics"

→ Show comprehensive blocking stats

```

Important Notes

API Version Compatibility

This skill is designed for **Pi-hole v6 API**. Key differences from v5:

| Feature | v5 | v6 |

|---------|----|----|

| Base URL | `/admin/api.php` | `/api` |

| Authentication | Token in URL | Session-based |

| Whitelist Management | Available | **Not available via API** |

**Whitelisting:** Domain whitelisting must be done through the Pi-hole Admin UI, as v6 API does not support this operation.

Security Considerations

SSL/TLS Configuration

**Valid certificate:**

```yaml

apiUrl: "https://pi-hole.example.com/api"

insecure: false

```

**Self-signed certificate:**

```yaml

apiUrl: "https://pi-hole.local/api"

insecure: true

```

Troubleshooting

Authentication Failures

Status Check Failures

Network Issues

Response Formatting

When presenting results to users: