~~~~~~~~~~~~~~~~~~~~~~~~
.. versionchanged:: 4.2.0
- This option has been changed since v4.2.0
+ The syntax of the argument has been changed.
Comma, tab or space separated list of files to open. You can use
-`geoip-cvs-to-dat <https://github.com/dankamongmen/sprezzos-world/blob/master/packaging/geoip/debian/src/geoip-csv-to-dat.cpp>`__
+`geoip-cvs-to-dat <https://github.com/dankamongmen/sprezzos-world/blob/master/packaging/geoip/debian/src/geoip-csv-to-dat.cpp>`__.
to generate your own.
-For MMDB files, see `https://github.com/maxmind/getting-started-with-mmdb <https://github.com/maxmind/getting-started-with-mmdb>`
+For MMDB files, see `MaxMind's getting started guide <https://github.com/maxmind/getting-started-with-mmdb>`__.
Since v4.2.0, database type is determined by file suffix, or you can use new syntax.
New syntax is ``[driver:]path[;options]``.
-Currently supported options for dat driver (legacy libGeoIP):
- - mode=standard, memory, index or mmap
+Drivers and options
+^^^^^^^^^^^^^^^^^^^
-Currently supported options for mmdb driver (libmaxminddb):
- - mode=mmap
- - language=en (which language to use)
+:dat: legacy libGeoIP database. Options:
-.. _setting-geoip-database-cache:
+ :mode: The caching mode for data, one of ``standard``, ``memory``, ``index``, or ``mmap``.
-``geoip-database-cache`` (before v4.2.0)
+:mmdb: driver for libmaxminddb databases. Options:
+
+ :mode: The caching mode for data, only ``mmap`` is supported
+ :language: The language to use, ``en`` by default
+
+``geoip-database-cache``
~~~~~~~~~~~~~~~~~~~~~~~~
.. deprecated:: 4.2.0
+
This setting is removed
Specifies the kind of caching that is done on the database. This is one
---------------
Zone configuration file uses YAML syntax. Here is simple example. Note
-that the ‐ before certain keys is part of the syntax.
+that the ``‐`` before certain keys is part of the syntax.
.. code-block:: yaml
Keys explained
~~~~~~~~~~~~~~
-- **domains**: Mandatory root key. All configuration is below this
-- **domain**: Defines a domain. You need ttl, records, services under
- this.
-- **ttl**: TTL value for all records
-- **records**: Put fully qualified name as subkey, under which you must
- define at least soa: key. Note that this is an array of records, so ‐
- is needed for the values.
-- **services**: Defines one or more services for querying.
-- From 4.2.0, you can also use %lat, %lon, %loc to expand for geographic
- location, if available in backend. %loc in particular can be safely
- used with LOC record type.
-- From 4.2.0, you can also use %ip4 and %ip6 that will expand to the
- IP address when AFI matches, and empty otherwise. Can be particularly
- used with A and AAAA record types.
-- From 4.1.0, you can also use %cc = 2 letter country code
-- From 4.0.0, you can also use %as = ASn, %ip = Remote IP
-- From 4.0.0, you can also use additional specifiers. These are %hh =
- hour, %dd = day, %mo = month, %mos = month as short string, %wd =
- weekday (as number), %wds weekday as short string.
-- From 4.0.0, scopeMask is set to most specific value, in case of
- date/time modifiers it will be 32 or 128, but with the others it is
- set to what geoip says it used for matching.
-- From 4.0.0, You can add per-network overrides for format, they will
- be formatted with the same placeholders as default. Default is
- short-hand for adding 0.0.0.0/0 and ::/0. Default is default when
- only string is given for service name.
-- From 4.0.0, You can use array to specify return values, works only if
- you have those records specified. It matches the format results to
- your records, and if it finds match that is used. Otherwise the last
- is returned.
-- From 4.0.0, You can apply all the attributes for the content of
- static records too.
-- From 4.0.0, You can use record attributes to set TTL.
-- From 4.0.0, You can use record attributes to define weight. If this
- is given, only one record is chosen randomly based on the weight.
- **DO NOT** mix record types for these. It will not work. PROBABILITY
- is calculated by summing up the weights and dividing each weight with
- the sum. **WARNING**: If you use ip or time/date specifiers, caching
- will be disabled for that RR completely. That means, if you have a
-
-something.example.com: - a: 1.2.3.4 - txt: "your ip is %ip"
+:domains: Mandatory root key. All configuration is below this
-then caching will not happen for any records of something.example.com.
-If you need to use TXT for debugging, make sure you use dedicated name
-for it.
+ :domain: Defines a domain. You need ttl, records, services under this.
+ :ttl: TTL value for all records, if no TTL is specified in specific record.
+ :records: Records for this domain.
+ Each subkey must be a fully qualified name, under which an array of records follows.
+ Every record is then keyed by its type (e.g. ``a``, ``txt``) and a type may exist more than once.
+ The content for this record may then be confgured as the value.
+ However, a record can alternatively have one or more subkeys:
+
+ :content: The content of the record.
+ :ttl: The TTL for this record.
+ :weight: The weight for this specific content
-Since v4.1.0 you can mix service and static records to produce the sum
-of these records, including apex record.
+ :services: Defines one or more services for querying.
+ Each service name may have one or more placeholders.
-Format explained
-~~~~~~~~~~~~~~~~
+.. note::
-Following placeholders are supported, and support subnet caching with EDNS.
-- %%: %
-- %co: With legacy GeoIP database only expands to three letter country name,
+ For each **domain**, one record of the domain name **MUST** exist with a ``soa`` record.
+
+Placeholders
+~~~~~~~~~~~~
+
+Services, domains and record content can contain any number of placeholders that are replaced based on the information in the database and the query.
+
+Following placeholders are supported, and support subnet caching with EDNS:
+
+:%%: literal ``%``
+:%co: With legacy GeoIP database only expands to three letter country name,
with MMDB and others this will expand into ISO3166 country code.
-- %cc: ISO3166 country code.
-- %cn: ISO3166 continent code.
-- %af: v4 or v6.
-- %re: Region code
-- %na: AS organization name (spaces are converted to _)
-- %as: AS number
-- %ci: City name
-- %loc: LOC record style expansion of location
-- %lat: Decimal degree latitude
-- %lon: Decimal degree longitude
-
-Following placeholders disable caching completely.
-- %yy: Year
-- %mos: Month name
-- %mo: Month
-- %wds: Weekday name
-- %wd: Weekday
-- %dd: Year day
-- %hh: Hour
-- %ip: IP address
-- %ip4: IPv4 address
-- %ip6: IPv6 address
-
-.. warning::
- Before 4.2.0 if record expanded to empty value it could cause SERVFAIL. Since 4.2.0 such expansions for non-TXT record types are not included in response.
-
-.. warning::
- If the record which a service points to exists under "records" then it is returned as a direct answer. If it does not exist under "records" then it is returned as a CNAME.
-
-.. warning::
- If your services match wildcard records in your zone file
- then these will be returned as CNAMEs. This will only be an issue if you
- are trying to use a service record at the apex of your domain where you
- need other record types to be present (such as NS and SOA records.) Per
- :rfc:`2181`, CNAME records cannot appear in the same label as NS or SOA
- records.
+:%cc: ISO3166 country code.
+:%cn: ISO3166 continent code.
+:%af: v4 or v6.
+:%re: Region code
+:%na: AS organization name (spaces are converted to _)
+:%as: AS number
+:%ci: City name
+:%loc: LOC record style expansion of location
+:%lat: Decimal degree latitude
+:%lon: Decimal degree longitude
+
+These placeholders disable caching for the record completely:
+
+:%yy: Year
+:%mos: Month name
+:%mo: Month
+:%wds: Weekday name
+:%wd: Weekday
+:%dd: Year day
+:%hh: Hour
+:%ip: Client IP address
+:%ip4: Client IPv4 address
+:%ip6: Client IPv6 address
+
+.. versionadded:: 4.2.0
+
+ These placeholder have been added in version 4.2.0:
+
+ - %lat, %lon, %loc to expand for geographic location, if available in backend. %loc in particular can be safely used with LOC record type.
+ - %ip4 and %ip6 that will expand to the IP address when AFI matches, and empty otherwise. Can be particularly used with A and AAAA record types.
+
+.. versionadded:: 4.1.0
+
+ These placeholder have been added in version 4.1.0:
+
+ - %cc = 2 letter country code
+
+Using the ``weight`` attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use record attributes to define weight.
+If this is given, only one record is chosen randomly based on the weight.
+
+Probability is calculated by summing up the weights and dividing each weight with the sum.
+
+Responses to queries
+~~~~~~~~~~~~~~~~~~~~
+
+If the record which a service points to exists under "records" then it is returned as a direct answer.
+If it does not exist under "records" then it is returned as a CNAME.
+
+You can mix service and static records to produce the sum of these records, including apex record.
+For instance, this configuration will send the correct response both A and SOA queries:
+
+.. code-block:: yaml
+
+ domains:
+ - domain: example.com
+ - ttl: 300
+ - records:
+ geo.example.com:
+ - soa: ns1.example.com hostmaster.example.com 2014090125 7200 3600 1209600 3600
+ - ns: ns1.example.com
+ - a: 192.0.2.1
+ swe.eu.example.com:
+ - a: 192.0.2.2
+ - services:
+ geo.example.com: ['%co.%cn.example.com']
+
+If your services match wildcard records in your zone file then these will be returned as CNAMEs.
+This will only be an issue if you are trying to use a service record at the apex of your domain where you need other record types to be present (such as NS and SOA records).
+Per :rfc:`2181`, CNAME records cannot appear in the same label as NS or SOA records.
+
+.. versionchanged:: 4.2.0
+
+ Before, a record expanded to an empty value it could cause SERVFAIL.
+ Since 4.2.0 such expansions for non-TXT record types are not included in response.
+
+Caching and the GeoIP Backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :ref:`packet-cache` and :ref:`query-cache` will cache the records with EDNS Client Subnet information, when provided in the response.
+Use of certain placeholders (described above) can disable record caching for certail resource records.
+
+That means, if you have a record like this:
+
+.. code-block:: yaml
+
+ something.example.com:
+ - a: 1.2.3.4
+ - txt: "your ip is %ip"
+
+then caching will not happen for any records of something.example.com.
+
+If you need to use TXT for debugging, make sure you use dedicated name for it.
projects / thirdparty / pdns.git / commitdiff
