ITBlog

1. Architektura rozwiązania

Observium <-- SNMP -- Docker[ Pi-Hole ]

1. Skrypt na Linux pobiera statystyki z API Pi-hole v6 (/api/stats/summary)
2. Linux udostępnia te dane poprzez SNMP Extend (net-snmp)
3. Observium CE i LibreNMS zbierają statystyki SNMP z Linuxa (192.168.53.110)

2. Konfiguracja Pi-hole — API

2.1. Logowanie do panelu Pi-hole

Otwórz przeglądarkę i przejdź pod adres:

http://192.168.55.4/admin/login

Zaloguj się hasłem: ZAQ!2wsx

2.2. Generowanie klucza API (App Password)

Pi-hole v6 wymaga uwierzytelnienia dla endpointów API. Wygeneruj hasło aplikacji:

1. Przejdź do: Settings → API / Web Interface
2. Kliknij „Generate App Password”
3. Skopiuj wygenerowany token (zapisze się w schowku)

2.3. Test API (opcjonalnie z poziomu Linux 192.168.53.110)

# Pobranie tokena (SID) przez uwierzytelnienie
SID=$(curl -s -X POST http://192.168.55.4/api/auth \
  -H "Content-Type: application/json" \
  --data '{"password":"ZAQ!2wsx"}' | jq -r '.session.sid')

# Pobranie statystyk
curl -s -H "X-FTL-SID: ${SID}" \
  http://192.168.55.4/api/stats/summary | jq .

2.4. Alternatywa — brak hasła (tryb nieuwierzytelniony)

Jeśli Pi-hole nie ma ustawionego hasła (lub używasz starszej wersji), możesz pominąć uwierzytelnienie:

curl -s http://192.168.55.4/api/stats/summary | jq .

2.5. Najważniejsze endpointy

Endpoint	Opis
/api/stats/summary	Podsumowanie statystyk (zapytania, blokady, typy DNS)
/api/stats/top_domains	Najczęściej zapytane domeny
/api/stats/top_clients	Najaktywniejsi klienci
/api/dns/blocking	Status blokowania (włączone/wyłączone)

3. Przygotowanie Linux (192.168.53.110)

3.1. Instalacja pakietów

ssh yyy@192.168.53.110
# (hasło: zaq12wsx)

sudo apt update
sudo apt install -y snmpd snmp libsnmp-dev curl jq
sudo systemctl enable snmpd
sudo systemctl start snmpd

3.2. Pobranie skryptu distro (wymagane)

Skrypt distro pozwala Observium CE i LibreNMS automatycznie rozpoznać system operacyjny (dystrybucję, jądro, architekturę) zamiast wyświetlać „generic device”.

Dla LibreNMS:

sudo curl -o /usr/local/bin/distro \
  https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
sudo chmod +x /usr/local/bin/distro

Dla Observium CE:

sudo curl -o /usr/local/bin/distro https://www.observium.org/files/distro
sudo chmod +x /usr/local/bin/distro

3.3. Konfiguracja SNMP (snmpd.conf)

Edytuj plik /etc/snmp/snmpd.conf:

sudo nano /etc/snmp/snmpd.conf

Zawartość minimalnej konfiguracji dla v2c:

# Nasłuch na wszystkich interfejsach
agentAddress udp:161,udp6:[::1]:161

# Widok pełny
view   all    included   .1

# Dostęp read-only dla całej sieci LAN
rocommunity  public  192.168.0.0/16  -V all

# Lokalizacja i kontakt
syslocation  "Serwer monitoringu, Home Lab"
syscontact   "Admin <admin@example.com>"

# Dystrybucja (dla Observium/LibreNMS)
extend .1.3.6.1.4.1.2021.7890.1 distro /usr/local/bin/distro

4. Agent SNMP dla Pi-hole

4.1. Skrypt pobierający statystyki

Utwórz plik /usr/local/bin/pihole-stats.sh:

sudo nano /usr/local/bin/pihole-stats.sh

Wariant 1 — skrypt z App Password w zewnętrznym pliku configa (zalecane):

sudo nano /etc/snmp/pi-hole.conf

PIHOLE_HOST="192.168.55.4"
API_AUTH_KEY="wygenerowany_app_password"
CURL_TIMEOUT=10

sudo chmod 640 /etc/snmp/pi-hole.conf
sudo chown root:Debian-snmp /etc/snmp/pi-hole.conf

Następnie skrypt /usr/local/bin/pihole-stats.sh (wczytuje konfig z /etc/snmp/pi-hole.conf):

#!/usr/bin/env bash
set -euo pipefail

CONFIGFILE="/etc/snmp/pi-hole.conf"
[ -f "$CONFIGFILE" ] && source "$CONFIGFILE"

: ${PIHOLE_HOST:="192.168.55.4"}
: ${API_AUTH_KEY:=""}
: ${CURL_TIMEOUT:=10}

# Uwierzytelnienie przez App Password
SESSION_SID=$(curl -s --max-time ${CURL_TIMEOUT} \
  -X POST "http://${PIHOLE_HOST}/api/auth" \
  -H "Content-Type: application/json" \
  --data "{\"password\":\"${API_AUTH_KEY}\"}" \
  | jq -r '.session.sid // empty')

if [ -z "$SESSION_SID" ]; then
  echo "ERROR: auth failed"
  exit 1
fi

STATS=$(curl -s --max-time ${CURL_TIMEOUT} \
  -H "X-FTL-SID: ${SESSION_SID}" \
  "http://${PIHOLE_HOST}/api/stats/summary")

echo "$STATS" | jq -r '
  .gravity.domains_being_blocked,
  .queries.total,
  .queries.blocked,
  .queries.percent_blocked,
  .queries.unique_domains,
  .queries.forwarded,
  .queries.cached,
  .queries.types.A,
  .queries.types.AAAA,
  .queries.types.PTR,
  .queries.types.SRV
'

Wariant 2 — skrypt z hasłem bezpośrednio (prostszy, ale mniej bezpieczny):

#!/usr/bin/env bash
set -euo pipefail

PIHOLE_HOST="192.168.55.4"
PIHOLE_PASS="ZAQ!2wsx"
CURL_TIMEOUT=10

# Uwierzytelnienie i pobranie SID
SESSION_SID=$(curl -s --max-time ${CURL_TIMEOUT} \
  -X POST "http://${PIHOLE_HOST}/api/auth" \
  -H "Content-Type: application/json" \
  --data "{\"password\":\"${PIHOLE_PASS}\"}" \
  | jq -r '.session.sid // empty')

if [ -z "$SESSION_SID" ]; then
  echo "ERROR: auth failed"
  exit 1
fi

# Pobranie statystyk
STATS=$(curl -s --max-time ${CURL_TIMEOUT} \
  -H "X-FTL-SID: ${SESSION_SID}" \
  "http://${PIHOLE_HOST}/api/stats/summary")

# Wyodrębnienie wartości
echo "$STATS" | jq -r '
  .gravity.domains_being_blocked,
  .queries.total,
  .queries.blocked,
  .queries.percent_blocked,
  .queries.unique_domains,
  .queries.forwarded,
  .queries.cached,
  .queries.types.A,
  .queries.types.AAAA,
  .queries.types.PTR,
  .queries.types.SRV
'

Nadaj uprawnienia wykonania:

sudo chmod +x /usr/local/bin/pihole-stats.sh

4.2. Test skryptu

/usr/local/bin/pihole-stats.sh

Oczekiwany wynik — 11 liczb (po jednej w wierszu):

217894
184933
21358
11.55
53183
74257
71865
98765
35421
12345
6789

4.3. Rejestracja w SNMP (extend)

Dodaj do /etc/snmp/snmpd.conf:

extend .1.3.6.1.4.1.2021.7890.5 pihole /usr/local/bin/pihole-stats.sh

Uruchom ponownie snmpd:

sudo systemctl restart snmpd

4.4. Weryfikacja extensu

# Sprawdź całe drzewo nsExtendMIB
snmpwalk -v2c -c public 127.0.0.1 .1.3.6.1.4.1.2021.7890

# Sprawdź tylko dane per-line (Output2Table)
snmpwalk -v2c -c public 127.0.0.1 .1.3.6.1.4.1.2021.7890.5.4

W Output2Table zobaczysz 11 linii z wartościami liczbowymi (to są dane dla sensorów Observium).

5. Testowanie poprawnej konfiguracji SNMP

5.1. Podstawowe zapytanie

snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.2.1.1

5.2. Odczyt danych Pi-hole przez SNMP

snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890.5

5.3. Zdalnie z innej maszyny

Z poziomu serwera Observium/LibreNMS (bez Dockera):

snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890.5

Z poziomu kontenera Docker (Observium/LibreNMS w Dockerze):

# Przez docker exec — snmpwalk musi być zainstalowany w kontenerze
docker exec observium snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890.5

# Jeśli kontener nie ma snmpwalk — użyj innego kontenera z narzędziami sieciowymi
docker run --rm alpine/snmp snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890.5

# Lub bezpośrednio na hoście Docker (jeśli masz zainstalowane snmp)
snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890.5

6. Dodawanie do Observium CE

6.1. Dodanie urządzenia Linux

1. Zaloguj się do panelu Observium CE
2. Przejdź do: Devices → Add Device
3. Wypełnij:
   • Hostname: 192.168.53.110
   • Community: public
   • SNMP Version: 2c
   • Port: 161
4. Kliknij „Add Device”

Observium automatycznie wykryje system operacyjny i rozpocznie zbieranie danych.

6.2. Statyczne sensory w config.php (jedyna metoda w CE)

Observium CE pozwala definiować statyczne sensory i liczniki w pliku config.php po stronie serwera Observium. Są one pollowane przez standardowy mechanizm SNMP.

Opcja 1 — edytuj przez docker exec (najszybsza):

# Wejdź do kontenera i edytuj config.php
docker exec -it observium nano /opt/observium/config.php
# Jeśli nie ma nano, użyj vi lub sed

Opcja 2 — skopiuj na zewnątrz, edytuj, wgraj z powrotem:

# Wyciągnij plik z kontenera
docker cp observium:/opt/observium/config.php ./config.php

# Edytuj lokalnie
nano ./config.php

# Wgraj z powrotem do kontenera
docker cp ./config.php observium:/opt/observium/config.php

Opcja 3 — zamontuj config jako wolumen (trwała, przy docker-compose):

# w docker-compose.yml observium dodaj:
services:
  observium:
    ...
    volumes:
      - ./observium-config.php:/opt/observium/config.php

# Potem edytuj observium-config.php na hoście i restartuj:
docker-compose restart

Niezależnie od opcji — dodaj poniższy kod na końcu pliku config.php:

// === Pi-hole statyczne sensory (CE) ===
// OID pobrane z rzeczywistego snmpwalk dla extend "pihole".
// Format: .5.4.1.2.6.112.105.104.111.108.101.Y
// gdzie 6.112.105.104.111.108.101 = "pihole" zakodowane w OID, Y = nr linii.
//   Y=1: domains_being_blocked
//   Y=2: queries.total
//   Y=3: queries.blocked
//   Y=4: queries.percent_blocked
//   Y=5: queries.unique_domains
//   Y=6: queries.forwarded
//   Y=7: queries.cached

$config['sensors']['static'][] = [
  'device_id' => 6,
  'class'     => 'load',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.1',
  'descr'     => 'Pi-hole Domains Blocked',
  'multiplier' => 1,
];
$config['counters']['static'][] = [
  'device_id' => 6,
  'class'     => 'counter',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.2',
  'descr'     => 'Pi-hole Total Queries',
  'multiplier' => 1,
];
$config['counters']['static'][] = [
  'device_id' => 6,
  'class'     => 'counter',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.3',
  'descr'     => 'Pi-hole Blocked Today',
  'multiplier' => 1,
];
$config['sensors']['static'][] = [
  'device_id' => 6,
  'class'     => 'load',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.4',
  'descr'     => 'Pi-hole Block Percent',
  'multiplier' => 1,
];
$config['sensors']['static'][] = [
  'device_id' => 6,
  'class'     => 'load',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.5',
  'descr'     => 'Pi-hole Unique Domains',
  'multiplier' => 1,
];
$config['counters']['static'][] = [
  'device_id' => 6,
  'class'     => 'counter',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.6',
  'descr'     => 'Pi-hole Forwarded Queries',
  'multiplier' => 1,
];
$config['counters']['static'][] = [
  'device_id' => 6,
  'class'     => 'counter',
  'oid'       => '.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.7',
  'descr'     => 'Pi-hole Cached Queries',
  'multiplier' => 1,
];

Po zapisaniu wymuś odkrycie sensorów (użyj swojego ID urządzenia, np. 6):

Bezpośrednio na systemie:

cd /opt/observium
php discovery.php -h 6 -m sensors
php poller.php -h 6 -m sensors

W Dockerze:

docker exec -it observium php /opt/observium/discovery.php -h 6 -m sensors
docker exec -it observium php /opt/observium/poller.php -h 6 -m sensors

Sensory pojawią się w zakładce Health urządzenia. Jeśli nie widzisz żadnych — uruchom z flagą -d (debug):

# Użyj -i (bez -t) gdy pipe'ujesz output
docker exec -i observium php /opt/observium/poller.php -h 6 -m sensors -d 2>&1 | grep -i pihole

6.3. UNIX Agent (tylko dla Observium Subscription — płatna wersja)

Observium Subscription wspiera UNIX Agent — skrypt na Linux (192.168.53.110) wysyła dane przez TCP (port 655) do serwera Observium.

Część wspólna — konfiguracja na Linux 192.168.53.110:

sudo mkdir -p /usr/lib/observium_agent/scripts
sudo curl -o /usr/lib/observium_agent/scripts/pihole \
  https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/pi-hole
sudo chmod +x /usr/lib/observium_agent/scripts/pihole

# Konfiguracja API Pi-hole
echo 'API_URL="http://192.168.55.4"' | sudo tee /etc/snmp/pi-hole.conf
echo 'API_AUTH_KEY="wygenerowany_app_password"' | sudo tee -a /etc/snmp/pi-hole.conf

# Skrypt agent-local.sh
sudo mkdir -p /opt/observium/scripts
sudo tee /opt/observium/scripts/agent-local.sh << 'EOF'
#!/usr/bin/env bash
for script in /usr/lib/observium_agent/scripts/*; do
  [ -x "$script" ] || continue
  echo "<<<$(basename "$script")>>>"
  "$script" 2>/dev/null || true
done
EOF
sudo chmod +x /opt/observium/scripts/agent-local.sh

# Uruchom nasłuch na porcie 655
sudo apt install -y socat
sudo socat TCP-LISTEN:655,reuseaddr,fork EXEC:/opt/observium/scripts/agent-local.sh &

Konfiguracja w Observium:
Po włączeniu UNIX Agenta w config.php poller automatycznie łączy się na port 655 do urządzenia.

Wariant A — Observium na Linux (bez Dockera):

echo "\$config['poller_modules']['unix-agent'] = true;" >> /opt/observium/config.php
cd /opt/observium
php poller.php -h 6

Wariant B — Observium w Dockerze:

B1. Docker na tym samym hoście co agent:

docker exec -it observium bash -c 'echo "\$config['"'"'poller_modules'"'"']['"'"'unix-agent'"'"'] = true;" >> /opt/observium/config.php'
docker exec -it observium php /opt/observium/poller.php -h 6

B2. Docker na innym hoście niż agent:
Dodaj w docker-compose.yml: ports: - "655:655", następnie:

docker exec -it observium bash -c 'echo "\$config['"'"'poller_modules'"'"']['"'"'unix-agent'"'"'] = true;" >> /opt/observium/config.php'
docker exec -it observium php /opt/observium/poller.php -h 6

7. Dodawanie do LibreNMS

7.1. Oficjalny agent LibreNMS dla Pi-hole

LibreNMS posiada dedykowaną aplikację Pi-hole.

Krok 1: Pobranie agenta LibreNMS na Linux (192.168.53.110)

sudo mkdir -p /usr/lib/librenms_agent
sudo curl -o /usr/lib/librenms_agent/pihole \
  https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/pi-hole
sudo chmod +x /usr/lib/librenms_agent/pihole

Krok 2: Konfiguracja agenta

sudo nano /etc/snmp/pi-hole.conf

API_URL="http://192.168.55.4"
API_AUTH_KEY="ZAQ!2wsx"

Krok 3: Rejestracja w snmpd.conf

sudo nano /etc/snmp/snmpd.conf

extend pihole /usr/lib/librenms_agent/pihole

sudo systemctl restart snmpd

Krok 4: Test na serwerze LibreNMS

snmpwalk -v2c -c public 192.168.53.110 NET-SNMP-EXTEND-MIB::nsExtendOutput2Line

7.2. Dodanie urządzenia w LibreNMS

1. Zaloguj się do panelu LibreNMS
2. Przejdź: Devices → Add Device
3. Wypełnij:
   • Hostname: 192.168.53.110
   • SNMP Version: v2c
   • Community: public
   • Port: 161
4. Kliknij „Add Device”

7.3. Ręczne włączenie aplikacji Pi-hole

1. Wejdź w szczegóły urządzenia (192.168.53.110)
2. Device → Edit → Applications
3. Z listy wybierz „Pi-hole” i zapisz

Wymuś ponowne odkrycie:

./discovery.php -h 192.168.53.110

7.4. Weryfikacja w LibreNMS

• Przejdź do urządzenia → zakładka „Apps”
• Powinieneś zobaczyć „Pi-hole” z wykresami:
  • Domains being blocked
  • DNS Queries Total
  • DNS Queries Blocked
  • DNS Queries Percent Blocked
  • Unique Domains
  • Queries Forwarded / Cached
  • Query Types (A, AAAA, PTR, SRV)

8. Troubleshooting

SNMP: Connection refused

sudo ss -tlnp | grep 161
sudo systemctl status snmpd
# Sprawdź czy agentAddress w snmpd.conf jest poprawny

SNMP: No response

# Sprawdź firewall na Linux
sudo ufw status
sudo iptables -L -n | grep 161

# Sprawdź czy community string jest poprawny
snmpwalk -v2c -c public 127.0.0.1 .1.3.6.1.2.1.1

Pi-hole API: Unauthorized

# Hasło Pi-hole może być zmienione
# Wygeneruj nowy App Password w panelu Pi-hole
# Settings > API/Web Interface > Generate App Password

Skrypt pihole-stats.sh: puste wyniki

# Debug skryptu — uruchom ręcznie
bash -x /usr/local/bin/pihole-stats.sh

# Sprawdź czy curl i jq są zainstalowane
which curl
which jq

# Sprawdź czy Pi-hole jest dostępny
curl -s -o /dev/null -w "%{http_code}" http://192.168.55.4/api/stats/summary

LibreNMS: nie widzi aplikacji Pi-hole

# Wymuś ponowne odkrycie
cd /opt/librenms
php discovery.php -h 192.168.53.110

# Debug pollingu
snmpbulkwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890.5

Observium: brak wykresów

# Sprawdź logi pollingu (bezpośrednio na systemie)
tail -f /opt/observium/logs/poller.log

# Wymuś poll (bezpośrednio na systemie)
./poller.php -h 192.168.53.110 -d

Observium w Dockerze: SNMP connection refused

# Sprawdź czy kontener widzi Linux (192.168.53.110)
docker exec observium ping 192.168.53.110

# Sprawdź SNMP z wnętrza kontenera
docker exec observium snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.2.1.1

# Jeśli nie działa — kontener może być w innej sieci Docker.
# Użyj adresu IP bramy Docker (zwykle 172.17.0.1):
docker exec observium snmpwalk -v2c -c public 172.17.0.1 .1.3.6.1.2.1.1

Observium w Dockerze: config.php zmiany nie są widoczne

# Po edycji config.php przez docker exec ZAWSZE uruchom:
docker exec -it observium php /opt/observium/discovery.php -h 6 -m sensors
docker exec -it observium php /opt/observium/poller.php -h 6 -m sensors

# Sprawdź czy zmiany w config.php są widoczne wewnątrz kontenera:
docker exec observium grep -c pihole /opt/observium/config.php

# Debug pollera dla Pi-hole (użyj -i, nie -it, gdy pipe'ujesz):
docker exec -i observium php /opt/observium/poller.php -h 6 -m sensors -d 2>&1 | grep -i -E "(pihole|static|error|warning)"

Observium w Dockerze: sensory static nie pojawiają się

# Sprawdź rzeczywiste OID z wnętrza kontenera:
docker exec observium snmpwalk -v2c -c public 192.168.53.110 .1.3.6.1.4.1.2021.7890

# OID w nsExtendOutput2Table mają format:
# .1.3.6.1.4.1.2021.7890.5.4.1.2.{długość_nazwy}.{znaki_nazwy_ASCII}.{numer_linii}

# Przykład (dla extend "pihole"):
# .1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.1 = "2012986"  ← linia 1
# .1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.2 = "22842"    ← linia 2

# Wymuś pełne odkrycie dla urządzenia:
docker exec -it observium php /opt/observium/discovery.php -h 6

Podsumowanie OID

OID	Opis
.1.3.6.1.4.1.2021.7890.1	Distro (wykrywanie OS)
.1.3.6.1.4.1.2021.7890.5	Pi-hole extend (rejestracja)
.1.3.6.1.4.1.2021.7890.5.4.1.2.6.112.105.104.111.108.101.Y	Pi-hole stats per-line (Y=1..11)