passenger 4.0.60 → 5.0.0.beta1

data/doc/Users guide Nginx.txt

@@ -1,4 +1,5 @@
-= Phusion Passenger users guide, Nginx version =
+Phusion Passenger users guide, Nginx version
+============================================
 
 image:images/phusion_banner.png[link="http://www.phusion.nl/"]
 
@@ -27,139 +28,8 @@ include::users_guide_snippets/support_information.txt[]
 include::users_guide_snippets/installation.txt[]
 
 
-[[deploying_a_ror_app]]
-== Deploying a Ruby on Rails 1.x or 2.x (but NOT Rails >= 3) application ==
-
-Suppose you have a Ruby on Rails application in '/webapps/mycook', and you own
-the domain 'www.mycook.com'. You can either deploy your application to the
-virtual host's root (i.e. the application will be accessible from the root URL,
-'http://www.mycook.com/'), or in a sub URI (i.e. the application will be
-accessible from a sub URL, such as 'http://www.mycook.com/railsapplication').
-
-NOTE: The default `RAILS_ENV` environment in which deployed Rails applications
-are run, is ``production''. You can change this by changing the
-<<RailsEnv,rails_env>> configuration option.
-
-=== Deploying to a virtual host's root ===
-
-Add a 'server' virtual host entry to your Nginx configuration file. The virtual
-host's root must point to your Ruby on Rails application's 'public' folder.
-
-Inside the 'server' block, set 'passenger_enabled on'.
-
-For example:
--------------------------------------------
-http {
-    ...
-
-    server {
-        listen 80;
-        server_name www.mycook.com;
-        root /webapps/mycook/public;
-        passenger_enabled on;
-    }
-
-    ...
-}
--------------------------------------------
-Then restart Nginx. The application has now been deployed.
-
-[[deploying_rails_to_sub_uri]]
-=== Deploying to a sub URI ===
-
-Suppose that you already have a virtual host for the application `/websites/phusion`:
-
--------------------------------------------
-http {
-    ...
-
-    server {
-        listen 80;
-        server_name www.phusion.nl;
-        root /websites/phusion;
-        passenger_enabled on;
-    }
-
-    ...
-}
--------------------------------------------
-
-And you want your Rails application, located in `/websites/rails`, to be accessible from the URL
-'http://www.phusion.nl/subapp'.
-
-To do this, you need to perform the following:
-
- 1. Create a `location` with parameter `~ ^/<SUBURI>(/.*|$)`. This is a regular expression that says: "match everything that is exactly <SUBURI>, or starts with <SUBDURI>/".
- 2. Inside the location block, set `alias <PATH TO YOUR APPLICATION'S PUBLIC DIRECTORY>$1`.
- 3. Inside the location block, set `passenger_base_uri <SUBURI>`.
- 4. Inside the location block, set `passenger_app_root <PATH TO YOUR APPLICATION ROOT>`.
- 5. Inside the location block, set `passenger_document_root <PATH TO YOUR APPLICATION'S PUBLIC DIRECTORY>`.
- 6. Inside the location block, re-specify `passenger_enabled on`.
-
-Here is an example:
-
--------------------------------------------
-http {
-    ...
-
-    server {
-        listen 80;
-        server_name www.phusion.nl;
-        root /websites/phusion;
-
-        # This block has been added.
-        location ~ ^/subapp(/.*|$) {
-            alias /websites/rails/public$1;  # <-- be sure to point to 'public'!
-            passenger_base_uri /subapp;
-            passenger_app_root /websites/rails;
-            passenger_document_root /websites/rails/public;
-            passenger_enabled on;
-        }
-    }
-
-    ...
-}
--------------------------------------------
-
-Then restart Nginx. The application has now been deployed on the sub-URI.
-
-=== Redeploying (restarting the Ruby on Rails application) ===
-
-Deploying a new version of a Ruby on Rails application is as simple as
-re-uploading the application files, and restarting the application.
-
-There are two ways to restart the application:
-
-1. By restarting Nginx.
-2. By creating or modifying the file 'tmp/restart.txt' in the Rails
-   application's <<application_root,root folder>>. Phusion Passenger will
-   automatically restart the application during the next request.
-
-For example, to restart our example MyCook application, we type this in the
-command line:
--------------------------------------------
-touch /webapps/mycook/tmp/restart.txt
--------------------------------------------
-
-Please note that, unlike earlier versions of Phusion Passenger, 'restart.txt'
-is not automatically deleted. Phusion Passenger checks whether the timestamp
-of this file has changed in order to determine whether the application should
-be restarted.
-
-=== Migrations ===
-
-Phusion Passenger is not related to Ruby on Rails migrations in any way. To
-run migrations on your deployment server, please login to your deployment
-server (e.g. with 'ssh') and type `rake db:migrate RAILS_ENV=production` in
-a shell console, just like one would normally run migrations.
-
-=== Capistrano integration ===
-
-See <<capistrano,Capistrano recipe>>.
-
-
 [[deploying_a_rack_app]]
-== Deploying a Rack-based Ruby application (including Rails >= 3) ==
+== Deploying a Rack-based Ruby application ==
 
 Phusion Passenger supports arbitrary Ruby web applications that follow the
 link:http://rack.rubyforge.org/[Rack] interface.
@@ -560,21 +430,31 @@ Please see <<deploying_a_rack_app,Deploying a Rack-based Ruby application>>
 and <<deploying_a_wsgi_app,Deploying a WSGI (Python) application>>
 for examples.
 
-When using `location` blocks, you must re-specify `passenger_enabled` in each `location` block that you want to enable Phusion Passenger. This is because each `location` block has `passenger_enabled` turned off by default. For example:
+.This configuration option is NOT inherited across contexts
+[WARNING]
+===============================================
+In each new context (e.g. in each new 'location' block), you must re-specify `passenger_enabled`. Values set in parent contexts have no effect on subcontexts. For example:
 
-----------------------------
+------------------------------
 server {
-    listen 80;
-    server_name www.foo.com;
-    root /webapps/foo/public;
+    ...
     passenger_enabled on;
 
-    location /attachments {
-        # Re-specify passenger_enabled here!
+    location /users {
+        passenger_set_header X-Foo bar;
+        # !!!THIS IS WRONG!!! We did not re-specify 'passenger_enabled on'
+        # here, so Phusion Passenger will not handle requests that begin with
+        # /users.
+    }
+
+    location /apps {
         passenger_enabled on;
+        passenger_set_header X-Foo bar;
+        # This is correct. Here we re-specify 'passenger_enabled'.
     }
 }
-----------------------------
+------------------------------
+===============================================
 
 [[PassengerBaseURI]]
 ==== passenger_base_uri <uri>
@@ -718,6 +598,8 @@ Phusion Passenger for Nginx sets the default value to **production**. If you're
 
 If you want to set other environment variables, please refer to <<env_vars_passenger_apps,Setting environment variables for Phusion Passenger-served apps>>.
 
+Setting this option also adds the application environment name to the default <<PassengerAppGroupName,application group name>>, so that you can run multiple versions of your application with different application environment names.
+
 This option may occur in the following places:
 
  * In the 'http' configuration block.
@@ -767,6 +649,90 @@ server {
 }
 -----------------------------
 
+[[PassengerAppGroupName]]
+==== passenger_app_group_name <name>
+Sets the name of the application group that the current application should belong to. Its default value is the virtual host's root directory, plus (if it is set), the <<PassengerAppEnv,application environment name>>.
+
+Phusion Passenger stores and caches most application spawning settings -- such as environment variables, process limits, etc -- on a per-app-group-name basis. This means that if you want to start two versions of your application, with each version having different environment variables, then you must assign them under different application group names.
+
+For example, consider a situation in which you are running multiple versions of the same app, with each version intended for a different customer. You use the `CUSTOMER_NAME` environment variable to tell the app which customer that version should serve.
+
+------------------------------------
+# WRONG example! Doesn't work!
+
+server {
+    listen 80;
+    server_name customer1.foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+    passenger_env_var CUSTOMER_NAME customer1;
+}
+
+server {
+    listen 80;
+    server_name customer2.foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+    passenger_env_var CUSTOMER_NAME customer2;
+}
+------------------------------------
+
+This example doesn't work, because Phusion Passenger thinks that they are the same application. When a user visits customer1.foo.com, Phusion Passenger will start a process with `CUSTOMER_NAME=customer1`. When another user visits customer2.foo.com, Phusion Passenger will route the request to the application process that was started earlier. Because environment variables are only set during application process startup, the second user will be served the website for customer 1.
+
+To make this work, assign unique application group names:
+
+------------------------------------
+server {
+    listen 80;
+    server_name customer1.foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+    passenger_env_var CUSTOMER_NAME customer1;
+    passenger_app_group_name foo_customer1;
+}
+
+server {
+    listen 80;
+    server_name customer2.foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+    passenger_env_var CUSTOMER_NAME customer2;
+    passenger_app_group_name foo_customer2;
+}
+------------------------------------
+
+Note that it is not necessary to set `passenger_app_group_name` if you want to run two versions of your application under different <<PassengerAppEnv,application environment names>>, because the application environment name is included in the default application group name. For example, consider a situation in which you want to run a production and a staging version of your application. The following configuration will work fine:
+
+------------------------------------
+server {
+    listen 80;
+    server_name bar.com;
+    root /webapps/bar/public;
+    passenger_enabled on;
+    # Phusion Passenger implicitly sets:
+    # passenger_app_group_name /webapps/bar/public;
+}
+
+server {
+    listen 80;
+    server_name staging.com;
+    root /webapps/bar/public;
+    passenger_enabled on;
+    passenger_app_env staging;
+    # Phusion Passenger implicitly sets:
+    # passenger_app_group_name '/webapps/bar/public (staging)';
+}
+------------------------------------
+
+This option may occur in the following places:
+
+ * In the 'http' configuration block.
+ * In a 'server' configuration block.
+ * In a 'location' configuration block.
+ * In an 'if' configuration scope.
+
+In each place, it may be specified at most once.
+
 [[PassengerAppType]]
 ==== passenger_app_type <name>
 :version: 4.0.25
@@ -776,8 +742,7 @@ By default, Phusion Passenger autodetects the type of the application, e.g. whet
 
 Allowed values are:
 
- * `rack` - Ruby on Rails >= 3.0 and Ruby Rack
- * `classic-rails` - Ruby on Rails 1.x and 2.0
+ * `rack` - Ruby and Rails
  * `wsgi` - Python
  * `node` - Node.js, or Meteor JS in bundled mode
  * `meteor` - Meteor JS in non-bundled mode
@@ -885,6 +850,35 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once. The default value is 'smart'.
 
+[[PassengerEnvVar]]
+==== passenger_env_var <name> <value>
+:version: 5.0.0
+include::users_guide_snippets/since_version.txt[]
+
+Sets environment variables to pass to the application. Environment variables are only set during application loading.
+
+Example:
+
+-------------------------
+server {
+    server_name www.foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+
+    passenger_env_var DATABASE_USERNAME foo_db;
+    passenger_env_var DATABASE_PASSWORD secret;
+}
+-------------------------
+
+This option may occur in the following places:
+
+ * In the 'http' configuration block.
+ * In a 'server' configuration block.
+ * In a 'location' configuration block.
+ * In an 'if' configuration scope.
+
+In each place, it may be specified multiple times.
+
 [[PassengerLoadShellEnvvars]]
 ==== passenger_load_shell_envvars <on|off>
 :version: 4.0.20
@@ -1064,14 +1058,8 @@ Server: nginx/1.3.11 + Phusion Passenger
 X-Powered-By: Phusion Passenger
 ----------------------------------------------------
 
-This option may occur in the following places:
-
- * In the 'http' configuration block.
- * In a 'server' configuration block.
- * 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'.
+This option may only occur once, in the 'http' configuration block.
+The default value is 'on'.
 
 [[PassengerFriendlyErrorPages]]
 ==== passenger_friendly_error_pages <on|off> ====
@@ -1291,11 +1279,13 @@ In each place, it may be specified at most once. The default value is '90'.
 :version: 4.0.0
 include::users_guide_snippets/enterprise_only.txt[]
 
-Specifies the I/O concurrency model that should be used for application processes. Phusion Passenger supports two concurrency models:
+Specifies the I/O concurrency model that should be used for Ruby application processes. Phusion Passenger supports two concurrency models:
 
  * 'process' - single-threaded, multi-processed I/O concurrency. Each application process only has a single thread and can only handle 1 request at a time. This is the concurrency model that Ruby applications traditionally used. It has excellent compatiblity (can work with applications that are not designed to be thread-safe) but is unsuitable for workloads in which the application has to wait for a lot of external I/O (e.g. HTTP API calls), and uses more memory because each process has a large memory overhead.
  * 'thread' - multi-threaded, multi-processed I/O concurrency. Each application process has multiple threads (customizable via <<PassengerThreadCount,passenger_thread_count>>). This model provides much better I/O concurrency and uses less memory because threads share memory with each other within the same process. However, using this model may cause compatibility problems if the application is not designed to be thread-safe.
 
+This option has no effect on non-Ruby applications.
+
 This option may occur in the following places:
 
  * In the 'http' configuration block.
@@ -1310,7 +1300,9 @@ In each place, it may be specified at most once. The default value is 'process'.
 :version: 4.0.0
 include::users_guide_snippets/enterprise_only.txt[]
 
-Specifies the number of threads that Phusion Passenger should spawn per application process. This option only has effect if <<PassengerConcurrencyModel,passenger_concurrency_model>> is 'thread'.
+Specifies the number of threads that Phusion Passenger should spawn per Ruby application process. This option only has effect if <<PassengerConcurrencyModel,passenger_concurrency_model>> is 'thread'.
+
+This option has no effect on non-Ruby applications.
 
 This option may occur in the following places:
 
@@ -1446,6 +1438,27 @@ problem in your application rather than relying on these directives as a
 measure to avoid memory leaks.
 =====================================================
 
+==== passenger_stat_throttle_rate <integer> ====
+By default, Phusion Passenger performs several filesystem checks (or, in
+programmers jargon, 'stat() calls') each time a request is processed:
+
+- It checks which the application <<PassengerStartupFile,startup files>> are present, in order to autodetect the application type.
+- It checks whether 'restart.txt' has changed or whether 'always_restart.txt'
+  exists, in order to determine whether the application should be restarted.
+
+On some systems where disk I/O is expensive, e.g. systems where the harddisk is
+already being heavily loaded, or systems where applications are stored on NFS
+shares, these filesystem checks can incur a lot of overhead.
+
+You can decrease or almost entirely eliminate this overhead by setting
+'PassengerStatThrottleRate'. Setting this option to a value of 'x' means that
+the above list of filesystem checks will be performed at most once every 'x'
+seconds. Setting it to a value of '0' means that no throttling will take place,
+or in other words, that the above list of filesystem checks will be performed on
+every request.
+
+This option may be specified once, in the `http` configuration block. The default value is '10'.
+
 [[PassengerPreStart]]
 ==== passenger_pre_start <url> ====
 By default, Phusion Passenger does not start any application processes until said
@@ -1641,65 +1654,46 @@ Yes. And it does not perform any certificate validation.
 
 === Connection handling options ===
 
-[[passenger_set_cgi_param]]
-==== passenger_set_cgi_param <CGI environment name> <value> ====
-Allows one to define additional CGI environment variables to pass to the web
-application. This is comparable to ngx_http_fastcgi_module's 'fastcgi_param'
-directive, and to ngx_http_proxy_module's 'proxy_set_header' option.
-Nginx variables in the value are interpolated.
-
-These variables passed in the following manner:
-
- * On every request, in the form of a request variable.
- * During application spawning, in the form of a system environment variable that can be looked up through `getenv()`.
-
-Example usage:
-------------------------------
-# Application will see a CGI environment "APP_NAME" with value "my super blog".
-passenger_set_cgi_param APP_NAME "my super blog";
-
-# Nginx variables are interpolated.
-passenger_set_cgi_param EXTRA_REQUEST_METHOD method=$request_method;
-------------------------------
+[[PassengerSetHeader]]
+==== passenger_set_header <HTTP header name> <value> ====
+Sets additional HTTP headers to pass to the web application. This is comparable to ngx_http_proxy_module's 'proxy_set_header' option. Nginx variables in the value are interpolated.
 
-.Use CGI environment names
-[NOTE]
-===============================================
-If you want to set an HTTP header, then you must set it in the CGI environment name
-format, i.e. 'HTTP_*':
+Example:
 
-------------------------------
-# !!!THIS IS WRONG!!! Don't do this!
-passenger_set_cgi_param X-Forwarded-For 127.0.0.2;
+-------------------------
+server {
+    server_name www.foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
 
-# Instead, write it like this:
-passenger_set_cgi_param HTTP_X_FORWARDED_FOR 127.0.0.2;
-------------------------------
-===============================================
+    passenger_set_header X-Power-Level 9000;
+    passenger_set_header X-Forwarded-For internal-router.foo.com;
+}
+-------------------------
 
 .This configuration option is NOT inherited across contexts
 [WARNING]
 ===============================================
-In each new context (e.g. in each new 'location' block), you must re-specify `passenger_set_cgi_param`. Values set in parent contexts have no effect on subcontexts. For example:
+In each new context (e.g. in each new 'location' block), you must re-specify `passenger_set_header`. Values set in parent contexts have no effect on subcontexts. For example:
 
 ------------------------------
 server {
     ...
-    passenger_set_cgi_param FOO foo;
+    passenger_set_header X-Foo foo;
 
     location /users {
-        passenger_enabled_on;
-        # !!!THIS IS WRONG!!! The 'FOO' CGI variable will not
-        # be passed URLs beginning with /users because you didn't
-        # re-specify passenger_set_cgi_param.
+        passenger_enabled on;
+        # !!!THIS IS WRONG!!! The 'X-Foo' header will not
+        # be passed URLs beginning with /users because we didn't
+        # re-specify passenger_set_header.
     }
 
     location /apps {
         passenger_enabled on;
-        # This is correct. Here we re-specify passenger_set_cgi_param,
-        # so the 'FOO' CGI variable will be correctly passed to URLs
+        # This is correct. Here we re-specify passenger_set_header,
+        # so the 'X-Foo' header will be correctly passed to URLs
         # starting with /apps.
-        passenger_set_cgi_param FOO foo;
+        passenger_set_header X-Foo foo;
     }
 }
 ------------------------------
@@ -1711,6 +1705,8 @@ 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 multiple times.
+
 [[passenger_max_request_queue_size]]
 ==== passenger_max_request_queue_size <number> ====
 :version: 4.0.15
@@ -1871,6 +1867,30 @@ This option may occur in the following places:
  * In a 'location' configuration block.
  * In an 'if' configuration scope.
 
+==== passenger_headers_hash_bucket_size <size> ====
+Sets the bucket size of the hash tables used by the <<PassengerSetHeader,passenger_set_header>> directive. The details of setting up hash tables are can be found in link:http://nginx.org/en/docs/hash.html[the Nginx documentation].
+
+This option may occur in the following places:
+
+ * In the 'http' configuration block.
+ * In a 'server' configuration block.
+ * In a 'location' configuration block.
+ * In an 'if' configuration scope.
+
+In each place, it may be specified at most once. The default value is '64'.
+
+==== passenger_headers_hash_max_size <size> ====
+Sets the maximum size of the hash tables used by the <<PassengerSetHeader,passenger_set_header>> directive. The details of setting up hash tables are can be found in link:http://nginx.org/en/docs/hash.html[the Nginx documentation].
+
+This option may occur in the following places:
+
+ * In the 'http' configuration block.
+ * In a 'server' configuration block.
+ * In a 'location' configuration block.
+ * In an 'if' configuration scope.
+
+In each place, it may be specified at most once. The default value is '512'.
+
 ==== passenger_buffer_response <on|off> ====
 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.
@@ -1958,15 +1978,16 @@ information will be logged.
 
 Possible values are:
 
-- '0': Show only errors and warnings.
-- '1': Show the most important debugging information. This might be useful for
-       system administrators who are trying to figure out the cause of a
-       problem.
-- '2': Show more debugging information. This is typically only useful for developers.
-- '3': Show even more debugging information.
+- '0' (crit): Show only critical errors which would cause Phusion Passenger to abort.
+- '1' (error): Also show non-critical errors -- errors that do not cause Phusion Passenger to abort.
+- '2' (warn): Also show warnings. These are not errors, and Phusion Passenger continues to operate correctly, but they might be an indication that something is wrong with the system.
+- '3' (notice): Also show important informational messages. These give you a high-level overview of what Phusion Passenger is doing.
+- '4' (info): Also show less important informational messages. These messages show more details about what Phusion Passenger is doing. They're high-level enough to be readable by users.
+- '5' (debug): Also show the most important debugging information. Reading this information requires some system or programming knowledge, but the information shown is typically high-level enough to be understood by experienced system administrators.
+- '6' (debug2): Show more debugging information. This is typically only useful for developers.
+- '7' (debug3): Show even more debugging information.
 
-This option may only occur once, in the 'http' configuration block.
-The default is '0'.
+This option may only occur once, in the 'http' configuration block. The default is '3'.
 
 ==== passenger_debug_log_file <filename> ====
 By default Phusion Passenger debugging and error messages are written to the global
@@ -2007,36 +2028,57 @@ In each place, it may be specified at most once. The default value is 'off'.
 
 === Advanced options
 
-[[PassengerTempDir]]
-==== passenger_temp_dir <directory>
-Specifies the directory that Phusion Passenger should use for storing temporary
-files. This includes things such as Unix socket files.
+[[PassengerInstanceRegistryDir]]
+==== passenger_instance_registry_dir <directory>
+:version: 5.0.0
+include::users_guide_snippets/since_version.txt[]
 
-This option may only be specified in the 'http' configuration block. The
-default temp directory that Phusion Passenger uses is '/tmp'.
+Specifies the directory that Phusion Passenger should use for registering its current instance.
 
-This option is especially useful if Nginx is not allowed to write to /tmp
-(which is the case on some systems with strict SELinux policies) or if the
-partition that /tmp lives on doesn't have enough disk space.
+When Phusion Passenger starts up, it creates a temporary directory inside the 'instance registry directory'. This temporary directory is called the 'instance directory'. It contains all sorts of files that are important to that specific running Phusion Passenger instance, such as Unix domain socket files so that all the different Phusion Passenger processes can communicate with each other. Command line tools such as `passenger-status` use the files in this directory in order to query Phusion Passenger's status.
 
-.Command line tools
-Some Phusion Passenger command line administration tools, such as
-`passenger-status`, must know what Phusion Passenger's temp directory is
-in order to function properly. You can pass the directory through the
-`PASSENGER_TMPDIR` environment variable, or the `TMPDIR` environment variable
-(the former will be used if both are specified).
+It is therefore important that, while Phusion Passenger is working, the instance directory is never removed or tampered with. However, the default path for the instance registry directory is the system's temporary directory, and some systems may run background jobs that periodically clean this directory. If this happens, and the files inside the instance directory are removed, then it will cause Phusion Passenger to malfunction: Phusion Passenger won't be able to communicate with its own processes, and you will see all kinds of connection errors in the log files. This malfunction can only be recovered from by restarting Nginx. You can prevent such cleaning background jobs from interfering by setting this option to a different directory.
 
-For example, if you set 'passenger_temp_dir' to '/my_temp_dir', then invoke
-`passenger-status` after you've set the `PASSENGER_TMPDIR` or `TMPDIR`
-environment variable, like this:
+This option is also useful if the partition that the temporary directory lives on doesn't have enough disk space.
+
+The instance directory is automatically removed when Nginx shuts down.
+
+This option may be specified once, in the `http` configuration block. The default value is the value of the `$TMPDIR` environment variable. Or, if `$TMPDIR` is not set, `/tmp`.
+
+:option: `--instance-registry-dir`
+include::users_guide_snippets/alternative_for_flying_passenger.txt[]
+
+.Note regarding command line tools
+Some Phusion Passenger command line administration tools, such as `passenger-status`, must know what Phusion Passenger's instance registry directory is in order to function properly. You can pass the directory through the `PASSENGER_INSTANCE_REGISTRY_DIR` environment variable or the `TMPDIR` environment variable.
+
+For example, if you set 'passenger_instance_registry_dir' to '/my_temp_dir', then invoke `passenger-status` after you've set the `PASSENGER_INSTANCE_REGISTRY_DIR`, like this:
 
 ----------------------------------------------------------
-export PASSENGER_TMPDIR=/my_temp-dir
+export PASSENGER_INSTANCE_REGISTRY_DIR=/my_temp-dir
 sudo -E passenger-status
-# The -E option tells 'sudo' to preserve environment variables.
 ----------------------------------------------------------
 
-:option: `--temp-dir`
+Notes regarding the above example:
+
+ * The -E option tells 'sudo' to preserve environment variables.
+ * If Phusion Passenger is installed through an RVM Ruby, then you must use `rvmsudo` instead of `sudo`.
+
+[[PassengerDataBufferDir]]
+==== passenger_data_buffer_dir <directory>
+:version: 5.0.0
+include::users_guide_snippets/since_version.txt[]
+
+By default, Phusion Passenger buffers large web application responses. This prevents slow HTTP clients from blocking web applications by reading responses very slowly. This feature is also known as 'real-time disk-backed response buffering'.
+
+By default, such buffers are stored in the directory given by the `$TMPDIR` environment variable, or (if `$TMPDIR` is not set) the `/tmp` directory. This configuration directive allows you to specify a different directory.
+
+Changing this option is especially useful if the partition that the default directory lives on doesn't have enough disk space.
+
+If you've specified such a directory (as opposed to using Phusion Passenger's default) then you *must* ensure that this directory exists.
+
+This option may be specified once, in the `http` configuration block.
+
+:option: `--data-buffer-dir`
 include::users_guide_snippets/alternative_for_flying_passenger.txt[]
 
 ==== passenger_fly_with <socket filename>