thinproxy.8

.Dd March 20, 2026
.Dt THINPROXY 8
.Os
.Sh NAME
.Nm thinproxy
.Nd lightweight asynchronous HTTP/HTTPS proxy
.Sh SYNOPSIS
.Nm
.Op Fl dVv
.Op Fl b Ar address
.Op Fl f Ar config
.Op Fl p Ar port
.Op Fl u Ar user
.Sh DESCRIPTION
.Nm
is a minimal, single-threaded HTTP/HTTPS proxy with a small memory
footprint.
It uses non-blocking I/O with
.Xr poll 2
for asynchronous event handling and supports both HTTP request forwarding
and HTTPS tunneling via the CONNECT method.
.Pp
On
.Ox ,
CONNECT tunnels use
.Dv SO_SPLICE
for zero-copy kernel relay, avoiding data copies through userspace.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b Ar address
Bind to
.Ar address .
The default is
.Cm 127.0.0.1 .
Use
.Cm 0.0.0.0
to listen on all IPv4 interfaces, or
.Cm ::
for all interfaces including IPv6.
.It Fl d
Daemonize.
Run in the background and log to
.Xr syslog 3
instead of standard error.
.It Fl f Ar config
Read configuration from
.Ar config
instead of the default
.Pa /etc/thinproxy.conf .
.It Fl p Ar port
Listen on
.Ar port .
The default is
.Cm 8080 .
.It Fl u Ar user
Drop privileges to
.Ar user
after binding the listening socket.
If the process is already running as
.Ar user
(e.g.\& via
.Xr rc.subr 8
.Va daemon_user ) ,
the privilege drop is skipped.
.It Fl V
Print version and exit.
.It Fl v
Verbose mode.
Log each proxied request with the client IP address.
.El
.Pp
Command-line flags override values set in the configuration file.
.Sh CONFIGURATION FILE
.Nm
reads its configuration from
.Pa /etc/thinproxy.conf
by default, or from the file specified with
.Fl f .
If the default file does not exist, it is silently ignored.
If a file specified with
.Fl f
does not exist, it is an error.
.Pp
The file format is one directive per line.
Empty lines and lines starting with
.Sq #
are ignored.
Inline comments starting with
.Sq #
are also supported.
Lines may not exceed 1023 characters.
.Pp
The following directives are recognized:
.Bl -tag -width Ds
.It Cm listen Ar address
Equivalent to
.Fl b .
.It Cm port Ar number
Equivalent to
.Fl p .
.It Cm user Ar name
Equivalent to
.Fl u .
.It Cm daemon Cm yes | no
Equivalent to
.Fl d .
.It Cm verbose Cm yes | no
Equivalent to
.Fl v .
.It Cm max_connections Ar number
Maximum concurrent connections.
Must be between 1 and 512.
The default is 512.
.It Cm idle_timeout Ar seconds
Close connections idle for longer than
.Ar seconds .
Must be between 1 and 86400.
The default is 300.
.It Cm max_connections_per_ip Ar number
Maximum concurrent connections from a single source IP address.
Must be between 1 and 512.
New connections exceeding this limit are rejected with 503
Service Unavailable.
The default is 32.
.It Cm deny_private Cm yes | no
Block connections to private and reserved destination addresses.
This includes RFC 1918 private ranges (10/8, 172.16/12, 192.168/16),
loopback (127/8, ::1), link-local (169.254/16, fe80::/10),
shared address space (100.64/10), unique local IPv6 (fc00::/7),
multicast, and reserved ranges.
IPv4-mapped IPv6 addresses are also checked.
The default is
.Cm yes .
.It Cm connect_port Ar port
Restrict the CONNECT method to the specified
.Ar port .
May be specified multiple times to allow several ports.
When any
.Cm connect_port
directive is present, CONNECT requests to unlisted ports are denied
with 403 Forbidden.
The default allows port 443 only.
Config entries replace the defaults.
.It Cm allow Ar address Ns Op / Ns Ar prefix
Allow connections from
.Ar address .
The address may be an IPv4 or IPv6 address, optionally followed by a
CIDR prefix length.
When any
.Cm allow
directive is present,
all addresses not matching an
.Cm allow
rule are denied.
Cannot be mixed with
.Cm deny .
.It Cm deny Ar address Ns Op / Ns Ar prefix
Deny connections from
.Ar address .
When any
.Cm deny
directive is present,
all addresses not matching a
.Cm deny
rule are allowed.
Cannot be mixed with
.Cm allow .
.El
.Sh OPERATION
For HTTP requests, the proxy rewrites the absolute URI to a relative
path, strips hop-by-hop headers
.Pq Proxy-Connection, Proxy-Authorization ,
forces
.Cm Connection: close ,
and forwards the request to the upstream server.
.Pp
DNS resolution is performed asynchronously by forking a short-lived
child process for each lookup, preventing slow responses from blocking
the event loop.
.Pp
For HTTPS requests using the CONNECT method, the proxy establishes a
TCP tunnel to the upstream host and relays data bidirectionally without
inspecting the encrypted traffic.
On
.Ox ,
the kernel handles the relay via
.Dv SO_SPLICE
with zero data copies through userspace.
.Pp
On restart, if the listen address is temporarily held by orphaned
TCP connections, the proxy retries
.Xr bind 2
up to five times with one-second intervals.
.Sh SECURITY
.Nm
binds to localhost by default, preventing external access.
.Pp
When started as root with the
.Fl u
flag or the
.Cm user
directive, privileges are dropped immediately after binding the
listening socket.
.Pp
Accepted client sockets are configured with
.Dv SO_LINGER
to send RST on close, preventing FIN_WAIT_2 orphans from blocking
.Xr bind 2
on restart.
.Pp
On
.Ox ,
.Xr unveil 2
restricts filesystem access to
.Pa /etc/resolv.conf
and
.Pa /etc/hosts
(read-only, for DNS resolution in forked children),
and
.Xr pledge 2
restricts system calls to
.Cm stdio inet dns proc .
.Pp
On Linux,
.Xr seccomp 2
restricts system calls to an allowlist matching the
.Ox
.Xr pledge 2
promises: I/O, networking, DNS resolution, and process forking.
Attempts to invoke any other system call terminate the process
immediately.
.Pp
.Nm
does not inspect, decrypt, or modify HTTPS traffic.
TLS connections are tunneled opaquely via CONNECT.
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/thinproxy.conf
Default configuration file.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Start on the default address and port:
.Pp
.Dl $ thinproxy
.Pp
Use a custom configuration file:
.Pp
.Dl $ thinproxy -f /path/to/thinproxy.conf
.Pp
Listen on all interfaces, port 3128, with verbose logging:
.Pp
.Dl $ thinproxy -v -b 0.0.0.0 -p 3128
.Pp
Run as a daemon, dropping privileges to the
.Cm _thinproxy
user:
.Pp
.Dl # thinproxy -d -u _thinproxy -p 8080
.Pp
Use with curl:
.Pp
.Dl $ curl -x http://127.0.0.1:8080 http://example.com
.Dl $ curl -x http://127.0.0.1:8080 https://example.com
.Pp
Example configuration file allowing only a local network:
.Bd -literal -offset indent
listen 0.0.0.0
port 3128
user _thinproxy
daemon yes
deny_private yes
connect_port 443
connect_port 8443
max_connections_per_ip 16
allow 192.168.1.0/24
allow 127.0.0.1
.Ed
.Ex -std
.Sh SEE ALSO
.Xr pledge 2 ,
.Xr poll 2 ,
.Xr seccomp 2 ,
.Xr unveil 2 ,
.Xr syslog 3 ,
.Xr sosplice 9
.Sh AUTHORS
.An Renaud Allard Aq Mt renaud@allard.it