1= Name = 2 3'''nginx_ajp_module''' - support AJP protocol proxy with Nginx 4 5= Synopsis = 6 7<geshi lang="nginx"> 8 9 http { 10 upstream tomcats { 11 server 127.0.0.1:8009; 12 keepalive 10; 13 } 14 15 server { 16 17 listen 80; 18 19 location / { 20 ajp_keep_conn on; 21 ajp_pass tomcats; 22 } 23 } 24 } 25 26</geshi> 27 28= Description = 29With this module, Nginx can connect to AJP port directly. The motivation of writing these modules is Nginx's high performance and robustness. 30 31= Directives = 32 33== ajp_buffers == 34 35'''syntax:''' ''ajp_buffers the_number is_size;'' 36 37'''default:''' ''ajp_buffers 8 4k/8k;'' 38 39'''context:''' ''http, server, location'' 40 41This directive specifies the number and the size of buffers, into which will be read the response, obtained from the AJP server. By default, the size of one buffer is equal to the size of a page. Depending on platform this is either 4K, 8K or 16K. 42 43== ajp_buffer_size == 44 45'''syntax:''' ''ajp_buffer_size the_size;'' 46 47'''default:''' ''ajp_buffer_size 4k/8k;'' 48 49'''context:''' ''http, server, location'' 50 51This directive sets the buffer size, into which will be read the first part of the response, obtained from the AJP server. 52 53In this part of response the small response-header is located, as a rule. 54 55By default, the buffersize is equal to the size of one buffer in directive <code>ajp_buffers</code>; however, it is possible to set it to less. 56 57== ajp_cache == 58 59'''syntax:''' ''ajp_cache zone;'' 60 61'''default:''' ''off'' 62 63'''context:''' ''http, server, location'' 64 65The directive specifies the area which actually is the share memory's name for caching. The same area can be used in several places. You must set the <code>ajp_cache_path</code> first. 66 67== ajp_cache_key == 68 69'''syntax:''' ''ajp_cache_key line;'' 70 71'''default:''' ''none'' 72 73'''context:''' ''http, server, location'' 74 75The directive specifies what information is included in the key for caching, for example 76 77<geshi lang="nginx"> 78 79 ajp_cache_key "$host$request_uri$cookie_user"; 80 81</geshi> 82 83Note that by default, the hostname of the server is not included in the cache key. If you are using subdomains for different locations on your website, you need to include it, e.g. by changing the cache key to something like 84 85<geshi lang="nginx"> 86 ajp_cache_key "$scheme$host$request_uri"; 87</geshi> 88 89== ajp_cache_methods == 90 91'''syntax:''' ''ajp_cache_methods [GET HEAD POST];'' 92 93'''default:''' ''ajp_cache_methods GET HEAD;'' 94 95'''context:''' ''main,http,location'' 96 97GET/HEAD is syntax sugar, i.e. you can not disable GET/HEAD even if you set just 98 99<geshi lang="nginx"> 100 101 ajp_cache_methods POST; 102 103</geshi> 104 105== ajp_cache_min_uses == 106 107'''syntax:''' ''ajp_cache_min_uses n;'' 108 109'''default:''' ''ajp_cache_min_uses 1;'' 110 111'''context:''' ''http, server, location'' 112 113Sets the number of requests after which the response will be cached. 114 115== ajp_cache_path == 116 117'''syntax:''' ''ajp_cache_path /path/to/cache [levels=m:n keys_zone=name:time inactive=time clean_time=time];'' 118 119'''default:''' ''none'' 120 121'''context:''' ''http, server, location'' 122 123This directive sets the cache path and other cache parameters. Cached data stored in files. Key and filename in cache is md5 of proxied URL. '''Levels''' parameter set number of subdirectories in cache, for example for: 124 125<geshi lang="nginx"> 126 127 ajp_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; 128 129</geshi> 130 131file names will be like: 132 133/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c 134 135== ajp_cache_use_stale == 136 137'''syntax:''' ''ajp_cache_use_stale [updating|error|timeout|invalid_header|http_500];'' 138 139'''default:''' ''ajp_cache_use_stale off;'' 140 141'''context:''' ''http, server, location'' 142 143If an error occurs while working with the AJP server it is possible to use a stale cached response. This directives determines in which cases it is permitted. The directive’s parameters match those of the <code>ajp_next_upstream</code> directive. 144 145Additionally, the updating parameter permits to use a stale cached response if it is currently being updated. This allows to minimize the number of accesses to AJP servers when updating cached data. 146 147== ajp_cache_valid == 148 149'''syntax:''' ''ajp_cache_valid [http_error_code|time];'' 150 151'''default:''' ''none'' 152 153'''context:''' ''http, server, location'' 154 155Sets caching time for different response codes. For example, the following directives 156 157<geshi lang="nginx"> 158 159 ajp_cache_valid 200 302 10m; 160 ajp_cache_valid 404 1m; 161 162</geshi> 163 164set 10 minutes of caching for responses with codes 200 and 302, and 1 minute for responses with code 404. 165 166If only caching time is specified 167 168<geshi lang="nginx"> 169 170 ajp_cache_valid 5m; 171 172</geshi> 173 174then only 200, 301, and 302 responses are cached. 175 176In addition, it can be specified to cache any responses using the any parameter: 177 178<geshi lang="nginx"> 179 180 ajp_cache_valid 200 302 10m; 181 ajp_cache_valid 301 1h; 182 ajp_cache_valid any 1m; 183 184</geshi> 185 186Parameters of caching can also be set directly in the response header. This has a higher precedence than setting of caching time using the directive. The “X-Accel-Expires” header field sets caching time of a response in seconds. The value 0 disables to cache a response. If a value starts with the prefix @, it sets an absolute time in seconds since Epoch, up to which the response may be cached. If header does not include the “X-Accel-Expires” field, parameters of caching may be set in the header fields “Expires” or “Cache-Control”. If a header includes the “Set-Cookie” field, such a response will not be cached. Processing of one or more of these response header fields can be disabled using the <code>ajp_ignore_headers</code> directive. 187 188== ajp_connect_timeout == 189 190'''syntax:''' ''ajp_connect_timeout time;'' 191 192'''default:''' ''ajp_connect_timeout 60s;'' 193 194'''context:''' ''http, server, location'' 195 196This directive assigns a timeout for the connection to the upstream server. It is necessary to keep in mind that this time out cannot be more than 75 seconds. 197 198This is not the time until the server returns the pages, this is the [[#ajp_read_timeout| ajp_read_timeout]] statement. If your upstream server is up, but hanging (e.g. it does not have enough threads to process your request so it puts you in the pool of connections to deal with later), then this statement will not help as the connection to the server has been made. 199 200== ajp_header_packet_buffer_size == 201 202'''syntax:''' ''ajp_header packet_buffer_size;'' 203 204'''default:''' ''ajp_header_packet_buffer_size 8k;'' 205 206'''context:''' ''http, server, location'' 207 208Set the buffer size of Forward Request packet. The range is (0, 2^16). 209 210== ajp_hide_header == 211 212'''syntax:''' ''ajp_hide_header name;'' 213 214'''context:''' ''http, server, location'' 215 216By default, Nginx does not pass headers "Status" and "X-Accel-..." from the AJP process back to the client. This directive can be used to hide other headers as well. 217 218If the headers "Status" and "X-Accel-..." must be provided, then it is necessary to use directive ajp_pass_header to force them to be returned to the client. 219 220== ajp_ignore_headers == 221 222'''syntax:''' ''ajp_ignore_headers name [name ...];'' 223 224'''default:''' ''none'' 225 226'''context:''' ''http, server, location'' 227 228This directive(0.7.54+) prohibits the processing of the header lines from the proxy server's response. 229 230It can specify the string as "[[NginxXSendfile|X-Accel-Redirect]]", "X-Accel-Expires", "Expires" or "Cache-Control". 231 232== ajp_ignore_client_abort == 233 234'''syntax:''' ''ajp_ignore_client_abort on|off;'' 235 236'''default:''' ''ajp_ignore_client_abort off;'' 237 238'''context:''' ''http, server, location'' 239 240This directive determines if current request to the AJP-server must be aborted in case the client aborts the request to the server. 241 242== ajp_intercept_errors == 243 244'''syntax:''' ''ajp_intercept_errors on|off;'' 245 246'''default:''' ''ajp_intercept_errors off;'' 247 248'''context:''' ''http, server, location'' 249 250This 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. 251 252Note: 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." 253 254== ajp_keep_conn == 255 256'''syntax:''' ''ajp_keep_conn on|off;'' 257 258'''default:''' ''ajp_keep_conn off;'' 259 260'''context:''' ''http, server, location'' 261 262This directive determines whether or not to keep the connection alive with backend server. 263 264== ajp_next_upstream == 265 266'''syntax:''' ''ajp_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off];'' 267 268'''default:''' ''ajp_next_upstream error timeout;'' 269 270'''context:''' ''http, server, location'' 271 272Directive determines, in what cases the request will be transmitted to the next server: 273 274* error — an error has occurred while connecting to the server, sending a request to it, or reading its response; 275* timeout — occurred timeout during the connection with the server, transfer the request or while reading response from the server; 276* invalid_header — server returned a empty or incorrect answer; 277* http_500 — server returned answer with code 500; 278* http_502 — server returned answer with code 502; 279* http_503 — server returned answer with code 503; 280* http_504 — server returned answer with code 504; 281* http_404 — server returned answer with code 404; 282* off — it forbids the request transfer to the next server Transferring the request to the next server is only possible when nothing has been transferred to the client -- that is, if an error or timeout arises in the middle of the transfer of the request, then it is not possible to retry the current request on a different server. 283 284== ajp_max_data_packet_size == 285 286'''syntax:''' ''ajp_max_data_packet_size size;'' 287 288'''default:''' ''ajp_max_data_packet_size 8k;'' 289 290'''context:''' ''http, server, location'' 291 292Set the maximum size of AJP's Data packet. The range is [8k, 2^16]; 293 294== ajp_max_temp_file_size == 295 296'''syntax:''' ''ajp_max_temp_file_size size;'' 297 298'''default:''' ''ajp_max_temp_file_size 1G;'' 299 300'''context:''' ''http, server, location, if'' 301 302The 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. 303 304If ajp_max_temp_file_size is equal to zero, temporary files usage will be disabled. 305 306== ajp_pass == 307 308'''syntax:''' ''ajp_pass ajp-server'' 309 310'''default:''' ''none'' 311 312'''context:''' ''location, if in location'' 313 314Directive assigns the port or socket on which the AJP-server is listening. Port can be indicated by itself or as an address and port, for example: 315 316<geshi lang="nginx"> 317 318 ajp_pass localhost:9000; 319 320</geshi> 321 322using a Unix domain socket: 323 324<geshi lang="nginx"> 325 326 ajp_pass unix:/tmp/ajp.socket; 327 328</geshi> 329 330You may also use an upstream block. 331 332<geshi lang="nginx"> 333 334 upstream backend { 335 server localhost:1234; 336 } 337 338 ajp_pass backend; 339 340</geshi> 341 342== ajp_pass_header == 343 344'''syntax:''' ''ajp_pass_header name;'' 345 346'''context:''' ''http, server, location'' 347 348Permits to pass specific header fields from the AJP server to a client. 349 350== ajp_pass_request_headers == 351 352'''syntax:''' ''ajp_pass_request_headers [ on | off ];'' 353 354'''default:''' ''ajp_pass_request_headers on;'' 355 356'''context:''' ''http, server, location'' 357 358Permits to pass request header fields from the client to server. 359 360== ajp_pass_request_body == 361 362'''syntax:''' ''ajp_pass_request_body [ on | off ] ;'' 363 364'''default:''' ''ajp_pass_request_body on;'' 365 366'''context:''' ''http, server, location'' 367 368Permits to pass request body from the client to server. 369 370== ajp_read_timeout == 371 372'''syntax:''' ''ajp_read_timeout time;'' 373 374'''default:''' ''ajp_read_timeout_time 60'' 375 376'''context:''' ''http, server, location'' 377 378Directive sets the amount of time for upstream to wait for a AJP process to send data. Change this directive if you have long running AJP 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. 379 380== ajp_send_lowat == 381 382'''syntax:''' ''ajp_send_lowat [ on | off ];'' 383 384'''default:''' ''ajp_send_lowat off;'' 385 386'''context:''' ''http, server, location, if'' 387 388This directive set SO_SNDLOWAT. This directive is only available on FreeBSD 389 390== ajp_send_timeout == 391 392'''syntax:''' ''ajp_send_timeout time;'' 393 394'''default:''' ''ajp_send_timeout 60;'' 395 396'''context:''' ''http, server, location'' 397 398This directive assigns timeout with the transfer of request to the upstream server. Timeout is established not on entire transfer of request, but only between two write operations. If after this time the upstream server will not take new data, then nginx is shutdown the connection. 399 400== ajp_store == 401 402'''syntax:''' ''ajp_store [on | off | path] ;'' 403 404'''default:''' ''ajp_store off;'' 405 406'''context:''' ''http, server, location'' 407 408This 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: 409 410<geshi lang="nginx"> 411 ajp_store /data/www$original_uri; 412</geshi> 413 414The 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 <code>ajp_temp_path</code> for the data location. 415 416This directive can be used for creating the local copies for dynamic output of the backend which is not very often changed, for example: 417 418<geshi lang="nginx"> 419 location /images/ { 420 root /data/www; 421 error_page 404 = @fetch; 422 } 423 424 location @fetch { 425 internal; 426 ajp_pass backend; 427 ajp_store on; 428 ajp_store_access user:rw group:rw all:r; 429 ajp_temp_path /data/temp; 430 431 root /data/www; 432 } 433</geshi> 434 435To be clear ajp_store is not a cache, it's rather mirror on demand. 436 437== ajp_store_access == 438 439'''syntax:''' ''ajp_store_access users:permissions [users:permission ...];'' 440 441'''default:''' ''ajp_store_access user:rw;'' 442 443'''context:''' ''http, server, location'' 444 445This directive assigns the permissions for the created files and directories, for example: 446 447<geshi lang="nginx"> 448 ajp_store_access user:rw group:rw all:r; 449</geshi> 450 451If any rights for groups or all are assigned, then it is not necessary to assign rights for user: 452 453<geshi lang="nginx"> 454 ajp_store_access group:rw all:r; 455</geshi> 456 457== ajp_temp_path == 458 459'''syntax:''' ''ajp_temp_path dir-path [ level1 [ level2 [ level3 ] ] ] ;'' 460 461'''default:''' ''$NGX_PREFIX/ajp_temp'' 462 463'''context:''' ''http, server, location'' 464 465This directive works like [[NginxHttpCoreModule#client_body_temp_path|client_body_temp_path]] to specify a location to buffer large proxied requests to the filesystem. 466 467== ajp_temp_file_write_size == 468 469'''syntax:''' ''ajp_temp_file_write_size size;'' 470 471'''default:''' ''ajp_temp_file_write_size ["#ajp buffer size"] * 2;'' 472 473'''context:''' ''http, server, location, if'' 474 475Sets the amount of data that will be flushed to the ajp_temp_path when writing. It may be used to prevent a worker process blocking for too long while spooling data. 476 477= Installation = 478 479Download the latest version of the release tarball of this module from [http://github.com/yaoweibin/nginx_ajp_module github] 480 481Grab the nginx source code from [http://nginx.org/ nginx.org], for example, the version 1.2.0 (see nginx compatibility), and then build the source with this module: 482 483<geshi lang="bash"> 484 $ wget 'http://nginx.org/download/nginx-1.4.4.tar.gz' 485 $ tar -xzvf nginx-1.4.4.tar.gz 486 $ cd nginx-1.4.4/ 487 $ ./configure --add-module=/path/to/nginx_ajp_module 488 489 $ make 490 $ make install 491</geshi> 492 493= Compatibility = 494 495* The master branch is for Nginx-1.1.4+ 496* If you want to use it with Nginx-1.0.x, you can use this [https://github.com/yaoweibin/nginx_ajp_module/tree/nginx-1.0 nginx-1.0] branch. 497 498= TODO = 499 500* SSL 501 502= Known Issues = 503 504* 505 506= Changelogs = 507 508== v0.3 == 509* remove the jvm_route and keepalive module 510 511== v0.2 == 512* bugfix 513 514== v0.1 == 515* first release 516 517= Authors = 518 519* Weibin Yao(姚伟斌) ''yaoweibin AT gmail DOT com'' 520* Jinti Shen(路奇) ''jinti.shen AT gmail DOT com'' 521* Joshua Zhu(叔度) ''zhuzhaoyuan AT gmail DOT com'' 522* Simon Liu(雕梁) ''simohayha.bobo AT gmail DOT com'' 523* Matthew Ma(东坡) ''mj19821214 AT gmail DOT com'' 524 525= Acknowledgments = 526 527* Thanks 李金虎(beagem@163.com) to improve the keepalive feature with this module. 528 529= License = 530 531This README template is from [http://github.com/agentzh agentzh]. 532 533I borrowed a lot of codes from Fastcgi module of Nginx. This part of code is copyrighted by Igor Sysoev. And the design of apache's [http://httpd.apache.org/docs/trunk/mod/mod_proxy_ajp.html mod_ajp_proxy]. Thanks for their hard work. 534 535This module is licensed under the BSD license. 536 537Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 538 539* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 540* 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. 541 542THIS 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. 543 544