Pi-hole icon

Pi-hole

Get information from Pi-hole API

Actions10

Overview

This node interacts with the Pi-hole API to retrieve information about the clients with the highest number of blocked requests. Specifically, when configured for the TopClientBlocked resource and the Get operation, it fetches a list of network clients that have had the most DNS queries blocked by Pi-hole. This is useful for network administrators who want to monitor which devices are being most affected by Pi-hole's blocking rules.

Practical scenarios:

  • Identifying devices on your network that are frequently attempting to access blocked domains.
  • Monitoring potential malware-infected devices generating excessive blocked requests.
  • Auditing network usage patterns for security or policy enforcement.

Properties

Name Type Meaning
API Url String The base URL of the Pi-hole API endpoint (e.g., http://localhost/admin/api.php).
Additional Fields Collection Optional fields to refine the query.
Number Results Number Maximum number of top blocked clients to return. Defaults to 10.

Output

The output will be a JSON object containing the list of clients with the highest number of blocked requests. The structure typically includes:

{
  "top_clients_blocked": {
    "client1.example.com": 123,
    "client2.example.com": 98,
    ...
  }
}
  • top_clients_blocked: An object where each key is a client identifier (hostname or IP address) and the value is the count of blocked requests for that client.

Note: The node does not output binary data.

Dependencies

  • Pi-hole API: Requires access to a running Pi-hole instance with its API enabled.
  • API Url: Must be correctly set to point to your Pi-hole server.
  • n8n Credentials: Optionally, you may need to configure credentials if your Pi-hole API requires authentication.

Troubleshooting

Common issues:

  • Incorrect API Url: If the API URL is wrong or unreachable, the node will fail to connect.
  • Insufficient Permissions: If the Pi-hole API requires authentication and credentials are missing or incorrect, requests may be denied.
  • Empty Results: If no clients have blocked requests, the result may be empty.

Error messages and resolutions:

  • "Network Error": Check that the API URL is correct and the Pi-hole server is accessible from n8n.
  • "401 Unauthorized": Ensure that any required API tokens or credentials are properly configured in n8n.
  • "Invalid Response Format": Make sure the Pi-hole API is up-to-date and returning expected JSON responses.

Links and References

Discussion