Pihole

Pi-hole角色。这将为您安装Pi-hole®: 网络广告的黑洞。

它还帮助您通过一个简单的CSV文件来管理Pi-Hole，您可以用您喜欢的编辑器进行编辑。

要求

需要一台运行Ubuntu/Debian/Photon OS的主机，例如运行Raspberry Pi OS (Lite)的树莓派。

如果遇到问题，可以查看Pi-hole文档以获取帮助。

主机CSV文件

Pi-hole的配置通过一个CSV文件完成。这提供了一个良好的概览，并且使管理环境变得简单。

该角色在files文件夹中包含一个完整的示例CSV文件供您参考。

以下行显示将写入dnsmasq配置文件的dhcp-option设置。这些行将一个IP地址标记为基于虚拟机的DNS服务器，另一个为实际运行在树莓派上的基于树莓派的DNS服务器。

设置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，如果该地址仍然可用，将为其分配192.168.128.2的IP地址。如果已将DHCP租约分配给另一台机器，则将分配新的IP地址。它还将该机器标识为物理主机。

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

设置静态IP地址

如果您希望确保IP地址仅分配给特定主机，可以将static字段设置为true来实现。设置此选项将指示dnsmasq忽略任何名为vmhole的主机的DHCP请求，如下面的示例所示。该类型也标识为虚拟机。

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地址映射

要使用设备的MAC地址将特定IP地址和主机名分配给特定设备，请在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选项来实现。下面的示例显示如何为Photon主机设置vm-dns DNS服务器。

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","基于docker镜像的代理服务器虚拟机，使用vm-dns服务器"

角色变量

该角色使用以下变量：

变量	默认值	描述
riv_pihole_admin_password_generated	{{ lookup('password', '/dev/null length=15 chars=ascii_letters') }}	此变量设置Web用户界面的密码。如果未设置密码，将自动生成。 如果将此变量riv_pihole_show_summary设置为true，密码值将在最后一步以纯文本显示。
riv_pihole_dns_default_tag		此变量设置DHCP标签，让您可以为未列在配置CSV文件中的主机指定默认DNS服务器。
riv_pihole_show_summary	false	如果设置为true，最后一步将显示（生成的）密码的明文 along with some useful information like the IP address and name of the host pihole was installed on.
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	在DHCP上启用IPv6支持。
riv_pihole_dhcp_rapid_commit	false	用于快速提交选项的控制开关。
riv_pihole_dnsmasq_listening	all	dnsmasq应该监听的接口。
riv_pihole_query_logging	true	日志记录DNS查询。
riv_pihole_install_web_server	true	安装内置Web服务器。
riv_pihole_install_web_interface	true	安装Web界面。
riv_pihole_lighttpd_enabled		启用lighttpd
riv_pihole_ipv4_address	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	您希望Pi-Hole监听的IPv4地址。
riv_pihole_ipv6_address		您希望Pi-Hole监听的IPv6地址。
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	Pi-hole的系统DNS服务器。第一个必须是127.0.0.1。
riv_pihole_sys_dns_server2	8.8.8.8	Pi-hole的系统DNS服务器。
riv_pihole_dns_server1	1.1.1.1	在docker容器内部使用的DNS服务器。
riv_pihole_dns_server2	8.8.8.8	在docker容器内部使用的DNS服务器。
riv_pihole_serverip	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	Pi-hole主机的IP地址。
riv_pihole_timezone	Europe/Berlin	您的时区
riv_pihole_open_firewall_ports	true	如果您不希望角色打开所需的防火墙端口，请设置为false。
riv_pihole_dns_db_configuration_file	{{ role_path }}/files/mappings.csv	DNS配置文件的位置。默认指向的文件应被复制并适当地使用。

示例剧本

下面的示例显示了一个演示剧本，您可以用其在基于Photon OS的虚拟机上配置pi-hole，这在清单文件中有反映。

文件夹结构

文件夹结构如下（角色文件夹稍后将自动创建）：

|-- 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主机"
mohh,example.net,192.168.128.5,,,,"大脑 (vCenter Server)"
blib,example.net,192.168.128.18,,00:0c:29:43:37:dc,"pi-dns","使用树莓派的DNS (和DHCP) 服务器的虚拟机"
photon,example.net,192.168.128.19,,00:0c:29:51:80:1f,"vm-dns","使用VM基础的DNS服务器的虚拟机"
vmhole,example.net,192.168.128.253,true,,,"Pi-hole虚拟机DNS服务器"
pihole,example.net,192.168.128.254,,,,"基于树莓派的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:

---
# 在docker容器中配置一台运行pi-hole的机器
- 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来设置配置在inventory中的系统上的pi-hole。

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

许可证

MIT