[doc] Make usage of dig "+retry" clearer.
The dig
command line options tries
and retry
are redundant and overwrite each other, the last given in the command wins. You only need to use one, exclusively.
Steps to reproduce:
Setup a firewall rule that drops all traffic to a random IP address that we want to timeout when querying with dig. Here it is 1.2.3.4:
iptables -I OUTPUT -d 1.2.3.4/32 -j DROP
Now we query with dig 9.14.8 and +tries=4 +retry=1
:
time dig +timeout=1 +tries=4 +retry=1 @1.2.3.4 example.com
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
; <<>> DiG 9.14.8 <<>> +timeout +tries +retry @1.2.3.4 exaple.com
; (1 server found)
;; global options: +cmd
;; connection timed out; no servers could be reached
;; Connection to 1.2.3.4#53(1.2.3.4) for example.com failed: timed out.
real 0m2,004s
Dig times out after 2 s. Since we have timeout set to 1 s, this indicates that there have been 2 queries that timed out. This is the value of retry+1
.
Now we query the same, but with the reverse order: +retry=1 +tries=4
:
time dig +timeout=1 +retry=1 +tries=4 @1.2.3.4 example.com
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
; <<>> DiG 9.14.8 <<>> +timeout +retry +tries @1.2.3.4 exaple.com
; (1 server found)
;; global options: +cmd
;; connection timed out; no servers could be reached
;; Connection to 1.2.3.4#53(1.2.3.4) for example.com failed: timed out.
real 0m4,004s
Dig times out after 4 s. Since we have timeout set to 1 s, this indicates that there have been 4 queries that timed out. This is the value tries
.
Now we query the same, but with +retry=9 +tries=4
:
time dig +timeout=1 +retry=9 +tries=4 @1.2.3.4 example.com
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
;; Connection to 1.2.3.4#53(1.2.3.4) for exaple.com failed: timed out.
; <<>> DiG 9.14.8 <<>> +timeout +retry +tries @1.2.3.4 exaple.com
; (1 server found)
;; global options: +cmd
;; connection timed out; no servers could be reached
;; Connection to 1.2.3.4#53(1.2.3.4) for example.com failed: timed out.
real 0m4,004s
The result is the same as with +retry=1 +tries=4
. It doesn't count what You set as retry
, if tries
is set afterwards, and vice versa.
When reading the man page, I first guessed with e.g. +tries=2 +retry=4
there would be two tries with each being 4 times retried, so 8 queries total, or something.
Since the behavior is so simple, the man page should be made simple to understand, too, and redundant text cut.