README

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.