thinproxy.8

.Dd May 29, 2026
.Dt THINPROXY 8
.Os
.Sh NAME
.Nm thinproxy
.Nd lightweight asynchronous HTTP/HTTPS proxy
.Sh SYNOPSIS
.Nm
.Op Fl dFVv
.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
Run in the foreground, overriding a
.Cm daemon Cm yes
setting in the configuration file.
Useful under process supervisors such as
.Xr systemd 1
that expect the service to stay in the foreground.
.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
Enable all log categories.
Equivalent to specifying
.Cm log requests ,
.Cm log denied ,
and
.Cm log wildcard .
.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
Enable or disable all log categories.
.Cm yes
is equivalent to
.Fl v .
.It Cm log Ar category
Enable logging for the specified category.
May be specified multiple times.
The following categories are recognized:
.Bl -tag -width "wildcard" -compact
.It Cm requests
Log each accepted request with client IP, method, destination, and
.Pq for plain HTTP
path.
The line is emitted only after the request clears every access check, so a
denied request is never also logged as accepted.
A connection later reaped for exceeding
.Cm idle_timeout
is logged in this category as a
.Cm TIMEOUT
line with the client IP and destination.
.It Cm denied
Log denied connections with client IP, destination
.Pq when known, including the path for plain HTTP ,
and denial reason.
Reasons:
.Cm ACL ,
.Cm PER_IP_LIMIT ,
.Cm CONNECT_PORT ,
.Cm PRIVATE_ADDRESS .
Enabled by default.
.It Cm wildcard
Tag the outcome line of CONNECT requests whose port matched the wildcard
rule with
.Cm WILDCARD_PORT ,
whether the request was accepted, denied, timed out, or failed to resolve.
An accepted wildcard request is logged even when
.Cm requests
is disabled.
.El
.Pp
Name resolution failures are always logged, independent of the categories
above, as a
.Cm RESOLVE_FAILED
line carrying the client IP, destination, and one of the reasons
.Cm LOOKUP ,
.Cm CHILD_KILLED ,
.Cm SHORT_READ ,
or
.Cm SETUP .
.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.
For IPv6 peers, connections are aggregated by the leading /64 so that a
single host cannot trivially bypass the limit by varying the low 64 bits
of its 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),
deprecated site-local IPv6 (fec0::/10), multicast, IETF protocol
assignments (192.0.0/24), benchmarking (198.18/15), 6to4 relay anycast
(192.88.99/24), and the documentation ranges (192.0.2/24, 198.51.100/24,
203.0.113/24).
IPv4-mapped IPv6 addresses, IPv4-compatible
.Pq Li ::a.b.c.d
and 6to4
.Pq Li 2002::/16
addresses that embed a private IPv4 destination, and the RFC 6052
well-known NAT64 prefix
.Pa 64:ff9b::/96
are also checked.
The default is
.Cm yes .
.It Cm nat64_prefix Ar addr/96
Additional NAT64 /96 prefix whose embedded IPv4 address should be
unwrapped during
.Cm deny_private
checks.
Use this when the local network operates its own NAT64 with a custom
prefix in addition to (or instead of) the well-known one.
The low 32 bits of
.Ar addr
must be zero.
.It Cm connect_port Ar port
Restrict the CONNECT method to the specified
.Ar port .
May be specified multiple times to allow several ports.
A
.Ar port
of
.Cm 0
acts as a wildcard, allowing all ports.
When combined with explicit port entries, specific ports are checked
first; the wildcard is used as a fallback.
Connections allowed by the wildcard are logged when the
.Cm wildcard
log category is enabled.
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, Keep-Alive, Trailer, Upgrade ,
forces
.Cm Connection: close ,
and forwards the request to the upstream server.
The following constructs are HTTP request-smuggling vectors and are
rejected with
.Cm 400 Bad Request :
control bytes (other than SP) anywhere in the request line; whitespace
inside the request-target; control bytes other than HTAB inside any
header line; whitespace between a header name and its colon; obsolete line folding
.Pq obs-fold ;
duplicate
.Cm Host ,
.Cm Content-Length ,
or
.Cm Transfer-Encoding
headers; a missing
.Cm Host
header on a forwarded
.Pq non-CONNECT
request; a
.Cm Transfer-Encoding
value other than
.Cm chunked ;
and any request that carries both
.Cm Transfer-Encoding
and
.Cm Content-Length .
.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
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.
Violations log the blocked syscall number to standard error before
terminating the process.
.Pp
.Nm
does not inspect, decrypt, or modify HTTPS traffic.
TLS connections are tunneled opaquely via CONNECT.
.Sh SIGNALS
.Bl -tag -width "SIGTERM, SIGINT, SIGHUP"
.It Dv SIGTERM , Dv SIGINT , Dv SIGHUP
Shut down cleanly: the event loop finishes the current iteration and
the listener and any active connections are closed.
.Nm
does not reload its configuration on
.Dv SIGHUP ;
restart the daemon to pick up changes.
.It Dv SIGPIPE , Dv SIGCHLD
Ignored.
.El
.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