Skip to content

[doc] Make usage of dig "+retry" clearer.

wodry requested to merge (removed):patch-2 into main

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.

Edited by Ondřej Surý

Merge request reports