Connecting to Your Pi-hole

On this page, there are explained all the instructions about how to create a connection to the server with different circumstances. These are the most common cases. There may be other configurations that aren’t covered by this guide.

⚙️ Common settings

• Version: You can choose between v5 and v6 (default). The latest version is v6, while the previous generation is v5.
• Authentication:
  • v5: Requires an API token (See: Getting the API token (v5 only)).
  • v6: Requires a password to log in to the web UI.
  • v6 with two-factor authentication (2FA): Requires the password and a 6-digit code from your authenticator app.

Two-factor authentication (2FA)

If your Pi-hole v6 server has 2FA enabled, the app asks for a 6-digit authentication code when it logs in. This happens when you:

• add a server or save changes to an existing one
• connect to a server from the server list
• return to a server whose session has expired

Enter the current code from your authenticator app. A code can only be used once, so if it is rejected as already used, wait for the next code.

Note

App versions 1.9.0 - 1.9.2 cannot connect to a Pi-hole v6 server that has no password set. This was fixed in v1.10.0 - update the app if you are still on 1.9.x. See FAQ Q8 for details.

1. Basic connection

The simplest case. The Pi-hole server usually is installed on a Raspberry Pi and the web administration panel is on the default port (80).

• IP address or domain: your Pi-hole server IP or domain
• Subroute: empty
• Port: empty
• HTTP/HTTPS: HTTP

2. Basic connection with custom port

The Pi-hole server is usually installed on a Docker container or virtual machine.

• IP address or domain: your Pi-hole server IP or domain
• Subroute: empty
• Port: the port you are using for the web administration panel
• HTTP/HTTPS: HTTP

3. HTTPS connection 🔒

You have enabled HTTPS connections on your Pi-hole server config, but you access it using the default HTTPS port (443).

• IP address or domain: your Pi-hole server IP or domain
• Subroute: empty
• Port: empty
• HTTP/HTTPS: HTTPS

Note

If you are using Pi-hole v6 with a self-signed SSL certificate, the connection may fail if self-signed certificates are not allowed. To prevent SSL certificate validation errors, please follow the steps below based on your app version:

App version >= v1.9.0

1. Go to: Settings > Servers
2. Create a new server, or open ⋮ > Edit on an existing one
3. Expand Advanced Options
4. Check Allow untrusted certificates (default: checked)

The app then asks you to confirm the certificate fingerprint and pins it. See Certificate settings for what each certificate status means.

App version v1.3.0 - v1.8.x

1. Go to: Settings > Servers
2. Select an existing server or create a new one
3. Check Allow self-signed certificates (default: checked)

App version < v1.3.0

1. Go to: Settings > Advanced settings > Don't check SSL certificate
2. Turn it ON (default: ON)
3. Restart the application

Once the app restarts, you can proceed with the connection.

Note

If the connection still fails

Depending on how the server certificate was generated, the app may not be able to validate it even with Allow untrusted certificates enabled. This is common with the web server built into the Pi-hole Docker image.

In that case, turn on Don’t check SSL certificate in the same Advanced Options section, then save and reconnect.

⚠️ Don’t check SSL certificate disables all certificate validation, so only use it on a network you trust. Putting a reverse proxy with a valid certificate in front of Pi-hole is the safer fix - see Pi-hole in Docker: Special Considerations and FAQ Q3.

4. HTTPS connection with custom port (or exposed port) 🔒

You have enabled HTTPS connections on your Pi-hole server config and you have an exposed port on your router to access it.

• IP address or domain: your Pi-hole server IP or domain
• Subroute: empty
• Port: the port you are exposing for the web administration panel
• HTTP/HTTPS: HTTPS

5. HTTPS connection with reverse proxy ⚡

You have your Pi-hole server behind a reverse proxy.

• IP address or domain: your Pi-hole server IP or domain
• Subroute: the route you are using on your reverse proxy to access Pi-hole web administration panel
• Port: empty
• HTTP/HTTPS: HTTPS

Caution

Currently, connections via a reverse proxy have not been tested, and their operation is not guaranteed.