From 7391755f7c914ec492d8396e55b1fd2c8ee72e3c Mon Sep 17 00:00:00 2001
From: Ville Vesilehto <ville@vesilehto.fi>
Date: Sun, 18 May 2025 06:25:15 +0300
Subject: [PATCH] docs: add man page for multisocket plugin (#7297)

Missed from #6882

Signed-off-by: Ville Vesilehto <ville@vesilehto.fi>
---
 man/coredns-multisocket.7 | 92 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 man/coredns-multisocket.7

diff --git a/man/coredns-multisocket.7 b/man/coredns-multisocket.7
new file mode 100644
index 000000000..f0013a4c5
--- /dev/null
+++ b/man/coredns-multisocket.7
@@ -0,0 +1,92 @@
+.\" Generated by Mmark Markdown Processer - mmark.miek.nl
+.TH "COREDNS-MULTISOCKET" 7 "May 2025" "CoreDNS" "CoreDNS Plugins"
+
+.SH "NAME"
+.PP
+\fImultisocket\fP - allows to start multiple servers that will listen on one port.
+
+.SH "DESCRIPTION"
+.PP
+With \fImultisocket\fP, you can define the number of servers that will listen on the same port. The SO_REUSEPORT socket
+option allows to open multiple listening sockets at the same address and port. In this case, kernel distributes incoming
+connections between sockets.
+
+.PP
+Enabling this option allows to start multiple servers, which increases the throughput of CoreDNS in environments with a
+large number of CPU cores.
+
+.SH "SYNTAX"
+.PP
+.RS
+
+.nf
+multisocket [NUM\_SOCKETS]
+
+.fi
+.RE
+
+.IP \(bu 4
+\fBNUM_SOCKETS\fP - the number of servers that will listen on one port. Default value is equal to GOMAXPROCS.
+
+
+.SH "EXAMPLES"
+.PP
+Start 5 TCP/UDP servers on the same port.
+
+.PP
+.RS
+
+.nf
+\&. {
+    multisocket 5
+    forward . /etc/resolv.conf
+}
+
+.fi
+.RE
+
+.PP
+Do not define \fB\fCNUM_SOCKETS\fR, in this case it will take a value equal to GOMAXPROCS.
+
+.PP
+.RS
+
+.nf
+\&. {
+    multisocket
+    forward . /etc/resolv.conf
+}
+
+.fi
+.RE
+
+.SH "RECOMMENDATIONS"
+.PP
+The tests of the \fB\fCmultisocket\fR plugin, which were conducted for \fB\fCNUM_SOCKETS\fR from 1 to 10, did not reveal any side
+effects or performance degradation.
+
+.PP
+This means that the \fB\fCmultisocket\fR plugin can be used with a default value that is equal to GOMAXPROCS.
+
+.PP
+However, to achieve the best results, it is recommended to consider the specific environment and plugins used in
+CoreDNS. To determine the optimal configuration, it is advisable to conduct performance tests with different
+\fB\fCNUM_SOCKETS\fR, measuring Queries Per Second (QPS) and system load.
+
+.PP
+If conducting such tests is difficult, follow these recommendations:
+1. Determine the maximum CPU consumption of CoreDNS server without \fB\fCmultisocket\fR plugin. Estimate how much CPU CoreDNS
+   actually consumes in specific environment under maximum load.
+2. Align \fB\fCNUM_SOCKETS\fR with the estimated CPU usage and CPU limits or system's available resources.
+   Examples:
+   - If CoreDNS consumes 4 CPUs and 8 CPUs are available, set \fB\fCNUM_SOCKETS\fR to 2.
+   - If CoreDNS consumes 8 CPUs and 64 CPUs are available, set \fB\fCNUM_SOCKETS\fR to 8.
+
+.SH "LIMITATIONS"
+.PP
+The SO_REUSEPORT socket option is not available for some operating systems. It is available since Linux Kernel 3.9 and
+not available for Windows at all.
+
+.PP
+Using this plugin with a system that does not support SO_REUSEPORT will cause an \fB\fCaddress already in use\fR error.
+