Homebridge Pi-hole

Pi-hole plugin for Homebridge. This plugin publishes a virtual switch that disables Pi-hole, making it easier to temporarily turn off the ad-blocker. Supports SSL connections and can be configured with a timer to turn Pi-hole back on.

Requirements

• Homebridge - HomeKit support for the impatient
• Pi-hole - A black hole for Internet advertisements

Installation

1. Install this plugin npm install -g homebridge-pihole
2. Update your configuration file. See sample-config.json in this repository for a sample.

See the Pi-hole installation section for more details.

Configuration

There are the following options:

• name Required. Accessory name, default is Pi-hole.

Pi-hole Configuration

• auth Pi-hole password or app password when using 2FA, see the section on how to get an app password.
• baseUrl Pi-hole base URL, default is http://localhost.
• path The directory where the Pi-hole dashboard is located. Default is /api.
• rejectUnauthorized If the HTTPS agent should check the validity of SSL cert, set it to false to allow self-signed certs to work. Default is true.
• time How long Pi-hole will be disabled, in seconds, default is 0 that means permanently disabled.
• reversed When set to true reverse the status of Pi-hole. When Pi-hole is off the plugin will be set to on and when Pi-hole is on the plugin will be set to off. Default is false.
• persistSession If the session should be persisted to disk. Default is false.
• logLevel Logging level, three different levels: 0: logging disabled, 1: logs only HTTP errors, 2: logs each HTTP response. Default is set to 1.

Device Information

• manufacturer Custom manufacturer, default is Raspberry Pi.
• model Custom model, default is Pi-hole.
• serial-number Should be a 9 digit number in the string format 123-456-789.

See the sample-config.json file to see an example of how to configure the accessory. In the example the configured accessory will disable Pi-hole for a time interval of two minutes (120 seconds).

How to get a Pi-hole app password

1. Login into your Pi-hole Admin Console.
2. Navigate to the Settings page and then to the Web interface / API tab, and enable the Expert settings.
3. In the Advanced Settings panel, click on the Configure app password button, a popup window will ask for confirmation, go ahead and copy the app password then click on Enable new app password.
4. Paste your App password in the homebridge-pihole configuration file.

Common Errors

api_seats_exceeded

This error occurs when the maximum number of Pi-hole API sessions is reached. By default, the plugin does not persist sessions, so each time Homebridge restarts, a new session is created. To fix this, you can:

1. Enable persistSession in the configuration.
2. Delete old sessions that are not expired (from Pi-hole /admin/settings/api page remove session with userAgent homebridge-pihole).
3. Increase the webserver.api.max_session Pi-hole setting.