Name nginx_hmux_module - Support HMUX protocol proxy with Nginx. Synopsis events { use epoll; epoll_events 4096; worker_connections 8192; accept_mutex off; } http { upstream resins{ server xxx.xxx.xxx.xxx:6800; keepalive 1024; } server { listen xxxx; server_name xxx.xxx.com; location / { hmux_pass resins; } } } Description With this module, Nginx can directly connect to Resin using the HMUX protocol, with backend connections maintained as keepalive. The motivation for creating this module is to leverage Nginx's high performance and robustness. Directives hmux_buffers syntax: *hmux_buffers the_number is_size;* default: *hmux_buffers 8 4k/8k;* context: *http, server, location* This directive sets the number and the size of the buffers into which the reply from the hmux process in the backend is read. By default, the size of each buffer is equal to the OS page size. Depending on the platform and architecture this value is one of 4k, 8k or 16k. hmux_buffer_size syntax: *hmux_buffer_size the_size;* default: *hmux_buffer_size 4k/8k;* context: *http, server, location* This directive sets the buffer size for reading the header of the backend hmux process. By default, the buffer size is equal to the size of one buffer in hmux_buffers. This directive allows you to set it to an arbitrary value. hmux_cache The usage is the same as fastcgi_cache. hmux_cache_key Same as fastcgi_cache_key. hmux_cache_methods Same as fastcgi_cache_methods. hmux_cache_min_uses Same as fastcgi_cache_min_uses. hmux_cache_path Same as fastcgi_cache_path. hmux_cache_use_stale Same as fastcgi_cache_use_stale. hmux_cache_valid Same as fastcgi_cache_valid. hmux_connect_timeout syntax: *hmux_connect_timeout time;* default: *hmux_connect_timeout 60s;* context: *http, server, location* Directive sets timeout period for connection with hmux-server. It should be noted that this value can't exceed 75 seconds. hmux_header_packet_buffer_size syntax: *hmux_header packet_buffer_size;* default: *hmux_header_packet_buffer_size 8k;* context: *http, server, location* Set the buffer size of Forward Request packet. The range is (0, 2^16). hmux_hide_header syntax: *hmux_hide_header name;* context: *http, server, location* By default, Nginx does not pass headers "Status" and "X-Accel-..." from the hmux process back to the client. This directive can be used to hide other headers as well. If the headers "Status" and "X-Accel-..." must be provided, then it is necessary to use directive hmux_pass_header to force them to be returned to the client. hmux_ignore_headers syntax: *hmux_ignore_headers name [name ...];* default: *none* context: *http, server, location* This directive forbids processing of the named headers from the hmux-server reply. It is possible to specify headers like "X-Accel-Redirect", "X-Accel-Expires", "Expires" or "Cache-Control". hmux_ignore_client_abort syntax: *hmux_ignore_client_abort on|off;* default: *hmux_ignore_client_abort off;* context: *http, server, location* This directive determines if current request to the hmux-server must be aborted in case the client aborts the request to the server. hmux_intercept_errors syntax: *hmux_intercept_errors on|off;* default: *hmux_intercept_errors off;* context: *http, server, location* This directive determines whether or not to transfer 4xx and 5xx errors back to the client or to allow Nginx to answer with directive error_page. Note: You need to explicitly define the error_page handler for this for it to be useful. As Igor says, "Nginx does not intercept an error if there is no custom handler for it, it does not show its default pages. This allows to intercept some errors, while passing others as are." hmux_next_upstream syntax: *hmux_next_upstream [error|timeout|invalid_header|http_500|http_503|http_404|non_idempotent|off];* default: *hmux_next_upstream error timeout;* context: *http, server, location* This directive defines in which cases request will be passed to the next server: error - an error occurred during connection to the server, passing request to it or reading server respond header; timeout - a timeout occurred during connection to the server, passing request to it or reading server respond header; invalid_header - server returned empty or invalid answer; http_500 - a server returned a response with the code 500; http_502 - a server returned a response with the code 502; http_503 - a server returned a response with the code 503; http_504 - a server returned a response with the code 504; http_404 - a server returned a response with the code 404; non_idempotent - normally, requests with a non-idempotent method (POST, LOCK, PATCH) are not passed to the next server if a request has been sent to an upstream server (Nginx 1.9.13); enabling this option explicitly allows retrying such requests; off - explicitly forbids passing request to the next server; It should be clear that passing request to the next server is possible only if no data have been yet returned to the client. So, if the error or timeout occurred during the data transmission to the client it's too late to fix it. hmux_next_upstream_timeout syntax: *hmux_next_upstream_timeout time;* default: *hmux_next_upstream_timeout 0s;* context: *http, server, location* This directive appeared in Nginx version 1.7.5. hmux_next_upstream_tries syntax: *hmux_next_upstream_tries number;* default: *hmux_next_upstream_tries 0;* context: *http, server, location* This directive appeared in Nginx version 1.7.5. hmux_max_data_packet_size syntax: *hmux_max_data_packet_size size;* default: *hmux_max_data_packet_size 8k;* context: *http, server, location* Set the maximum size of hmux's Data packet. The range is [8k, 2^16]; hmux_max_temp_file_size syntax: *hmux_max_temp_file_size size;* default: *hmux_max_temp_file_size 1G;* context: *http, server, location, if* The maximum size of a temporary file when the content is larger than the proxy buffer. If file is larger than this size, it will be served synchronously from upstream server rather than buffered to disk. If hmux_max_temp_file_size is equal to zero, temporary files usage will be disabled. hmux_pass syntax: *hmux_pass hmux-server* default: *none* context: *location, if in location* Directive assigns the port or socket on which the hmux-server is listening. Port can be indicated by itself or as an address and port, for example: hmux_pass localhost:6800; using a Unix domain socket: hmux_pass unix:/tmp/hmux.socket; You may also use an upstream block. upstream backend { server localhost:6800; } hmux_pass backend; hmux_pass_header syntax: *hmux_pass_header name;* context: *http, server, location* This directive explicitly allows to pass named headers to the client. hmux_pass_request_headers syntax: *hmux_pass_request_headers [ on | off ];* default: *hmux_pass_request_headers on;* context: *http, server, location* Permits to pass request header fields from the client to server. hmux_pass_request_body syntax: *hmux_pass_request_body [ on | off ] ;* default: *hmux_pass_request_body on;* context: *http, server, location* Permits to pass request body from the client to server. hmux_read_timeout syntax: *hmux_read_timeout time;* default: *hmux_read_timeout_time 60* context: *http, server, location* Directive sets the amount of time for upstream to wait for a hmux process to send data. Change this directive if you have long running hmux processes that do not produce output until they have finished processing. If you are seeing an upstream timed out error in the error log, then increase this parameter to something more appropriate. hmux_send_lowat syntax: *hmux_send_lowat [ on | off ];* default: *hmux_send_lowat off;* context: *http, server, location, if* This directive set SO_SNDLOWAT. This directive is only available on FreeBSD hmux_send_timeout syntax: *hmux_send_timeout time;* default: *hmux_send_timeout 60;* context: *http, server, location* Directive sets the amount of time for upstream to wait for a hmux process to send data. Change this directive if you have long running hmux processes that do not produce output until they have finished processing. If you are seeing an upstream timed out error in the error log, then increase this parameter to something more appropriate. Directive specifies request timeout to the server. The timeout is calculated between two write operations, not for the whole request. If no data have been written during this period then serve closes the connection. hmux_store syntax: *hmux_store [on | off | path] ;* default: *hmux_store off;* context: *http, server, location* This directive sets the path in which upstream files are stored. The parameter "on" preserves files in accordance with path specified in directives *alias* or *root*. The parameter "off" forbids storing. Furthermore, the name of the path can be clearly assigned with the aid of the line with the variables: hmux_store /data/www$original_uri; The time of modification for the file will be set to the date of "Last-Modified" header in the response. To be able to safe files in this directory it is necessary that the path is under the directory with temporary files, given by directive hmux_temp_path for the data location. This directive can be used for creating the local copies for dynamic output of the backend which is not very often changed, for example: location /images/ { root /data/www; error_page 404 = @fetch; } location @fetch { internal; hmux_pass backend; hmux_store on; hmux_store_access user:rw group:rw all:r; hmux_temp_path /data/temp; root /data/www; } To be clear hmux_store is not a cache, it's rather mirror on demand. hmux_store_access syntax: *hmux_store_access users:permissions [users:permission ...];* default: *hmux_store_access user:rw;* context: *http, server, location* This directive assigns the permissions for the created files and directories, for example: hmux_store_access user:rw group:rw all:r; If any rights for groups or all are assigned, then it is not necessary to assign rights for user: hmux_store_access group:rw all:r; hmux_temp_file_write_size syntax: *hmux_temp_file_write_size size;* default: *hmux_temp_file_write_size ["#hmux buffer size"] * 2;* context: *http, server, location, if* Sets the amount of data that will be flushed to the hmux_temp_path when writing. It may be used to prevent a worker process blocking for too long while spooling data. hmux_x_forwarded_for syntax: *hmux_x_forwarded_for [ on | off ];* default: *hmux_x_forwarded_for off;* context: *http, server, location* This directive explicitly allows to pass the X-Forwarded-For header to the backend. keepalive syntax: *keepalive <num> default: *none* context: *upstream* Parameters: - <num> Maximum number of connections to cache. If there isn't enough room to cache new connections - last recently used connections will be kicked off the cache. The instruction is for keeping alive between Nginx and Resin. It may not work when Nginx has multiple processes,if not working,you should set accept_mutex off; Installation Download the latest version of the release tarball of this module from github (git clone http://github.com/wangbin579/nginx-hmux-module) Grab the Nginx source code from nginx.org (<http://nginx.org/>). For example, the version 1.2.3, and then build the source with this module: $wget 'http://nginx.org/download/nginx-1.2.3.tar.gz' $tar -xzvf nginx-1.2.3.tar.gz $cd nginx-1.2.3/ $./configure --add-module=/path/to/hmux/directory $make $make install Note: This module is for Nginx 1.1.4+ Known Issues SSL proxy to backend is not supported Changelogs v0.1 first release v0.5 fixed keepalive problems for Nginx 1.1.14 or above v0.7 added "HTTPS ON" for https Authors Bin Wang License This README template is from agentzh (<http://github.com/agentzh>). I borrowed a lot of codes from fastcgi module of Nginx and the design of Nginx's nginx_ajp_module (<https://github.com/yaoweibin/nginx_ajp_module>). Thanks for their hard work. This module is licensed under the BSD license. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
session-replay-tools/nginx-hmux-module
The module implements Resin's HMUX protocol in NGINX.
CNOASSERTION