Update README

Author: dannote

README.md

@@ -1,45 +1,101 @@
 # socks-nginx-module
 
-An `nginx_http_proxy_module` fork with SOCKS5 support
+An nginx module that adds SOCKS5 proxy support to `proxy_pass`.
+
+## Features
+
+- Route upstream traffic through a SOCKS5 proxy
+- Username/password authentication (RFC 1929)
+- SSL to upstream through the SOCKS tunnel (`proxy_pass https://...`)
+- IPv4, IPv6, and domain name address types
 
 ## Building
 
-nginx >= **1.18.0** is supported.
+Requires nginx **1.26.x** and PCRE2.
 
 ```bash
-# apt-get install git build-essential zlib1g-dev libpcre3 libpcre3-dev unzip
+git clone https://github.com/dannote/socks-nginx-module
+wget http://nginx.org/download/nginx-1.26.3.tar.gz
+tar -xzf nginx-1.26.3.tar.gz
+cd nginx-1.26.3
 
-$ git clone https://github.com/dannote/socks-nginx-module
-$ wget http://nginx.org/download/nginx-1.18.0.tar.gz
+./configure --add-dynamic-module=../socks-nginx-module
+make
+make install
+```
 
-$ tar -xzvf nginx-1.18.0.tar.gz
+## Directives
 
-$ cd nginx-1.18.0
+### `socks_pass`
 
-# See http://nginx.org/en/docs/configure.html for more configuration options
-$ ./configure --add-dynamic-module=../socks-nginx-module
+Specifies the SOCKS5 proxy to route upstream traffic through. Must follow a `proxy_pass` directive.
 
-$ make
-# make install
+```nginx
+socks_pass socks5://proxy:1080;
 ```
 
-## Configuring
+Credentials can be provided inline:
+
+```nginx
+socks_pass socks5://user:password@proxy:1080;
+```
+
+### `socks_username` / `socks_password`
+
+Set SOCKS5 authentication credentials separately from the URL.
+
+```nginx
+socks_pass socks5://proxy:1080;
+socks_username myuser;
+socks_password mypassword;
+```
+
+## Configuration examples
+
+### HTTP through SOCKS
+
+```nginx
+location / {
+    proxy_pass http://httpbin.org/get;
+    socks_pass socks5://proxy:1080;
+}
+```
 
-Sample HTTP to SOCKS5 proxy configuration:
+### HTTPS through SOCKS
 
+```nginx
+location / {
+    proxy_pass https://httpbin.org/get;
+    proxy_ssl_server_name on;
+    socks_pass socks5://proxy:1080;
+}
 ```
+
+### With authentication
+
+```nginx
 location / {
-  proxy_pass http://httpbin.org/get;
-  socks_pass socks5://proxy:1080;
+    proxy_pass http://httpbin.org/get;
+    socks_pass socks5://user:password@proxy:1080;
 }
 ```
 
-## Debugging
+## Development
+
+### Running tests
 
+```bash
+make ci
 ```
+
+Individual targets: `build`, `build-clang`, `build-asan`, `test`, `test-asan`, `lint`, `cppcheck`, `format`.
+
+### Debugging
+
+```bash
 cd debug
-docker-compose run --service-ports nginx
+docker compose run --service-ports nginx
 
 (gdb) set follow-fork-mode child
 (gdb) run
-```
+```

ngx_http_socks_module.c

@@ -1523,17 +1523,16 @@ ngx_http_socks_read_connect_response(ngx_http_request_t *r,
 static void
 ngx_http_socks_handshake_done(ngx_http_request_t *r, ngx_http_upstream_t *u)
 {
-    ngx_connection_t *c;
-
-    c = u->peer.connection;
-
-    ngx_log_debug0(NGX_LOG_DEBUG_HTTP, c->log, 0, "http socks handshake done");
+    ngx_log_debug0(NGX_LOG_DEBUG_HTTP, u->peer.connection->log, 0,
+                   "http socks handshake done");
 
 #if (NGX_HTTP_SSL)
 
-    if (u->ssl && c->ssl == NULL) {
+    if (u->ssl && u->peer.connection->ssl == NULL) {
+        ngx_connection_t *c;
         ngx_http_proxy_ctx_t *pctx;
 
+        c = u->peer.connection;
         pctx = ngx_http_get_module_ctx(r, ngx_http_proxy_module);
 
         /*

ngx_http_socks_upstream.h

@@ -3719,6 +3719,8 @@ ngx_http_upstream_finalize_request(ngx_http_request_t *r,
 }
 
 
+#if (NGX_HTTP_SSL)
+
 static void
 ngx_http_upstream_ssl_init_connection(ngx_http_request_t *r,
     ngx_http_upstream_t *u, ngx_connection_t *c)
@@ -4024,6 +4026,8 @@ ngx_http_upstream_ssl_certificate(ngx_http_request_t *r,
     return NGX_OK;
 }
 
+#endif
+
 
 static ngx_int_t
 ngx_http_upstream_process_header_line(ngx_http_request_t *r, ngx_table_elt_t *h,