stud is a network proxy that terminates TLS/SSL connections and forwards the
unencrypted traffic to some backend. It's designed to handle 10s of thousands of
connections efficiently on multicore machines.
It follows a process-per-core model; a parent process spawns N children who
accept() on a common socket to distribute connected clients among them.
Within each child, asynchronous socket I/O is conducted across the local
OpenSSL's nonblocking API. By default,
stud has an overhead of ~200KB per connection--it preallocates
some buffer space for data in flight between frontend in backend.
stud has very few features--it's designed to be paired with an intelligent
backend like haproxy or nginx. It maintains a strict 1:1 connection pattern
with this backend handler so that the backend can dictate throttling behavior,
maxmium connection behavior, availability of service, etc.
stud has one "cool trick"--it will optionally write the client IP address
as the first few octets (depending on IPv4 or IPv6) to the backend--or provide
that information using HAProxy's PROXY protocol. In this way, backends
who care about the client IP can still access it even though
appears to be the connected client.
libev >= 4 openssl (recent, >=1.0.0 recommended)
Stud currently works on Linux, OpenBSD, FreeBSD, and MacOSX. It has been tested the most heavily on Linux/x86_64.
While porting it to other POSIX platforms is likely trivial, it hasn't be done yet. Patches welcome!
If you're handling a large number of connections, you'll
probably want to raise
ulimit -n before running
It's very strongly recommended to not run
stud as root; ideally, it would
be run as a user ("stud", perhaps) that does nothing but run
$ make $ sudo make install
The only required argument is a path to a PEM file that contains the certificate and private key.
The entire set of arguments can be invoked with
Encryption Methods: --tls (TLSv1, default) --ssl (SSLv3) -c CIPHER_SUITE (set allowed ciphers) Socket: -b HOST,PORT (backend [connect], default "127.0.0.1,8000") -f HOST,PORT (frontend [bind], default "*,8443") Performance: -n CORES (number of worker processes, default 1) Special: --write-ip (write 1 octet with the IP family followed by 4 (IPv4) or 16 (IPv6) octets little-endian to backend before the actual data) --write-proxy (write HaProxy's PROXY protocol line before actual data: "PROXY TCP4 <source-ip> <dest-ip> <source-port> <dest-port>\r\n" Note, that currently only TCP4 implemented. Also note, that dest-ip and dest-port are initialized once after the socket is bound. It means that you will get 0.0.0.0 as dest-ip instead of actual IP if that what the listening socket was bound to)
stud uses no configuration file.
stud was originally written by Jamie Turner (@jamwt) and is maintained
by the Bump (http://bu.mp) server team. It currently (6/11) provides
server-side TLS termination for over 40 million Bump users.
* Colin Percival @cperciva -- early audit and code review * Frank DENIS @jedisct1 -- port to BSD, IPv6 support, various fixes * Denis Bilenko -- HAProxy PROXY protocol support