ngx_http_proxy_connect_module

name ==== This module provides support for [the CONNECT method request](https://tools.ietf.org/html/rfc7231#section-4.3.6). This method is mainly used to [tunnel SSL requests](https://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_tunneling) through proxy servers. Table of Contents ================= * [name](#name) * [Example](#example) * [configuration example](#configuration-example) * [example for curl](#example-for-curl) * [configuration example for CONNECT request in https](#configuration-example-for-connect-request-in-https) * [example for curl (CONNECT request in https)](#example-for-curl-connect-request-in-https) * [example for browser](#example-for-browser) * [example for basic authentication](#example-for-basic-authentication) * [example for proxying WebSocket](#example-for-proxying-websocket) * [Install](#install) * [select patch](#select-patch) * [build nginx](#build-nginx) * [build as a dynamic module](#build-as-a-dynamic-module) * [build OpenResty](#build-openresty) * [Test Suite](#test-suite) * [Error Log](#error-log) * [Directive](#directive) * [proxy_connect](#proxy_connect) * [proxy_connect_allow](#proxy_connect_allow) * [proxy_connect_connect_timeout](#proxy_connect_connect_timeout) * [proxy_connect_data_timeout](#proxy_connect_data_timeout) * [proxy_connect_read_timeout(deprecated)](#proxy_connect_read_timeout) * [proxy_connect_send_timeout(deprecated)](#proxy_connect_send_timeout) * [proxy_connect_address](#proxy_connect_address) * [proxy_connect_bind](#proxy_connect_bind) * [proxy_connect_response](#proxy_connect_response) * [Variables](#variables) * [$connect_host](#connect_host) * [$connect_port](#connect_port) * [$connect_addr](#connect_addr) * [$proxy_connect_connect_timeout](#proxy_connect_connect_timeout-1) * [$proxy_connect_data_timeout](#proxy_connect_data_timeout-1) * [$proxy_connect_read_timeout(deprecated)](#proxy_connect_read_timeout-1) * [$proxy_connect_send_timeout(deprecated)](#proxy_connect_send_timeout-1) * [$proxy_connect_resolve_time](#proxy_connect_resolve_time) * [$proxy_connect_connect_time](#proxy_connect_connect_time) * [$proxy_connect_first_byte_time](#proxy_connect_first_byte_time) * [$proxy_connect_response](#proxy_connect_response-1) * [Compatibility](#compatibility) * [Nginx Compatibility](#nginx-compatibility) * [OpenResty Compatibility](#openresty-compatibility) * [Tengine Compatibility](#tengine-compatibility) * [FAQ](#faq) * [Known Issues](#known-issues) * [See Also](#see-also) * [Author](#author) * [License](#license) Example ======= Configuration Example --------------------- ```nginx server { listen 3128; # dns resolver used by forward proxying resolver 8.8.8.8; # forward proxy for CONNECT requests proxy_connect; proxy_connect_allow 443 563; proxy_connect_connect_timeout 10s; proxy_connect_data_timeout 10s; # defined by yourself for non-CONNECT requests # Example: reverse proxy for non-CONNECT requests location / { proxy_pass http://$host; proxy_set_header Host $host; } } ``` * The `resolver` directive MUST be configured globally in `server {}` block (or `http {}` block). * Any `location {}` block, `upstream {}` block and any other standard backend/upstream directives, such as `proxy_pass`, do not impact the functionality of this module. (The proxy_connect module only executes the logic for requests that use the CONNECT method and that have a data flow under this tunnel.) * If you dont want to handle non-CONNECT requests, you can modify `location {}` block as following: ``` location / { return 403 "Non-CONNECT requests are forbidden"; } ``` Example for curl ---------------- With above configuration([configuration example](#configuration-example) ), you can get any https website via HTTP CONNECT tunnel. A simple test with command `curl` is as following: ``` … ``` The sequence diagram of above example is as following: ``` … ``` configuration example for CONNECT request in HTTPS -------------------------------------------------- ``` … ``` example for curl (CONNECT request in https) ------------------------------------------- With above configuration([configuration example for CONNECT request in https](#configuration-example-for-connect-request-in-https)), you can get any https website via HTTPS CONNECT tunnel(CONNECT request in https). A simple test with command `curl` is as following: Tips on using curl command: * `-x https://...` makes curl send CONNECT request in https. * `--proxy-insecure` disables ssl signature verification for ssl connection established with nginx proxy_connect server(`https://localhost:3128`), but it does not disable verification with proxied backend server(`https://nginx.org` in the example below). * If you want to disable signature verfication with proxied backend server, you can use `-k` option. output of curl command :point_left:

``` … ```

Example for browser ------------------- You can configure your browser to use this nginx as PROXY server. * Google Chrome HTTPS PROXY SETTING: [guide & config](https://github.com/chobits/ngx_http_proxy_connect_module/issues/22#issuecomment-346941271) for how to configure this module working under SSL layer. Example for Basic Authentication -------------------------------- We can do access control on CONNECT request using nginx auth basic module. See [this guide](https://github.com/chobits/ngx_http_proxy_connect_module/issues/42#issuecomment-502985437) for more details. Example for proxying WebSocket ------------------------------ * Note that nginx has its own WebSocket reverse proxy module, which is is not limited to the CONNECT tunnel, see [nginx.org doc: Nginx WebSocket proxying](https://nginx.org/en/docs/http/websocket.html) and [nginx.com blog: NGINX as a WebSocket Proxy](https://www.nginx.com/blog/websocket-nginx/). * This module enables the WebSocket protocol to work over the CONNECT tunnel, see https://github.com/chobits/ngx_http_proxy_connect_module/issues/267#issuecomment-1575449174 Install ======= Select patch ------------ * Select right patch for building: * All patch files have been included in `patch/` directory of this module. You dont need to download the patch directly from web page. | nginx version | enable REWRITE phase | patch | | --: | --: | --: | | 1.4.x ~ 1.12.x | NO | [proxy_connect.patch](patch/proxy_connect.patch) | | 1.4.x ~ 1.12.x | YES | [proxy_connect_rewrite.patch](patch/proxy_connect_rewrite.patch) | | 1.13.x ~ 1.14.x | NO | [proxy_connect_1014.patch](patch/proxy_connect_1014.patch) | | 1.13.x ~ 1.14.x | YES | [proxy_connect_rewrite_1014.patch](patch/proxy_connect_rewrite_1014.patch) | | 1.15.2 | YES | [proxy_connect_rewrite_1015.patch](patch/proxy_connect_rewrite_1015.patch) | | 1.15.4 ~ 1.16.x | YES | [proxy_connect_rewrite_101504.patch](patch/proxy_connect_rewrite_101504.patch) | | 1.17.x ~ 1.18.x | YES | [proxy_connect_rewrite_1018.patch](patch/proxy_connect_rewrite_1018.patch) | | 1.19.x ~ 1.21.0 | YES | [proxy_connect_rewrite_1018.patch](patch/proxy_connect_rewrite_1018.patch) | | 1.21.1 ~ 1.22.x | YES | [proxy_connect_rewrite_102101.patch](patch/proxy_connect_rewrite_102101.patch) | | 1.23.x ~ 1.24.0 | YES | [proxy_connect_rewrite_102101.patch](patch/proxy_connect_rewrite_102101.patch) | | 1.25.0 ~ 1.26.x | YES | [proxy_connect_rewrite_102101.patch](patch/proxy_connect_rewrite_102101.patch) | | 1.27.1 | YES | [proxy_connect_rewrite_102101.patch](patch/proxy_connect_rewrite_102101.patch) | | OpenResty version | enable REWRITE phase | patch | | --: | --: | --: | | 1.13.6 | NO | [proxy_connect_1014.patch](patch/proxy_connect_1014.patch) | | 1.13.6 | YES | [proxy_connect_rewrite_1014.patch](patch/proxy_connect_rewrite_1014.patch) | | 1.15.8 | YES | [proxy_connect_rewrite_101504.patch](patch/proxy_connect_rewrite_101504.patch) | | 1.17.8 | YES | [proxy_connect_rewrite_1018.patch](patch/proxy_connect_rewrite_1018.patch) | | 1.19.3 | YES | [proxy_connect_rewrite_1018.patch](patch/proxy_connect_rewrite_1018.patch) | | 1.21.4 | YES | [proxy_connect_rewrite_102101.patch](patch/proxy_connect_rewrite_102101.patch) | | 1.25.3 | YES | [proxy_connect_rewrite_102101.patch](patch/proxy_connect_rewrite_102101.patch) | * `proxy_connect_.patch` disables nginx REWRITE phase for CONNECT request by default, which means `if`, `set`, `rewrite_by_lua` and other REWRITE phase directives cannot be used. * `proxy_connect_rewrite_.patch` enables these REWRITE phase directives. Build nginx ----------- * Build nginx with this module from source: ```bash $ wget http://nginx.org/download/nginx-1.9.2.tar.gz $ tar -xzvf nginx-1.9.2.tar.gz $ cd nginx-1.9.2/ $ patch -p1 < /path/to/ngx_http_proxy_connect_module/patch/proxy_connect.patch $ ./configure --add-module=/path/to/ngx_http_proxy_connect_module $ make && make install ``` Build as a dynamic module ------------------------- * Starting from nginx 1.9.11, you can also compile this module as a dynamic module, by using the `--add-dynamic-module=PATH` option instead of `--add-module=PATH` on the `./configure` command line. ```bash $ wget http://nginx.org/download/nginx-1.9.12.tar.gz $ tar -xzvf nginx-1.9.12.tar.gz $ cd nginx-1.9.12/ $ patch -p1 < /path/to/ngx_http_proxy_connect_module/patch/proxy_connect.patch $ ./configure --add-dynamic-module=/path/to/ngx_http_proxy_connect_module $ make && make install ``` * And then you can explicitly load the module in your nginx.conf via the `load_module` directive, for example, ``` load_module /path/to/modules/ngx_http_proxy_connect_module.so; ``` * :exclamation: Note that the ngx_http_proxy_connect_module.so file MUST be loaded by nginx binary that is compiled with the .so file at the same time. Build OpenResty --------------- * Build OpenResty with this module from source: ```bash $ wget https://openresty.org/download/openresty-1.19.3.1.tar.gz $ tar -zxvf openresty-1.19.3.1.tar.gz $ cd openresty-1.19.3.1 $ ./configure --add-module=/path/to/ngx_http_proxy_connect_module $ patch -d build/nginx-1.19.3/ -p 1 < /path/to/ngx_http_proxy_connect_module/patch/proxy_connect_rewrite_101504.patch $ make && make install ``` Test Suite ========== * To run the whole test suite: ```bash $ hg clone http://hg.nginx.org/nginx-tests/ # If you use latest lua-nginx-module that needs lua-resty-core and # lua-resty-lrucache, you should add "lua_package_path ...;" directive # into nginx.conf of test cases. You can use the following command: # # $ export TEST_NGINX_GLOBALS_HTTP='lua_package_path "/path/to/nginx/lib/lua/?.lua;;";' $ export TEST_NGINX_BINARY=/path/to/nginx/binary $ prove -v -I /path/to/nginx-tests/lib /path/to/ngx_http_proxy_connect_module/t/ ``` * For the complete process of building and testing this module, see: * workflow files: [here](https://github.com/chobits/ngx_http_proxy_connect_module/tree/master/.github/workflows) * runs from all workflows: [here](https://github.com/chobits/ngx_http_proxy_connect_module/actions) Error Log ========= This module logs its own error message beginning with `"proxy_connect:"` string. Some typical error logs are shown as following: * The proxy_connect module tries to establish tunnel connection with backend server, but the TCP connection timeout occurs. ``` 2019/08/07 17:27:20 [error] 19257#0: *1 proxy_connect: upstream connect timed out (peer:216.58.200.4:443) while connecting to upstream, client: 127.0.0.1, server: , request: "CONNECT www.google.com:443 HTTP/1.1", host: "www.google.com:443" ``` Directive ========= proxy_connect ------------- Syntax: **proxy_connect*