From 7b41a5430d4e1d04ac38afbf274458c17127939c Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Thu, 23 Apr 2015 18:49:27 +0200 Subject: [PATCH] Add manpages to the html documentation --- docs/Makefile.am | 3 ++- docs/markdown/tools/analysis.md | 43 ++++++++++++--------------------- docs/mkdocs.yml | 16 ++++++++++++ docs/process-md.sh | 10 ++++++++ 4 files changed, 44 insertions(+), 28 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 297e4d83ea..af7c4ea80b 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -32,9 +32,10 @@ EXTRA_DIST = manpages \ .PHONY: html manpages html: html/index.html -html/index.html: process-md.sh mkdocs.yml markdown/** markdown/*/** +html/index.html: process-md.sh mkdocs.yml markdown/** markdown/*/** manpages/* mkdir -p doc-build rsync -a --delete markdown/. doc-build/. + cp -r manpages/ doc-build/ ./process-md.sh pre mkdocs build --clean ./process-md.sh post diff --git a/docs/markdown/tools/analysis.md b/docs/markdown/tools/analysis.md index 50db56ec57..9c68ec46c7 100644 --- a/docs/markdown/tools/analysis.md +++ b/docs/markdown/tools/analysis.md @@ -1,10 +1,22 @@ # Tools to analyse DNS traffic DNS is highly mission critical, it is therefore necessary to be able to study and compare DNS traffic. Since version 2.9.18, PowerDNS comes with -various tools to aid in analysis. These tools are best documented by their -manpages, and their `--help` output. - -The PowerDNS tools do not (yet) follow an independent release process. +various tools to aid in analysis. + +The following tools are available: + + * [dnsbulktest](../manpages/dnsbulktest.1.md) - A resolver stress-tester + * [dnsgram](../manpages/dnsgram.1.md) - Show per 5-second statistics to study intermittent resolver issues + * [dnsreplay](../manpages/dnsreplay.1.md) - Replay a pcap with DNS queries + * [dnsscan](../manpages/dnsscan.1.md) - Prints the query-type amounts in a pcap + * [dnsscope](../manpages/dnsscope.1.md) - Calculates statistics without replaying traffic + * [dnstcpbench](../manpages/dnstcpbench.1.md) - Perform TCP benchmarking of DNS servers + * [dnswasher](../manpages/dnswasher.1.md) - Clean a pcap of identifying IP information + * [nsec3dig](../manpages/nsec3dig.1.md) - Calculate the correctness of NSEC3 proofs + * [saxfr](../manpages/saxfr.1.md) - AXFR zones and show extra information + +# Downloading the tools +The PowerDNS tools do not (yet) follow an independent release process. However, we keep them working, and they are shipped with PowerDNS Authoritative Server tarballs. @@ -15,26 +27,3 @@ commit, and these can be found on: * * * - -## `dnsreplay pcapfile [ipaddress] [port number]` -This program takes recorded questions and answers and replays them to a specified nameserver and reporting afterwards which percentage of answers matched, were worse or better. - -## `dnswasher pcapfile output` -Anonymises recorded traffic, making sure it only contains DNS, and that the originating IP addresses of queries are stripped, which may allow you to send traces to our company or mailing list without violating obligations towards your customers or privacy laws. - -## `dnsscope pcapfile` -Calculates statistics without replaying traffic. - -## `dnsgram` -Creates statistics on 5-second segments of a pcap, allowing you to study intermittent -performance problems. - -## `dnsbulktest` -Send out thousands of queries in parallel from Alexa top list to stress out resolvers. - -## `dnsdist` -Simple but high performance UDP and TCP DNS load balancer/distributor. - -## `dnstcpbench` -Stress out DNS servers with TCP based queries, as read from a file. - diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2f6d6d19c4..a0f2987dae 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -27,6 +27,11 @@ pages: - [authoritative/recursion.md, 'Authoritative', 'Recursion with the Authoritative Server'] - [authoritative/dnssec.md, 'Authoritative', 'Serve DNSSEC Signed Data'] - [authoritative/settings.md, 'Authoritative', 'List of Settings'] + - [manpages/zone2ldap.1.md, 'Authoritative', 'Manpage: zone2ldap.1'] + - [manpages/zone2sql.1.md, 'Authoritative', 'Manpage: zone2sql.1'] + - [manpages/pdns_control.1.md, 'Authoritative', 'Manpage: pdns_control.1'] + - [manpages/pdnssec.1.md, 'Authoritative', 'Manpage: pdnssec.1'] + - [manpages/pdns_server.1.md, 'Authoritative', 'Manpage: pdns_server.1'] - [authoritative/backend-bind.md, 'Authoritative Backends', 'BIND'] - [authoritative/backend-generic-mypgsql.md, 'Authoritative Backends', 'Generic MySQL and PostgreSQL'] - [authoritative/backend-geo.md, 'Authoritative Backends', 'Geo(graphic loadbalancing)'] @@ -47,6 +52,8 @@ pages: - [recursor/security.md, 'Recursor', 'Security of the Recursor'] - [recursor/stats.md, 'Recursor', 'Recursor Statistics'] - [recursor/running.md, 'Recursor', 'Controlling & Querying'] + - [manpages/pdns_recursor.1.md, 'Recursor', 'Manpage: pdns_recursor.1'] + - [manpages/rec_control.1.md, 'Recursor', 'Manpage: rec_control.1'] - [recursor/performance.md, 'Recursor', 'Performance Tuning'] - [recursor/scripting.md, 'Recursor', 'Scripting'] - [recursor/dns64.md, 'Recursor', 'DNS64 support'] @@ -69,3 +76,12 @@ pages: - [appendix/documentation.md, 'Tools and Appendices', "Documentation details"] - [appendix/compiling-powerdns.md, 'Tools and Appendices', 'Compiling PowerDNS'] - [tools/analysis.md, 'Tools and Appendices', 'DNS Analysis Tools'] + - [manpages/dnsbulktest.1.md, 'Tools and Appendices', 'Manpage: dnsbulktest.1'] + - [manpages/dnsgram.1.md, 'Tools and Appendices', 'Manpage: dnsgram.1'] + - [manpages/dnsreplay.1.md, 'Tools and Appendices', 'Manpage: dnsreplay.1'] + - [manpages/dnsscan.1.md, 'Tools and Appendices', 'Manpage: dnsscan.1'] + - [manpages/dnsscope.1.md, 'Tools and Appendices', 'Manpage: dnsscope.1'] + - [manpages/dnstcpbench.1.md, 'Tools and Appendices', 'Manpage: dnstcpbench.1'] + - [manpages/dnswasher.1.md, 'Tools and Appendices', 'Manpage: dnswasher.1'] + - [manpages/nsec3dig.1.md, 'Tools and Appendices', 'Manpage: nsec3dig.1'] + - [manpages/saxfr.1.md, 'Tools and Appendices', 'Manpage: saxfr.1'] diff --git a/docs/process-md.sh b/docs/process-md.sh index 384cac0560..5aadb7468a 100755 --- a/docs/process-md.sh +++ b/docs/process-md.sh @@ -2,7 +2,17 @@ pre() { for file in `find doc-build -name '*.md' -type f -print`; do + # Remove lines starting with '%' from manpages + if echo "$file" | grep -q -e '\.1\.md$'; then + cat $file | perl -n -e '!/^%/ && print;' > ${file}.tmp + mv -f ${file}.tmp $file + fi + + # Process include statements pandoc -f markdown_github+pipe_tables -t markdown_github+pipe_tables -F markdown/process-includes.py $file -o $file + + # Remove crap: + # * Escaped symbols perl -i -p \ -e 's/\\([\$\*\^><])/\1/g;' \ $file -- 2.47.2