passenger 2.2.15 → 3.0.0.pre1

data/doc/Users guide Nginx.txt

@@ -19,26 +19,30 @@ This guide assumes that the reader is somewhat familiar with Nginx and with
 using the commandline.
 
 
-== Supported operating systems ==
+== Support information ==
+
+=== Supported operating systems ===
 
 Phusion Passenger works on any POSIX-compliant operating system. In other
 words: practically any operating system on earth, except Microsoft Windows.
 
-Phusion Passenger for Nginx has been tested on:
-
-- Ubuntu Linux 8.04 (x86)
-- Gentoo Linux (AMD64)
-- MacOS X Leopard (x86)
-
-Other operating systems have not been tested, but Phusion Passenger will probably
-work fine on them. Please
+Phusion Passenger is confirmed on a large number of operating systems and Linux
+distributions, including, but not limited to, Ubuntu, Debian, CentOS/Fedora/RHEL,
+Gentoo, Mac OS X, FreeBSD and Solaris. Both 32-bit and 64-bit platforms are supported.
+Please
 link:http://code.google.com/p/phusion-passenger/issues/list[report a bug]
 or
-link:http://groups.google.com/group/phusion-passenger[join our discussion list]
-if it doesn't.
+link:http://groups.google.com/group/phusion-passenger[join our discussion forum]
+if it doesn't work on your POSIX-compliant operating system.
+
+=== Where to get support ===
+
+* link:http://code.google.com/p/phusion-passenger/issues/list[Issue tracker] - report
+  bugs here.
+* link:http://groups.google.com/group/phusion-passenger[Discussion forum] - post a
+  message here if you're experiencing problems.
 
 
-[[install_passenger]]
 == Installing Phusion Passenger ==
 
 === Overview ===
@@ -163,6 +167,113 @@ 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 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;
+        passenger_use_global_queue 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.
+
 
 [[deploying_a_ror_app]]
 == Deploying a Ruby on Rails application ==
@@ -223,8 +334,8 @@ http {
 And you want your Ruby on Rails application to be accessible from the URL
 'http://www.phusion.nl/rails'.
 
-To do this, make a symlink from your Ruby on Rails application's 'public'
-folder to a directory in the document root. For example:
+To do this, make a symlink in the virtual host's document root, and have it
+point to your Ruby on Rails application's 'public' folder. For example:
 -------------------------------------------
 ln -s /webapps/mycook/public /websites/phusion/rails
 -------------------------------------------
@@ -357,7 +468,7 @@ run app
 -------------------------------------------
 
 Finally, we deploy it by adding the following configuration options to
-the Apache configuration file:
+the Nginx configuration file:
 
 -------------------------------------------
 http {
@@ -419,8 +530,8 @@ http {
 And you want your Rack application to be accessible from the URL
 'http://www.phusion.nl/rack'.
 
-To do this, make a symlink from your Rack application's 'public'
-folder to a directory in the document root. For example:
+To do this, make a symlink in the virtual host's document root, and have it
+point to your Rack application's 'public' folder. For example:
 -------------------------------------------
 ln -s /webapps/rackapp/public /websites/phusion/rack
 -------------------------------------------
@@ -442,7 +553,7 @@ http {
     ...
 }
 -------------------------------------------
-Then restart Apache. The application has now been deployed.
+Then restart Nginx. The application has now been deployed.
 
 [TIP]
 ======================================
@@ -498,89 +609,303 @@ this option as well. Please read
 
 This required option may only occur once, in the 'http' configuration block.
 
-=== passenger_log_level <integer> ===
-This option allows one to specify how much information Phusion Passenger should
-write to the Apache error log file. A higher log level value means that more
-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.
-
-This option may only occur once, in the 'http' configuration block.
-The default is '0'.
-
 === passenger_ruby <filename> ===
 This option allows one to specify the Ruby interpreter to use.
 
 This option may only occur once, in the 'http' configuration block.
 The default is 'ruby'.
 
+[[PassengerSpawnMethod]]
+=== passenger_spawn_method <string> ===
+[TIP]
+."What spawn method should I use?"
+=========================================================
+This subsection attempts to describe spawn methods, but it's okay if you don't (want to)
+understand it, as it's mostly a technical detail. You can basically follow this rule of thumb:
+
+************************************************
+If your application works on Mongrel, but not on Phusion Passenger, then set
+`passenger_spawn_method` to 'conservative'. Otherwise, leave it at 'smart-lv2' (the default).
+************************************************
+
+However, we do recommend you to try to understand it. The 'smart' and 'smart-lv2' spawn
+methods bring many benefits.
+=========================================================
+
+include::users_guide_snippets/passenger_spawn_method.txt[]
+
+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 'smart-lv2'.
+
+=== Important deployment options ===
+==== passenger_enabled <on|off> ====
+This option may be specified in the 'http' configuration block, a
+'server' configuration block, a 'location' configuration block or
+an 'if' configuration scope, to enable or disable Phusion Passenger
+for that server or that location.
+
+Phusion Passenger is disabled by default, so you must explicitly enable
+it for server blocks that you wish to serve through Phusion Passenger.
+Please see <<deploying_a_ror_app,Deploying a Ruby on Rails application>>
+and <<deploying_a_rack_app,Deploying a Rack-based Ruby application>>
+for examples.
+
+[[PassengerBaseURI]]
+==== passenger_base_uri <uri> ====
+Used to specify that the given URI is an distinct application that should
+be served by Phusion Passenger. This option can be used for both Rails and
+Rack applications. See <<deploying_rails_to_sub_uri,Deploying Rails to a sub URI>>
+for an example.
+
+It is allowed to specify this option multiple times. Do this to deploy multiple
+applications in different sub-URIs under the same virtual host.
+
+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.
+
+=== Connection handling options ===
+
 [[PassengerUseGlobalQueue]]
-=== passenger_use_global_queue <on|off> ===
+==== passenger_use_global_queue <on|off> ====
 Turns the use of global queuing on or off.
 
 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 'off'.
+In each place, it may be specified at most once. The default value is 'on'.
 
 'This feature is sponsored by http://www.37signals.com/[37signals].'
 
 include::users_guide_snippets/global_queueing_explained.txt[]
 
+==== passenger_ignore_client_abort <on|off> ====
+Normally, when the HTTP client aborts the connection (e.g. when the user clicked on "Stop"
+in the browser), the connection with the application process will be closed too. If the
+application process continues to send its response, then that will result in EPIPE errors
+in the application, which will be printed in the error log if the application doesn't
+handle them gracefully.
+
+If this option is turned on then upon client abort Phusion Passenger will continue to
+read the application process's response while discarding all the read data. This prevents
+EPIPE errors but it'll also mean the backend process will be unavailable for new requests
+until it is done sending its response.
+
+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 'off'.
+
+==== passenger_set_cgi_param <CGI environment name> <value> ====
+Allows one to define additional CGI environment variables to pass to the backend
+application. This is equivalent to ngx_http_fastcgi_module's 'fastcgi_param'
+directive, and is comparable to ngx_http_proxy_module's 'proxy_set_header' option.
+Nginx variables in the value are interpolated.
+
+For example:
+------------------------------
+# 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;
+------------------------------
+
+If you want to set an HTTP header, then you must set it in the CGI environment name
+format, i.e. 'HTTP_*':
+
+------------------------------
+# !!!THIS IS WRONG!!! Don't do this!
+passenger_set_cgi_param X-Forwarded-For 127.0.0.2;
+
+# Instead, write it like this:
+passenger_set_cgi_param HTTP_X_FORWARDED_FOR 127.0.0.2;
+------------------------------
+
+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.
+
+==== passenger_pass_header <header name> ====
+Some headers generated by backend applications are not forwarded to the HTTP client,
+e.g. 'X-Accel-Redirect' which is directly processed by Nginx and then discarded from
+the final response. This directive allows one to force Nginx to pass those headers
+anyway, similar to how 'proxy_pass_header' works.
+
+For example:
+
+------------------------------
+location / {
+   passenger_pass_header X-Accel-Redirect;
+}
+------------------------------
+
+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.
+
+==== 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 instance generates a 2 MB response. If response buffering is turned
+off then your application instance will be blocked until the entire 2 MB has been
+sent out to the HTTP client. This disallows your application instance 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.
+
+However, keep in mind that enabling this option will make streaming responses
+impossible. Consider for example this piece of Rails code:
+
+--------------------------------
+render :text => lambda { |response, output|
+    10.times do |i|
+        output.write("entry #{i}\n")
+        output.flush
+        sleep 1
+    end
+}
+--------------------------------
+
+...or this piece of Rack code:
+
+--------------------------------
+class Response
+    def each
+        10.times do |i|
+            yield("entry #{i}\n")
+            sleep 1
+        end
+    end
+end
+
+app = lambda do |env|
+    [200, { "Content-Type" => "text/plain" }, Response.new]
+end
+--------------------------------
+
+When response buffering is turned on, Phusion Passenger 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
+receives an "entry X" message every second for 10 seconds.
+
+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'.
+
+=== Security options ===
 [[PassengerUserSwitching]]
-=== passenger_user_switching <on|off> ===
+==== passenger_user_switching <on|off> ====
 Whether to enable <<user_switching,user switching support>>.
 
 This option may only occur once, in the 'http' configuration block.
 The default value is 'on'.
 
+==== passenger_user <username> ====
+If <<user_switching,user switching support>> is enabled, then Phusion Passenger will
+by default run the web application as the owner if the file 'config/environment.rb'
+(for Rails apps) or 'config.ru' (for Rack apps). This option allows you to override
+that behavior and explicitly set a user to run the web application as, regardless
+of the ownership of 'environment.rb'/'config.ru'.
+
+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.
+
+==== passenger_user <group name> ====
+If <<user_switching,user switching support>> is enabled, then Phusion Passenger will
+by default run the web application as the primary group of the owner of the file
+'config/environment.rb' (for Rails apps) or 'config.ru' (for Rack apps). This option
+allows you to override that behavior and explicitly set a group to run the web application
+as, regardless of the ownership of 'environment.rb'/'config.ru'.
+
+'<group name>' may also be set to the special value '!STARTUP_FILE!', in which case
+the web application's group will be set to 'environment.rb'/'config.ru''s group.
+
+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.
+
 [[PassengerDefaultUser]]
-=== passenger_default_user <username> ===
+==== passenger_default_user <username> ====
 Phusion Passenger enables <<user_switching,user switching support>> by default.
-This configuration option allows one to specify which user Rails/Rack
-applications must run as, if user switching fails or is disabled.
+This configuration option allows one to specify the user that applications must
+run as, if user switching fails or is disabled.
 
 This option may only occur once, in the 'http' configuration block.
 The default value is 'nobody'.
 
-=== Important deployment options
-==== passenger_enabled <on|off> ====
-This option may be specified in a 'server' configuration block, a
-'location' configuration block or an 'if' configuration scope, to
-enable or disable Phusion Passenger for that server or that location.
-
-Phusion Passenger is disabled by default, so you must explicitly enable
-it for server blocks that you wish to serve through Phusion Passenger.
-Please see <<deploying_a_ror_app,Deploying a Ruby on Rails application>>
-and <<deploying_a_rack_app,Deploying a Rack-based Ruby application>>
-for examples.
-
-[[PassengerBaseURI]]
-==== passenger_base_uri <uri> ====
-Used to specify that the given URI is an distinct application that should
-be served by Phusion Passenger. This option can be used for both Rails and
-Rack applications. See <<deploying_rails_to_sub_uri,Deploying Rails to a sub URI>>
-for an example.
+[[PassengerDefaultGroup]]
+==== Passenger_default_group <group name> ====
+Phusion Passenger enables <<user_switching,user switching support>> by default.
+This configuration option allows one to specify the group that applications must
+run as, if user switching fails or is disabled.
 
-It is allowed to specify this option multiple times. Do this to deploy multiple
-applications in different sub-URIs under the same virtual host.
+This option may only occur once, in the 'http' configuration block.
+The default value is the primary group of the user specifified by
+<<PassengerDefaultUser,passenger_default_user>>.
+
+==== passenger_friendly_error_pages <on|off> ====
+Phusion Passenger can display friendly error pages whenever an application fails
+to start. This friendly error page presents the startup error message, some
+suggestions for solving the problem, and a backtrace. This feature is very useful
+during application development and useful for less experienced system administrators,
+but the page might reveal potentially sensitive information, depending on the
+application. Experienced system administrators who are using Phusion Passenger
+on serious production servers should consider turning this feature off.
 
 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'.
+
 === Resource control and optimization options ===
 [[PassengerMaxPoolSize]]
 ==== passenger_max_pool_size <integer> ====
@@ -607,6 +932,61 @@ TIP: We strongly recommend you to <<reducing_memory_usage,use Ruby Enterprise
 Edition>>. This allows you to reduce the memory usage of your Ruby on Rails applications
 by about 33%. And it's not hard to install.
 
+[[PassengerMinInstances]]
+==== passenger_min_instances <integer> ====
+This specifies the minimum number of application instances that must be kept around
+whenever Phusion Passenger cleans up idle instances. You should set this option to a
+non-zero value if you want to avoid potentially long startup times after a website
+has been idle for an extended period.
+
+Please note that this option does *not* pre-start application instances during Nginx
+startup. It just makes sure that when the application is first accessed:
+
+1. at least the given number of instances will be spawned.
+2. the given number of processes will be kept around even when instances are being
+   idle cleaned (see <<PassengerPoolIdleTime,passenger_pool_idle_time>>).
+
+If you want to pre-start application instances during Nginx startup, then you should use the <<PassengerPreStart,passenger_pre_start>> directive, possibly in combination with
+'passenger_min_instances'. This behavior might seem counter-intuitive at first sight,
+but <<PassengerPreStart,passenger_pre_start>> explains the rationale behind it.
+
+For example, suppose that you have the following configuration:
+
+---------------------------------
+http {
+    ...
+    passenger_max_pool_size 15;
+    passenger_pool_idle_time 10;
+    
+    server {
+        listen 80;
+        server_name foobar.com;
+        root /webapps/foobar/public;
+        passenger_min_instances 3;
+    }
+}
+---------------------------------
+
+When you start Nginx, there are 0 application instances for 'foobar.com'. Things will
+stay that way until someone visits 'foobar.com'. Suppose that there is only 1 visitor.
+1 application instance will be started immediately to serve the visitor, while 2 will
+be spawned in the background. After 10 seconds, when the idle timeout has
+been reached, these 3 application instances will not be cleaned up.
+
+Now suppose that there's a sudden spike of traffic, and 100 users visit 'foobar.com'
+simultanously. Phusion Passenger will start 12 more application instances. After the idle
+timeout of 10 seconds have passed, Phusion Passenger will clean up 12 application
+instances, keeping 3 instances around.
+
+The passenger_min_instances 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 '1'.
+
 ==== passenger_max_instances_per_app <integer> ====
 The maximum number of application instances that may be simultaneously active
 for a single application. This helps to make sure that a single application
@@ -646,36 +1026,227 @@ applications, each which must be available at all times.
 This option may only occur once, in the 'http' configuration block.
 The default value is '300'.
 
-=== Ruby on Rails-specific options ===
-[[RailsEnv]]
-==== rails_env <string> ====
-This option allows one to specify the default `RAILS_ENV` value.
+[[PassengerPreStart]]
+==== passenger_pre_start <url> ====
+By default, Phusion Passenger does not start any application instances until said
+web application is first accessed. The result is that the first visitor of said
+web application might experience a small delay as Phusion Passenger is starting
+the web application on demand. If that is undesirable, then this directive can be
+used to pre-started application instances during Nginx startup.
+
+A few things to be careful of:
+
+- This directive accepts the *URL* of the web application you want to pre-start,
+  not a on/off value! This might seem a bit weird, but read on for rationale. As
+  for the specifics of the URL:
+  * The domain part of the URL must be equal to the value of the 'server_name'
+    directive of the server block that defines the web application.
+  * Unless the web application is deployed on port 80, the URL should contain
+    the web application's port number too.
+  * The path part of the URL must point to some URI that the web application
+    handles.
+- You will probably want to combine this option with
+  <<PassengerMinInstances,passenger_min_instances>> because application instances
+  started with 'passenger_pre_start' are subject to the usual idle timeout rules.
+  See the example below for an explanation.
+
+This option may only occur in the 'http' configuration block. It may be specified
+any number of times.
+
+===== Example 1: basic usage =====
+
+Suppose that you have the following web applications.
+
+---------------------------
+server {
+    listen 80;
+    server_name foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+}
 
-This option may occur in the following places:
+server {
+    listen 3500;
+    server_name bar.com;
+    root /webapps/bar/public;
+    passenger_enabled on;
+}
+---------------------------
 
- * In a 'server' configuration block.
- * In a 'location' configuration block.
- * In an 'if' configuration scope.
+You want both of them to be pre-started during Nginx startup. The URL for
+foo.com is 'http://foo.com/' (or, equivalently, 'http://foo.com:80/') and
+the URL for bar.com is 'http://bar.com:3500/'. So we add two passenger_pre_start
+directives, like this:
 
-In each place, it may be specified at most once. The default value is 'production'.
+---------------------------
+server {
+    listen 80;
+    server_name foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+}
 
-==== rails_spawn_method <string> ====
-[TIP]
-."What spawn method should I use?"
-=========================================================
-This subsection attempts to describe spawn methods, but it's okay if you don't (want to)
-understand it, as it's mostly a technical detail. You can basically follow this rule of thumb:
+server {
+    listen 3500;
+    server_name bar.com;
+    root /webapps/bar/public;
+    passenger_enabled on;
+}
 
-************************************************
-If your application works on Mongrel, but not on Phusion Passenger, then set
-`rails_spawn_method` to 'conservative'. Otherwise, leave it at 'smart-lv2' (the default).
-************************************************
+passenger_pre_start http://foo.com/;           # <--- added
+passenger_pre_start http://bar.com:3500/;      # <--- added
+---------------------------
 
-However, we do recommend you to try to understand it. The 'smart' and 'smart-lv2' spawn
-methods bring many benefits.
-=========================================================
+===== Example 2: pre-starting apps that are deployed in sub-URIs =====
+
+Suppose that you have a web application deployed in a sub-URI '/store', like this:
+
+---------------------------
+server {
+    listen 80;
+    server_name myblog.com;
+    root /webapps/wordpress;
+    rails_base_uri /store;
+}
+---------------------------
+
+Then specify the 'server_name' valuue followed by the sub-URI, like this:
+
+---------------------------
+server {
+    listen 80;
+    server_name myblog.com;
+    root /webapps/wordpress;
+    rails_base_uri /store;
+}
+
+passenger_pre_start http://myblog.com/store;    # <----- added
+---------------------------
+
+The sub-URI *must* be included; if you don't then the directive will have no effect.
+The following example is wrong and won't pre-start the store web application:
+
+---------------------------
+passenger_pre_start http://myblog.com/;    # <----- WRONG! Missing "/store" part.
+---------------------------
+
+===== Example 3: combining with passenger_min_instances =====
+
+Application instances started with passenger_pre_start are
+also subject to the idle timeout rules as specified by
+<<PassengerPoolIdleTime,passenger_pool_idle_time>>! That means that by default,
+the pre-started application instances for foo.com are bar.com are shut down
+after a few minutes of inactivity. If you don't want that to happen, then
+you should combine passenger_pre_start with
+<<PassengerMinInstances,passenger_min_instances>>, like this:
+
+---------------------------
+server {
+    listen 80;
+    server_name foo.com;
+    root /webapps/foo/public;
+    passenger_enabled on;
+    passenger_min_instances 1;      # <--- added
+}
+
+server {
+    listen 3500;
+    server_name bar.com;
+    root /webapps/bar/public;
+    passenger_enabled on;
+    passenger_min_instances 1;      # <--- added
+}
 
-include::users_guide_snippets/rails_spawn_method.txt[]
+passenger_pre_start http://foo.com/;
+passenger_pre_start http://bar.com:3500/;
+---------------------------
+
+===== So why a URL? Why not just an on/off flag? =====
+
+A directive that accepts a simple on/off flag is definitely more intuitive,
+but due technical difficulties w.r.t. the way Nginx works, it's very hard
+to implement it like that:
+
+It is very hard to obtain a full list of web applications defined in the
+Nginx configuration file(s). In other words, it's hard for Phusion Passenger
+to know which web applications are deployed on Nginx until a web application
+is first accessed, and without such a list Phusion Passenger wouldn't know
+which web applications to pre-start. So as a compromise, we made it accept a
+URL.
+
+===== What does Phusion Passenger do with the URL? =====
+
+During Nginx startup, Phusion Passenger will send a dummy HEAD request to the
+given URL and discard the result. In other words, Phusion Passenger simulates a
+web access at the given URL. However this simulated request is always sent to
+localhost, *not* to the IP that the domain resolves to. Suppose that bar.com
+in example 1 resolves to 209.85.227.99; Phusion Passenger will
+send the following HTTP request to 127.0.0.1 port 3500 (and not to 209.85.227.99
+port 3500):
+
+----------------------
+HEAD / HTTP/1.1
+Host: bar.com
+Connection: close
+----------------------
+
+Similarly, for example 2, Phusion Passenger will send the following HTTP request
+to 127.0.0.1 port 80:
+
+----------------------
+HEAD /store HTTP/1.1
+Host: myblog.com
+Connection: close
+----------------------
+
+===== Do I need to edit /etc/hosts and point the domain in the URL to 127.0.0.1? =====
+
+No. See previous subsection.
+
+===== My web application consists of multiple web servers. What URL do I need to specify, and in which web server's Nginx config file? =====
+
+Put the web application's 'server_name' value and the server block's
+port in the URL, and put
+passenger_pre_start on all machines that you want to pre-start the web application
+on. The simulated web request is always sent to 127.0.0.1, with the domain name
+in the URL as value for the 'Host' HTTP header, so you don't need to worry about
+the request ending up at a different web server in the cluster.
+
+===== Does passenger_pre_start support https:// URLs? =====
+
+Yes. And it does not perform any certificate validation.
+
+
+=== Logging and debugging options ===
+=== passenger_log_level <integer> ===
+This option allows one to specify how much information Phusion Passenger should
+write to the Nginx error log file. A higher log level value means that more
+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.
+
+This option may only occur once, in the 'http' configuration block.
+The default is '0'.
+
+=== passenger_debug_log_file <filename> ===
+By default Phusion Passenger debugging and error messages are written to the global
+web server error log. This option allows one to specify the file that debugging and
+error messages should be written to instead.
+
+This option may only occur once, in the 'http' configuration block.
+
+
+=== Ruby on Rails-specific options ===
+[[RailsEnv]]
+==== rails_env <string> ====
+This option allows one to specify the default `RAILS_ENV` value.
 
 This option may occur in the following places:
 
@@ -684,7 +1255,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 'smart-lv2'.
+In each place, it may be specified at most once. The default value is 'production'.
 
 ==== rails_framework_spawner_idle_time <integer> ====
 The FrameworkSpawner server (explained in <<spawning_methods_explained,Spawning
@@ -745,6 +1316,7 @@ This option allows one to specify the default `RACK_ENV` value.
 
 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.
@@ -752,9 +1324,18 @@ This option may occur in the following places:
 In each place, it may be specified at most once. The default value is 'production'.
 
 
-== Analysis and system maintenance tools ==
+=== Deprecated options ===
 
-include::users_guide_snippets/analysis_and_system_maintenance_tools.txt[]
+The following options have been deprecated, but are still supported for backwards
+compatibility reasons.
+
+==== rails_spawn_method ====
+Deprecated in favor of <<PassengerSpawnMethod,passenger_spawn_method>>.
+
+
+== Analysis and system maintenance ==
+
+include::users_guide_snippets/analysis_and_system_maintenance.txt[]
 
 
 == Tips ==
@@ -762,6 +1343,49 @@ include::users_guide_snippets/analysis_and_system_maintenance_tools.txt[]
 include::users_guide_snippets/tips.txt[]
 
 
+== Under the hood ==
+Phusion Passenger hides a lot of complexity for the end user (i.e. the web server
+system administrator), but sometimes it is desirable to know what is going on.
+This section describes a few things that Phusion Passenger does under the hood.
+
+=== Page caching support ===
+include::users_guide_snippets/under_the_hood/page_caching_support.txt[]
+
+[[application_detection]]
+=== How Phusion Passenger detects whether a virtual host is a web application ===
+After you've read the deployment instructions you might wonder how Phusion Passenger
+knows that the server root points to a web application that Phusion Passenger is
+able to serve, and how it knows what kind of web application it is (e.g. Rails or Rack).
+
+Phusion Passenger checks whether the virtual host is a Rails application by checking
+whether the following file exists:
+
+------------------------------------------------
+dirname(DocumentRoot) + "/config/environment.rb"
+------------------------------------------------
+
+If you're not a programmer and don't understand the above pseudo-code snippet, it means
+that Phusion Passenger will:
+
+1. Extract the parent directory filename from the value of the ``root'' directive.
+2. Append the text "/config/environment.rb" to the result, and check whether the resulting
+   filename exists.
+
+So suppose that your server root is '/webapps/foo/public'. Phusion Passenger will check
+whether the file '/webapps/foo/config/environment.rb' exists.
+
+Note that Phusion Passenger for Nginx does *not* resolve any symlinks in the root path.
+So for example, suppose that your root points to '/home/www/example.com', which in
+turn is a symlink to '/webapps/example.com/public'. Phusion Passenger for Nginx will check for
+'/home/www/config/environment.rb', *not* '/webapps/example.com/config/environment.rb'.
+This file of course doesn't exist, and as a result Phusion Passenger will not activate
+itself for this virtual host, and you'll most likely see some output generated by the
+Nginx default directory handler such as a Forbidden error message.
+
+Detection of Rack applications happens through the same mechanism, exception that
+Phusion Passenger will look for 'config.ru' instead of 'config/environment.rb'.
+
+
 include::users_guide_snippets/appendix_a_about.txt[]
 
 include::users_guide_snippets/appendix_b_terminology.txt[]