Pihole

Роль Pi-hole. Это установит Pi-hole®: Чёрная дыра для интернет-рекламы для вас.

Также она помогает управлять Pi-hole с помощью простого CSV-файла, который вы можете редактировать с помощью своего любимого редактора.

Требования

Хост с установленной Ubuntu/Debian/Photon OS или, например, Raspberry Pi, работающий на Raspberry Pi OS (Lite).

Если вы столкнулись с проблемами, загляните в документацию Pi-hole, это может помочь.

CSV-файл хоста

Конфигурация Pi-hole выполняется через CSV-файл. Это даёт вам хороший обзор и упрощает управление вашей средой.

Роль включает полный пример CSV-файла в папке files для вашего ознакомления.

Следующие строки показывают настройки dhcp-option, которые будут записаны в конфигурационный файл dnsmasq. Эти строки помечают один IP-адрес как DNS-сервер на базе vm и DNS-сервер на базе Raspberry Pi, работающий на фактическом Raspberry Pi.

Настройка параметров DHCP

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
,,,,,"tag:vm-dns,option:dns-server,192.168.30.253","<<tag>>","Устанавливает значение параметра конфигурации dhcp-option, здесь какой DNS-сервер использовать"
,,,,,"tag:pi-dns,option:dns-server,192.168.30.254","<<tag>>","Устанавливает значение параметра конфигурации dhcp-option, здесь какой DNS-сервер использовать"

Примечание: Если вы настраиваете несколько DNS-серверов, вам, вероятно, стоит установить параметр riv_pihole_dns_default_tag при настройке, чтобы задать DNS-сервер по умолчанию для клиентов без конкретной конфигурации.

Настройка сопоставления IP/хост

Конфигурация ниже настраивает хост с именем slash, чтобы он получил IP-адрес 192.168.128.2, если этот адрес все еще доступен. Если DHCP-аренда уже была выдана другому устройству, будет назначен новый IP-адрес. Также он идентифицирует машину как физический хост.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
slash,example.net,192.168.128.2,true,,,"<<physical>>","ESXi Host"

Настройка статического IP-адреса

Если вы хотите убедиться, что IP-адрес назначен только конкретному имени хоста, вы можете установить поле static в true. Установка этого параметра укажет dnsmasq игнорировать DHCP-запросы от любого хоста с именем vmhole, как показано в примере ниже. Тип также будет идентифицирован как виртуальная машина.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
vmhole,example.net,192.168.128.253,true,,,"<<virtual>>","Pi-hole Виртуальная машина DNS-сервер"

Настройка сопоставления MAC-адрес/IP-адрес

Чтобы назначить конкретный IP-адрес и имя хоста специальному устройству, используя его MAC-адрес, используйте следующую запись в CSV-файле конфигурации.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
blib,example.net,192.168.128.18,,00:0c:29:43:37:dc,,"<<virtual>>","Pi-hole Виртуальная машина DNS-сервер"

Установка другого DNS-сервера

Настройка специального DNS-сервера для некоторых устройств достигается путём предоставления соответствующего DHCP-параметра при определении сопоставления. Ниже приведён пример, как установить DNS-сервер vm-dns для хоста photon.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
photon,example.net,192.168.128.19,,00:0c:29:51:80:1f,"vm-dns","Прокси-сервер VM на основе образа docker, использующий сервер vm-dns"

Переменные роли

Роль использует следующие переменные:

Переменная	По умолчанию	Описание
riv_pihole_admin_password_generated	{{ lookup('password', '/dev/null length=15 chars=ascii_letters') }}	Эта переменная устанавливает пароль для веб-интерфейса. Если пароль не установлен, он будет сгенерирован автоматически. Значение пароля отображается в открытом виде на последнем этапе, если переменная riv_pihole_show_summary установлена в true.
riv_pihole_dns_default_tag		Эта переменная устанавливает DHCP-тег, который позволяет указать DNS-сервер по умолчанию для хостов, не перечисленных в CSV-файле конфигурации.
riv_pihole_show_summary	false	Если установить true, на последнем этапе будет показан (сгенерированный) пароль в открытом виде вместе с некоторой полезной информацией, такой как IP-адрес и имя хоста, на котором был установлен pi-hole.
riv_pihole_docker_network	host	Сеть, к которой подключается docker. Если вы хотите использовать DHCP, вы должны подключиться к сети хоста.
riv_pihole_docker_purge_networks	yes	Удалить созданную сеть, когда контейнер docker будет отключен.
riv_pihole_dhcp_active	false	Включить или отключить встроенный DHCP-сервер. Если вы хотите использовать Pi-hole в качестве DHCP-сервера, вам нужно включить эту опцию.
riv_pihole_dhcp_leasetime	24h	Время аренды по умолчанию, установленное при выдаче IP-адреса клиенту
riv_pihole_dhcp_start	192.168.1.2	Начальный диапазон встроенного DHCP-сервера.
riv_pihole_dhcp_end	192.168.1.253	Последний адрес встроенного DHCP-сервера.
riv_pihole_dhcp_router	192.168.1.1	Маршрутизатор, который следует рекламировать клиентам, получающим IP-адрес.
riv_pihole_domain	example.net	Домен вашей локальной сети.
riv_pihole_interface	eth0	Интерфейс, к которому будут привязаны процессы внутри Pi-hole.
riv_pihole_dhcp_ipv6	false	Включить поддержку IPv6 на DHCP.
riv_pihole_dhcp_rapid_commit	false	Функция управления для опции быстрого подтверждения.
riv_pihole_dnsmasq_listening	all	Интерфейс, на котором должен слушать dnsmasq.
riv_pihole_query_logging	true	Вести журнал DNS-запросов.
riv_pihole_install_web_server	true	Установить встроенный веб-сервер.
riv_pihole_install_web_interface	true	Установить веб-интерфейс.
riv_pihole_lighttpd_enabled		Включить lighttpd
riv_pihole_ipv4_address	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	IPv4-адрес, на который вы хотите, чтобы Pi-Hole слушал.
riv_pihole_ipv6_address		IPv6-адрес, на который вы хотите, чтобы Pi-Hole слушал.
riv_pihole_dns_bogus_priv		Контроль ошибочных частных обратных запросов
riv_pihole_dns_fqdn_required		Контролирует, помещается ли неквалифицированное имя в DNS
riv_pihole_dnssec		Контроль DNSSEC
riv_pihole_rev_server_enabled		Включить условную переадресацию DNS для разрешения имён устройств.
riv_pihole_rev_server_cidr		Если условная переадресация включена, задайте обратную зону DNS (например, 192.168.0.0/24)
riv_pihole_rev_server_domain		Если условная переадресация включена, задайте домен маршрутизатора локальной сети (например, example.net).
riv_pihole_rev_server_target		Если условная переадресация включена, задайте IP-адрес локального маршрутизатора.
riv_pihole_docker_image	pihole/pihole:latest	Какой образ docker загрузить. Вы можете, например, указать версию.
riv_pihole_configuration_base_folder	/opt/pihole	Где вы хотите, чтобы ваша конфигурация находилась на целевом хосте.
riv_pihole_etc_pihole_folder	{{ riv_pihole_configuration_base_folder }}/pihole	Контролирует положение папки pihole.
riv_pihole_etc_dnsmasq_folder	{{ riv_pihole_configuration_base_folder }}/dnsmasq.d	Контролирует положение папки dnsmasq.d.
riv_pihole_sys_dns_server1	127.0.0.1	Системные DNS-серверы для Pi-hole. Первый обязательно должен быть 127.0.0.1
riv_pihole_sys_dns_server2	8.8.8.8	Системный DNS-сервер для Pi-hole
riv_pihole_dns_server1	1.1.1.1	DNS-сервер, используемый внутри контейнера docker
riv_pihole_dns_server2	8.8.8.8	DNS-сервер, используемый внутри контейнера docker
riv_pihole_serverip	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	IP-адрес хоста Pi-hole
riv_pihole_timezone	Europe/Berlin	Ваш часовой пояс
riv_pihole_open_firewall_ports	true	Установите значение false, если вы не хотите, чтобы роль открывала необходимые порты файрвола.
riv_pihole_dns_db_configuration_file	{{ role_path }}/files/mappings.csv	Местоположение файла конфигурации DNS. Указанный файл по умолчанию должен быть скопирован и соответствующим образом адаптирован.

Пример Playbook

Пример ниже показывает playbook, который вы можете использовать для настройки Pi-hole на виртуальной машине на базе Photon OS, что отражается в файле инвентаря.

Структура папок

Структура папок выглядит следующим образом (папка ролей будет создана автоматически позже):

|-- dns-db.csv
|-- inventory
|-- pihole-vm.yml
`-- roles
    `-- authsec.pihole
        |-- defaults
        |   `-- main.yml
        |-- files
        |   `-- mappings.csv
        |-- LICENSE
        |-- meta
        |   `-- main.yml
        |-- README.md
        |-- tasks
        |   |-- checkssh-photonos.yml
        |   |-- checkssh.yml
        |   |-- firewall-iptables.yml
        |   |-- install-apt.yml
        |   |-- install-photonos.yml
        |   `-- main.yml
        `-- templates
            |-- 02-pihole-dhcp.conf.j2
            |-- 10-pihole-custom-static.conf.j2
            `-- setupVars.conf.j2

Импорт роли

Вы можете импортировать роль в ваш проект, используя:

#> ansible-galaxy install -p roles authsec.pihole

Создание базы данных

Это копия примерной базы данных в roles/authsec.pihole/files.

dns-db.csv:

hostname,domainname,ip_address,static,mac_address,dhcp_option,comment
,,,,,"tag:vm-dns,option:dns-server,192.168.128.253","Устанавливает значение параметра конфигурации dhcp-option"
,,,,,"tag:pi-dns,option:dns-server,192.168.128.254","Устанавливает значение параметра конфигурации dhcp-option"
slash,example.net,192.168.128.2,,,,"ESXi Host"
mohh,example.net,192.168.128.5,,,,"The Brain (vCenter Server)"
blib,example.net,192.168.128.18,,00:0c:29:43:37:dc,"pi-dns","VM использует DNS (и DHCP) сервер на базе Raspberry Pi"
photon,example.net,192.168.128.19,,00:0c:29:51:80:1f,"vm-dns","VM использует VM на базе DNS-сервера"
vmhole,example.net,192.168.128.253,true,,,"Pi-hole Виртуальная машина DNS-сервер"
pihole,example.net,192.168.128.254,,,,"Raspberry Pi поддерживает Pi-Hole DNS и DHCP сервер для этой сети, основанный на docker и управляемый ansible"

inventory:

[dns_vms]
vmhole.example.net ansible_host=192.168.128.253 ansible_user=pihole ansible_become_method='su' ansible_become_password='kevin.is.dead' ansible_python_interpreter=/usr/bin/python3

pihole-vm.yml:

---
# Настройка машины для запуска pi-hole внутри контейнера docker
- hosts: dns_vms
  gather_facts: yes
  become: yes
  tasks: 
    - include_role: 
        name: authsec.pihole
      vars:
        # true|false
        riv_pihole_admin_password: "secure.me"
        riv_pihole_dhcp_active: "false"
        riv_pihole_dhcp_start: "192.168.128.8"
        riv_pihole_dhcp_end: "192.168.128.252"
        riv_pihole_dhcp_router: "192.168.128.1"
        riv_pihole_domain: "example.net"
        riv_pihole_show_summary: true
        riv_pihole_dns_db_configuration_file: "dns-db.csv"

Запуск ansible

После того как всё настроено, вы можете запустить ansible, чтобы настроить Pi-hole на системе, указанной в inventory.

#> ansible-playbook -i inventory pihole-vm.yml

Лицензия

MIT