🪪 Certificate Configuration Guide
This guide explains the certificate status (cert status) displayed in the app and helps you understand what each status means, what actions you should take, and which settings to configure based on your environment.
Certificate Status Overview
The app displays the connection security status for each server. Here are all possible statuses:
| Status | Security Level | Description |
|---|---|---|
| HTTPS Verified | Highest | Valid CA-signed certificate |
| HTTPS Pinned | High | Certificate fingerprint verified |
| Don't check SSL certificate | Low | All certificate validation disabled |
| HTTPS Untrusted Allowed | Low | Self-signed certificates accepted |
| HTTP | None | Unencrypted connection |
| HTTPS Pin Mismatch | Error | Pinned fingerprint doesn't match |
| HTTPS Untrusted Blocked | Error | Self-signed certificate rejected |
Certificate Status Details
HTTPS Verified
What it means:
- The server has a valid SSL certificate signed by a trusted Certificate Authority (CA)
- This is the most secure and recommended configuration
When this appears:
- Server uses a certificate from Let's Encrypt, DigiCert, or other trusted CAs
- "Allow self-signed certificates" is OFF
User action:
- No action needed. This is the ideal state.
Recommended for:
- Production environments
- Servers accessible over the internet
- Users with reverse proxy setups using Let's Encrypt
HTTPS Pinned
What it means:
- The app has saved (pinned) the server's certificate fingerprint
- Each connection verifies the fingerprint matches the saved value
- Provides protection against certificate tampering or MITM attacks
When this appears:
- "Allow self-signed certificates" is ON
- You've connected and pinned the certificate fingerprint
User action:
- Verify the fingerprint matches your server's actual certificate (out-of-band verification recommended)
- If you regenerate your server's certificate, you'll need to update the pin
Recommended for:
- Self-signed certificate users who want additional security
- Users who can verify the certificate fingerprint manually
You can view and update the pinned fingerprint from the server's menu by selecting "View certificate" or "Update".
Don't check SSL certificate
What it means:
- All SSL/TLS certificate validation is disabled
- The app accepts any certificate without verification
When this appears:
- "Don't check SSL certificate" option is ON
User action:
- Use only on trusted local networks
- Consider setting up a proper certificate instead
This setting bypasses all security checks. Only use this when absolutely necessary and on trusted networks.
Recommended for:
- Pi-hole running in Docker without proper TLS termination
- Temporary troubleshooting
- Isolated local networks with no external access
HTTPS Untrusted Allowed
What it means:
- The server's certificate is not signed by a trusted CA
- The app is configured to accept self-signed certificates
- No certificate pinning is active
When this appears:
- Server uses a self-signed certificate
- "Allow self-signed certificates" is ON
- Certificate has not been pinned yet
User action:
- For better security, pin the certificate fingerprint when prompted
- Or consider getting a CA-signed certificate
HTTP
What it means:
- Connection is unencrypted
- Data is transmitted in plain text
When this appears:
- Server URL uses
http://scheme
User action:
- Consider enabling HTTPS on your Pi-hole server for better security
- Acceptable only on isolated local networks
HTTP connections transmit your API token/password in plain text. Anyone on the same network could potentially intercept this data.
HTTPS Pin Mismatch
What it means:
- The server's certificate fingerprint doesn't match the pinned value
- Connection is blocked for security
When this appears:
- Server certificate was renewed or regenerated
- Potential MITM attack (rare but possible)
User action:
- Verify if you recently changed your server's certificate
- If intentional change: Update the pinned fingerprint from server settings
- If unexpected: Investigate before updating the pin
If you didn't change your certificate, this could indicate a security issue. Verify your server's certificate before updating the pin.
HTTPS Untrusted Blocked
What it means:
- Server has a self-signed or invalid certificate
- "Allow self-signed certificates" is OFF
- Connection is blocked
When this appears:
- Attempting to connect to a server with self-signed certificate
- App default settings are in effect but server needs self-signed support
User action:
- Enable "Allow self-signed certificates" in server settings
- Or install a CA-signed certificate on your server
Default App Settings
By default, the app has:
- Allow self-signed certificates: ON
- Don't check SSL certificate: OFF
If your Pi-hole server uses a valid CA-signed certificate (e.g., Let's Encrypt), you should turn OFF "Allow self-signed certificates" to achieve the "HTTPS Verified" status.
After App Update: Backward Compatibility
This backward compatibility behavior applies only when updating to v1.8.0.
In v1.8.0, the SSL verification settings were restructured. To prevent existing connections from breaking, servers that had "Allow self-signed certificates" enabled before the update are automatically migrated to a less strict configuration.
For better security, we strongly recommend reviewing each affected server and switching back to the certificate pinning approach.
If you had "Allow self-signed certificates" enabled before updating the app, the update will automatically enable both "Allow self-signed certificates" and "Don't check SSL certificate" for backward compatibility.
As a result, all your HTTPS servers will display the "Don't check SSL certificate" status, and a warning banner will appear:
After the app update, if "Allow self-signed certificates" was ON before the update, all HTTPS servers will show the "Don't check SSL certificate" status. This configuration is less secure than the certificate pinning approach.
If it was OFF before the update, no changes are applied— your servers will remain in either "HTTPS Verified" or "HTTPS Untrusted Blocked" status.
How to Fix This
- Open the server details screen for the affected server
- Turn OFF "Don't check SSL certificate"
- Save the settings
- The "Allow self-signed certificates" confirmation modal will appear
- Verify the certificate fingerprint and tap "Confirm"
After confirming, the server will show the "HTTPS Pinned" status, which provides stronger security than "Don't check SSL certificate".
Pi-hole in Docker: Special Considerations
If you're running Pi-hole in Docker, you may encounter connection issues even with "Allow self-signed certificates" enabled.
This happens because the Pi-hole Docker container's built-in web server certificate cannot be properly validated by the app's TLS implementation.
Solution 1: Disable Certificate Checking (Simple)
- In server settings, enable "Don't check SSL certificate"
- Save and reconnect
Only use this on trusted local networks. This disables all certificate validation.
Solution 2: Use a Reverse Proxy (Recommended)
Set up a reverse proxy (nginx, Caddy, Traefik, etc.) in front of Pi-hole:
- Configure the reverse proxy to handle TLS termination
- Use either a free, valid certificate from Let’s Encrypt or a self-signed certificate on the reverse proxy.
- Connect to Pi-hole through the reverse proxy URL
Benefits:
- Achieve "HTTPS Verified" or "HTTPS Pinned" status
- Proper certificate management
- Better security overall
Example with Caddy:
pihole.local {
reverse_proxy pihole:80
tls internal
}
Recommended Configuration by Use Case
| Use Case | Recommended Setting | Expected Status |
|---|---|---|
| Valid CA certificate (Let's Encrypt) | Allow self-signed certificates: OFF | HTTPS Verified |
| Self-signed certificate | Allow self-signed certificates: ON, Pin the cert | HTTPS Pinned |
| Docker without reverse proxy | Don't check SSL certificate: ON | Don't check SSL |
| Local HTTP only | - | HTTP |
Troubleshooting
Having issues with certificate configuration? Check out the FAQ for common questions and solutions: