mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 23:22:02 +01:00
3b474220fb
Signed-off-by: Leo Siepel <leosiepel@gmail.com> Signed-off-by: Ciprian Pascu <contact@ciprianpascu.ro>
168 lines
10 KiB
Markdown
168 lines
10 KiB
Markdown
# Pi-hole Binding
|
|
|
|
The Pi-hole Binding is a bridge between openHAB and Pi-hole, enabling users to integrate Pi-hole statistics and controls into their home automation setup. Pi-hole is a DNS-based ad blocker that can run on a variety of platforms, including Raspberry Pi.
|
|
|
|
Pi-hole is a powerful network-level advertisement and internet tracker blocking application.
|
|
By intercepting DNS requests, it can prevent unwanted content from being displayed on devices connected to your network.
|
|
The Pi-hole Binding allows you to monitor Pi-hole statistics and control its functionality directly from your openHAB setup.
|
|
|
|
### Features
|
|
|
|
- Real-time Statistics: Monitor key metrics such as the number of domains being blocked, DNS queries made today, ads blocked today, and more.
|
|
- Control: Enable or disable Pi-hole's blocking functionality, configure blocking options, and adjust privacy settings directly from openHAB.
|
|
- Integration: Seamlessly integrate Pi-hole data and controls with other openHAB items and rules to create advanced automation scenarios.
|
|
|
|
## Supported Things
|
|
|
|
- `server`: Pi-hole server
|
|
|
|
## Thing Configuration
|
|
|
|
### `server` Thing Configuration
|
|
|
|
| Name | Type | Description | Default | Required | Advanced |
|
|
|-----------------|---------|-------------------------------------------------------------------------------------------|---------|----------|----------|
|
|
| hostname | text | Hostname or IP address of the device | N/A | yes | no |
|
|
| token | text | Token to access the device. To generate token go to `settings` > `API` > `Show API token` | N/A | yes | no |
|
|
| refreshInterval | integer | Interval the device is polled in sec. | 600 | no | yes |
|
|
|
|
## Channels
|
|
|
|
| Channel | Type | Read/Write | Description |
|
|
|-------------------------|----------|------------|------------------------------------------------------------|
|
|
| domains-being-blocked | Number | RO | The total number of domains currently being blocked. |
|
|
| dns-queries-today | Number | RO | The count of DNS queries made today. |
|
|
| ads-blocked-today | Number | RO | The number of ads blocked today. |
|
|
| ads-percentage-today | Number | RO | The percentage of ads blocked today. |
|
|
| unique-domains | Number | RO | The count of unique domains queried. |
|
|
| queries-forwarded | Number | RO | The number of queries forwarded to an external DNS server. |
|
|
| queries-cached | Number | RO | The number of queries served from the cache. |
|
|
| clients-ever-seen | Number | RO | The total number of unique clients ever seen. |
|
|
| unique-clients | Number | RO | The current count of unique clients. |
|
|
| dns-queries-all-types | Number | RO | The total number of DNS queries of all types. |
|
|
| reply-unknown | Number | RO | DNS replies with an unknown status. |
|
|
| reply-nodata | Number | RO | DNS replies indicating no data. |
|
|
| reply-nxdomain | Number | RO | DNS replies indicating non-existent domain. |
|
|
| reply-cname | Number | RO | DNS replies with a CNAME record. |
|
|
| reply-ip | Number | RO | DNS replies with an IP address. |
|
|
| reply-domain | Number | RO | DNS replies with a domain name. |
|
|
| reply-rrname | Number | RO | DNS replies with a resource record name. |
|
|
| reply-servfail | Number | RO | DNS replies indicating a server failure. |
|
|
| reply-refused | Number | RO | DNS replies indicating refusal. |
|
|
| reply-notimp | Number | RO | DNS replies indicating not implemented. |
|
|
| reply-other | Number | RO | DNS replies with other statuses. |
|
|
| reply-dnssec | Number | RO | DNS replies with DNSSEC information. |
|
|
| reply-none | Number | RO | DNS replies with no data. |
|
|
| reply-blob | Number | RO | DNS replies with a BLOB (binary large object). |
|
|
| dns-queries-all-replies | Number | RO | The total number of DNS queries with all reply types. |
|
|
| privacy-level | Number | RO | The privacy level setting. |
|
|
| enabled | Switch | RO | The current status of blocking |
|
|
| disable-enable | String | RW | Is blocking enabled/disabled |
|
|
| gravity-last-update | DateTime | RO | Last update of gravity |
|
|
| gravity-file-exists | DateTime | RO | Does gravity file exists |
|
|
|
|
## Full Example
|
|
|
|
### Thing Configuration
|
|
|
|
```java
|
|
Thing pihole:server:a4a077edb8 "Pi-hole" @ "Location"
|
|
[
|
|
refreshIntervalSeconds=600,
|
|
hostname="http://123.456.7.89",
|
|
token="as654gadf3h1dsfh654dfh6fh7et654asd3g21fh654eth8t4swd4g3s1g65sfg5"
|
|
] {
|
|
Channels:
|
|
Type number : domains_being_blocked "Domains Blocked" [ ]
|
|
Type number : dns_queries_today "DNS Queries Today" [ ]
|
|
Type number : ads_blocked_today "Ads Blocked Today" [ ]
|
|
Type number : ads_percentage_today "Ads Percentage Today" [ ]
|
|
Type number : unique_domains "Unique Domains" [ ]
|
|
Type number : queries_forwarded "Queries Forwarded" [ ]
|
|
Type number : queries_cached "Queries Cached" [ ]
|
|
Type number : clients_ever_seen "Clients Ever Seen" [ ]
|
|
Type number : unique_clients "Unique Clients" [ ]
|
|
Type number : dns_queries_all_types "DNS Queries (All Types)" [ ]
|
|
Type number : reply_UNKNOWN "Reply UNKNOWN" [ ]
|
|
Type number : reply_NODATA "Reply NODATA" [ ]
|
|
Type number : reply_NXDOMAIN "Reply NXDOMAIN" [ ]
|
|
Type number : reply_CNAME "Reply CNAME" [ ]
|
|
Type number : reply_IP "Reply IP" [ ]
|
|
Type number : reply_DOMAIN "Reply DOMAIN" [ ]
|
|
Type number : reply_RRNAME "Reply RRNAME" [ ]
|
|
Type number : reply_SERVFAIL "Reply SERVFAIL" [ ]
|
|
Type number : reply_REFUSED "Reply REFUSED" [ ]
|
|
Type number : reply_NOTIMP "Reply NOTIMP" [ ]
|
|
Type number : reply_OTHER "Reply OTHER" [ ]
|
|
Type number : reply_DNSSEC "Reply DNSSEC" [ ]
|
|
Type number : reply_NONE "Reply NONE" [ ]
|
|
Type number : reply_BLOB "Reply BLOB" [ ]
|
|
Type number : dns_queries_all_replies "DNS Queries (All Replies)" [ ]
|
|
Type number : privacy_level "Privacy Level" [ ]
|
|
Type switch : enabled "Status" [ ]
|
|
Type string : disable-enable "Disable Blocking" [ ]
|
|
}
|
|
```
|
|
|
|
### Item Configuration
|
|
|
|
```java
|
|
Number domains_being_blocked "Domains Blocked" { channel="pihole:server:a4a077edb8:domains_being_blocked" }
|
|
Number dns_queries_today "DNS Queries Today" { channel="pihole:server:a4a077edb8:dns_queries_today" }
|
|
Number ads_blocked_today "Ads Blocked Today" { channel="pihole:server:a4a077edb8:ads_blocked_today" }
|
|
Number ads_percentage_today "Ads Percentage Today" { channel="pihole:server:a4a077edb8:ads_percentage_today" }
|
|
Number unique_domains "Unique Domains" { channel="pihole:server:a4a077edb8:unique_domains" }
|
|
Number queries_forwarded "Queries Forwarded" { channel="pihole:server:a4a077edb8:queries_forwarded" }
|
|
Number queries_cached "Queries Cached" { channel="pihole:server:a4a077edb8:queries_cached" }
|
|
Number clients_ever_seen "Clients Ever Seen" { channel="pihole:server:a4a077edb8:clients_ever_seen" }
|
|
Number unique_clients "Unique Clients" { channel="pihole:server:a4a077edb8:unique_clients" }
|
|
Number dns_queries_all_types "DNS Queries (All Types)" { channel="pihole:server:a4a077edb8:dns_queries_all_types" }
|
|
Number reply_UNKNOWN "Reply UNKNOWN" { channel="pihole:server:a4a077edb8:reply_UNKNOWN" }
|
|
Number reply_NODATA "Reply NODATA" { channel="pihole:server:a4a077edb8:reply_NODATA" }
|
|
Number reply_NXDOMAIN "Reply NXDOMAIN" { channel="pihole:server:a4a077edb8:reply_NXDOMAIN" }
|
|
Number reply_CNAME "Reply CNAME" { channel="pihole:server:a4a077edb8:reply_CNAME" }
|
|
Number reply_IP "Reply IP" { channel="pihole:server:a4a077edb8:reply_IP" }
|
|
Number reply_DOMAIN "Reply DOMAIN" { channel="pihole:server:a4a077edb8:reply_DOMAIN" }
|
|
Number reply_RRNAME "Reply RRNAME" { channel="pihole:server:a4a077edb8:reply_RRNAME" }
|
|
Number reply_SERVFAIL "Reply SERVFAIL" { channel="pihole:server:a4a077edb8:reply_SERVFAIL" }
|
|
Number reply_REFUSED "Reply REFUSED" { channel="pihole:server:a4a077edb8:reply_REFUSED" }
|
|
Number reply_NOTIMP "Reply NOTIMP" { channel="pihole:server:a4a077edb8:reply_NOTIMP" }
|
|
Number reply_OTHER "Reply OTHER" { channel="pihole:server:a4a077edb8:reply_OTHER" }
|
|
Number reply_DNSSEC "Reply DNSSEC" { channel="pihole:server:a4a077edb8:reply_DNSSEC" }
|
|
Number reply_NONE "Reply NONE" { channel="pihole:server:a4a077edb8:reply_NONE" }
|
|
Number reply_BLOB "Reply BLOB" { channel="pihole:server:a4a077edb8:reply_BLOB" }
|
|
Number dns_queries_all_replies "DNS Queries (All Replies)" { channel="pihole:server:a4a077edb8:dns_queries_all_replies" }
|
|
Number privacy_level "Privacy Level" { channel="pihole:server:a4a077edb8:privacy_level" }
|
|
Switch enabled "Status" { channel="pihole:server:a4a077edb8:enabled" }
|
|
String disable_enable "Disable Blocking" { channel="pihole:server:a4a077edb8:disable-enable" }
|
|
```
|
|
|
|
### Actions
|
|
|
|
Pi-hole binding provides actions to use in rules:
|
|
|
|
```java
|
|
import java.util.concurrent.TimeUnit
|
|
|
|
rule "test"
|
|
when
|
|
/* when */
|
|
then
|
|
val actions = getActions("pihole", "pihole:server:as8af03m38")
|
|
if (actions !== null) {
|
|
// disable blocking for 5 * 60 seconds (5 minutes)
|
|
actions.disableBlocking(5 * 60)
|
|
|
|
// disable blocking for 5 minutes
|
|
actions.disableBlocking(5, TimeUnit.MINUTES)
|
|
|
|
// disable blocking for infinity
|
|
actions.disableBlocking(0)
|
|
actions.disableBlocking()
|
|
|
|
// enable blocking
|
|
actions.enableBlocking()
|
|
}
|
|
end
|
|
```
|