Skip to content

Latest commit

 

History

History
996 lines (605 loc) · 24.4 KB

REFERENCE.md

File metadata and controls

996 lines (605 loc) · 24.4 KB

Reference

Table of Contents

Classes

Public Classes

  • adguard: Manages an Adguard Home installation

Private Classes

  • adguard::params: Private class for managing some of the more complex default parameters

Functions

Data types

Classes

adguard

Manages an Adguard Home installation

Examples

Basic usage
class {'adguard':
  users => [{
    username => 'user',
    password => '$2a$10$DBX2KdCRP6JKS8TqvkVWTOjUgUQLtlWGkxkZAuiUZGTURhorjlX6K'
  }],
}

Parameters

The following parameters are available in the adguard class:

webui_interface

Data type: Stdlib::IP::Address::V4::Nosubnet

The interface to bind the WebUI to.

Default value: '0.0.0.0'

webui_port

Data type: Stdlib::Port

The port to bind the WebUI to.

Default value: 80

users

Data type: Array[Adguard::User]

The users to add to allow access to the WebUI. Note: the password needs to be in BCrypt-encrypted format.

http_proxy

Data type: Optional[Adguard::Http_proxy]

Define an optional http_proxy. While adguard supports SOCKS5 alongside HTTP/S, this is not supported in the Puppet module at this time.

Default value: undef

rlimit_nofile

Data type: Integer

Limit on the maximum number of open files for server process (Linux).

Default value: 0

debug_pprof

Data type: Boolean

Enable pprof HTTP server listening on port 6060 for debugging.

Default value: false

web_session_ttl

Data type: Integer

Web session TTL (in hours) a web user will stay signed in for this amount of time.

Default value: 8

dns_interface

Data type: Stdlib::IP::Address::V4::Nosubnet

The interface to bind to for DNS.

Default value: '0.0.0.0'

dns_port

Data type: Stdlib::Port

The port to bind dns to

Default value: 53

statistics_interval

Data type: Integer

Time interval for statistics (in days).

Default value: 1

querylog_enabled

Data type: Boolean

Query logging (also used to calculate top 50 clients, blocked domains and requested domains for statistical purposes).

Default value: true

querylog_file_enabled

Data type: Boolean

Write query logs to a file.

Default value: true

querylog_interval

Data type: Integer

Time interval for query log (in days).

Default value: 90

querylog_size_memory

Data type: Integer

Number of entries kept in memory before they are flushed to disk.

Default value: 1000

anonymize_client_ip

Data type: Boolean

If true, anonymize clients' IP addresses in logs and stats.

Default value: false

protection_enabled

Data type: Boolean

Whether any kind of filtering and protection should be done, when off it works as a plain dns forwarder.

Default value: true

blocking_mode

Data type: Enum['default','null_ip','custom_ip']

Specifies how to block DNS requests. Valid options:

  • default (respond with NXDOMAIN status)
  • null_ip (respond with the unspecified IP address (0.0.0.0))
  • custom_ip (respond with blocking_ipv4 or blocking_ipv6 address)

Default value: 'default'

blocking_ipv4

Data type: Optional[Stdlib::IP::Address::V4::Nosubnet]

IP address to be returned for a blocked A request if blocking_mode is set to custom_ip.

Default value: undef

blocking_ipv6

Data type: Optional[Stdlib::IP::Address::V6]

IP address to be returned for a blocked AAAA request if blocking_mode is set to custom_ip.

Default value: undef

blocked_response_ttl

Data type: Integer

For how many seconds the clients should cache a filtered response. Low values are useful on LAN if you change filters very often, high values are useful to increase performance and save traffic.

Default value: 10

parental_block_host

Data type: Variant[Stdlib::Fqdn,Stdlib::IP::Address]

IP (or domain name) which is used to respond to DNS requests blocked by parental control.

Default value: 'family-block.dns.adguard.com'

safebrowsing_block_host

Data type: Variant[Stdlib::Fqdn,Stdlib::IP::Address]

IP (or domain name) which is used to respond to DNS requests blocked by safe-browsing.

Default value: 'standard-block.dns.adguard.com'

ratelimit

Data type: Integer

DDoS protection, specifies in how many packets per second a client should receive. Anything above that is silently dropped. To disable set 0, default is 20. Safe to disable if DNS server is not available from internet.

Default value: 20

ratelimit_whitelist

Data type: Optional[Array[Stdlib::IP::Address]]

An array of ip addresses to whitelist from ratelimiting.

Default value: undef

refuse_any

Data type: Boolean

Another DDoS protection mechanism. Requests of type ANY are rarely needed, so refusing to serve them mitigates against attackers trying to use your DNS as a reflection. Safe to disable if DNS server is not available from internet.

Default value: true

upstream_dns

Data type: Array[Adguard::Dns_server]

An array of upstream DNS servers. Can be a URL or IP.

Default value: ['https://dns10.quad9.net/dns-query']

upstream_dns_file

Data type: Optional[Stdlib::Unixpath]

Path to a file with the list of upstream DNS servers. If it is configured, the value of upstream_dns is ignored. Defaults to undef

Default value: undef

bootstrap_dns

Data type: Array[Stdlib::IP::Address]

List of DNS servers used for initial hostname resolution in case an upstream server name is a hostname.

Default value: [ '9.9.9.10', '149.112.112.10', '2620:fe::10', '2620:fe::fe:10' ]

all_servers

Data type: Boolean

Enables parallel queries to all configured upstream servers to speed up resolving. If disabled, the queries are sent to each upstream server one-by-one and then sorted by RTT.

Default value: false

fastest_addr

Data type: Boolean

Use Fastest Address algorithm. It finds an IP address with the lowest latency and returns this IP address in DNS response.

Default value: false

allowed_clients

Data type: Optional[Array[Stdlib::IP::Address]]

IP addresses of allowed clients.

Default value: undef

disallowed_clients

Data type: Optional[Array[Stdlib::IP::Address]]

IP addresses of disallowed clients.

Default value: undef

blocked_hosts

Data type: Array

An array of hosts to block.

Default value: [ 'version.bind', 'id.server', 'hostname.bind' ]

dns_cache_size

Data type: Integer

DNS cache size (in bytes).

Default value: 4194304

dns_cache_ttl_min

Data type: Integer[default,3600]

Override TTL value (minimum) received from upstream server. This value can't larger than 3600 (1 hour).

Default value: 0

dns_cache_ttl_max

Data type: Integer[default,3600]

Override TTL value (maximum) received from upstream server.

Default value: 0

bogus_nxdomain

Data type: Optional[Array[Adguard::Dns_server]]

Transform responses with these IP addresses to NXDOMAIN

Default value: undef

aaaa_disabled

Data type: Boolean

Respond with an empty answer to all AAAA requests

Default value: false

enable_dnssec

Data type: Boolean

Set DNSSEC flag in the outgoing DNS requests and check the result. Note if running an additional DNS server (such as Unbound or BIND) that uses DNSSEC you do not want DNSSEC on both as you will get erroes with legitimate DNS requests.

Default value: false

edns_client_subnet

Data type: Boolean

Enable EDNS Client Subnet option. If enabled, AdGuard Home will be sending ECS extension to the upstream DNS servers. Please note, that this will be done for clients with public IP addresses only.

Default value: false

max_goroutines

Data type: Integer

Max. number of parallel goroutines for processing incoming requests

Default value: 300

ipset_rules

Data type: Optional[Array]

Set ipset rules

Default value: undef

filtering_enabled

Data type: Boolean

Filtering of DNS requests based on filter lists.

Default value: true

filters_update_interval

Data type: Integer

How often the filters update (in hours).

Default value: 24

parental_enabled

Data type: Boolean

Parental control-based DNS requests filtering

Default value: false

safesearch_enabled

Data type: Boolean

Enforcing "Safe search" option for search engines, when possible.

Default value: false

safebrowsing_enabled

Data type: Boolean

Filtering of DNS requests based on safebrowsing

Default value: false

safebrowsing_cache_size

Data type: Integer

Safe Browsing cache size (in bytes).

Default value: 1048576

safesearch_cache_size

Data type: Integer

Safe Search cache size (in bytes).

Default value: 1048576

parental_cache_size

Data type: Integer

Parental Control cache size (in bytes).

Default value: 1048576

cache_time

Data type: Integer

Safe Browsing, Safe Search, Parental Control cache TTL.

Default value: 30

rewrites

Data type: Optional[Array[Adguard::Rewrite]]

An array of custom rewrite rules Format:

  • domain: the domain to perform the rewrite on
  • answer: the ip address to point to

Default value: undef

blocked_services

Data type: Optional[Array[Adguard::Blocked_service]]

An array of any services you wish to block.

Default value: undef

enable_tls

Data type: Boolean

EXPERIMENTAL: enable TLS. This workflow is largely untested, use with caution.

Default value: false

tls_options

Data type: Optional[Adguard::Tls_options]

The TLS configuration options.

Default value: undef

filters

Data type: Array[Adguard::Filter]

An array of block filters to add. Will default to the standard list provided by AdGuard Format:

  • name: the name for the filter (eg AdGuard Default)
  • enabled: true/false
  • url: the URL to point to

Default value: $adguard::params::filters

whitelist_filters

Data type: Optional[Array[Adguard::Filter]]

An array of whitelist filters to add. Format:

  • name: the name for the filter (eg AdGuard Default)
  • enabled: true/false
  • url: the URL to point to

Default value: undef

user_rules

Data type: Optional[Array]

Any custom rules you'd like to define, optional.

Default value: undef

enable_dhcp

Data type: Boolean

EXPERIMENTAL: Enables the DHCP options within AdGuard.

Default value: false

dhcp_interface

Data type: Optional[String]

The network interface to enabled DHCP on (eg 'eth0')

Default value: undef

dhcp_v4_options

Data type: Optional[Adguard::Dhcp_v4_options]

The configuration options for IPV4 DHCP

Default value: undef

dhcp_v6_options

Data type: Optional[Adguard::Dhcp_v6_options]

The configuration options for IPV6 DHCP

Default value: undef

clients

Data type: Optional[Array[Adguard::Client]]

EXPERIMENTAL: Override global defaults for a given list of clients. See: https://github.com/AdguardTeam/AdGuardHome/wiki/Clients for details Not extensively tested, please report any issues on the project repo.

Default value: undef

log_compress

Data type: Boolean

Whether or not to compress the logs.

Default value: false

log_localtime

Data type: Boolean

Whether to format timestamps using computer's local time.

Default value: false

log_max_backups

Data type: Integer

Maximum number of old log files to retain (MaxAge may still cause them to get deleted) (default: 0, which retains all old log files)

Default value: 0

log_max_size

Data type: Integer

Maximum size in megabytes of the log file before it gets rotated.

Default value: 100

log_max_age

Data type: Integer

MaxAge is the maximum number of days to retain old log files.

Default value: 3

log_file

Data type: Adguard::Log_file

Path to the log file. If empty, writes to stdout, if syslog -- system log (or eventlog on Windows). Valid options are:

  • unixpath
  • undef
  • syslog

Default value: undef

verbose_logging

Data type: Boolean

Enable or disable verbose logging. Defaults to false

Default value: false

adguard_path

Data type: Stdlib::Unixpath

The path to where you'd like AdGuard installed, defaults to /opt/AdGuardHome

Default value: '/opt/AdGuardHome'

manage_config

Data type: Boolean

Whether or not to manage the AdGuardHome.yaml file

Default value: true

configuration_file

Data type: Adguard::Config_file

The path to where you want to store the configuration file, must be the full path to AdGuardHome.yaml.

Default value: "${adguard_path}/AdGuardHome.yaml"

service_name

Data type: String

The name of the service to manage, defaults to AdGuardHome

Default value: 'AdGuardHome'

version

Data type: String

The version to install from the GitHub release

Default value: 'latest'

Functions

adguard::validate_tls_options

Type: Puppet Language

This function ensures that the TLS config is valid before applying it.

adguard::validate_tls_options(Adguard::Tls_options $tls_options)

The adguard::validate_tls_options function.

Returns: Boolean Returns true if the configuration is valid

tls_options

Data type: Adguard::Tls_options

Accepts a hash of tls_options

Data types

Adguard::Blocked_service

A list of services that AdGuard Home is able to block out of the box.

Alias of

Enum['9gag', 'amazon', 'cloudflare', 'dailymotion', 'discord', 'disneyplus', 'ebay', 'epic_games', 'facebook', 'hulu', 'imgur', 'instagram', 'mail_ru', 'netflix', 'ok', 'origin', 'pinterest', 'qq', 'reddit', 'skype', 'snapchat', 'spotify', 'steam', 'telegram', 'tiktok', 'tinder', 'twitch', 'twitter', 'viber', 'vimeo', 'vk', 'wechat', 'weibo', 'whatsapp', 'youtube']

Adguard::Client

Provides a structure for defining client overrides.

Alias of

Struct[{
    name                        => String,
    tags                        => Optional[Array],
    ids                         => Array,
    use_global_settings         => Boolean,
    filtering_enabled           => Optional[Boolean],
    parental_enabled            => Optional[Boolean],
    safesearch_enabled          => Optional[Boolean],
    use_global_blocked_services => Boolean,
    blocked_services            => Optional[Array[Adguard::Blocked_service]],
    upstreams                   => Optional[Array]
}]

Adguard::Config_file

Simple regex check for the AdGuard config file

Alias of

Pattern[/(.*\/)(.*)(AdGuardHome.yaml$)/]

Adguard::Dhcp_option

Ensures correct input for DHCP options

Alias of

Variant[Pattern[/^(\d)* hex ([\da-fA-F]{2})([\da-fA-F]{2})([\da-fA-F]{2})*$/], Stdlib::IP::Address::V4::Nosubnet]

Adguard::Dhcp_v4_options

A structured hash used to supply DHCP options for IPV4

Alias of

Struct[{
  gateway_ip     => Stdlib::IP::Address::V4::Nosubnet,
  subnet_mask    => Stdlib::IP::Address::V4::Nosubnet,
  range_start    => Stdlib::IP::Address::V4::Nosubnet,
  range_end      => Stdlib::IP::Address::V4::Nosubnet,
  lease_duration => Integer,
  options        => Optional[Array[Adguard::Dhcp_option]],
}]

Adguard::Dhcp_v6_options

A structured hash for sepcifying DHCP options for IPV6

Alias of

Struct[{
  range_start    => Stdlib::IP::Address::V6,
  lease_duration => Integer,
  ra_slaac_only  => Boolean,
  ra_allow_slaac => Boolean,
}]

Adguard::Dns_server

Valid DNS server types

Alias of

Variant[Stdlib::IP::Address, Stdlib::HTTPUrl, Adguard::Ipv4_port]

Adguard::Filter

Used to manage filters in Adguard

Alias of

Struct[{
    name    => String,
    enabled => Boolean,
    url     => Stdlib::HTTPUrl,
}]

Adguard::Http_proxy

Very basic validation to ensure the proxy type is sensible

Alias of

Pattern[/^(http|https|socks5)\:\/\//]

Adguard::Ipv4_port

Accepts an IPV4 address with a port (eg 192.168.1.1:8080)

Alias of

Pattern[/[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}:[0-9]{1,5}/]

Adguard::Log_file

Supported log file types

Alias of

Variant[Stdlib::Unixpath, Enum['syslog'], Undef]

Adguard::Rewrite

Stuctured hash for managing rewrites

Alias of

Struct[{
    domain => String,
    answer => String,
}]

Adguard::Tls_options

Configures TLS options in AdGuard Home

Alias of

Struct[{
  server_name           => Stdlib::Host,
  force_https           => Boolean,
  port_https            => Stdlib::Port,
  port_dns_over_tls     => Stdlib::Port,
  port_dns_over_quic    => Stdlib::Port,
  port_dnscrypt         => Stdlib::Port,
  dnscrypt_config_file  => Optional[Stdlib::Unixpath],
  allow_unencrypted_doh => Boolean,
  strict_sni_check      => Boolean,
  certificate_chain     => Optional[String],
  private_key           => Optional[String],
  certificate_path      => Optional[Stdlib::Unixpath],
  private_key_path      => Optional[Stdlib::Unixpath]
}]

Adguard::User

A structed hash for providing users for the adguard web UI.

Alias of

Struct[{
    username => String,
    password => String
}]