--- name: pi-hole-skill-ef056a1f6c80 description: "Control your Pi-hole DNS ad blocker via the Pi-hole v6 API." --- # 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: Response: { "blocking": "enabled" | "disabled", "timer": 30 // seconds until re-enable (if disabled with timer) } ``` ### Enable/Disable ``` POST /api/dns/blocking Headers: sid: 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: Response: { "queries": { "total": 233512, "blocked": 23496, "percent_blocked": 10.06 }, "gravity": { "domains_being_blocked": 165606 }, "clients": { "active": 45 } } ``` ### Queries ``` GET /api/queries?start=- Headers: sid: 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) --- Source attribution: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/baanish/pihole/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 clawdbot Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/baanish/pihole/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Operations, Customer Support Roles: DevOps / SRE, IT Operations, Technical Support Specialties: API Tools: Pi Hole Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: a26b318af5a09ae7f22a5cc548f72c89fa28286a436a8aa5ff4980639ff21543