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#

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)[source]#

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)[source]#
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)[source]#

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)[source]#

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)[source]#

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)[source]#

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][source]#

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][source]#

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][source]#

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)[source]#

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)[source]#

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[source]#

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)[source]#

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)[source]#

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).