passenger 3.9.1.beta → 3.9.2.beta

data/doc/Users guide Nginx.idmap.txt

@@ -18,70 +18,27 @@
 
 1.2. Where to get support	=>	where-to-get-support-2s9na5
 
-# fuzzy
-10. Appendix A: About this document	=>	appendix-a-about-this-document-zfvixm
-
-# fuzzy
-11. Appendix B: Terminology	=>	appendix-b-terminology-wzv5ro
-
-# fuzzy
-11.1. Application root	=>	application-root-1fd6bqv
-
-# fuzzy
-11.2. Idle process	=>	idle-process-13byfw9
-
-# fuzzy
-11.3. Inactive process	=>	inactive-process-1d2h0po
-
-# fuzzy
-12. Appendix C: Spawning methods explained	=>	appendix-c-spawning-methods-explained-tcp8e6
-
-# fuzzy
-12.1. The most straightforward and traditional way: direct spawning	=>	the-most-straightforward-and-traditional-way-conservative-spawning-civ29z
-
-# fuzzy
-12.2. The smart spawning method	=>	the-smart-spawning-method-7nhgtj
-
-# fuzzy
-12.2.1. How it works	=>	how-it-works-f9umga
-
-# fuzzy
-12.2.2. Summary of benefits	=>	summary-of-benefits-qovyvk
-
-# fuzzy
-12.3. Smart spawning gotcha #1: unintentional file descriptor sharing	=>	smart-spawning-gotcha-1-unintentional-file-descriptor-sharing-cebw6q
+2. Installation	=>	installing-phusion-passenger-hn03ac
 
-# fuzzy
-12.3.1. Example 1: Memcached connection sharing (harmful)	=>	example-1-memcached-connection-sharing-harmful--1wfs3ad
-
-# fuzzy
-12.3.2. Example 2: Log file sharing (not harmful)	=>	example-2-log-file-sharing-not-harmful--ox4yfy
-
-# fuzzy
-12.4. Smart spawning gotcha #2: the need to revive threads	=>	smart-spawning-gotcha-2-the-need-to-revive-threads-1ey176o
-
-# fuzzy
-12.5. Smart spawning gotcha #3: code load order	=>	smart-spawning-gotcha-3-code-load-order-12ydsn8
+2.1. Generic installation, upgrade and downgrade method: via RubyGems	=>	generic-installation-upgrade-and-downgrade-method-via-rubygems-76uol7
 
-2. Installing Phusion Passenger	=>	installing-phusion-passenger-hn03ac
+2.2. Generic installation, upgrade and downgrade method: via tarball	=>	generic-installation-upgrade-and-downgrade-method-via-tarball-2gkx43
 
-2.1. Overview	=>	overview-kvhzi4
+2.3. Installing or upgrading on Ubuntu	=>	installing-or-upgrading-on-ubuntu-fw5fvp
 
-2.2. Specifying the correct Ruby installation	=>	specifying-the-correct-ruby-installation-jvqdv6
+2.4. Installing or upgrading on Red Hat, Fedora, CentOS or ScientificLinux	=>	installing-or-upgrading-on-red-hat-fedora-centos-or-scientificlinux-1uus5a1
 
-2.3. Installing Phusion Passenger for Nginx through the installer	=>	installing-phusion-passenger-for-nginx-through-the-installer-1lqxes1
+2.5. Upgrading from open source to Enterprise	=>	upgrading-from-open-source-to-enterprise-1a58c2b
 
-2.3.1. Obtaining the Phusion Passenger files and running the installer	=>	obtaining-the-phusion-passenger-files-and-running-the-installer-6l6ula
+2.6. Non-interactive, automatic, headless installs or upgrades	=>	non-interactive-automatic-headless-installs-or-upgrades-834ymv
 
-2.3.2. Non-interactive/automatic installation	=>	non-interactive-automatic-installation-1u97717
+2.7. Installing as a normal Nginx module without using the installer	=>	installing-as-a-normal-nginx-module-without-using-the-installer-1kkpes5
 
-2.4. Installing Phusion Passenger for Nginx manually	=>	installing-phusion-passenger-for-nginx-manually-1qg1e2x
+2.8. Disabling without uninstalling	=>	disabling-without-uninstalling-1t5tqan
 
-2.5. Upgrading or downgrading Phusion Passenger or Nginx itself	=>	upgrading-or-downgrading-phusion-passenger-or-nginx-itself-8dulxz
+2.9. Uninstalling	=>	uninstalling-phusion-passenger-wuycvb
 
-2.6. Unloading (disabling) Phusion Passenger from Nginx without uninstalling it	=>	unloading-disabling-phusion-passenger-from-nginx-without-uninstalling-it-v447e0
-
-2.7. Uninstalling Phusion Passenger	=>	uninstalling-phusion-passenger-wuycvb
+2.10. Moving to a different directory	=>	moving-to-a-different-directory-gif3wo
 
 3. Deploying a Ruby on Rails 1.x or 2.x (but NOT Rails >= 3) application	=>	deploying-a-ruby-on-rails-1-x-or-2-x-but-not-rails-3-application-b69gqa
 
@@ -127,198 +84,165 @@
 
 5.3. Redeploying (restarting the WSGI application)	=>	redeploying-restarting-the-wsgi-application--10zdh2k
 
-# fuzzy
 6. Configuring Phusion Passenger	=>	configuring-phusion-passenger-1g1svey
 
-# fuzzy
 6.1. passenger_root <directory>	=>	passenger-root-directory--bqvhhz
 
-# fuzzy
-6.10. Logging and debugging options	=>	logging-and-debugging-options-14e91ni
-
-# fuzzy
-6.10.1. passenger_log_level <integer>	=>	passenger-log-level-integer--17snhon
-
-# fuzzy
-6.10.2. passenger_debug_log_file <filename>	=>	passenger-debug-log-file-filename--21ubaj
-
-# fuzzy
-6.10.3. passenger_debugger <on|off>	=>	passenger-debugger-on-off--1wkuq85
-
-# fuzzy
-6.11. Ruby on Rails-specific options	=>	ruby-on-rails-specific-options-12vfokt
-
-# fuzzy
-6.11.1. rails_env <string>	=>	rails-env-string--jlh7v9
-
-# fuzzy
-6.12. Rack and Rails >= 3 specific options	=>	rack-specific-options-13yvdxs
-
-# fuzzy
-6.12.1. rack_env <string>	=>	rack-env-string--tqmrt0
-
-# fuzzy
-6.13. Deprecated options	=>	deprecated-options-1dtzo0g
-
-# fuzzy
-6.13.1. rails_spawn_method	=>	rails-spawn-method-17vdnpt
-
-# fuzzy
 6.2. passenger_ruby <filename>	=>	passenger-ruby-filename--1gnok5k
 
-# fuzzy
 6.3. passenger_spawn_method <string>	=>	passenger-spawn-method-string--1sc6njl
 
-# fuzzy
 6.4. passenger_rolling_restarts <on|off>	=>	passenger-rolling-restarts
 
-# fuzzy
 6.5. passenger_resist_deployment_errors <on|off>	=>	passenger-resist-deployment-errors-on-off--k9yf1
 
-# fuzzy
 6.6. Important deployment options	=>	important-deployment-options-av567
 
-# fuzzy
 6.6.1. passenger_enabled <on|off>	=>	passenger-enabled-on-off--1rpb2t7
 
-# fuzzy
 6.6.2. passenger_base_uri <uri>	=>	passenger-base-uri-uri--1xtuo50
 
-# fuzzy
 6.7. Connection handling options	=>	connection-handling-options-8jgq90
 
-# fuzzy
 6.7.1. passenger_ignore_client_abort <on|off>	=>	passenger-ignore-client-abort
 
-# fuzzy
 6.7.2. passenger_set_cgi_param <CGI environment name> <value>	=>	passenger-set-cgi-param-cgi-environment-name-value--rx9gc0
 
-# fuzzy
 6.7.3. passenger_pass_header <header name>	=>	passenger-pass-header-header-name--1cg31je
 
-# fuzzy
 6.7.4. passenger_buffer_response <on|off>	=>	passenger-buffer-response
 
-# fuzzy
 6.7.5. passenger_buffer_size	=>	passenger-buffer-size-1jfkq87
 
-# fuzzy
 6.7.6. passenger_buffers	=>	passenger-busy-buffers
 
-# fuzzy
 6.7.7. passenger_busy_buffer_size	=>	passenger-busy-buffer-size-124sj61
 
-# fuzzy
 6.8. Security options	=>	security-options-1bv93g4
 
-# fuzzy
 6.8.1. passenger_user_switching <on|off>	=>	passenger-user-switching-on-off--1p37u3l
 
-# fuzzy
 6.8.2. passenger_user <username>	=>	passenger-user-username--b06ur7
 
-# fuzzy
 6.8.3. passenger_group <group name>	=>	passenger-user-group-name--1fco4j7
 
-# fuzzy
 6.8.4. passenger_default_user <username>	=>	passenger-default-user-username--1h6cdmf
 
-# fuzzy
 6.8.5. Passenger_default_group <group name>	=>	passenger-default-group-group-name--1qxn2qa
 
-# fuzzy
 6.8.6. passenger_friendly_error_pages <on|off>	=>	passenger-friendly-error-pages-on-off--1ti1a0e
 
-# fuzzy
 6.9. Resource control and optimization options	=>	resource-control-and-optimization-options-xd7evs
 
-# fuzzy
 6.9.1. passenger_max_pool_size <integer>	=>	passenger-max-pool-size-integer--3jzefs
 
-# fuzzy
-6.9.10. passenger_max_request_time <seconds>	=>	passenger-pre-start-url--1f2phk7
-
-# fuzzy
-6.9.11. passenger_memory_limit <integer>	=>	passenger-memory-limit-integer--1ry7dwx
-
-# fuzzy
-6.9.12. passenger_pre_start <url>	=>	passenger-pre-start-url--npldeb
-
-# fuzzy
 6.9.2. passenger_min_instances <integer>	=>	passenger-min-instances-integer--uclykt
 
-# fuzzy
 6.9.3. passenger_max_instances <integer>	=>	passenger-max-instances
 
-# fuzzy
 6.9.4. passenger_max_instances_per_app <integer>	=>	passenger-max-instances-per-app-integer--1xhbbne
 
-# fuzzy
 6.9.5. passenger_pool_idle_time <integer>	=>	passenger-pool-idle-time-integer--xcw65o
 
-# fuzzy
 6.9.6. passenger_max_preloader_idle_time <integer>	=>	rails-app-spawner-idle-time-integer--1xjqe4b
 
-# fuzzy
-6.9.7. passenger_concurrency_model <process|thread>	=>	passenger-max-requests
+6.9.7. passenger_concurrency_model <process|thread>	=>	passenger-concurrency-model-process-thread--brcvkk
 
-# fuzzy
-6.9.8. passenger_thread_count <number>	=>	passenger-max-request-time-seconds--1qod9kg
+6.9.8. passenger_thread_count <number>	=>	passenger-thread-count-number--1kd6ffy
 
-# fuzzy
 6.9.9. passenger_max_requests <integer>	=>	passenger-max-requests-integer--sgzint
 
-# fuzzy
+6.9.10. passenger_max_request_time <seconds>	=>	passenger-max-request-time-seconds--1htog2g
+
+6.9.11. passenger_memory_limit <integer>	=>	passenger-memory-limit-integer--1ry7dwx
+
+6.9.12. passenger_pre_start <url>	=>	passenger-pre-start-url--npldeb
+
+6.10. Logging and debugging options	=>	logging-and-debugging-options-14e91ni
+
+6.10.1. passenger_log_level <integer>	=>	passenger-log-level-integer--17snhon
+
+6.10.2. passenger_debug_log_file <filename>	=>	passenger-debug-log-file-filename--21ubaj
+
+6.10.3. passenger_debugger <on|off>	=>	passenger-debugger-on-off--1wkuq85
+
+6.11. Ruby on Rails-specific options	=>	ruby-on-rails-specific-options-12vfokt
+
+6.11.1. rails_env <string>	=>	rails-env-string--jlh7v9
+
+6.12. Rack and Rails >= 3 specific options	=>	rack-specific-options-13yvdxs
+
+6.12.1. rack_env <string>	=>	rack-env-string--tqmrt0
+
+6.13. Deprecated options	=>	deprecated-options-1dtzo0g
+
+6.13.1. rails_spawn_method	=>	rails-spawn-method-17vdnpt
+
 7. Analysis and system maintenance	=>	analysis-and-system-maintenance-1nnlnj8
 
-# fuzzy
 7.1. Inspecting memory usage	=>	inspecting-memory-usage-1k6y8v0
 
-# fuzzy
 7.2. Inspecting Phusion Passenger’s internal status	=>	inspecting-phusion-passenger-s-internal-status-v36wbc
 
-# fuzzy
 7.3. Debugging frozen applications	=>	debugging-frozen-applications-qoctl8
 
-# fuzzy
 7.4. Accessing individual application processes	=>	accessing-individual-application-processes-1qe4fqk
 
-# fuzzy
 7.5. Attaching an IRB console to an application process	=>	attaching-an-irb-console-to-an-application-process-d36enw
 
-# fuzzy
 8. Tips	=>	tips-n4c22d
 
-# fuzzy
 8.1. User switching (security)	=>	user-switching-security--zmsy9o
 
-# fuzzy
 8.2. Reducing memory consumption of Ruby on Rails applications by 33%	=>	reducing-memory-consumption-of-ruby-on-rails-applications-by-33--1o3z66q
 
-# fuzzy
 8.3. Capistrano recipe	=>	capistrano-recipe-pfn4qu
 
-# fuzzy
 8.4. Bundler support	=>	bundler-support-19v1h43
 
-# fuzzy
 8.5. Moving Phusion Passenger to a different directory	=>	moving-phusion-passenger-to-a-different-directory-1hel5cp
 
-# fuzzy
 8.6. Installing multiple Ruby on Rails versions	=>	installing-multiple-ruby-on-rails-versions-1bp1fff
 
-# fuzzy
 8.7. Making the application restart after each request	=>	making-the-application-restart-after-each-request-vimy48
 
-# fuzzy
 8.8. How to fix broken images/CSS/JavaScript URIs in sub-URI deployments	=>	how-to-fix-broken-images-css-javascript-uris-in-sub-uri-deployments-11mzwt6
 
-# fuzzy
+8.9. Out-of-Band Garbage Work and Out-of-Band Garbage Collection	=>	out-of-band-garbage-work-and-out-of-band-garbage-collection-v89lu2
+
 9. Under the hood	=>	under-the-hood-8uney
 
-# fuzzy
 9.1. Page caching support	=>	page-caching-support-nafhf6
 
-# fuzzy
 9.2. How Phusion Passenger detects whether a virtual host is a web application	=>	how-phusion-passenger-detects-whether-a-virtual-host-is-a-web-application-13qbmhn
 
+10. Appendix A: About this document	=>	appendix-a-about-this-document-zfvixm
+
+11. Appendix B: Terminology	=>	appendix-b-terminology-wzv5ro
+
+11.1. Application root	=>	application-root-1fd6bqv
+
+11.2. Idle process	=>	idle-process-13byfw9
+
+11.3. Inactive process	=>	inactive-process-1d2h0po
+
+12. Appendix C: Spawning methods explained	=>	appendix-c-spawning-methods-explained-tcp8e6
+
+12.1. The most straightforward and traditional way: direct spawning	=>	the-most-straightforward-and-traditional-way-conservative-spawning-civ29z
+
+12.2. The smart spawning method	=>	the-smart-spawning-method-7nhgtj
+
+12.2.1. How it works	=>	how-it-works-f9umga
+
+12.2.2. Summary of benefits	=>	summary-of-benefits-qovyvk
+
+12.3. Smart spawning gotcha #1: unintentional file descriptor sharing	=>	smart-spawning-gotcha-1-unintentional-file-descriptor-sharing-cebw6q
+
+12.3.1. Example 1: Memcached connection sharing (harmful)	=>	example-1-memcached-connection-sharing-harmful--1wfs3ad
+
+12.3.2. Example 2: Log file sharing (not harmful)	=>	example-2-log-file-sharing-not-harmful--ox4yfy
+
+12.4. Smart spawning gotcha #2: the need to revive threads	=>	smart-spawning-gotcha-2-the-need-to-revive-threads-1ey176o
+
+12.5. Smart spawning gotcha #3: code load order	=>	smart-spawning-gotcha-3-code-load-order-12ydsn8
+

data/doc/Users guide Nginx.txt

@@ -17,240 +17,13 @@ This guide assumes that the reader is somewhat familiar with Nginx and with
 using the command line.
 
 
-== Support information ==
+== Support information
 
 include::users_guide_snippets/support_information.txt[]
 
+== Installation
 
-== Installing Phusion Passenger ==
-
-=== Overview ===
-
-As you might already know, Nginx does not support loadable modules, in contrast
-to most other web servers (e.g. Apache). Therefore, to install Phusion Passenger
-for Nginx, one must recompile and reinstall Nginx with Phusion Passenger support.
-There are two ways to do this:
-
-1. By running the Phusion Passenger installer for Nginx. This installer will
-   guide you through the entire installation process, including downloading,
-   compiling and installing Nginx. You should be able to get Nginx with Phusion
-   Passenger support up-and-running in a matter of minutes. This is the
-   recommended installation method.
-2. By manually configuring and compiling Nginx with Phusion Passenger support,
-   through Nginx's `--add-module` configure option. Generally, using our
-   installer is easier, so you should only use this method if you're already
-   familiar with compiling Nginx.
-
-TIP: You might have to run the installation commands in the following sections
-as 'root'. If the installer fails because of permission errors, it will tell
-you.
-
-[[specifying_ruby_installation]]
-=== Specifying the correct Ruby installation ===
-
-If your system has multiple Ruby installations -- which is likely the case on
-MacOS X, or if you've also installed
-link:http://www.rubyenterpriseedition.com[Ruby Enterprise Edition] -- then you
-will need to tell the operating system which Ruby installation to use, prior to
-running the Phusion Passenger installer. If you only have one Ruby installation
-(the case on most Linux systems), then you can skip this section because Phusion
-Passenger will automatically detect it.
-
-To specify a Ruby installation, prepend your Ruby installation's `bin`
-directory to the `PATH` environment variable. For example, if you have the
-following Ruby installations:
-
-- /usr/bin/ruby
-- /opt/myruby/bin/ruby
-
-and you want to use the latter, then type:
-
-----------------------------------
-export PATH=/opt/myruby/bin:$PATH
-----------------------------------
-
-=== Installing Phusion Passenger for Nginx through the installer ===
-
-==== Obtaining the Phusion Passenger files and running the installer ====
-
-You must obtain the Phusion Passenger files in order to run the installer.
-This can be done either by installing the Phusion Passenger gem, or by
-downloading the source tarball.
-
-===== Gem =====
-
-First, install the Phusion Passenger gem by running:
-
----------------------------------
-gem install passenger
----------------------------------
-
-Next, run the Phusion Passenger installer for Nginx:
-
----------------------------------
-passenger-install-nginx-module
----------------------------------
-
-Please follow the instructions given by the installer.
-
-===== Source tarball =====
-
-The source tarball can be download from the
-link:http://www.modrails.com/[Phusion Passenger website]. Extract the tarball to
-whatever location you prefer. *The Phusion Passenger files are to reside in that
-location permanently.* For example, if you would like Phusion Passenger to
-reside in `/opt/passenger-x.x.x`, then type:
-
---------------------------------------------------------------
-cd /opt
-tar xzvf ~/YourDownloadsFolder/passenger-x.x.x.tar.gz
---------------------------------------------------------------
-
-Next, run the Phusion Passenger installer for Nginx:
-
---------------------------------------------------------------
-/opt/passenger-x.x.x/bin/passenger-install-nginx-module
---------------------------------------------------------------
-
-Please follow the instructions given by the installer.
-
-IMPORTANT: Please do not remove the passenger-x.x.x folder after installation.
-Furthermore, the passenger-x.x.x folder must be accessible by Nginx.
-
-==== Non-interactive/automatic installation ====
-
-By default, the installer is interactive. If you want to automate installation,
-then you can do so by passing various answers to the installer through command
-line options.
-
-Please run the installer with `--help` for a list of available command line
-options.
-
-=== Installing Phusion Passenger for Nginx manually ===
-
-You can also install Phusion Passenger the way you install any other Nginx module.
-To do this, run Nginx's configure script with `--add-module=/path-to-passenger-root/ext/nginx`.
-
-If you installed Phusion Passenger via the gem, then 'path-to-passenger-root'
-can be obtained with the command:
-
---------------------------
-passenger-config --root
---------------------------
-
-This will probably output something along the lines of '/usr/lib/ruby/gems/1.8/gems/passenger-x.x.x',
-so you'll probably have to specify something like `--add-module=/usr/lib/ruby/gems/1.8/gems/passenger-x.x.x/ext/nginx`.
-
-If you installed Phusion Passenger via a source tarball, then 'path-to-passenger-root'
-is the directory which contains the Phusion Passenger source code. So if you
-extracted the Phusion Passenger source code to '/opt/passenger-x.x.x', then you'll
-have to specify `--add-module=/opt/passenger-x.x.x/ext/nginx`.
-
-After having installed Nginx with Phusion Passenger support, you must paste the following
-line into your Nginx configuration file:
-
-------------------------------------------
-passenger_root /path-to-passenger-root;
-------------------------------------------
-
-After having done so, restart Nginx.
-
-=== Upgrading or downgrading Phusion Passenger or Nginx itself ===
-
-Whether you're upgrading/downgrading Phusion Passenger or Nginx itself (or perhaps both),
-Nginx will have to be recompiled and reinstalled. The procedure is exactly the same as
-a normal installation so just follow the instructions in section 2.3 or 2.4.
-
-When following the installation instructions, eventually `passenger-install-nginx-module`
-or this document will instruct you to copy & paste some settings into the Nginx
-configuration file; something that looks along the lines of:
-
-------------------------------------------
-passenger_root ...;
-passenger_ruby ...;
-------------------------------------------
-
-Because you already had Phusion Passenger installed, you already had similar settings
-in your Nginx configuration file, just with different values. *Replace* the old settings with
-the new ones that you are instructed to paste. It is important that the old settings are
-removed, otherwise Phusion Passenger may malfunction.
-
-When you're done, restart Nginx.
-
-=== Unloading (disabling) Phusion Passenger from Nginx without uninstalling it ===
-
-You can temporarily unload (disable) Phusion Passenger from Nginx, without
-uninstalling the Phusion Passenger files, so that Nginx behaves as if Phusion
-Passenger was never installed in the first place. This might be useful to you if,
-for example, you seem to be experiencing a problem caused by Phusion Passenger,
-but you want to make sure whether that's actually the case, without having
-to go through the hassle of uninstalling Phusion Passenger completely. When disabled,
-Phusion Passenger will not occupy any memory or CPU or otherwise interfere with
-Nginx.
-
-To unload Phusion Passenger, edit your Nginx configuration file(s)
-and comment out all Phusion Passenger configuration directives.
-
-For example, if your configuration file looks like this...
-
------------------------------------
-...
-
-http {
-    passenger_root /somewhere/passenger-x.x.x;
-    passenger_ruby /usr/bin/ruby;
-    passenger_max_pool_size 10;
-
-    gzip on;
-
-    server {
-        server_name www.foo.com;
-        listen 80;
-        root /webapps/foo/public;
-        passenger_enabled on;
-    }
-}
------------------------------------
-
-...then comment out the relevant directives, so that it looks like this:
-
------------------------------------
-...
-
-http {
-    # passenger_root /somewhere/passenger-x.x.x;
-    # passenger_ruby /usr/bin/ruby;
-    # passenger_max_pool_size 10;
-
-    gzip on;
-
-    server {
-        server_name www.foo.com;
-        listen 80;
-        root /webapps/foo/public;
-        # passenger_enabled on;
-        # passenger_use_global_queue on;
-    }
-}
------------------------------------
-
-After you've done this, save the file and restart Nginx.
-
-=== Uninstalling Phusion Passenger ===
-
-To uninstall Phusion Passenger, please first remove all Phusion Passenger
-configuration directives from your Nginx configuration file(s). After you've
-done this, you need to remove the Phusion Passenger files.
-
-- If you installed Phusion Passenger via a gem, then type `gem uninstall passenger`.
-  You might have to run this as root.
-- If you installed Phusion Passenger via a source tarball, then remove the directory
-  in which you placed the extracted Phusion Passenger files. This directory is the
-  same as the one pointed to the by 'PassengerRoot' configuration directive.
-
-After having done so, recompile and reinstall Nginx itself, this time without
-Phusion Passenger support, in order to purge any Phusion Passenger code from the
-Nginx binary.
+include::users_guide_snippets/installation.txt[]
 
 
 [[deploying_a_ror_app]]
@@ -606,7 +379,7 @@ $ some_awesome_editor passenger_wsgi.py
 ...type in some source code...
 $ cat passenger_wsgi.py
 def application(environ, start_response):
-  start_response(200, [('Content-Type', 'text/plain')])
+  start_response('200 OK', [('Content-Type', 'text/plain')])
   return ["hello world!\n"]
 -------------------------------------------
 
@@ -901,19 +674,30 @@ This option may occur in the following places:
  * In an 'if' configuration scope.
 
 ==== passenger_buffer_response <on|off> ====
-When turned on, application-generated responses are buffered in memory and also on
-disk if the response is larger than a certain threshold. By buffering responses,
-protection is provided against slow HTTP clients that can not read your response
-immediately.
-
-For example, consider an HTTP client that's on a dial-up modem link, and your
-application process generates a 2 MB response. If response buffering is turned
-off then your application process will be blocked until the entire 2 MB has been
+When turned on, application-generated responses are buffered by Nginx. Buffering will
+happen in memory and also on disk if the response is larger than a certain threshold.
+
+Before we proceed with explaining this configuration option, we want to state the following to avoid confusion. If you use Phusion Passenger for Nginx, there are in fact two response buffering systems active:
+
+1. The Nginx response buffering system. `passenger_buffer_response` turns this on or off.
+2. The Phusion Passenger response buffering system, a.k.a. 'real-time disk-backed response buffering'. This buffering system is always on, regardless of the value of `passenger_buffer_response`.
+
+Response buffering is useful because it protects against slow HTTP clients that do not read responses immediately or quickly enough. Buffering prevents such slow clients from blocking web applications that have limited concurrency. Because Phusion Passenger's response buffering is always turned on, you are always protected. Therefore, `passenger_buffer_response` is off by default, and you never should have to turn it on.
+
+If for whatever reason you want to turn Nginx-level response buffering on, you can do so with this option.
+
+Nginx's response buffering works differently from Phusion Passenger's. Nginx's buffering system buffers the entire response before attempting to send it to the client, while Phusion Passenger's attempts to send the data to the client immediately. Therefore, if you turn on `passenger_buffer_response`, you may interfere with applications that want to stream responses to the client.
+
+How does response buffering - whether it's done by Nginx or by Phusion Passenger - exactly protect against slow clients?
+Consider an HTTP client that's on a dial-up modem link, and your
+application process generates a 2 MB response. If the response is buffered
+then your application process will be blocked until the entire 2 MB has been
 sent out to the HTTP client. This disallows your application process to do any useful
-work in the mean time. By enabling response buffering, Phusion Passenger will read
-the application response as quickly as possible and will take care of slow clients.
+work in the mean time. By buffering responses, Phusion Passenger or Nginx will read
+the application response as quickly as possible and will take care of forwarding the data
+to slow clients.
 
-However, keep in mind that enabling this option will make streaming responses
+So keep in mind that enabling `passenger_buffering_response` will make streaming responses
 impossible. Consider for example this piece of Rails code:
 
 --------------------------------
@@ -943,11 +727,11 @@ app = lambda do |env|
 end
 --------------------------------
 
-When response buffering is turned on, Phusion Passenger will wait until
+When `passenger_buffer_response` is turned on, Nginx will wait until
 the application is done sending the entire response before forwarding it
 to the client. The client will not receive anything for 10 seconds,
 after which it receives the entire response at once.
-When response buffering is turned off, it works as expected: the client
+When `passenger_buffer_response` is turned off, it works as expected: the client
 receives an "entry X" message every second for 10 seconds.
 
 This option may occur in the following places:
@@ -957,7 +741,7 @@ This option may occur in the following places:
  * In a 'location' configuration block.
  * In an 'if' configuration scope.
 
-In each place, it may be specified at most once. The default value is 'on'.
+In each place, it may be specified at most once. The default value is 'off'.
 
 ==== passenger_buffer_size ====
 ==== passenger_buffers ====