From: Pieter Lexis Date: Wed, 16 May 2018 11:41:11 +0000 (+0200) Subject: ixfrdist: update manpages wrt yml config X-Git-Tag: dnsdist-1.3.1~84^2~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d39a0d8a2a41fb69c010d675cfe216969ce986e0;p=thirdparty%2Fpdns.git ixfrdist: update manpages wrt yml config --- diff --git a/build-scripts/build-auth-rpm b/build-scripts/build-auth-rpm index fa1692c286..5c4edb72f6 100755 --- a/build-scripts/build-auth-rpm +++ b/build-scripts/build-auth-rpm @@ -473,6 +473,7 @@ fi %{_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 @@ -803,6 +804,7 @@ exit 0 %{_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 @@ -1084,6 +1086,7 @@ exit 0 %{_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 diff --git a/build-scripts/debian-authoritative/pdns-tools.manpages b/build-scripts/debian-authoritative/pdns-tools.manpages index a5195d1f8b..1530002b3b 100644 --- a/build-scripts/debian-authoritative/pdns-tools.manpages +++ b/build-scripts/debian-authoritative/pdns-tools.manpages @@ -10,6 +10,7 @@ debian/tmp/usr/share/man/man1/dnstcpbench.1 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 diff --git a/docs/Makefile.am b/docs/Makefile.am index 6d6832de74..1622f1d720 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -21,6 +21,7 @@ MANPAGES_TARGET_TOOLS = calidns.1 \ dnswasher.1 \ dumresp.1 \ ixfrdist.1 \ + ixfrdist.yml.5 \ ixplore.1 \ nproxy.1 \ nsec3dig.1 \ diff --git a/docs/conf.py b/docs/conf.py index 5c9cf39818..4e78590ee0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -197,7 +197,8 @@ for f in glob.glob('manpages/*.1.rst'): 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 diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 0c2ea99886..7e385a4dca 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -9,3 +9,4 @@ The manual pages for these programs are included here: :glob: *.1 + *.5 diff --git a/docs/manpages/ixfrdist.1.rst b/docs/manpages/ixfrdist.1.rst index 446d0bc859..72ecd5be1d 100644 --- a/docs/manpages/ixfrdist.1.rst +++ b/docs/manpages/ixfrdist.1.rst @@ -4,45 +4,32 @@ ixfrdist 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
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
IP address and port of the upstream server. - 127.0.0.1:5300 by default. ---work-dir Path to a directory where the AXFR data are saved. - By default, this is the current working directory. ---keep Keep at most *NUM* versions of any zone. - By default, 20 versions are kept. ---uid Drop effective user-id to *UID* after binding the listen sockets. ---gid Drop effective group-id to *GID* after binding the listen sockets. ---axfr-timeout Stop an inbound AXFR when it is not completed in *NUM* seconds. Defaults to 10 seconds. ---tcp-in-threads 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 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) diff --git a/docs/manpages/ixfrdist.yml.5.rst b/docs/manpages/ixfrdist.yml.5.rst new file mode 100644 index 0000000000..d39b66543d --- /dev/null +++ b/docs/manpages/ixfrdist.yml.5.rst @@ -0,0 +1,98 @@ +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)`