%{_mandir}/man1/dnswasher.1.gz
%{_mandir}/man1/dumresp.1.gz
%{_mandir}/man1/ixfrdist.1.gz
+%{_mandir}/man5/ixfrdist.yml.5.gz
%{_mandir}/man1/ixplore.1.gz
%{_mandir}/man1/pdns_notify.1.gz
%{_mandir}/man1/nproxy.1.gz
%{_mandir}/man1/dnswasher.1.gz
%{_mandir}/man1/dumresp.1.gz
%{_mandir}/man1/ixfrdist.1.gz
+%{_mandir}/man5/ixfrdist.yml.5.gz
%{_mandir}/man1/ixplore.1.gz
%{_mandir}/man1/pdns_notify.1.gz
%{_mandir}/man1/nproxy.1.gz
%{_mandir}/man1/dnswasher.1.gz
%{_mandir}/man1/dumresp.1.gz
%{_mandir}/man1/ixfrdist.1.gz
+%{_mandir}/man5/ixfrdist.yml.5.gz
%{_mandir}/man1/ixplore.1.gz
%{_mandir}/man1/pdns_notify.1.gz
%{_mandir}/man1/nproxy.1.gz
debian/tmp/usr/share/man/man1/dnswasher.1
debian/tmp/usr/share/man/man1/dumresp.1
debian/tmp/usr/share/man/man1/ixfrdist.1
+debian/tmp/usr/share/man/man5/ixfrdist.yml.5
debian/tmp/usr/share/man/man1/ixplore.1
debian/tmp/usr/share/man/man1/nproxy.1
debian/tmp/usr/share/man/man1/nsec3dig.1
dnswasher.1 \
dumresp.1 \
ixfrdist.1 \
+ ixfrdist.yml.5 \
ixplore.1 \
nproxy.1 \
nsec3dig.1 \
destname = srcname.split('/')[-1][:-2]
man_pages.append((srcname, destname, descriptions.get(destname, ''),
[author], 1))
-
+man_pages.append(('manpages/ixfrdist.yml.5', 'ixfrdist.yml',
+ 'The ixfrdist configuration file', [author], 5))
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
Synopsis
--------
-:program:`ixfrdist` [*OPTION*]... *DOMAIN* [*DOMAIN*]...
+:program:`ixfrdist` [*OPTION*]...
Description
-----------
:program:`ixfrdist` transfers zones from an authoritative server and re-serves these zones over AXFR and IXFR.
-It checks the SOA serial for all *DOMAIN*\ s from the server set with **--server-address** and downloads new versions to **--work-dir**.
-This working directory has the following structure: ``work-dir/ZONE/SERIAL``, e.g. ``work-dir/rpz.example./2018011902``.
+It checks the SOA serial for all configured domains and downloads new versions to disk.
-When a SOA query comes in on the address(es) set with **--listen-address**, :program:`ixfrdist` responds with the latest SOA for the zone it has.
-This query can be followed up with an IXFR or AXFR query, which will then be served.
-Should an IXFR be served, :program:`ixfrdist` will condense the diff into the IXFR.
+When a SOA query comes in and the client's address is allowed by the ACL, :program:`ixfrdist` responds with the latest SOA for the zone it has.
+This query can be followed up with an IXFR or AXFR query, which will then be served to the client.
+Should an IXFR be served, :program:`ixfrdist` will condense all differences it has for the domain into one IXFR.
-When using **--uid** or **--gid** the **--work-dir** directory will be accessed (and potentially created) as the proved user/group.
+:program:`ixfrdist` is configured with a configuration file in YAML format.
+Please see :manpage:`ixfrdist.yml(5)` for information.
Options
-------
---help Show all supported options
---verbose Log INFO messages
---debug Log INFO and DEBUG messages
---version Display the version of ixfrdist
---listen-address <ADDRESS> Listen on *ADDRESS* for incoming queries.
- *ADDRESS* may contain a port number, when unset 53 is assumed.
- This option can be given multiple times.
- When not set, 127.0.0.1:53 is assumed.
---server-address <ADDRESS> IP address and port of the upstream server.
- 127.0.0.1:5300 by default.
---work-dir <DIR> Path to a directory where the AXFR data are saved.
- By default, this is the current working directory.
---keep <NUM> Keep at most *NUM* versions of any zone.
- By default, 20 versions are kept.
---uid <UID> Drop effective user-id to *UID* after binding the listen sockets.
---gid <GID> Drop effective group-id to *GID* after binding the listen sockets.
---axfr-timeout <NUM> Stop an inbound AXFR when it is not completed in *NUM* seconds. Defaults to 10 seconds.
---tcp-in-threads <NUM> Amount of worker threads to handle TCP traffic from clients.
- This limits the number of concurrent AXFR/IXFR sessions, the default is 10.
+--help Show all supported options
+--verbose Log INFO messages
+--debug Log INFO and DEBUG messages
+--version Display the version of ixfrdist
+--config <PATH> Load configuration from *PATH*, a YAML file. When not set,
+ an `ixfrdist.yml` is attempted to be read from the SYSCONFDIR.
See also
--------
-ixplore(1), pdns_server(1)
+ixplore(1), pdns_server(1), ixfrdist.yml(5)
--- /dev/null
+ixfrdist.yml
+============
+
+Synopsis
+--------
+
+ixfrdist.yml
+
+Description
+-----------
+
+:program:`ixfrdist` reads its configuration for a YAML file.
+By default, this file is called `ixfrdist.yml` and is read from the directory configured as `SYSCONFDIR` when building the software.
+This directory is usually one of `/etc/pdns`, `/etc/powerdns`.
+Run `ixfrdist --help` to see the default.
+
+Example
+-------
+
+.. code-block:: yaml
+
+ listen:
+ - 192.0.2.2
+ - '[2001:DB8:ABCD::2]:5300'
+ - 127.0.0.1
+
+ acl:
+ - 127.0.0.1
+ - '192.0.2.0/24'
+ - '2001:DB8:ABCD:1234::/64'
+
+ workdir: /var/lib/ixfrdist
+
+ uid: ixfrdist
+ gid: ixfrdist
+
+ domains:
+ - domain: example.com
+ master: 192.0.2.18:5301
+ - domain: example.net
+ master: 2001:DB8:ABCD::2
+
+Options
+-------
+
+:listen:
+ The list of addresses to listen on.
+ :program:`ixfrdist` listens on both TCP and UDP.
+ When no port is specified, 53 is used. When specifying ports for IPv6, use the "bracket" notation.
+ By default, :program:`ixfrdist` listens on ``127.0.0.1:53`` and ``[::1]:53``.
+
+:acl:
+ A list of netmasks that are allowed to query :program:`ixfrdist` and request AXFRs and IXFRs
+ Entries without a netmask will be interpreted as a single address.
+ By default, the ACL is set is ``127.0.0.0/8`` and ``::1/128``.
+
+:axfr-timeout:
+ Timeout in seconds an AXFR transaction requested by :program:`ixfrdist` may take.
+ Increase this when the network to the authoritative servers is slow or the domains are very large and you experience timeouts.
+ Defaults to 20.
+
+:work-dir:
+ The directory where the domain data is stored.
+ When not set, the current working directory is used.
+ This working directory has the following structure: ``work-dir/ZONE/SERIAL``, e.g. ``work-dir/rpz.example./2018011902``.
+ It is highly recommended to set this option, as the current working directory might change between invocations.
+ This directory must be writable for the user or group :program:`ixfrdist` runs as.
+
+:keep:
+ Amount of older copies/IXFR diffs to keep for every domain.
+ This is set to 20 by default.
+
+:tcp-in-threads:
+ Number of threads to spawn for TCP connections (AXFRs) from downstream hosts.
+ This limits the number of concurrent AXFRs to clients.
+ Set to 10 by default.
+
+:gid:
+ Group name or numeric ID to drop privileges to after binding the listen sockets.
+ By default, :program:`ixfrdist` runs as the user that started the process.
+
+:uid:
+ User name or numeric ID to drop privileges to after binding the listen sockets.
+ By default, :program:`ixfrdist` runs as the user that started the process.
+
+:domains:
+ A list of domains to redistribute.
+ This option is mandatory.
+
+ :domain: The domain name to transfer from the ``master``.
+ Mandatory.
+ :master: IP address of the server to transfer this domain from.
+ Mandatory.
+
+See also
+--------
+
+:manpage:`ixfrdist(1)`
projects / pdns / commitdiff