3 files changed, 50 insertions, 5 deletions

diff --git a/man4/opentracker.conf.4 b/man4/opentracker.conf.4
index 2bc1389..b28879f 100644
--- a/man4/opentracker.conf.4
+++ b/man4/opentracker.conf.4
@@ -1,5 +1,5 @@
-.Dd 2024-04-18
-.Dt opentracker.conf 5
+.Dd 2026-10-28
+.Dt opentracker.conf 4
 .Os Unix
 .Sh NAME
 .Nm opentracker.conf
@@ -25,8 +25,29 @@ Specifies the address opentracker will listen on for TCP connections. Can be add
 .It listen.udp Ar address
 Specifies the address opentracker will listen on for UDP connections. Can be added more than once.
 .Pp
+A listen statement may carry options after the address, as in
+.Dl listen.udp 10.0.0.5:6969 workers=4 shared
+where
+.Cm workers Ns = Ns Ar count
+sets the worker count for that socket alone and is ignored for TCP, and
+.Cm shared
+permits another process to bind the same address.
+.Pp
 .It listen.udp.workers Ar threads
-Specifies how many threads will be spawned to handle UDP connections. Defaults to 4.
+Specifies how many threads will be spawned to handle UDP requests, for every
+listen statement that does not carry a
+.Cm workers
+option of its own. Defaults to 1. A count of 0 serves UDP from the event loop,
+in the thread that also serves TCP. See
+.Sx TUNING
+before raising it.
+.Pp
+.It listen.shared Ar boolean
+Permits another process to bind the same address, for every listen statement
+that does not carry a
+.Cm shared
+option of its own. Defaults to 0, and is useful only where a second tracker is
+deliberately run on the same address.
 .Pp
 .It access.whitelist Ar path/to/whitelist
 Specifies the path to the whitelist file containing all torrent hashes that opentracker will serve. Use this option if opentracker runs in a non-open mode.
@@ -67,6 +88,18 @@ Specifies the user opentracker will setuid to after binding to potentially privi
 .It tracker.redirect_url Ar URL
 Specifies the URL opentracker will redirect to in response to a "GET / HTTP" request.
 .El
+.Sh TUNING
+A worker is a thread that blocks in a read until a datagram arrives. Where the
+kernel spreads arriving datagrams over a group of sockets bound to one address,
+opentracker binds one socket per worker and throughput rises with the worker
+count. Linux does so, and FreeBSD since 12.0. Where a kernel does not, every
+worker reads the same socket and they contend for its receive queue, so more
+than one worker costs throughput. opentracker asks at start up and binds a
+group only where the answer is yes.
+.Pp
+.Pa tests/udp_scaling.py
+in the source distribution sweeps the setting against a running tracker.
+Measure on the machine that will carry the traffic.
 .Sh EXAMPLES
 To specify the address opentracker will listen on for both TCP and UDP connections:
 .Dl listen.tcp_udp 0.0.0.0:6969
diff --git a/opentracker.conf.sample b/opentracker.conf.sample
index 4adb736..1d535e8 100644
--- a/opentracker.conf.sample
+++ b/opentracker.conf.sample
@@ -23,7 +23,7 @@
 #
 #        workers=<count>  handle this udp socket in blocking reads in that
 #                         many dedicated worker threads instead of in the
-#                         event loop. Ignored for tcp.
+#                         event loop. Defaults to 1. Ignored for tcp.
 #        shared           allow another process to bind the same address and
 #                         let the kernel share the traffic. Only useful if you
 #                         deliberately run a second tracker there.
@@ -37,6 +37,18 @@
 # listen.udp.workers 4
 # listen.shared 1
 #
+#      Raising the worker count pays off where the kernel spreads arriving
+#      datagrams over a group of sockets bound to one address. Linux does so
+#      and FreeBSD has since 12.0, Darwin does not. opentracker asks at start
+#      up and binds one socket per worker only where the answer is yes. Where
+#      it is no, all workers read the one socket and contend for its receive
+#      queue, which costs more than it returns. See the TUNING section of
+#      opentracker.conf(5); tests/udp_scaling.py sweeps the setting on the
+#      machine that will carry the traffic.
+#
+#      A count of 0 answers udp from the event loop, in the thread that also
+#      serves tcp, which is what opentracker did before.
+#
 #      Note, that using 0.0.0.0 for udp sockets may yield surprising results.
 #      An answer packet sent on that socket will not necessarily have the
 #      source address that the requesting client may expect, but any address
diff --git a/ot_config.c b/ot_config.c
index ee6bc12..a0dbef1 100644
--- a/ot_config.c
+++ b/ot_config.c
@@ -32,7 +32,7 @@ const char   *g_statefile;
 static ot_listen *g_listen;
 static size_t     g_listen_count;
 static int        g_listen_shared;
-static int        g_listen_workers;
+static int        g_listen_workers = 1;
 
 static void panic(const char *routine) __attribute__((noreturn));
 static void panic(const char *routine) {