session-replay-tools/nginx-hmux-module

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."

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

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

readme