1 files changed, 103 insertions, 0 deletions
diff --git a/man/coredns-timeouts.7 b/man/coredns-timeouts.7
new file mode 100644
index 000000000..a283f6cbd
--- /dev/null
+++ b/man/coredns-timeouts.7
@@ -0,0 +1,103 @@
+.\" Generated by Mmark Markdown Processer - mmark.miek.nl
+.TH "COREDNS-TIMEOUTS" 7 "July 2023" "CoreDNS" "CoreDNS Plugins"
+
+.SH "NAME"
+.PP
+\fItimeouts\fP - allows you to configure the server read, write and idle timeouts for the TCP, TLS and DoH servers.
+
+.SH "DESCRIPTION"
+.PP
+CoreDNS is configured with sensible timeouts for server connections by default.
+However in some cases for example where CoreDNS is serving over a slow mobile
+data connection the default timeouts are not optimal.
+
+.PP
+Additionally some routers hold open connections when using DNS over TLS or DNS
+over HTTPS. Allowing a longer idle timeout helps performance and reduces issues
+with such routers.
+
+.PP
+The \fItimeouts\fP "plugin" allows you to configure CoreDNS server read, write and
+idle timeouts.
+
+.SH "SYNTAX"
+.PP
+.RS
+
+.nf
+timeouts {
+    read DURATION
+    write DURATION
+    idle DURATION
+}
+
+.fi
+.RE
+
+.PP
+For any timeouts that are not provided, default values are used which may vary
+depending on the server type. At least one timeout must be specified otherwise
+the entire timeouts block should be omitted.
+
+.SH "EXAMPLES"
+.PP
+Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port
+5553 and uses the nameservers defined in \fB\fC/etc/resolv.conf\fR to resolve the
+query. This proxy path uses plain old DNS. A 10 second read timeout, 20
+second write timeout and a 60 second idle timeout have been configured.
+
+.PP
+.RS
+
+.nf
+tls://.:5553 {
+    tls cert.pem key.pem ca.pem
+    timeouts {
+        read 10s
+        write 20s
+        idle 60s
+    }
+    forward . /etc/resolv.conf
+}
+
+.fi
+.RE
+
+.PP
+Start a DNS-over-HTTPS server that is similar to the previous example. Only the
+read timeout has been configured for 1 minute.
+
+.PP
+.RS
+
+.nf
+https://. {
+    tls cert.pem key.pem ca.pem
+    timeouts {
+        read 1m
+    }
+    forward . /etc/resolv.conf
+}
+
+.fi
+.RE
+
+.PP
+Start a standard TCP/UDP server on port 1053. A read and write timeout has been
+configured. The timeouts are only applied to the TCP side of the server.
+
+.PP
+.RS
+
+.nf
+\&.:1053 {
+    timeouts {
+        read 15s
+                write 30s
+    }
+    forward . /etc/resolv.conf
+}
+
+.fi
+.RE
+