coredns/man/coredns-multisocket.7
Ville Vesilehto 7391755f7c
docs: add man page for multisocket plugin (#7297)
Missed from #6882

Signed-off-by: Ville Vesilehto <ville@vesilehto.fi>
2025-05-17 20:25:15 -07:00

93 lines
2.6 KiB
Groff

.\" 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.