From: Miod Vallat Date: Fri, 13 Dec 2024 09:38:10 +0000 (+0100) Subject: Tweaks to get manpages to render better. X-Git-Tag: dnsdist-2.0.0-alpha1~198^2~2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5ecfddf161d16a36a53b9852b48c97479ecccf99;p=thirdparty%2Fpdns.git Tweaks to get manpages to render better. --- diff --git a/docs/manpages/calidns.1.rst b/docs/manpages/calidns.1.rst index 8ec977b8c8..27e68e9554 100644 --- a/docs/manpages/calidns.1.rst +++ b/docs/manpages/calidns.1.rst @@ -44,5 +44,5 @@ Options in percent. --plot-file Write results to the specified file. --quiet Whether to run quietly, outputting only the maximum QPS reached. - This option is mostly useful when used with --minimum-success-rate. + This option is mostly useful when used with ``--minimum-success-rate``. --want-recursion Set this flag to send queries with the Recursion Desired flag set. diff --git a/docs/manpages/dnsbulktest.1.rst b/docs/manpages/dnsbulktest.1.rst index fce6b236b6..c3e5f225c2 100644 --- a/docs/manpages/dnsbulktest.1.rst +++ b/docs/manpages/dnsbulktest.1.rst @@ -11,7 +11,7 @@ Description :program:`dnsbulktest` sends a large amount of different queries (for up to *LIMIT* different domains) to the nameserver at *IPADDRESS* on port -*PORT*. It reads the domain names from STDIN in the alexa topX format +*PORT*. It reads the domain names from STDIN in the Alexa topX format and outputs statistics on STDOUT. Options diff --git a/docs/manpages/dnspcap2calidns.1.rst b/docs/manpages/dnspcap2calidns.1.rst index f85f724a7b..91f1ac60a6 100644 --- a/docs/manpages/dnspcap2calidns.1.rst +++ b/docs/manpages/dnspcap2calidns.1.rst @@ -10,7 +10,7 @@ Description ----------- :program:`dnspcap2calidns` reads the PCAP file *PCAPFILE* for DNS queries and -writes these to *OUTFILE* in the format understood by :program:`calidns` +writes these to *OUTFILE* in the format understood by :program:`calidns`. Options ------- diff --git a/docs/manpages/dnsreplay.1.rst b/docs/manpages/dnsreplay.1.rst index 8635498062..1263328124 100644 --- a/docs/manpages/dnsreplay.1.rst +++ b/docs/manpages/dnsreplay.1.rst @@ -13,10 +13,10 @@ This program takes recorded questions and answers and replays them to the specified nameserver and reporting afterwards which percentage of answers matched, were worse or better. -dnsreplay compares the answers and some other metrics with the actual +:program:`dnsreplay` compares the answers and some other metrics with the actual ones with those found in the dumpfile. -By default it only replay queries with recursion-desired flag set. +By default it will only replay queries with recursion-desired flag set. Options ------- @@ -36,11 +36,11 @@ PORT --packet-limit Stop after replaying *NUM* packets. Default for *NUM* is 0, which means no limit. --pcap-dns-port Look at packets from or to this port in the PCAP. Default is 53. ---quiet If *FLAG* is set to 1. dnsreplay will not be very noisy with its +--quiet If *FLAG* is set to 1, :program:`dnsreplay` will not be very noisy with its output. This is the default. ---recursive If *FLAG* is set to 1. dnsreplay will only replay queries with +--recursive If *FLAG* is set to 1, :program:`dnsreplay` will only replay queries with recursion desired flag set. This is the default. ---source-from-pcap If *FLAG* is set to 1. dnsreplay will send the replayed queries from the +--source-from-pcap If *FLAG* is set to 1, :program:`dnsreplay` will send the replayed queries from the source IP address and port present in the PCAP file. This requires IP_TRANSPARENT support. Default is 0 which means replayed queries will be sent from a local address. diff --git a/docs/manpages/dnstcpbench.1.rst b/docs/manpages/dnstcpbench.1.rst index c5b18f2371..2bcbe46445 100644 --- a/docs/manpages/dnstcpbench.1.rst +++ b/docs/manpages/dnstcpbench.1.rst @@ -35,16 +35,17 @@ The equivalent for IPv6 is not known. Options ------- --f, , --file *FILENAME* from which to read queries. Defaults to standard input if unspecified. --h, --help Provide a helpful message. ---timeout-msec *MSEC* milliseconds to wait for an answer. --u, --udp-first Attempt resolution via UDP first, only do TCP if truncated answer is received. --v, --verbose Be wordy on what the program is doing. ---workers Use *NUM* parallel worker threads. - -*REMOTE-ADDRESS*: IPv4 or IPv6 to test against. - -*REMOTE-PORT*: Port to test against, defaults to 53. +REMOTE-ADDRESS + IPv4 or IPv6 to test against. +REMOTE-PORT + Port to test against, defaults to 53. + +-f , --file *FILENAME* from which to read queries. Defaults to standard input if unspecified. +-h, --help Provide a helpful message. +--timeout-msec *MSEC* milliseconds to wait for an answer. +-u, --udp-first Attempt resolution via UDP first, only do TCP if truncated answer is received. +-v, --verbose Be wordy on what the program is doing. +--workers Use *NUM* parallel worker threads. Bugs ---- diff --git a/docs/manpages/dnswasher.1.rst b/docs/manpages/dnswasher.1.rst index 1b20806226..57dea35bbf 100644 --- a/docs/manpages/dnswasher.1.rst +++ b/docs/manpages/dnswasher.1.rst @@ -4,12 +4,12 @@ dnswasher Synopsis -------- -:program:`dnswasher` *INFILE* [*INFILE*] *OUTFILE* +:program:`dnswasher` [*OPTION*]... *INFILE* [*INFILE*] *OUTFILE* Description ----------- -dnswasher takes one or more *INFILE*\ s in PCAP format and writes out +:program:`dnswasher` takes one or more *INFILE*\ s in PCAP format and writes out *OUTFILE* also in PCAP format, while obfuscating end-user IP addresses. This is useful to share data with third parties while attempting to @@ -25,11 +25,11 @@ about. Options ------- ---decrypt,-d Undo IPCipher encryption of IP addresses ---help, -h Show summary of options. ---key,-k Base64 encoded 128-bit key for IPCipher ---passphrase,-p Passphrase that will be used to derive an IPCipher key ---version,-v Output version +--decrypt, -d Undo IPCipher encryption of IP addresses. +--help, -h Show summary of options. +--key, -k Base64 encoded 128-bit key for IPCipher. +--passphrase, -p Passphrase that will be used to derive an IPCipher key. +--version, -v Output version. See also -------- diff --git a/docs/manpages/ixplore.1.rst b/docs/manpages/ixplore.1.rst index 1fb08b2f67..dd935fbad1 100644 --- a/docs/manpages/ixplore.1.rst +++ b/docs/manpages/ixplore.1.rst @@ -35,7 +35,7 @@ ZONE The name of the zone the IXFRs are consumed from. BEFORE Path to the 'before' zonefile. -AFYER +AFTER Path to the 'after' zonefile. track-mode diff --git a/docs/manpages/pdns_control.1.rst b/docs/manpages/pdns_control.1.rst index 032cb8ef72..17ce3a0b58 100644 --- a/docs/manpages/pdns_control.1.rst +++ b/docs/manpages/pdns_control.1.rst @@ -39,7 +39,7 @@ bind-domain-extended-status [*ZONE*...] Output an extended status of all zones, containing much more information than the simple zone status, like the number of records currently loaded, whether pdns -is primary or secondary for the zone, the list of primaries, various timers, etc +is primary or secondary for the zone, the list of primaries, various timers, etc. Optionally, append *ZONE*\ s to get the status of specific zones. bind-domain-status [*ZONE*...] @@ -66,7 +66,7 @@ Show the content of the cache. current-config [diff] ^^^^^^^^^^^^^^^^^^^^^ -Show the currently running configuration. The output has the same format as ``pdns_server --config``. With the diff option only modified options are included in the output. +Show the currently running configuration. The output has the same format as ``pdns_server --config``. With the diff option, only modified options are included in the output. cycle ^^^^^ @@ -118,7 +118,7 @@ specified the entire cache is purged. qtypes ^^^^^^ -Get a count of queries per qtype on standard out. +Get a count of queries per qtype on standard output. quit ^^^^ diff --git a/docs/manpages/pdns_server.1.rst b/docs/manpages/pdns_server.1.rst index 9ee765ae15..b383a509b7 100644 --- a/docs/manpages/pdns_server.1.rst +++ b/docs/manpages/pdns_server.1.rst @@ -17,21 +17,22 @@ documentation for more information. Options ------- -See the online documentation for all options +See the online documentation for all options. The most important ones are: --daemon Indicate if the server should run in the background as a real daemon, or in the foreground. --guardian Run :program:`pdns_server` inside a guardian. This guardian monitors the performance of the inner :program:`pdns_server` instance. It is also this - guardian that :program:`pdns_control`\ talks to. + guardian that :program:`pdns_control` talks to. --control-console Run the server in a special monitor mode. This enables detailed logging and exposes the raw control socket. --loglevel= Set the logging level. --config Show the currently configuration. There are three optional values: - --config=default show the default configuration. - --config=diff show modified options in the current configuration. - --config=check parse the current configuration, with error checking. ---help To view more options that are available use this program. + + --config=default show the default configuration. + --config=diff show modified options in the current configuration. + --config=check parse the current configuration, with error checking. +--help Display the list of all the available options. See also -------- diff --git a/docs/manpages/pdnsutil.1.rst b/docs/manpages/pdnsutil.1.rst index dfc8e01c60..3ddfcc218b 100644 --- a/docs/manpages/pdnsutil.1.rst +++ b/docs/manpages/pdnsutil.1.rst @@ -24,13 +24,13 @@ Options --config-name Virtual configuration name --config-dir Location of pdns.conf. Default is /etc/powerdns. -COMMANDS +Commands -------- There are many available commands, this section splits them up into -their respective uses +their respective uses. -DNSSEC RELATED COMMANDS +DNSSEC-related Commands ----------------------- Several commands manipulate the DNSSEC keys and options for zones. Some @@ -103,12 +103,13 @@ set-nsec3 *ZONE* ['*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*'] [**narrow**] NSEC3 records are created. The NSEC3 parameters must be quoted on the command line. *HASH-ALGORITHM* must be 1 (SHA-1). Setting *FLAGS* to 1 enables NSEC3 opt-out operation. Only do this if you - know you need it. For *ITERATIONS*, please consult RFC 5155, section - 10.3. And be aware that a high number might overload validating + know you need it. For *ITERATIONS*, please consult + :rfc:`RFC 5155<5155#section-10.3>`. + And be aware that a high number might overload validating resolvers and that a limit can be set with ``max-nsec3-iterations`` in ``pdns.conf``. The *SALT* is a hexadecimal string encoding the bits for the salt, or - to use no salt. Setting **narrow** will make PowerDNS - send out "white lies" (RFC 7129) about the next secure record to + send out "white lies" (:rfc:`7129`) about the next secure record to prevent zone enumeration. Instead of looking it up in the database, it will send out the hash + 1 as the next secure record. Narrow mode requires online signing capabilities by the nameserver and therefore diff --git a/docs/manpages/zone2json.1.rst b/docs/manpages/zone2json.1.rst index b9c9d3ff1d..850388a6e0 100644 --- a/docs/manpages/zone2json.1.rst +++ b/docs/manpages/zone2json.1.rst @@ -10,7 +10,7 @@ Description ----------- :program:`zone2json` parses BIND named.conf files and zonefiles and outputs -JSON on standard out, which can then be fed to the PowerDNS API. +JSON on standard output, which can then be fed to the PowerDNS API. :program:`zone2json` understands the BIND master file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and ``$TTL``. diff --git a/docs/manpages/zone2sql.1.rst b/docs/manpages/zone2sql.1.rst index 92beab49c5..c177bae8de 100644 --- a/docs/manpages/zone2sql.1.rst +++ b/docs/manpages/zone2sql.1.rst @@ -10,7 +10,7 @@ Description ----------- :program:`zone2sql` parses BIND named.conf files and zonefiles and outputs SQL -on standard out, which can then be fed to your database. +on standard output, which can then be fed to your database. :program:`zone2sql` understands the BIND master file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and ``$TTL``. diff --git a/docs/migration.rst b/docs/migration.rst index a25f54c6d3..737cec9061 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -103,7 +103,7 @@ Using ``zone2sql`` ^^^^^^^^^^^^^^^^^^ To migrate, the ``zone2sql`` tool is provided. This tool parses a BIND -``named.conf`` file and zone files and outputs SQL on standard out, +``named.conf`` file and zone files and outputs SQL on standard output, which can then be fed to your database. It understands the BIND master file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and ``$TTL``.