pihole

Description

Plugin for interacting with a Pi-Hole DNS server for advertisement and content blocking.

Configuration

pihole:
  # [Optional]
  # Default Pi-hole server IP address.
  # server:   # type=Optional[str]

  # [Optional]
  # Password for the default Pi-hole server.
  # password:   # type=Optional[str]

  # [Optional]
  # Alternatively to the password, you can also provide the server ``api_key``, as retrieved from
  # http://pi-hole-server/admin/scripts/pi-hole/php/api_token.php
  # api_key:   # type=Optional[str]

  # [Optional]
  # Set to true if the host uses HTTPS (default: False).
  # ssl: False  # type=bool

  # [Optional]
  # Set to False to disable SSL certificate check.
  # verify_ssl: True  # type=bool

  # [Optional]
  # Default timeout for the HTTP requests.
  # timeout: 10  # type=int

Actions

• pihole.blacklist_add

• pihole.blacklist_remove

• pihole.disable

• pihole.enable

• pihole.get_blacklist

• pihole.get_list

• pihole.get_whitelist

• pihole.list_add

• pihole.list_remove

• pihole.status

• pihole.whitelist_add

• pihole.whitelist_remove

Module reference

class platypush.plugins.pihole.PiholePlugin(server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool = False, verify_ssl: bool = True, timeout: int = 10, **kwargs)

Bases: Plugin

Plugin for interacting with a Pi-Hole DNS server for advertisement and content blocking.

__init__(server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool = False, verify_ssl: bool = True, timeout: int = 10, **kwargs)

Parameters:

• server – Default Pi-hole server IP address.

• password – Password for the default Pi-hole server.

• api_key – Alternatively to the password, you can also provide the server api_key, as retrieved from http://pi-hole-server/admin/scripts/pi-hole/php/api_token.php

• ssl – Set to true if the host uses HTTPS (default: False).

• verify_ssl – Set to False to disable SSL certificate check.

• timeout – Default timeout for the HTTP requests.

blacklist_add(domain: str, server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Add a domain to the blacklist.

Parameters:

• domain – Domain name.

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

blacklist_remove(domain: str, server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Remove a domain from the blacklist.

Parameters:

• domain – Domain name.

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

disable(server: str | None = None, password: str | None = None, api_key: str | None = None, seconds: int | None = None, ssl: bool | None = None)

Disable a Pi-hole server.

Parameters:

• seconds – How long the server will be disabled in seconds (default: None, indefinitely).

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

enable(server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Enable a Pi-hole server.

Parameters:

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

get_blacklist(server: str | None = None, ssl: bool | None = None) → List[str]

Get the content of the blacklist.

Parameters:

• server – Server IP address (default: default configured server value).

• ssl – Set to True if the server uses SSL (default: False).

get_list(list_name: str, server: str | None = None, ssl: bool | None = None) → List[str]

Get the content of a list stored on the server.

Parameters:

• list_name – List name

• server – Server IP address (default: default configured server value).

• ssl – Set to True if the server uses SSL (default: False).

get_whitelist(server: str | None = None, ssl: bool | None = None) → List[str]

Get the content of the whitelist.

Parameters:

• server – Server IP address (default: default configured server value).

• ssl – Set to True if the server uses SSL (default: False).

list_add(list_name: str, domain: str, server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Add a domain to a custom list stored on the server.

Parameters:

• list_name – List name

• domain – Domain name.

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

list_remove(list_name: str, domain: str, server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Remove a domain from a custom list stored on the server.

Parameters:

• list_name – List name

• domain – Domain name.

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

status(server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None) → dict

Get the status and statistics of a running Pi-hole server.

Parameters:

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

Returns:

{
  "ads_percentage": 6.7,
  "blocked": 37191,
  "cached": 361426,
  "domain_count": 1656690,
  "forwarded": 150187,
  "queries": 552076,
  "server": "192.168.1.254",
  "status": "enabled",
  "total_clients": 57,
  "total_queries": 552076,
  "unique_clients": 41,
  "unique_domains": 39348,
  "version": "5.18.2"
}

whitelist_add(domain: str, server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Add a domain to the whitelist.

Parameters:

• domain – Domain name.

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).

whitelist_remove(domain: str, server: str | None = None, password: str | None = None, api_key: str | None = None, ssl: bool | None = None)

Remove a domain from the whitelist.

Parameters:

• domain – Domain name.

• server – Server IP address (default: default configured server value).

• password – Server password (default: default configured password value).

• api_key – Server API key (default: default configured api_key value).

• ssl – Set to True if the server uses SSL (default: False).