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 connect to Resin through hmux protocol directly. The
backend connections are keepalive. The motivation of writing this module is
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 *163.beijing AT gmail DOT com*
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.