passenger 4.0.5 → 4.0.6

data/doc/Users guide Nginx.idmap.txt

@@ -56,7 +56,7 @@
 
 2.9.2. Adding additional compiler or linker flags	=>	adding-additional-compiler-or-linker-flags-1jehjon
 
-2.9.3. Forcing location of certain command line tools	=>	forcing-location-of-certain-command-line-tools-1j93cki
+2.9.3. Forcing location of command line tools and dependencies	=>	forcing-location-of-certain-command-line-tools-1j93cki
 
 2.10. Installing as a normal Nginx module without using the installer	=>	installing-as-a-normal-nginx-module-without-using-the-installer-1kkpes5
 
@@ -130,89 +130,91 @@
 
 6.8. passenger_temp_dir <directory>	=>	passenger-temp-dir-directory--1t3opri
 
-6.9. Important deployment options	=>	important-deployment-options-av567
+6.9. passenger_fly_with <socket filename>	=>	passenger-fly-with-socket-filename--1amd1xn
 
-6.9.1. passenger_enabled <on|off>	=>	passenger-enabled-on-off--1rpb2t7
+6.10. Important deployment options	=>	important-deployment-options-av567
 
-6.9.2. passenger_base_uri <uri>	=>	passenger-base-uri-uri--1xtuo50
+6.10.1. passenger_enabled <on|off>	=>	passenger-enabled-on-off--1rpb2t7
 
-6.10. Connection handling options	=>	connection-handling-options-8jgq90
+6.10.2. passenger_base_uri <uri>	=>	passenger-base-uri-uri--1xtuo50
 
-6.10.1. passenger_ignore_client_abort <on|off>	=>	passenger-ignore-client-abort
+6.11. Connection handling options	=>	connection-handling-options-8jgq90
 
-6.10.2. passenger_set_cgi_param <CGI environment name> <value>	=>	passenger-set-cgi-param-cgi-environment-name-value--rx9gc0
+6.11.1. passenger_ignore_client_abort <on|off>	=>	passenger-ignore-client-abort
 
-6.10.3. passenger_pass_header <header name>	=>	passenger-pass-header-header-name--1cg31je
+6.11.2. passenger_set_cgi_param <CGI environment name> <value>	=>	passenger-set-cgi-param-cgi-environment-name-value--rx9gc0
 
-6.10.4. passenger_buffer_response <on|off>	=>	passenger-buffer-response
+6.11.3. passenger_pass_header <header name>	=>	passenger-pass-header-header-name--1cg31je
 
-6.10.5. passenger_buffer_size	=>	passenger-buffer-size-1jfkq87
+6.11.4. passenger_buffer_response <on|off>	=>	passenger-buffer-response
 
-6.10.6. passenger_buffers	=>	passenger-busy-buffers
+6.11.5. passenger_buffer_size	=>	passenger-buffer-size-1jfkq87
 
-6.10.7. passenger_busy_buffer_size	=>	passenger-busy-buffer-size-124sj61
+6.11.6. passenger_buffers	=>	passenger-busy-buffers
 
-6.11. Security options	=>	security-options-1bv93g4
+6.11.7. passenger_busy_buffer_size	=>	passenger-busy-buffer-size-124sj61
 
-6.11.1. passenger_user_switching <on|off>	=>	passenger-user-switching-on-off--1p37u3l
+6.12. Security options	=>	security-options-1bv93g4
 
-6.11.2. passenger_user <username>	=>	passenger-user-username--b06ur7
+6.12.1. passenger_user_switching <on|off>	=>	passenger-user-switching-on-off--1p37u3l
 
-6.11.3. passenger_group <group name>	=>	passenger-user-group-name--1fco4j7
+6.12.2. passenger_user <username>	=>	passenger-user-username--b06ur7
 
-6.11.4. passenger_default_user <username>	=>	passenger-default-user-username--1h6cdmf
+6.12.3. passenger_group <group name>	=>	passenger-user-group-name--1fco4j7
 
-6.11.5. Passenger_default_group <group name>	=>	passenger-default-group-group-name--1qxn2qa
+6.12.4. passenger_default_user <username>	=>	passenger-default-user-username--1h6cdmf
 
-6.11.6. passenger_show_version_in_header <on|off>	=>	passenger-show-version-in-header-on-off--2h49av
+6.12.5. Passenger_default_group <group name>	=>	passenger-default-group-group-name--1qxn2qa
 
-6.11.7. passenger_friendly_error_pages <on|off>	=>	passenger-friendly-error-pages-on-off--1ti1a0e
+6.12.6. passenger_show_version_in_header <on|off>	=>	passenger-show-version-in-header-on-off--2h49av
 
-6.12. Resource control and optimization options	=>	resource-control-and-optimization-options-xd7evs
+6.12.7. passenger_friendly_error_pages <on|off>	=>	passenger-friendly-error-pages-on-off--1ti1a0e
 
-6.12.1. passenger_max_pool_size <integer>	=>	passenger-max-pool-size-integer--3jzefs
+6.13. Resource control and optimization options	=>	resource-control-and-optimization-options-xd7evs
 
-6.12.2. passenger_min_instances <integer>	=>	passenger-min-instances-integer--uclykt
+6.13.1. passenger_max_pool_size <integer>	=>	passenger-max-pool-size-integer--3jzefs
 
-6.12.3. passenger_max_instances <integer>	=>	passenger-max-instances
+6.13.2. passenger_min_instances <integer>	=>	passenger-min-instances-integer--uclykt
 
-6.12.4. passenger_max_instances_per_app <integer>	=>	passenger-max-instances-per-app-integer--1xhbbne
+6.13.3. passenger_max_instances <integer>	=>	passenger-max-instances
 
-6.12.5. passenger_pool_idle_time <integer>	=>	passenger-pool-idle-time-integer--xcw65o
+6.13.4. passenger_max_instances_per_app <integer>	=>	passenger-max-instances-per-app-integer--1xhbbne
 
-6.12.6. passenger_max_preloader_idle_time <integer>	=>	rails-app-spawner-idle-time-integer--1xjqe4b
+6.13.5. passenger_pool_idle_time <integer>	=>	passenger-pool-idle-time-integer--xcw65o
 
-6.12.7. passenger_concurrency_model <process|thread>	=>	passenger-concurrency-model-process-thread--brcvkk
+6.13.6. passenger_max_preloader_idle_time <integer>	=>	rails-app-spawner-idle-time-integer--1xjqe4b
 
-6.12.8. passenger_thread_count <number>	=>	passenger-thread-count-number--1kd6ffy
+6.13.7. passenger_concurrency_model <process|thread>	=>	passenger-concurrency-model-process-thread--brcvkk
 
-6.12.9. passenger_max_requests <integer>	=>	passenger-max-requests-integer--sgzint
+6.13.8. passenger_thread_count <number>	=>	passenger-thread-count-number--1kd6ffy
 
-6.12.10. passenger_max_request_time <seconds>	=>	passenger-max-request-time-seconds--1htog2g
+6.13.9. passenger_max_requests <integer>	=>	passenger-max-requests-integer--sgzint
 
-6.12.11. passenger_memory_limit <integer>	=>	passenger-memory-limit-integer--1ry7dwx
+6.13.10. passenger_max_request_time <seconds>	=>	passenger-max-request-time-seconds--1htog2g
 
-6.12.12. passenger_pre_start <url>	=>	passenger-pre-start-url--npldeb
+6.13.11. passenger_memory_limit <integer>	=>	passenger-memory-limit-integer--1ry7dwx
 
-6.13. Logging and debugging options	=>	logging-and-debugging-options-14e91ni
+6.13.12. passenger_pre_start <url>	=>	passenger-pre-start-url--npldeb
 
-6.13.1. passenger_log_level <integer>	=>	passenger-log-level-integer--17snhon
+6.14. Logging and debugging options	=>	logging-and-debugging-options-14e91ni
 
-6.13.2. passenger_debug_log_file <filename>	=>	passenger-debug-log-file-filename--21ubaj
+6.14.1. passenger_log_level <integer>	=>	passenger-log-level-integer--17snhon
 
-6.13.3. passenger_debugger <on|off>	=>	passenger-debugger-on-off--1wkuq85
+6.14.2. passenger_debug_log_file <filename>	=>	passenger-debug-log-file-filename--21ubaj
 
-6.14. Ruby on Rails-specific options	=>	ruby-on-rails-specific-options-12vfokt
+6.14.3. passenger_debugger <on|off>	=>	passenger-debugger-on-off--1wkuq85
 
-6.14.1. rails_env <string>	=>	rails-env-string--jlh7v9
+6.15. Ruby on Rails-specific options	=>	ruby-on-rails-specific-options-12vfokt
 
-6.15. Rack and Rails >= 3 specific options	=>	rack-specific-options-13yvdxs
+6.15.1. rails_env <string>	=>	rails-env-string--jlh7v9
 
-6.15.1. rack_env <string>	=>	rack-env-string--tqmrt0
+6.16. Rack and Rails >= 3 specific options	=>	rack-specific-options-13yvdxs
 
-6.16. Deprecated options	=>	deprecated-options-1dtzo0g
+6.16.1. rack_env <string>	=>	rack-env-string--tqmrt0
 
-6.16.1. rails_spawn_method	=>	rails-spawn-method-17vdnpt
+6.17. Deprecated options	=>	deprecated-options-1dtzo0g
+
+6.17.1. rails_spawn_method	=>	rails-spawn-method-17vdnpt
 
 7. Analysis and system maintenance	=>	analysis-and-system-maintenance-1nnlnj8
 
@@ -228,14 +230,24 @@
 
 8. Tips	=>	tips-n4c22d
 
-8.1. User switching (security)	=>	user-switching-security--zmsy9o
+8.1. User Switching (security feature)	=>	user-switching-security--zmsy9o
+
+8.1.1. Requirements	=>	requirements-15ozqdj
+
+8.1.2. Effects	=>	effects-nd2m44
 
-8.2. Reducing memory consumption of Ruby on Rails applications by 33%	=>	reducing-memory-consumption-of-ruby-on-rails-applications-by-33--1o3z66q
+8.1.3. Caveats & troubleshooting	=>	caveats-troubleshooting-mbw582
+
+8.1.4. Finding out what user an application is running as	=>	finding-out-what-user-an-application-is-running-as-1ni7zk6
+
+8.2. Copy-on-write memory support (reducing memory consumption of Ruby applications)	=>	reducing-memory-consumption-of-ruby-on-rails-applications-by-33--1o3z66q
 
 8.3. Capistrano recipe	=>	capistrano-recipe-pfn4qu
 
 8.4. Bundler support	=>	bundler-support-19v1h43
 
+8.4.1. Does Phusion Passenger itself need to be added to the Gemfile?	=>	does-phusion-passenger-itself-need-to-be-added-to-the-gemfile--xn1a11
+
 8.5. Installing multiple Ruby on Rails versions	=>	installing-multiple-ruby-on-rails-versions-1bp1fff
 
 8.6. Making the application restart after each request	=>	making-the-application-restart-after-each-request-vimy48
@@ -244,6 +256,18 @@
 
 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
 
+8.9. Flying Passenger	=>	flying-passenger-137qg5e
+
+8.9.1. Requirements	=>	requirements-194ysj6
+
+8.9.2. Basic usage	=>	basic-usage-1qtgvwx
+
+8.9.3. Configuring Flying Passenger	=>	configuring-flying-passenger-n558np
+
+8.9.4. Managing the Flying Passenger daemon	=>	managing-the-flying-passenger-daemon-vjmzdh
+
+8.9.5. Caveats and limitations	=>	caveats-and-limitations-15wakf
+
 9. Under the hood	=>	under-the-hood-8uney
 
 9.1. Page caching support	=>	page-caching-support-nafhf6
@@ -280,3 +304,23 @@
 
 12.5. Smart spawning gotcha #3: code load order	=>	smart-spawning-gotcha-3-code-load-order-12ydsn8
 
+13. Appendix D: About environment variables	=>	appendix-d-about-environment-variables-1t2cuff
+
+13.1. Working with environment variables	=>	working-with-environment-variables-1kmvq8w
+
+13.2. The PATH environment variable	=>	the-path-environment-variable-vlp05e
+
+13.3. Making environment variables permanent	=>	making-environment-variables-permanent-1wjyhzt
+
+13.3.1. bash	=>	bash-19xsxec
+
+13.3.2. Apache	=>	apache-9hqtyj
+
+13.3.3. Nginx	=>	nginx-157dpwy
+
+13.3.4. cron	=>	cron-1nuc9cz
+
+13.3.5. Phusion Passenger-served apps	=>	phusion-passenger-served-apps-uiewl5
+
+13.4. Environment variables and sudo	=>	environment-variables-and-sudo-10lphxn
+

data/doc/Users guide Nginx.txt

@@ -460,6 +460,8 @@ this option as well. Please read
 
 This required option may only occur once, in the 'http' configuration block.
 
+NOTE: This option has no effect when you are using <<flying_passenger,Flying Passenger>>.
+
 [[PassengerRuby]]
 === passenger_ruby <filename> ===
 The `passenger_ruby` option allows one to specify the Ruby interpreter to use. Similarly, the `passenger_python` option is for specifying the Python interpreter.
@@ -687,6 +689,17 @@ sudo -E passenger-status
 # The -E option tells 'sudo' to preserve environment variables.
 ----------------------------------------------------------
 
+:option: `--temp-dir`
+include::users_guide_snippets/alternative_for_flying_passenger.txt[]
+
+=== passenger_fly_with <socket filename>
+:version: 4.1.0
+include::users_guide_snippets/enterprise_only.txt[]
+
+Enables <<flying_passenger,Flying Passenger>> mode, and configures Nginx to connect to the Flying Passenger daemon that's listening on the given socket filename.
+
+This option may only occur once, in the 'http' configuration block. When not set, Flying Passenger is not enabled.
+
 === Important deployment options ===
 ==== passenger_enabled <on|off> ====
 This option may be specified in the 'http' configuration block, a
@@ -878,6 +891,9 @@ Whether to enable <<user_switching,user switching support>>.
 This option may only occur once, in the 'http' configuration block.
 The default value is 'on'.
 
+NOTE: This option has no effect when you are using <<flying_passenger,Flying Passenger>>. You can disable user switching for Flying Passenger by starting the Flying Passenger daemon as a non-root user.
+
+[[PassengerUser]]
 ==== passenger_user <username> ====
 If <<user_switching,user switching support>> is enabled, then Phusion Passenger will
 by default run the web application as the owner of the file 'config/environment.rb'
@@ -894,6 +910,7 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once.
 
+[[PassengerGroup]]
 ==== passenger_group <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
@@ -922,6 +939,8 @@ 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'.
 
+NOTE: This option has no effect when you are using <<flying_passenger,Flying Passenger>>. There is currently no way to set this option when using Flying Passenger, but if you want to disable user switching for Flying Passenger then you can do so by starting the Flying Passenger daemon as a non-root user.
+
 [[PassengerDefaultGroup]]
 ==== Passenger_default_group <group name> ====
 Phusion Passenger enables <<user_switching,user switching support>> by default.
@@ -932,6 +951,8 @@ 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>>.
 
+NOTE: This option has no effect when you are using <<flying_passenger,Flying Passenger>>. There is currently no way to set this option when using Flying Passenger, but if you want to disable user switching for Flying Passenger then you can do so by starting the Flying Passenger daemon as a non-root 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:
 
@@ -956,6 +977,7 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once. The default value is 'on'.
 
+[[PassengerFriendlyErrorPages]]
 ==== 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
@@ -988,6 +1010,9 @@ If you find that your server is running out of memory then you should lower this
 This option may only occur once, in the 'http' configuration block.
 The default value is '6'.
 
+:option: `--max-pool-size`
+include::users_guide_snippets/alternative_for_flying_passenger.txt[]
+
 [[PassengerMinInstances]]
 ==== passenger_min_instances <integer> ====
 This specifies the minimum number of application processes that should exist for a
@@ -1115,6 +1140,9 @@ 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'.
 
+:option: `--pool-idle-time`
+include::users_guide_snippets/alternative_for_flying_passenger.txt[]
+
 ==== passenger_max_preloader_idle_time <integer> ====
 The ApplicationSpawner server (explained in <<spawning_methods_explained,Spawning
 methods explained>>) has an idle timeout, just like the backend processes spawned by
@@ -1141,6 +1169,9 @@ This option may occur in the following places:
 
 In each place, it may be specified at most once. The default value is '300' (5 minutes).
 
+:option: `--max-preloader-idle-time`
+include::users_guide_snippets/alternative_for_flying_passenger.txt[]
+
 [[PassengerConcurrencyModel]]
 ==== passenger_concurrency_model <process|thread> ====
 :version: 4.0.0
@@ -1258,6 +1289,12 @@ fix the problem in your application rather than relying on these directives as a
 measure to avoid freezing applications.
 =====================================================
 
+[NOTE]
+=====================================================
+This option is currently only available for Ruby apps. It is not yet available
+for Python and Node.js.
+=====================================================
+
 [[PassengerMemoryLimit]]
 ==== passenger_memory_limit <integer> ====
 :version: 3.0.0
@@ -1328,6 +1365,8 @@ A few things to be careful of:
 This option may only occur in the 'http' configuration block. It may be specified
 any number of times.
 
+NOTE: This option is currently not available when using <<flying_passenger,Flying Passenger>>.
+
 ===== Example 1: basic usage =====
 
 Suppose that you have the following web applications.
@@ -1494,6 +1533,7 @@ Yes. And it does not perform any certificate validation.
 
 === Logging and debugging options ===
 
+[[PassengerLogLevel]]
 ==== 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
@@ -1518,6 +1558,9 @@ error messages should be written to instead.
 
 This option may only occur once, in the 'http' configuration block.
 
+:option: `--log-file`
+include::users_guide_snippets/alternative_for_flying_passenger.txt[]
+
 ==== passenger_debugger <on|off> ====
 :version: 3.0.0
 include::users_guide_snippets/enterprise_only.txt[]
@@ -1640,3 +1683,5 @@ include::users_guide_snippets/appendix_a_about.txt[]
 include::users_guide_snippets/appendix_b_terminology.txt[]
 
 include::users_guide_snippets/appendix_c_spawning_methods.txt[]
+
+include::users_guide_snippets/environment_variables.txt[]

data/doc/Users guide Standalone.html

@@ -1059,8 +1059,8 @@ pre {
 <body class="article">
 <div id="topbar" style="display: none">
 	<div class="title">
-		<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAsAAAAKCAYAAAEV95QVAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A/wD/oL2nkwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9sGCRMSACDxkZwAAAAidEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIEdJTVAgb24gYSBNYWOHqHdDAAAAZUlEQVQY032PSxbAIAjEIlfygL6ePF3UUvpzNjgSYWwqAMEhUQnANnsC7TQPeJpsVWzMuh2sog4vDTUbqP081zECrW4dtdaQGSIKlWluPyjK+VXxAz5XfcKufCzA130AfQHWB30HZxlPaP080xsAAAAASUVORK5CYII=" width="11" height="10" alt="">
-		<a href="javascript:void(Mizuho.smoothlyScrollToToc())">Phusion Passenger Standalone users guide</a>
+		<!-- Don't put a space between the img and a. That will break the hover layout. -->
+		<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAsAAAAKCAYAAAEV95QVAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A/wD/oL2nkwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9sGCRMSACDxkZwAAAAidEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIEdJTVAgb24gYSBNYWOHqHdDAAAAZUlEQVQY032PSxbAIAjEIlfygL6ePF3UUvpzNjgSYWwqAMEhUQnANnsC7TQPeJpsVWzMuh2sog4vDTUbqP081zECrW4dtdaQGSIKlWluPyjK+VXxAz5XfcKufCzA130AfQHWB30HZxlPaP080xsAAAAASUVORK5CYII=" width="11" height="10" alt=""><a href="javascript:void(Mizuho.smoothlyScrollToToc())">Phusion Passenger Standalone users guide</a>
 	</div>
 	<a href="javascript:void(0)" id="current_section"></a>
 </div>
@@ -1138,14 +1138,14 @@ if it doesn’t work on your POSIX-compliant operating system.</p></div>
 <div class="ulist"><ul>
 <li>
 <p>
-<a href="http://code.google.com/p/phusion-passenger/issues/list">Issue tracker</a> - report
-  bugs here.
+<a href="http://groups.google.com/group/phusion-passenger">Discussion forum</a> - post a
+  message here if you’re experiencing problems. Support on this forum is provided by the community on a best-effort basis, so a (timely) response is not guaranteed.
 </p>
 </li>
 <li>
 <p>
-<a href="http://groups.google.com/group/phusion-passenger">Discussion forum</a> - post a
-  message here if you’re experiencing problems. Support on this forum is provided by the community on a best-effort basis, so a (timely) response is not guaranteed.
+<a href="http://code.google.com/p/phusion-passenger/issues/list">Issue tracker</a> - report
+  bugs here.
 </p>
 </li>
 <li>
@@ -1160,7 +1160,7 @@ Email <a href="mailto:support@phusion.nl">support@phusion.nl</a> if you are a <a
 </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.
+Report security vulnerabilities to <a href="mailto:security@phusion.nl">security@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>

data/doc/users_guide_snippets/alternative_for_flying_passenger.txt

@@ -0,0 +1 @@
+NOTE: This option has no effect when you are using <<flying_passenger,Flying Passenger>>. Instead, you should configure this by passing the {option} command line option to the Flying Passenger daemon.

data/doc/users_guide_snippets/environment_variables.txt

@@ -0,0 +1,221 @@
+[[about_environment_variables]]
+== Appendix D: About environment variables
+
+The Phusion Passenger compilation process can be customized with environment variables.
+
+Environment variables are named values that affect how the system works. For example they tell the system where to look for commands (the `PATH` variable) or where to look for libraries (`LD_LIBRARY_PATH`). Their names are often in all-uppercase. Sometimes people refer to an environment variable with a dollar sign `$` in front, but that's the same thing: when people say "the $PATH environment variable" they mean "the PATH environment variable". This is because the dollar sign `$` is a shell syntax for refering to an environment variable, as you will learn later.
+
+Environment variables are set on a **per-process** basis, but they are **inherited** by child processes. This means that if you set environment variables in process A, another already running process B will not see these new environment variables. But if A spawns a child process C, then C will have all environment variables that A had. If you once again change the environment variables in A, then C will not see the changes.
+
+The per-process nature of environment variables some implications. When you set environment variables in your `bashrc` or other bash startup files...
+
+ * ...only newly spawned bash shells see them.
+ * ...the web server usually does not see them, because the web server tends to be started from init scripts, not from bash.
+ * ...cron jobs do not see them, because cron jobs' environment variables are entirely dictated by their crontabs.
+
+NOTE: Because this chapter is meant for beginners, it assumes that the reader uses the bash shell. This chapter does not describe instructions for zsh, csh or other shells. We assume that users of other shells are familiar with the Bourne shell syntax, and know how to apply the instructions in this chapter in their shells' native syntaxes.
+
+=== Working with environment variables
+
+You can see all environment variables in your shell by running the following command:
+
+[source,sh]
+---------------------------------
+env
+---------------------------------
+
+You can set an evironment variable with the syntax `export <NAME>=<VALUE>`. For example, to set the `APXS2` variable to the value `/usr/sbin/apxs2`:
+
+[source,sh]
+---------------------------------
+export APXS2=/usr/sbin/apxs2
+---------------------------------
+
+Any process that you run from your shell from that point on will have said environment variable:
+
+[source,sh]
+---------------------------------
+export APXS2=/usr/sbin/apxs2
+ruby -e 'p ENV["APXS2"]'
+# => "/usr/sbin/apxs2"
+---------------------------------
+
+.The "export" keyword is important
+[NOTE]
+===================================================
+You **must** set the `export` keyword. If you omit the `export` keyword then the environment variable will not be visible to other processes:
+
+[source,sh]
+---------------------------------
+APXS2=/usr/sbin/apxs2
+ruby -e 'p ENV["APXS2"]'
+# => nil
+---------------------------------
+===================================================
+
+You can reference an environment variable in your shell by typing the `$` sign followed by the environment variable's name. For example, to see the value of the `PATH` variable:
+
+[source,sh]
+---------------------------------
+echo $PATH
+---------------------------------
+
+You can also use this trick to extend the value of an environment variable:
+
+[source,sh]
+---------------------------------
+export PATH=/usr/bin
+
+# Prepends '/opt/local/bin', so that it becomes /opt/local/bin:/usr/bin
+export PATH=/opt/local/bin:$PATH
+# Appends '/usr/local/bin', so that it becomes /opt/local/bin:/usr/bin:/usr/local/bin
+export PATH=$PATH:/usr/local/bin
+---------------------------------
+
+=== The PATH environment variable
+
+The `PATH` environment variable dictates where the system looks for command. It is a colon-separated list of directories. If you get a "command not found" error while you know that the command is installed, then setting `PATH` will help. For example suppose that the command `frobnicator` is in `/opt/local/bin`:
+
+[source,sh]
+----------------------
+user@localhost bash$ frobnicator
+bash: frobnicator: command not found
+----------------------
+
+We verify that `/opt/local/bin` is not in `PATH`:
+
+[source,sh]
+----------------------
+user@localhost bash$ echo $PATH
+/bin:/usr/bin:/usr/local/bin
+----------------------
+
+We can run `frobnicator` through it's full path...
+
+[source,sh]
+----------------------
+user@localhost bash$ /opt/local/bin/frobnicator
+# => success!
+----------------------
+
+...or we can add `/opt/local/bin` to `PATH`.
+
+[source,sh]
+----------------------
+user@localhost bash$ export PATH=$PATH:/opt/local/bin
+user@localhost bash$ frobnicator
+# => success!
+----------------------
+
+=== Making environment variables permanent
+
+When you exit your shell, the evironment variable changes are lost. There is no standard method to set environment variables system-wide, so you have to set them in different configuration files for different services.
+
+==== bash
+
+To make environment variables permanent for future bash sessions **for the current user**, add them to your `~/.bashrc`:
+
+[source,sh]
+---------------------------------
+echo 'export FOO=bar' >> ~/.bashrc
+echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bashrc
+---------------------------------
+
+To make them permanent for future bash sessions **for all users**, add them to `/etc/bashrc`.
+
+NOTE: Depending on the system, the bashrc file may have a different filename. On Debian and Ubuntu, it's `/etc/bash.bashrc`.
+
+==== Apache
+
+NOTE: This subsection describes how to set environment variables on Apache itself, not on apps served through Phusion Passenger for Apache. The environment variables you set here will be passed to all apps, but you cannot customize them on a per-app basis. See also <<env_vars_passenger_apps,Setting environment variables on Phusion Passenger-served apps>>.
+
+On Debian and Ubuntu, with an Apache installed through apt, Apache environment variables are defined in the file `/etc/apache2/envvars`. This is a shell script so environment variables must be specified with the shell syntax.
+
+On Red Hat, Fedora, CentOS and ScientificLinux, with an Apache installed through YUM, Apache environment variables are defined in `/etc/sysconfig/httpd`.
+
+On OS X they are defined in `/System/Library/LaunchDaemons/org.apache.httpd.plist`, as explained link:/System/Library/LaunchDaemons/org.apache.httpd.plist[here on Stack Overflow].
+
+On other systems, or if you did not install Apache through the system's package manager, the configuration file for environment variables is specific to the vendor that supplied Apache. There may not even be such a configuration file. You should contact the vendor for support.
+
+==== Nginx
+
+NOTE: This subsection describes how to set environment variables on Nginx itself, not on apps served through Phusion Passenger for Nginx. The environment variables you set here will be passed to all apps, but you cannot customize them on a per-app basis. See also <<env_vars_passenger_apps,Setting environment variables on Phusion Passenger-served apps>>.
+
+If you installed Nginx through <<install_on_debian_ubuntu,the Brightbox packages>>, then you can define environment variables in `/etc/default/nginx`. This is a shell script so you must use the `export FOO=bar` syntax.
+
+Otherwise, environment variables are best set through the script which starts Nginx. For example, if you installed Nginx from source and you used
+ifdef::apache[]
+the Nginx init script described in the link:http://www.modrails.com/documentation/Users%20guide%20Nginx.html[Phusion Passenger Users Guide, Nginx version],
+endif::apache[]
+ifdef::nginx[]
+<<nginx_init_script,the Nginx init script described earlier in this manual,
+endif::nginx[]
+then you should edit that script to define the environment variables. Those init scripts are regular shell scripts, so use the `export FOO=bar` syntax. Just make sure your set your environment variables before the script starts Nginx.
+
+NOTE: Setting environment variables on Nginx has no effect on the <<flying_passenger,Flying Passenger daemon>> because the daemon is started seperately. You should set the environment variables in the shell right before starting the daemon.
+
+==== cron
+
+To make environment variables permanent for cron jobs, add those variables to the relevant crontab. But note that inside crontabs you cannot refer to existing environment variables with the `$` syntax because crontabs are not shell scripts. You have to specify the entire value.
+
+.What to put in "crontab -e"
+-------------------------
+# Environment variable definitions
+FOO=bar
+APXS2=/usr/sbin/apxs2
+
+# **WRONG!** You cannot refer to existing variables with the `$` syntax!
+PATH=/usr/bin:$PATH
+# **WRONG!** You cannot use the 'export' keyword!
+export PATH=/usr/bin:/usr/local/bin
+# Correct:
+PATH=/usr/bin:/usr/local/bin
+
+# Jobs:
+# m h  dom mon dow   command
+  * *  *   *   *     frobnicator
+-------------------------
+
+[[env_vars_passenger_apps]]
+==== Phusion Passenger-served apps
+
+You can pass environment variables to Phusion Passenger-served apps through various methods:
+
+ * When running Apache, use the `PassEnv` and `SetEnv` directives of link:http://httpd.apache.org/docs/2.4/mod/mod_env.html[mod_env]. This is supported starting from Phusion Passenger 4.0.
+ * When running Nginx, use the `env` directive. Unlike Apache, Nginx's `env` directive can only be set globally and cannot be customized on a per-virtual host basis.
+ * Through your `bashrc`. Starting from version 4.0, Phusion Passenger 4.0 spawns applications through bash and inherit all bash environment variables. Phusion Passenger Standalone tends to be started from the shell and thus inherits all environment variables set by the shell.
+ * Through Apache and Nginx, as described earlier in this chapter. Any environment variables that you set on Apache and Nginx itself are inherited by Phusion Passenger, and thus by Phusion Passenger-served apps as well.
+ * Through the application itself. Most programming languages provide APIs for setting environment variables. For example in Ruby you can write:
++
+[source,ruby]
+-------------------
+ENV['FOO'] = 'bar'
+-------------------
++
+In Python you can write:
++
+[source,python]
+-------------------
+import os
+os.environ['FOO'] = 'bar'
+-------------------
+
+[[env_vars_and_sudo]]
+=== Environment variables and sudo
+
+The `sudo` command resets all environment variables before running the specified command, for security reasons. So if you set environment variables before running `sudo passenger-install-xxx-module`, `sudo passenger-status` or any other commands, then the environment variables are not correctly passed to the command. You can solve this by running sudo with `-E` (preserve environment variables):
+
+[source,sh]
+-------------------------
+user@localhost bash$ export APXS2=/usr/sbin/apxs2
+user@localhost bash$ sudo -E passenger-install-apache2-module
+-------------------------
+
+Alternatively, you can obtain a root prompt with sudo first, and *then* set the environment variables, before running any further commands:
+
+-------------------------
+user@localhost bash$ sudo -s
+Password: ...
+root@localhost bash# export APXS2=/usr/sbin/apxs2
+root@localhost bash# passenger-install-apache2-module
+-------------------------