887ff4afea
* fix(client): Check uint16 bounds for user provided port see https://github.com/csfreak/adguard-exporter/security/code-scanning/4 * fix(client): add option to disable tls verification defaults to false see https://github.com/csfreak/adguard-exporter/security/code-scanning/3
282 lines
10 KiB
Markdown
282 lines
10 KiB
Markdown
# AdguardHome Prometheus Exporter
|
|
|
|
/badge.svg?branch=main)
|
|
[](https://godoc.org/github.com/csfreak/adguard-exporter)
|
|
[](https://goreportcard.com/report/github.com/csfreak/adguard-exporter)
|
|
|
|
|
|
This is a Prometheus exporter for [AdguardHome](https://github.com/AdguardTeam/AdguardHome)'s Raspberry PI ad blocker.
|
|
It is based on the famous pihole-exporter [available here](https://github.com/eko/pihole-exporter/)
|
|
It was forked from ebrianne/adguard-exporter, which is no longer available
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
* [Go](https://golang.org/doc/)
|
|
|
|
## Installation
|
|
|
|
### Download binary
|
|
|
|
You can download the latest version of the binary built for your architecture here:
|
|
|
|
* Architecture **i386** [
|
|
[FreeBSD](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-freebsd-386) /
|
|
[Linux](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-linux-386) /
|
|
[Windows](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-windows-386.exe)
|
|
]
|
|
* Architecture **amd64** [
|
|
[Darwin](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-darwin-amd64) /
|
|
[FreeBSD](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-freebsd-amd64) /
|
|
[Linux](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-linux-amd64) /
|
|
[Windows](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-windows-amd64.exe)
|
|
]
|
|
* Architecture **arm** [
|
|
[Linux](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-linux-arm)
|
|
]
|
|
* Architecture **arm64** [
|
|
[Linux](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-linux-arm64) /
|
|
[Darwin](https://github.com/csfreak/adguard-exporter/releases/latest/download/adguard_exporter-darwin-arm64)
|
|
]
|
|
|
|
### From sources
|
|
|
|
Optionally, you can download and build it from the sources. You have to retrieve the project sources by using one of the following way:
|
|
```bash
|
|
$ go get -u github.com/csfreak/adguard-exporter
|
|
# or
|
|
$ git clone https://github.com/csfreak/adguard-exporter.git
|
|
```
|
|
|
|
Then, build the binary (here, an example to run on Raspberry PI ARM architecture):
|
|
```bash
|
|
$ GOOS=linux GOARCH=arm GOARM=7 go build -o adguard_exporter .
|
|
```
|
|
|
|
## Using Docker
|
|
|
|
The exporter has been made available as a docker image. You can simply run it by the following command and pass the configuration with environment variables:
|
|
|
|
```bash
|
|
docker run \
|
|
-e 'adguard_protocol=http' \
|
|
-e 'adguard_hostname=192.168.10.252' \
|
|
-e 'adguard_username=admin' \
|
|
-e 'adguard_password=mypassword' \
|
|
-e 'adguard_port=' \ #optional if adguard is not using port 80 (http)/443 (https)
|
|
-e 'interval=10s' \
|
|
-e 'log_limit=10000' \
|
|
-e 'server_port=9617' \
|
|
-p 9617:9617 \
|
|
csfreak/adguard-exporter:latest
|
|
```
|
|
|
|
If you prefer you can use an .env file where the environment variables are defined and using the command:
|
|
|
|
```bash
|
|
docker run --env-file=.env -p 9617:9617 \
|
|
csfreak/adguard-exporter:latest
|
|
```
|
|
|
|
You can also use docker-compose passing the environment file or using secrets locally
|
|
### Local with environment file
|
|
|
|
```yml
|
|
version: "3.7"
|
|
|
|
services:
|
|
adguard_exporter:
|
|
image: csfreak/adguard-exporter:latest
|
|
restart: always
|
|
ports:
|
|
- "9617:9617"
|
|
env_file:
|
|
- .env
|
|
```
|
|
### Local with secret file (compose version 3 minimum)
|
|
|
|
```yml
|
|
version: "3.7"
|
|
|
|
secrets:
|
|
my-adguard-pass:
|
|
file: ./my-adguard-pass.txt
|
|
|
|
services:
|
|
adguard_exporter:
|
|
image: csfreak/adguard-exporter:latest
|
|
restart: always
|
|
secrets:
|
|
- my-adguard-pass
|
|
ports:
|
|
- "9617:9617"
|
|
environment:
|
|
- adguard_protocol=http
|
|
- adguard_hostname=192.168.10.252
|
|
- adguard_username=admin
|
|
- adguard_password=/run/secrets/my-adguard-pass
|
|
- adguard_port= #optional
|
|
- server_port=9617
|
|
- interval=10s
|
|
- log_limit=10000
|
|
- password_from_file=true
|
|
```
|
|
### Swarm mode (docker swarm init)
|
|
|
|
```bash
|
|
echo "mypassword" | docker secret create my-adguard-pass -
|
|
```
|
|
Here is an example of docker-compose file.
|
|
|
|
```yml
|
|
version: "3.7"
|
|
|
|
secrets:
|
|
my-adguard-pass:
|
|
external: true
|
|
|
|
services:
|
|
adguard_exporter:
|
|
image: csfreak/adguard-exporter:latest
|
|
restart: always
|
|
secrets:
|
|
- my-adguard-pass
|
|
ports:
|
|
- "9617:9617"
|
|
environment:
|
|
- adguard_protocol=http
|
|
- adguard_hostname=192.168.10.252
|
|
- adguard_username=admin
|
|
- adguard_password=/run/secrets/my-adguard-pass
|
|
- adguard_port= #optional
|
|
- server_port=9617
|
|
- interval=10s
|
|
- log_limit=10000
|
|
- password_from_file=true
|
|
```
|
|
|
|
## Usage
|
|
|
|
In order to run the exporter, type the following command (arguments are optional):
|
|
|
|
Using a password
|
|
|
|
```bash
|
|
$ ./adguard_exporter -adguard_protocol https -adguard_hostname 192.168.10.252 -adguard_username admin -adguard_password qwerty -log_limit 10000
|
|
```
|
|
|
|
```bash
|
|
2020/11/04 17:16:14 ---------------------------------------
|
|
2020/11/04 17:16:14 - AdGuard Home exporter configuration -
|
|
2020/11/04 17:16:14 ---------------------------------------
|
|
2020/11/04 17:16:14 AdguardProtocol : https
|
|
2020/11/04 17:16:14 AdguardHostname : 192.168.10.252
|
|
2020/11/04 17:16:14 AdguardUsername : admin
|
|
2020/11/04 17:16:14 AdGuard Authentication Method : AdguardPassword
|
|
2020/11/04 17:16:14 ServerPort : 9617
|
|
2020/11/04 17:16:14 Interval : 10s
|
|
2020/11/04 17:16:14 LogLimit : 10000
|
|
2020/11/04 17:16:14 ---------------------------------------
|
|
2020/11/04 17:16:14 New Prometheus metric registered: avg_processing_time
|
|
2020/11/04 17:16:14 New Prometheus metric registered: num_dns_queries
|
|
2020/11/04 17:16:14 New Prometheus metric registered: num_blocked_filtering
|
|
2020/11/04 17:16:14 New Prometheus metric registered: num_replaced_parental
|
|
2020/11/04 17:16:14 New Prometheus metric registered: num_replaced_safebrowsing
|
|
2020/11/04 17:16:14 New Prometheus metric registered: num_replaced_safesearch
|
|
2020/11/04 17:16:14 New Prometheus metric registered: top_queried_domains
|
|
2020/11/04 17:16:14 New Prometheus metric registered: top_blocked_domains
|
|
2020/11/04 17:16:14 New Prometheus metric registered: top_clients
|
|
2020/11/04 17:16:14 New Prometheus metric registered: query_types
|
|
2020/11/04 17:16:14 New Prometheus metric registered: running
|
|
2020/11/04 17:16:14 New Prometheus metric registered: protection_enabled
|
|
2020/11/04 17:16:14 Starting HTTP server
|
|
2020/11/04 17:16:30 New tick of statistics: 3824 ads blocked / 36367 total DNS queries
|
|
```
|
|
|
|
Once the exporter is running, you also have to update your `prometheus.yml` configuration to let it scrape the exporter:
|
|
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: 'adguard'
|
|
static_configs:
|
|
- targets: ['localhost:9617']
|
|
```
|
|
|
|
## Available CLI options
|
|
```bash
|
|
# Interval of time the exporter will fetch data from Adguard
|
|
-interval duration (optional) (default 10s)
|
|
|
|
# Protocol to use to query Adguard
|
|
-adguard_protocol string (optional: "http", "https") (default "http")
|
|
|
|
# Hostname of the Raspberry PI where Adguard is installed
|
|
-adguard_hostname string (optional) (default "127.0.0.1")
|
|
|
|
# Username to login to Adguard Home
|
|
-adguard_username string (optional)
|
|
|
|
# Password defined on the Adguard interface
|
|
-adguard_password string (optional)
|
|
|
|
# Port to use to communicate with Adguard API
|
|
-adguard_port string (optional)
|
|
|
|
# Limit for the return log data
|
|
-log_limit string (optional) (default "1000")
|
|
|
|
# Port to be used for the exporter
|
|
-server_port string (optional) (default "9617")
|
|
|
|
# Disable TLS verification
|
|
-insecure_tls_skip_verify bool (optional) (default "false")
|
|
```
|
|
|
|
## Available Prometheus metrics
|
|
|
|
| Metric name | Description |
|
|
|:---------------------------------:|----------------------------------------------------------------------|
|
|
| adguard_avg_processing_time | This represent the average DNS query processing time |
|
|
| adguard_num_blocked_filtering | This represent the number of blocked DNS queries |
|
|
| adguard_num_dns_queries | This represent the number of DNS queries |
|
|
| adguard_num_replaced_parental | This represent the number of blocked DNS queries (parental) |
|
|
| adguard_num_replaced_safebrowsing | This represent the number of blocked DNS queries (safe browsing) |
|
|
| adguard_num_replaced_safesearch | This represent the number of blocked DNS queries (safe search) |
|
|
| adguard_top_blocked_domains | This represent the top blocked domains |
|
|
| adguard_top_clients | This represent the top clients |
|
|
| adguard_top_queried_domains | This represent the top domains that are queried |
|
|
| adguard_query_types | This represent the types of DNS queries |
|
|
| running | Is Adguard running? |
|
|
| protection_enabled | Is the protection enabled? |
|
|
|
|
## Systemd file
|
|
|
|
### Ubuntu
|
|
|
|
One can enable the program to work at startup by writing a systemd file. You can put this file in /etc/systemd/system/adguard-home.service
|
|
|
|
```
|
|
[Unit]
|
|
Description=AdGuard-Exporter
|
|
After=syslog.target network-online.target
|
|
Requires=AdGuardHome.Service
|
|
|
|
[Service]
|
|
ExecStart=/opt/adguard_exporter/adguard_exporter-linux-arm -adguard_protocol http -adguard_hostname <hostname> -adguard_username <username> -adguard_password <password> -log_limit 5000
|
|
Restart=on-failure
|
|
RestartSec=10s
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
Then do this command to start the service:
|
|
```
|
|
$ sudo systemctl start adguard-home.service
|
|
```
|
|
To enable the service at startup:
|
|
```
|
|
$ sudo systemctl enable adguard-home.service
|
|
```
|