passenger 3.9.2.beta → 4.0.0.rc4

data/doc/Users guide Nginx.idmap.txt

@@ -20,25 +20,37 @@
 
 2. Installation	=>	installing-phusion-passenger-hn03ac
 
-2.1. Generic installation, upgrade and downgrade method: via RubyGems	=>	generic-installation-upgrade-and-downgrade-method-via-rubygems-76uol7
+2.1. Synopsis	=>	synopsis-1uu3sqp
 
-2.2. Generic installation, upgrade and downgrade method: via tarball	=>	generic-installation-upgrade-and-downgrade-method-via-tarball-2gkx43
+2.2. Generic installation, upgrade and downgrade method: via RubyGems	=>	generic-installation-upgrade-and-downgrade-method-via-rubygems-76uol7
 
-2.3. Installing or upgrading on Ubuntu	=>	installing-or-upgrading-on-ubuntu-fw5fvp
+2.3. Generic installation, upgrade and downgrade method: via tarball	=>	generic-installation-upgrade-and-downgrade-method-via-tarball-2gkx43
 
-2.4. Installing or upgrading on Red Hat, Fedora, CentOS or ScientificLinux	=>	installing-or-upgrading-on-red-hat-fedora-centos-or-scientificlinux-1uus5a1
+2.4. Installing or upgrading on Debian 6 or Ubuntu	=>	installing-or-upgrading-on-ubuntu-fw5fvp
 
-2.5. Upgrading from open source to Enterprise	=>	upgrading-from-open-source-to-enterprise-1a58c2b
+2.5. Installing or upgrading on Red Hat, Fedora, CentOS or ScientificLinux	=>	installing-or-upgrading-on-red-hat-fedora-centos-or-scientificlinux-1uus5a1
 
-2.6. Non-interactive, automatic, headless installs or upgrades	=>	non-interactive-automatic-headless-installs-or-upgrades-834ymv
+2.6. Upgrading from open source to Enterprise	=>	upgrading-from-open-source-to-enterprise-1a58c2b
 
-2.7. Installing as a normal Nginx module without using the installer	=>	installing-as-a-normal-nginx-module-without-using-the-installer-1kkpes5
+2.7. Non-interactive, automatic, headless installs or upgrades	=>	non-interactive-automatic-headless-installs-or-upgrades-834ymv
 
-2.8. Disabling without uninstalling	=>	disabling-without-uninstalling-1t5tqan
+2.8. Customizing the compilation process	=>	customizing-the-compilation-process-u4cdcf
 
-2.9. Uninstalling	=>	uninstalling-phusion-passenger-wuycvb
+2.8.1. Setting the compiler	=>	setting-the-compiler-1l6dpe1
 
-2.10. Moving to a different directory	=>	moving-to-a-different-directory-gif3wo
+2.8.2. Adding additional compiler or linker flags	=>	adding-additional-compiler-or-linker-flags-1jehjon
+
+2.8.3. Forcing location of certain command line tools	=>	forcing-location-of-certain-command-line-tools-1j93cki
+
+2.9. Installing as a normal Nginx module without using the installer	=>	installing-as-a-normal-nginx-module-without-using-the-installer-1kkpes5
+
+2.10. Creating an Nginx init script	=>	creating-an-nginx-init-script-1kd8zg5
+
+2.11. Disabling without uninstalling	=>	disabling-without-uninstalling-1t5tqan
+
+2.12. Uninstalling	=>	uninstalling-phusion-passenger-wuycvb
+
+2.13. 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
 
@@ -90,93 +102,101 @@
 
 6.2. passenger_ruby <filename>	=>	passenger-ruby-filename--1gnok5k
 
-6.3. passenger_spawn_method <string>	=>	passenger-spawn-method-string--1sc6njl
+6.3. passenger_python <filename>	=>	passenger-python-filename--14p554
 
-6.4. passenger_rolling_restarts <on|off>	=>	passenger-rolling-restarts
+6.4. passenger_app_root <path/to/root>	=>	passenger-app-root-path-to-root--1dbudc6
 
-6.5. passenger_resist_deployment_errors <on|off>	=>	passenger-resist-deployment-errors-on-off--k9yf1
+6.5. passenger_spawn_method <string>	=>	passenger-spawn-method-string--1sc6njl
 
-6.6. Important deployment options	=>	important-deployment-options-av567
+6.6. passenger_rolling_restarts <on|off>	=>	passenger-rolling-restarts
 
-6.6.1. passenger_enabled <on|off>	=>	passenger-enabled-on-off--1rpb2t7
+6.7. passenger_resist_deployment_errors <on|off>	=>	passenger-resist-deployment-errors-on-off--k9yf1
 
-6.6.2. passenger_base_uri <uri>	=>	passenger-base-uri-uri--1xtuo50
+6.8. passenger_temp_dir <directory>	=>	passenger-temp-dir-directory--1t3opri
 
-6.7. Connection handling options	=>	connection-handling-options-8jgq90
+6.9. Important deployment options	=>	important-deployment-options-av567
 
-6.7.1. passenger_ignore_client_abort <on|off>	=>	passenger-ignore-client-abort
+6.9.1. passenger_enabled <on|off>	=>	passenger-enabled-on-off--1rpb2t7
 
-6.7.2. passenger_set_cgi_param <CGI environment name> <value>	=>	passenger-set-cgi-param-cgi-environment-name-value--rx9gc0
+6.9.2. passenger_base_uri <uri>	=>	passenger-base-uri-uri--1xtuo50
 
-6.7.3. passenger_pass_header <header name>	=>	passenger-pass-header-header-name--1cg31je
+6.10. Connection handling options	=>	connection-handling-options-8jgq90
 
-6.7.4. passenger_buffer_response <on|off>	=>	passenger-buffer-response
+6.10.1. passenger_ignore_client_abort <on|off>	=>	passenger-ignore-client-abort
 
-6.7.5. passenger_buffer_size	=>	passenger-buffer-size-1jfkq87
+6.10.2. passenger_set_cgi_param <CGI environment name> <value>	=>	passenger-set-cgi-param-cgi-environment-name-value--rx9gc0
 
-6.7.6. passenger_buffers	=>	passenger-busy-buffers
+6.10.3. passenger_pass_header <header name>	=>	passenger-pass-header-header-name--1cg31je
 
-6.7.7. passenger_busy_buffer_size	=>	passenger-busy-buffer-size-124sj61
+6.10.4. passenger_buffer_response <on|off>	=>	passenger-buffer-response
 
-6.8. Security options	=>	security-options-1bv93g4
+6.10.5. passenger_buffer_size	=>	passenger-buffer-size-1jfkq87
 
-6.8.1. passenger_user_switching <on|off>	=>	passenger-user-switching-on-off--1p37u3l
+6.10.6. passenger_buffers	=>	passenger-busy-buffers
 
-6.8.2. passenger_user <username>	=>	passenger-user-username--b06ur7
+6.10.7. passenger_busy_buffer_size	=>	passenger-busy-buffer-size-124sj61
 
-6.8.3. passenger_group <group name>	=>	passenger-user-group-name--1fco4j7
+6.11. Security options	=>	security-options-1bv93g4
 
-6.8.4. passenger_default_user <username>	=>	passenger-default-user-username--1h6cdmf
+6.11.1. passenger_user_switching <on|off>	=>	passenger-user-switching-on-off--1p37u3l
 
-6.8.5. Passenger_default_group <group name>	=>	passenger-default-group-group-name--1qxn2qa
+6.11.2. passenger_user <username>	=>	passenger-user-username--b06ur7
 
-6.8.6. passenger_friendly_error_pages <on|off>	=>	passenger-friendly-error-pages-on-off--1ti1a0e
+6.11.3. passenger_group <group name>	=>	passenger-user-group-name--1fco4j7
 
-6.9. Resource control and optimization options	=>	resource-control-and-optimization-options-xd7evs
+6.11.4. passenger_default_user <username>	=>	passenger-default-user-username--1h6cdmf
 
-6.9.1. passenger_max_pool_size <integer>	=>	passenger-max-pool-size-integer--3jzefs
+6.11.5. Passenger_default_group <group name>	=>	passenger-default-group-group-name--1qxn2qa
 
-6.9.2. passenger_min_instances <integer>	=>	passenger-min-instances-integer--uclykt
+6.11.6. passenger_show_version_in_header <on|off>	=>	passenger-show-version-in-header-on-off--2h49av
 
-6.9.3. passenger_max_instances <integer>	=>	passenger-max-instances
+6.11.7. passenger_friendly_error_pages <on|off>	=>	passenger-friendly-error-pages-on-off--1ti1a0e
 
-6.9.4. passenger_max_instances_per_app <integer>	=>	passenger-max-instances-per-app-integer--1xhbbne
+6.12. Resource control and optimization options	=>	resource-control-and-optimization-options-xd7evs
 
-6.9.5. passenger_pool_idle_time <integer>	=>	passenger-pool-idle-time-integer--xcw65o
+6.12.1. passenger_max_pool_size <integer>	=>	passenger-max-pool-size-integer--3jzefs
 
-6.9.6. passenger_max_preloader_idle_time <integer>	=>	rails-app-spawner-idle-time-integer--1xjqe4b
+6.12.2. passenger_min_instances <integer>	=>	passenger-min-instances-integer--uclykt
 
-6.9.7. passenger_concurrency_model <process|thread>	=>	passenger-concurrency-model-process-thread--brcvkk
+6.12.3. passenger_max_instances <integer>	=>	passenger-max-instances
 
-6.9.8. passenger_thread_count <number>	=>	passenger-thread-count-number--1kd6ffy
+6.12.4. passenger_max_instances_per_app <integer>	=>	passenger-max-instances-per-app-integer--1xhbbne
 
-6.9.9. passenger_max_requests <integer>	=>	passenger-max-requests-integer--sgzint
+6.12.5. passenger_pool_idle_time <integer>	=>	passenger-pool-idle-time-integer--xcw65o
 
-6.9.10. passenger_max_request_time <seconds>	=>	passenger-max-request-time-seconds--1htog2g
+6.12.6. passenger_max_preloader_idle_time <integer>	=>	rails-app-spawner-idle-time-integer--1xjqe4b
 
-6.9.11. passenger_memory_limit <integer>	=>	passenger-memory-limit-integer--1ry7dwx
+6.12.7. passenger_concurrency_model <process|thread>	=>	passenger-concurrency-model-process-thread--brcvkk
 
-6.9.12. passenger_pre_start <url>	=>	passenger-pre-start-url--npldeb
+6.12.8. passenger_thread_count <number>	=>	passenger-thread-count-number--1kd6ffy
 
-6.10. Logging and debugging options	=>	logging-and-debugging-options-14e91ni
+6.12.9. passenger_max_requests <integer>	=>	passenger-max-requests-integer--sgzint
 
-6.10.1. passenger_log_level <integer>	=>	passenger-log-level-integer--17snhon
+6.12.10. passenger_max_request_time <seconds>	=>	passenger-max-request-time-seconds--1htog2g
 
-6.10.2. passenger_debug_log_file <filename>	=>	passenger-debug-log-file-filename--21ubaj
+6.12.11. passenger_memory_limit <integer>	=>	passenger-memory-limit-integer--1ry7dwx
 
-6.10.3. passenger_debugger <on|off>	=>	passenger-debugger-on-off--1wkuq85
+6.12.12. passenger_pre_start <url>	=>	passenger-pre-start-url--npldeb
 
-6.11. Ruby on Rails-specific options	=>	ruby-on-rails-specific-options-12vfokt
+6.13. Logging and debugging options	=>	logging-and-debugging-options-14e91ni
 
-6.11.1. rails_env <string>	=>	rails-env-string--jlh7v9
+6.13.1. passenger_log_level <integer>	=>	passenger-log-level-integer--17snhon
 
-6.12. Rack and Rails >= 3 specific options	=>	rack-specific-options-13yvdxs
+6.13.2. passenger_debug_log_file <filename>	=>	passenger-debug-log-file-filename--21ubaj
 
-6.12.1. rack_env <string>	=>	rack-env-string--tqmrt0
+6.13.3. passenger_debugger <on|off>	=>	passenger-debugger-on-off--1wkuq85
 
-6.13. Deprecated options	=>	deprecated-options-1dtzo0g
+6.14. Ruby on Rails-specific options	=>	ruby-on-rails-specific-options-12vfokt
 
-6.13.1. rails_spawn_method	=>	rails-spawn-method-17vdnpt
+6.14.1. rails_env <string>	=>	rails-env-string--jlh7v9
+
+6.15. Rack and Rails >= 3 specific options	=>	rack-specific-options-13yvdxs
+
+6.15.1. rack_env <string>	=>	rack-env-string--tqmrt0
+
+6.16. Deprecated options	=>	deprecated-options-1dtzo0g
+
+6.16.1. rails_spawn_method	=>	rails-spawn-method-17vdnpt
 
 7. Analysis and system maintenance	=>	analysis-and-system-maintenance-1nnlnj8
 
@@ -200,15 +220,13 @@
 
 8.4. Bundler support	=>	bundler-support-19v1h43
 
-8.5. Moving Phusion Passenger to a different directory	=>	moving-phusion-passenger-to-a-different-directory-1hel5cp
-
-8.6. Installing multiple Ruby on Rails versions	=>	installing-multiple-ruby-on-rails-versions-1bp1fff
+8.5. Installing multiple Ruby on Rails versions	=>	installing-multiple-ruby-on-rails-versions-1bp1fff
 
-8.7. Making the application restart after each request	=>	making-the-application-restart-after-each-request-vimy48
+8.6. Making the application restart after each request	=>	making-the-application-restart-after-each-request-vimy48
 
-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
+8.7. 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
 
-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
+8.8. 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
 

data/doc/Users guide Nginx.txt

@@ -463,12 +463,64 @@ This required option may only occur once, in the 'http' configuration block.
 === passenger_ruby <filename> ===
 This option allows one to specify the Ruby interpreter to use.
 
-* In the 'http' configuration block.
+Since version 4.0.0, 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.
+
+If you want to use a different Ruby interpreter for two different applications then you should define different `passenger_ruby` directives in different 'http' blocks.
+
+In versions prior to 4.0.0, only a single Ruby version is supported for the entire Nginx instance, so `passenger_ruby` may only occur in the 'http' configuration block.
+
+The default value is 'ruby', meaning that the Ruby interpreter will be looked up according to the `PATH` environment variable.
+
+=== passenger_python <filename> ===
+:version: 4.0.0
+include::users_guide_snippets/since_version.txt[]
+
+This option allows one to specify the Python interpreter to use. It 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 'ruby', meaning that the Ruby interpreter will be looked up according to the `PATH` environment variable.
+If you want to use a different Python interpreter for two different applications then you should define different `passenger_python` directives in different 'http' blocks.
+
+The default value is 'python', meaning that the Python interpreter will be looked up according to the `PATH` environment variable.
+
+[[PassengerAppRoot]]
+=== passenger_app_root <path/to/root> ===
+:version: 4.0.0
+include::users_guide_snippets/since_version.txt[]
+By default, Phusion Passenger assumes that the application's root directory
+is the parent directory of the 'public' directory. This option allows one to
+specify the application's root independently from the Nginx 'root', which
+is useful if the 'public' directory lives in a non-standard place.
+
+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.
+
+Example:
+
+-----------------------------
+server {
+    server_name test.host;
+    root /var/rails/zena/sites/example.com/public;
+    # normally Phusion Passenger would
+    # have assumed that the application
+    # root is "/var/rails/zena/sites/example.com"
+    passenger_app_root /var/rails/zena;
+}
+-----------------------------
 
 [[PassengerSpawnMethod]]
 === passenger_spawn_method <string> ===
@@ -566,6 +618,35 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once. The default value is 'off'.
 
+[[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.
+
+This option may only be specified in the 'http' configuration block. The
+default temp directory that Phusion Passenger uses is '/tmp'.
+
+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.
+
+.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).
+
+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:
+
+----------------------------------------------------------
+export PASSENGER_TMPDIR=/my_temp-dir
+sudo -E passenger-status
+# The -E option tells 'sudo' to preserve environment variables.
+----------------------------------------------------------
+
 === Important deployment options ===
 ==== passenger_enabled <on|off> ====
 This option may be specified in the 'http' configuration block, a
@@ -811,6 +892,30 @@ 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_show_version_in_header <on|off> ====
+When turned on, Phusion Passenger will output its version number in the `Server` and `X-Powered-By` header in all Phusion Passenger-served requests:
+
+----------------------------------------------------
+Server: nginx/1.3.11 + Phusion Passenger 4.0.0
+X-Powered-By: Phusion Passenger 4.0.0
+----------------------------------------------------
+
+When turned off, the version number will be hidden:
+
+----------------------------------------------------
+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'.
+
 ==== 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
@@ -848,7 +953,7 @@ If you find that your server is unable to handle the load on your Rails/Rack web
 sites are really that popular, then you should strongly consider upgrading your
 hardware or getting more servers.)
 
-This option may only occur once, in the 'http' configuration bock.
+This option may only occur once, in the 'http' configuration block.
 The default value is '6'.
 
 TIP: We strongly recommend you to <<reducing_memory_usage,use Ruby Enterprise
@@ -1146,33 +1251,17 @@ 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 '200'.
+In each place, it may be specified at most once. The default value is '0'.
 
 [NOTE]
 .A word about permissions
 =====================================================
-The <<PassengerMemoryLimit,passenger_memory_limit>> directive requires that the
-user that the application is running as (see <<PassengerUserSwitching,passenger_user_switching>>)
-to have access to the `/proc` file system, or to be able to inspect its status
-with `ps` (which on Linux and FreeBSD systems basically means the same thing, since `ps`
-reads process information from `/proc`). Therefore, on servers running with
-tight permissions on `/proc`, this directive may not work. If you wish to use
-this directive and your `/proc` permissions are too tight, then please consider
-untightening the permissions.
-=====================================================
-
-[TIP]
-.FreeBSD and `/proc`
-=====================================================
-On many FreeBSD systems, `/proc` is not mounted by default. `/proc` *must* be
-mounted in order for <<PassengerMemoryLimit,passenger_memory_limit>> to work.
-
-It is also advised that you mount `/proc` with the `linprocfs` filesystem type
-instead of the regular FreeBSD `proc` filesystem type. The `linprocfs` filesystem
-type allows Phusion Passenger to read memory information from `/proc` directly,
-which is very fast. If you mount `/proc` with a different filesystem type, then
-Phusion Passenger must resort to querying memory information from the `ps` command,
-which is a lot slower.
+The <<PassengerMemoryLimit,passenger_memory_limit>> directive uses the
+`ps` command to query memory usage information. On Linux, it further
+queries `/proc` to obtain additional memory usage information that's
+not obtainable through `ps`. You should ensure that the `ps` works
+correctly and that the `/proc` filesystem is accessible by the
+`PassengerHelperAgent` process.
 =====================================================
 
 [CAUTION]

data/doc/Users guide Standalone.html

@@ -1122,7 +1122,8 @@ Can listen on a Unix socket, for use in reverse proxy setups.
 words: practically any operating system on earth, except Microsoft Windows.</p></div>
 <div class="paragraph"><p>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.</p></div>
+Gentoo, Mac OS X, FreeBSD and Solaris. OpenBSD is supported since version 5.2.
+Both 32-bit and 64-bit platforms are supported.</p></div>
 <div class="paragraph"><p>Please
 <a href="http://code.google.com/p/phusion-passenger/issues/list">report a bug</a>
 or
@@ -1154,6 +1155,11 @@ Email <a href="mailto:support@phusion.nl">support@phusion.nl</a> if you are a <a
 <a href="https://www.phusionpassenger.com/commercial_support">Commercial support contracts</a> are also available.
 </p>
 </li>
+<li>
+<p>
+Report security vulnerabilities to <a href="mailto:support@phusion.nl">support@phusion.nl</a>. We will do our best to respond to you as quickly as we can, so please do not disclose the vulnerability until then.
+</p>
+</li>
 </ul></div>
 <div class="paragraph"><p>Please consult <a href="https://www.phusionpassenger.com/support">the Phusion Passenger website</a> for a full list of support resources.</p></div>
 </div>
@@ -1192,7 +1198,7 @@ use the <span class="monospaced">-p</span> option, e.g.:</p></div>
 <div id="footnotes"><hr></div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2013-01-23 15:31:31 CET
+Last updated 2013-03-03 11:14:55 CET
 </div>
 </div>
 <script>/*! jQuery v1.7.1 jquery.com | jquery.org/license */

data/doc/users_guide_snippets/analysis_and_system_maintenance.txt

@@ -116,13 +116,7 @@ sessions compared to the others, then there might be a problem:
                                +---- "spike"
 --------------------------------
 
-Possible reasons why spikes can occur:
-
-. Your application is busy processing a request that takes a very long time.
-  If this is the case, then you might want to turn
-  <<PassengerUseGlobalQueue,global queuing>> on.
-. Your application is frozen, i.e. has stopped responding. See
-  <<debugging_frozen,Debugging frozen applications>> for tips.
+The most likely reason why a spike occurs is because your application is frozen, i.e. it has stopped responding. See <<debugging_frozen,Debugging frozen applications>> for tips.
 
 
 [[debugging_frozen]]

data/doc/users_guide_snippets/installation.txt

@@ -1,9 +1,11 @@
+=== Synopsis
+
 The Phusion Passenger installation process consists of two steps:
 
 1. The *obtainment step*, where you download the Phusion Passenger files puts them somewhere on your system. This can be done through downloading the source tarball, installing the Ruby gem or installing a native OS package via APT or YUM.
 2. The *integration step*, where you configure Phusion Passenger so that it works properly with other system components such as Apache, Nginx, Ruby, Python, etc.
 
-Because Phusion Passenger is designed to run in a wide variety of operating systems and configurations, both steps can be done in multiple ways. Most users will be satisfied with the generic installation instructions which covers both steps, but some users may prefer OS-specific installation instructions in order to integrate better.
+Because Phusion Passenger is designed to run in a wide variety of operating systems and configurations, both steps can be done in multiple ways. Most users -- especially first-time users -- will be satisfied with the _generic installation instructions_ which covers both steps. However some users may prefer _OS-specific installation instructions_, which allow Phusion Passenger to better integrate into the operating system. Better integration is characterized by following OS-specific conventions.
 
 If you are not familiar with system administration and do not understand all the choices, then we recommend you to go with the <<rubygems_generic_install,RubyGems generic installation method>> (if you're a Ruby user) or the <<tarball_generic_install,tarball generic installation method>> (if you're not a Ruby user).
 
@@ -13,6 +15,8 @@ The steps for upgrading or downgrading Phusion Passenger is almost the same as t
 [[rubygems_generic_install]]
 === Generic installation, upgrade and downgrade method: via RubyGems
 
+RubyGems is only used as a method to obtain the Phusion Passenger files, so in case you have multiple Ruby versions it does not matter which Ruby's RubyGems you use for installation. Once installed, Phusion Passenger can work with all other Ruby versions on your system.
+
 [[is_ruby_home_or_system_wide_installed]]
 [float]
 ==== Step 1: figuring out whether your Ruby is installed the home directory or system-wide
@@ -78,7 +82,7 @@ gem install passenger-enterprise-server-x.x.x.gem
 [float]
 ==== Step 3: add the RubyGems bin directory to your $PATH
 
-If you all the following are applicable to you:
+If you all of the following are applicable to you:
 
 - You are on Debian or Ubuntu,
 - and you installed RubyGems through APT,
@@ -129,7 +133,7 @@ passenger-install-apache2-module
 
 At the end of the installation process, you will be asked to copy and paste a configuration snippet (containing `LoadModule`, `PassengerRoot`, etc.) into your Apache configuration file. If you're upgrading, then you already had a similar configuration snippet. Be sure to remove the old one before pasting the new one.
 
-If you have trouble finding the Apache configuration file, see <<locating_apache_conf,Locating the Apache configuration file>>. If you're on OS X Server >= 10.8 (Mountain Lion) and you're running Web Services, then you should definitely read that section because the configuration file may not be where you think it is.
+Different operating systems and Apache installations have different conventions with regard to where the Apache configuration file is and how it is organized. Please read <<working_with_apache_conf,Working with the Apache configuration file>> if you're not familiar with it. That section is especially of interest for OS X Server >= 10.8 users because the configuration file may not be at a surprising location.
 
 If compilation doesn't succeed, then please consult the <<troubleshooting,Troubleshooting>> section.
 
@@ -172,6 +176,9 @@ passenger-memory-stats
 ---------------------------
 
 You should see the web server processes as well as a number of Phusion Passenger processes (e.g. PassengerWatchdog, PassengerHelperAgent). Congratulations, Phusion Passenger is now installed and running!
+ifdef::nginx[]
+At this point you may be interested in <<nginx_init_script,creating an Nginx init script>>.
+endif::[]
 
 If the output is not as expected, then please refer to the <<troubleshooting,Troubleshooting>> section.
 
@@ -263,7 +270,7 @@ sudo apt-add-repository ppa:brightbox/passenger
 sudo apt-get update
 -----------------------------
 
-If you're on the older Ubuntu 8.04 Hardy release, the 'apt-add-repository' command isn't available so you have to install the repository and the key by hand:
+If you're on the older Ubuntu 8.04 Hardy release, the `apt-add-repository` command isn't available so you have to install the repository and the key by hand:
 
 -----------------------------
 sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger.list'
@@ -301,37 +308,103 @@ endif::[]
 Please refer to <<verify_passenger_running,this section>>. Note that all Phusion Passenger administration scripts are located inside the 'bin' subdirectory of the Phusion Passenger source directory, so you would have to run something like '/opt/passenger/passenger-x.x.x/bin/passenger-memory-stats'.
 
 
-=== Installing or upgrading on Ubuntu
+=== Installing or upgrading on Debian 6 or Ubuntu
 
-John Leach from Brightbox has kindly provided a Ubuntu packages for Phusion Passenger. The packages are available from the link:http://wiki.brightbox.co.uk/docs:phusion-passenger[Brightbox repository]. Only packages for the open source version of Phusion Passenger are provided. link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customers should use the <<rubygems_generic_install,generic RubyGems installation method>> or <<tarball_generic_install,the generic tarball installation method>> instead.
+John Leach from Brightbox has kindly provided Ubuntu packages for Phusion Passenger. The Ubuntu Lucid packages are compatible with Debian 6. The packages are available from the link:http://wiki.brightbox.co.uk/docs:phusion-passenger[Brightbox repository]. Only packages for the open source version of Phusion Passenger are provided. link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customers should use the <<rubygems_generic_install,generic RubyGems installation method>> or <<tarball_generic_install,the generic tarball installation method>> instead.
 
-Add the following line to the Third Party Software Sources:
+If you use these packages to install Phusion Passenger then you do not need to run `passenger-install-apache2-module` or `passenger-install-nginx-module`. These packages contain all the binaries that you need.
 
----------------------------------------------
-deb http://apt.brightbox.net hardy main
----------------------------------------------
+.Apache
+
+On Ubuntu versions newer than 8.04 Hardy, register the Brightbox Apache PPA as follows:
+
+-----------------------------
+sudo apt-add-repository ppa:brightbox/passenger
+sudo apt-get update
+-----------------------------
+
+On Ubuntu 8.04 Hardy and on Debian, the `apt-add-repository` command isn't available so you have to install the repository and the key by hand.
+
+Debian 6:
+
+-----------------------------
+sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu lucid main" > /etc/apt/sources.list.d/brightbox-passenger.list'
+sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
+sudo apt-get update
+-----------------------------
+
+Ubuntu 8.04 Hardy:
 
-The simplest way to do that is to create a file in '/etc/apt/sources.list.d' containing the deb instruction, and then run `sudo apt-get update`.
+-----------------------------
+sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger.list'
+sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
+sudo apt-get update
+-----------------------------
 
-Once you've done that, you can proceed with installing Phusion Passenger by running:
+You can proceed with installing Phusion Passenger by running:
 
 ---------------------------------------------
 sudo apt-get install libapache2-mod-passenger
 ---------------------------------------------
 
-or, for the Nginx version:
+The Apache package provides configuration snippets for you, so you don't need to modify any Apache configuration to get it to load Phusion Passenger.
+
+.Nginx
+
+On Ubuntu versions newer than 8.04 Hardy, register the Brightbox Apache PPA as follows:
+
+-----------------------------
+sudo apt-add-repository ppa:brightbox/passenger-nginx
+sudo apt-get update
+-----------------------------
+
+On Ubuntu 8.04 Hardy and on Debian, the `apt-add-repository` command isn't available so you have to install the repository and the key by hand.
+
+Debian 6:
+
+-----------------------------
+sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger-nginx/ubuntu lucid main" > /etc/apt/sources.list.d/brightbox-passenger-nginx.list'
+sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
+sudo apt-get update
+-----------------------------
+
+Ubuntu 8.04 Hardy:
+
+-----------------------------
+sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger-nginx.list'
+sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
+sudo apt-get update
+-----------------------------
+
+Then:
 
 ---------------------------------------------
-sudo apt-get install nginx-brightbox
+sudo apt-get install nginx-full
 ---------------------------------------------
 
-Please also visit link:http://wiki.brightbox.co.uk/docs:phusion-passenger[the package's wiki page] for more documentation about this package.
+You'll then need to enable the Phusion Passenger module in Nginx by creating the following configuration file:
+
+-----------------------------------------------
+sudo sh -c 'echo "passenger_root /usr/lib/phusion-passenger;" > /etc/nginx/conf.d/passenger.conf'
+-----------------------------------------------
+
+Then restart Nginx to apply the changes:
+
+----------------------------------------
+sudo /etc/init.d/nginx restart
+----------------------------------------
+
+.Standalone
+
+Unfortunately, no packages are provided for Phusion Passenger Standalone.
 
 
 === Installing or upgrading on Red Hat, Fedora, CentOS or ScientificLinux
 
 YUM repositories with RPMs are maintained by link:https://github.com/erikogan/passenger[Erik Ogan] and link:http://stealthymonkeys.com/[Stealthy Monkeys Consulting]. Only packages for the open source version of Phusion Passenger are provided. link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customers should use the <<rubygems_generic_install,generic RubyGems installation method>> or <<tarball_generic_install,the generic tarball installation method>> instead.
 
+If you use YUM to install Phusion Passenger then you do not need to run `passenger-install-apache2-module` or `passenger-install-nginx-module`. The YUM packages contain all the binaries that you need. You also don't need to modify any Apache or Nginx configuration to get them to load Phusion Passenger, the packages provide configuration snippets for you as well.
+
 [float]
 ==== Step 1: Install the release package
 
@@ -365,13 +438,13 @@ From there you can use link:http://prefetch.net/articles/yum.html[YUM] to instal
 Phusion Passenger for Apache:
 
 ---------------------------------------------
-yum install nginx-passenger
+yum install mod_passenger
 ---------------------------------------------
 
 Phusion Passenger for Nginx:
 
 ---------------------------------------------
-yum install mod_passenger
+yum install nginx-passenger
 ---------------------------------------------
 
 Phusion Passenger Standalone:
@@ -408,13 +481,73 @@ By default, the installer (`passenger-install-nginx-module`) is interactive. If
 endif::[]
 
 
+=== Customizing the compilation process
+
+==== Setting the compiler
+
+You can force the Phusion Passenger build system to use a specific C or C++ compiler by setting the `CC` and `CXX` environment variables. These may be set to any arbitrary shell commands.
+
+For example, contributors who want to hack on Phusion Passenger may want to use Clang for faster compilation and link:http://ccache.samba.org/[ccache] for faster recompilation, and may want to enable more error-catching compilation flags:
+
+----------------------
+export CC='ccache clang -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
+export CXX='ccache clang++ -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
+----------------------
+
+==== Adding additional compiler or linker flags
+
+On some systems, C/C++ libraries and headers that Phusion Passenger requires may be located in a non-standard directory. You can force the Phusion Passenger build system to look in those locations by injecting compiler and linker flags using the following environment variables:
+
+`EXTRA_PRE_CFLAGS`::
+	These flags are injected into all C compiler invocations that involve compiling C or C++ source files. This includes compiler invocations that compile *and* link. The flags are injected at the beginning of the command string, even before `EXTRA_PRE_LDFLAGS`.
+`EXTRA_CFLAGS`::
+	Similar to `EXTRA_PRE_CFLAGS`, but injected at the end of the command string, before `EXTRA_LDFLAGS`.
+`EXTRA_PRE_CXXFLAGS`::
+	Similar to `EXTRA_PRE_CFLAGS`, but for C++ compiler invocations.
+`EXTRA_CXXFLAGS`::
+	Similar to `EXTRA_CFLAGS`, but for C++ compiler invocations.
+`EXTRA_PRE_LDFLAGS`::
+	These flags are injected into all C/C++ compiler invocations that involve linking. This includes compiler invocations that compile *and* link. The flags are injected at the beginning of the command string, but after `EXTRA_PRE_CFLAGS` and `EXTRA_PRE_CXXFLAGS`.
+`EXTRA_LDFLAGS`::
+	Similar to `EXTRA_PRE_LDFLAGS`, but injected at the very end of the command string, even after `EXTRA_CFLAGS` and `EXTRA_CXXFLAGS`.
+
+==== Forcing location of certain command line tools
+
+The Phusion Passenger build system attempts to autodetect many things by locating relevant helper tools. For example, to find out which compiler flags it should use for compiling Apache modules, it locates the `apxs2` command and queries it. To find out which compiler flags it should use for libcurl, it queries the `curl-config` command. These commands may not be in `$PATH`, or even when they are you may want to use a different one.
+
+You can often force the build to find certain command line tools at certain locations by using the following environment variables:
+
+`HTTPD`::
+	The location of the `httpd` executable (the Apache server executable).
+`APXS2`::
+	The location of the `apxs2` executable (the Apache module developer tool).
+`APR_CONFIG`::
+	The location of the `apr-config` executable (the Apache Portable Runtime developer tool).
+`APU_CONFIG`::
+	The location of the `apu-config` executable (the Apache Portable Runtime Utility developer tool).
+`MAKE`::
+	The location of a `make` tool. It does not matter which implementation of `make` this is.
+`GMAKE`::
+	The location of the GNU-compatible `make` tool.
+
+
 ifdef::apache[]
-[[locating_apache_conf]]
-=== Locating the Apache configuration file
+[[working_with_apache_conf]]
+=== Working with the Apache configuration file
 
-On most systems, the Apache configuration file is located in either '/etc/apache2/httpd.conf' or '/etc/apache2/apache2.conf'.
+On most systems the Apache configuration file is located in either '/etc/apache2/httpd.conf' or '/etc/apache2/apache2.conf'. However, to allow better organization, many operating systems and Apache distributions also read configuration files in the 'conf.d', 'mods-enabled' and 'sites-enabled' subdirectories.
 
-Not so on OS X Server >= 10.8 Mountain Lion with Web Services. If you do not use Web Services then the configuration file *is* in '/etc', but if you do use Web Services then the configuration file is in '/Library/Server/Web/Config/apache2/httpd_server_app.conf'.
+'mods-enabled' contains symlinks to files in 'mods-available'. This latter subdirectory contains config files for all available modules, while 'mods-enabled' contains only a subset, namely the modules that should actually be enabled. The symlinks are created using the `a2enmod` tool. '*.load' files contain `LoadModule` directives, while '*.conf' files contain all other configuration directives.
+
+Use 'mods-enabled'/'mods-available' to store Phusion Passenger configuration if you can:
+
+- Create '/etc/apache2/mods-available/passenger.load' and paste the `LoadModule ...` directive that `passenger-install-apache2-module` outputs.
+- Create '/etc/apache2/mods-available/passenger.conf' and paste the `PassengerRoot` and other Phusion Passenger options.
+- Enable by running `sudo a2enmod passenger`.
+
+If the 'mods-enabled' mechanism is not available then you can paste configuration snippets into 'httpd.conf' or 'apache2.conf' directly.
+
+On OS X Server >= 10.8 Mountain Lion the location of the Apache configuration file depends on whether you use Web Services or not. If you do, then the configuration file is in '/Library/Server/Web/Config/apache2/httpd_server_app.conf'. If you do not, then the configuration file is in '/etc/apache2/httpd.conf'.
 endif::[]
 
 
@@ -445,6 +578,18 @@ passenger_root /path-to-passenger-root;
 ------------------------------------------
 
 After having done so, restart Nginx.
+
+[[nginx_init_script]]
+=== Creating an Nginx init script
+
+If you installed Nginx with one of the generic installation methods then you won't have an init script to start, stop and restart Nginx with. A bare Nginx installation works with signals: you start it by invoking it from the command line, you stop it by sending SIGTERM to it and you gracefully restart it by sending SIGHUP to it.
+
+If you prefer to use an init script then please refer to the following resources:
+
+- link:http://wiki.nginx.org/Nginx-init-ubuntu[Init script for Ubuntu]
+- link:http://wiki.nginx.org/RedHatNginxInitScript[Init script for Red Hat, Fedora and CentOS]
+
+When using one of those init scripts, please make sure that the paths inside the init script are correct. In particular, the paths to the Nginx binary, to the PID file and to the configuration file must match the actual locations of your Nginx installation.
 endif::[]
 
 
@@ -587,7 +732,7 @@ mv /opt/passenger/passenger-4.0.0 /usr/local/passenger-4.0.0
 
 Next you must tell your web server that Phusion Passenger has moved.
 ifdef::apache[]
-Open your <<locating_apache_conf,Apache configuration file>> and set the 'PassengerRoot' directive to the new location:
+Open your <<working_with_apache_conf,Apache configuration file>> and set the 'PassengerRoot' directive to the new location:
 
 ---------------------------------------------
 PassengerRoot /usr/local/passenger-4.0.0