.Dd 2026-10-28
.Dt opentracker.conf 4
.Os Unix
.Sh NAME
.Nm opentracker.conf
.Nd configuration file for opentracker
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
The
.Nm
configuration file specifies various options for configuring the behavior of the opentracker program.
.Pp
Lines starting with '#' are comments and are ignored. Options are specified as 'keyword value' pairs.
.Pp
The following options are available:
.Pp
.Bl -tag -width ".It access.proxy" -compact
.It listen.tcp_udp Ar address
Specifies an address opentracker will listen on for both TCP and UDP connections. If none are specified, opentracker listens on 0.0.0.0:6969 by default. Can be added more than once.
.Pp
.It listen.tcp Ar address
Specifies the address opentracker will listen on for TCP connections. Can be added more than once.
.Pp
.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 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.
.Pp
.It access.blacklist Ar path/to/blacklist
Specifies the path to the blacklist file containing all torrent hashes that opentracker will not serve. Use this option if opentracker was compiled to allow blacklisting.
.Pp
.It access.fifo_add Ar path/to/adder.fifo
Specifies the path to the FIFO (named pipe) used for dynamic changesets to accesslists. Info hashes written to this FIFO will be added to the main accesslist file.
.Pp
.It access.fifo_delete Ar path/to/deleter.fifo
Specifies the path to the FIFO (named pipe) used for dynamic changesets to accesslists. Info hashes written to this FIFO will be removed from the main accesslist file.
.Pp
.It access.stats Ar ip_address_or_network
Specifies the IP address or network in CIDR notation allowed to fetch stats from opentracker.
.Pp
.It access.stats_path Ar path
Specifies the path to the stats location. You can configure opentracker to appear anywhere on your tracker. Defaults to /stats.
.Pp
.It access.proxy Ar ip_address_or_network
Specifies the IP address or network of the reverse proxies. Opentracker will take the X-Forwarded-For address instead of the source IP address. Can be added more than once.
.Pp
.It livesync.cluster.listen Ar ip_address:port
Specifies the IP address and port opentracker will listen on for incoming live sync packets to keep a cluster of opentrackers synchronized.
.Pp
.It livesync.cluster.node_ip Ar ip_address
Specifies one trusted IP address for sync between trackers running in a cluster. Can be added more than once.
.Pp
.It batchsync.cluster.admin_ip Ar ip_address
Specifies the admin IP address for old-style (HTTP-based) asynchronous tracker syncing.
.Pp
.It tracker.rootdir Ar path
Specifies the directory opentracker will chroot/chdir to. All black/white list files must be located in this directory.
.Pp
.It tracker.user Ar username
Specifies the user opentracker will setuid to after binding to potentially privileged ports.
.Pp
.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
.Pp
To specify the address opentracker will listen on for TCP connections:
.Dl listen.tcp 0.0.0.0
.Pp
To specify the address opentracker will listen on for UDP connections:
.Dl listen.udp 0.0.0.0:6969
.Pp
.Sh SEE ALSO
.Xr opentracker 1
.Pp
.Sh AUTHOR
.An Dirk Engling
.Aq Mt erdgeist@erdgeist.org
.Pp