Enter usocksHEADmaster

SOCKS5 CONNECT proxy for Linux 6.1 or newer: C99, raw io_uring, libc
only. Each worker process runs one event loop with fixed 64 KB buffers
per direction; -w N workers share the port through SO_REUSEPORT.
IPv4, IPv6 and domain names, RFC 1929 authentication, TCP or unix
socket listener.

1 files changed, 57 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..7fa593c
--- /dev/null
+++ b/README
@@ -0,0 +1,57 @@
+usocks
+======
+SOCKS5 proxy for Linux 6.1 or newer on io_uring. CONNECT to IPv4, IPv6
+and domain names; one event loop thread per worker process, libc only.
+Domain names are resolved by getaddrinfo() in 16 threads per worker. A
+lookup that waits 10 s for a thread fails untried; one in progress takes
+as long as the system resolver allows, which options timeout:1 attempts:2
+in /etc/resolv.conf shortens. Half-close and data sent before the reply
+are relayed. The handshake and each connect attempt time out after 10 s;
+relayed connections have no idle timeout and rely on TCP keepalive. Each
+connection slot reserves 130 KB of buffers, resident once used and kept
+for later connections; past the limit, clients wait in the listen
+backlog. Connections that fail before relaying log one line to stderr.
+
+A worker relays on one CPU core. With -w, workers share the port through
+SO_REUSEPORT and nothing else: the kernel spreads new connections among
+them by address hash, -m applies to each, and when one exits, all exit.
+
+Destinations are not filtered: clients reach whatever the host can,
+including its loopback services, so listening beyond loopback without -u
+makes an open proxy. RFC 1929 sends the password in plaintext. -p is
+visible in ps until usocks blanks it at startup; USOCKS_PASS is not. A
+unix socket takes its mode from the umask; a stale socket at its path is
+replaced, a live one is not. Container seccomp profiles often block
+io_uring.
+
+
+Build
+-----
+    make
+    make install
+
+Needs a C99 compiler and Linux headers (Alpine: build-base linux-headers).
+PREFIX defaults to /usr/local; DESTDIR is honored. For a static binary, use
+make LDFLAGS=-static, preferably with musl.
+
+
+Usage
+-----
+    usocks [-l addr:port|path] [-m maxconn] [-w workers] [-u user -p pass]
+
+    -l  listen on addr:port, [addr6]:port or a unix socket path
+        (default 127.0.0.1:1080)
+    -m  connection limit per worker, 1 to 16384 (default 1024)
+    -w  worker processes, 1 to 64 (default 1); not with a unix socket
+    -u  require RFC 1929 authentication with this username
+    -p  password for -u
+
+USOCKS_LISTEN, USOCKS_MAXCONN, USOCKS_WORKERS, USOCKS_USER and USOCKS_PASS
+set the same values. Flags take precedence.
+
+
+Testing
+-------
+    make && ./test
+
+Needs python3; takes about 15 s.