passenger 5.0.14 → 5.0.15

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of passenger might be problematic. Click here for more details.

Files changed (70) hide show
  1. checksums.yaml +8 -8
  2. checksums.yaml.gz.asc +7 -7
  3. data.tar.gz.asc +7 -7
  4. data/CHANGELOG +9 -0
  5. data/INSTALL.md +1 -1
  6. data/LICENSE +1 -1
  7. data/README.md +1 -1
  8. data/bin/passenger-install-apache2-module +6 -10
  9. data/bin/passenger-install-nginx-module +6 -9
  10. data/doc/CloudLicensingConfiguration.html +1 -216
  11. data/doc/CloudLicensingConfiguration.txt.md +1 -192
  12. data/doc/Design and Architecture.html +4 -4
  13. data/doc/Design and Architecture.txt +4 -4
  14. data/doc/ServerOptimizationGuide.html +1 -489
  15. data/doc/ServerOptimizationGuide.txt.md +1 -399
  16. data/doc/Users guide Apache.html +594 -6720
  17. data/doc/Users guide Apache.idmap.txt +15 -12
  18. data/doc/Users guide Apache.txt +113 -2047
  19. data/doc/Users guide Nginx.html +565 -6720
  20. data/doc/Users guide Nginx.idmap.txt +15 -12
  21. data/doc/Users guide Nginx.txt +94 -1862
  22. data/doc/Users guide Standalone.html +53 -2183
  23. data/doc/Users guide Standalone.idmap.txt +9 -6
  24. data/doc/Users guide Standalone.txt +16 -360
  25. data/doc/Users guide.html +3 -145
  26. data/doc/Users guide.txt +2 -54
  27. data/doc/users_guide_snippets/analysis_and_system_maintenance.txt +36 -175
  28. data/doc/users_guide_snippets/appendix_c_spawning_methods.txt +9 -215
  29. data/doc/users_guide_snippets/environment_variables.txt +11 -243
  30. data/doc/users_guide_snippets/installation.txt +66 -946
  31. data/doc/users_guide_snippets/rackup_specifications.txt +1 -75
  32. data/doc/users_guide_snippets/support_information.txt +1 -48
  33. data/doc/users_guide_snippets/tips.txt +103 -704
  34. data/doc/users_guide_snippets/troubleshooting/default.txt +16 -130
  35. data/doc/users_guide_snippets/troubleshooting/rails.txt +15 -12
  36. data/doc/users_guide_snippets/under_the_hood/relationship_with_ruby.txt +2 -113
  37. data/ext/apache2/Configuration.hpp +2 -2
  38. data/ext/apache2/Hooks.cpp +2 -2
  39. data/ext/common/AgentsStarter.h +18 -10
  40. data/ext/common/ApplicationPool2/ErrorRenderer.h +0 -3
  41. data/ext/common/ApplicationPool2/Options.h +8 -1
  42. data/ext/common/Constants.h +3 -9
  43. data/ext/common/agent/Core/RequestHandler/InitRequest.cpp +2 -0
  44. data/ext/common/agent/Watchdog/Main.cpp +1 -1
  45. data/ext/nginx/ContentHandler.c +2 -3
  46. data/ext/nginx/config +2 -2
  47. data/lib/phusion_passenger.rb +1 -22
  48. data/lib/phusion_passenger/abstract_installer.rb +10 -10
  49. data/lib/phusion_passenger/config/agent_compiler.rb +5 -5
  50. data/lib/phusion_passenger/config/nginx_engine_compiler.rb +4 -4
  51. data/lib/phusion_passenger/config/validate_install_command.rb +3 -3
  52. data/lib/phusion_passenger/constants.rb +1 -5
  53. data/lib/phusion_passenger/loader_shared_helpers.rb +16 -5
  54. data/lib/phusion_passenger/platform_info/apache_detector.rb +2 -2
  55. data/lib/phusion_passenger/public_api.rb +11 -2
  56. data/lib/phusion_passenger/request_handler/thread_handler.rb +2 -3
  57. data/lib/phusion_passenger/ruby_core_io_enhancements.rb +4 -1
  58. data/lib/phusion_passenger/standalone/start_command.rb +1 -1
  59. data/resources/oss-binaries.phusionpassenger.com.crt +124 -0
  60. data/resources/templates/apache2/deployment_example.txt.erb +5 -23
  61. data/resources/templates/apache2/installing_against_a_different_apache.txt.erb +3 -4
  62. data/resources/templates/apache2/possible_solutions_for_compilation_and_installation_problems.txt.erb +3 -3
  63. data/resources/templates/apache2/rpm_installation_recommended.txt.erb +1 -1
  64. data/resources/templates/installer_common/low_amount_of_memory_warning.txt.erb +4 -5
  65. data/resources/templates/nginx/deployment_example.txt.erb +5 -17
  66. data/resources/templates/nginx/possible_solutions_for_compilation_and_installation_problems.txt.erb +3 -3
  67. data/resources/templates/standalone/config.erb +1 -1
  68. data/resources/templates/undisclosed_error.html.template +4 -11
  69. metadata +2 -2
  70. metadata.gz.asc +7 -7
@@ -94,18 +94,6 @@
94
94
 
95
95
  3.5. Rackup specifications for various web frameworks => rackup-specifications-for-various-web-frameworks-ndsqc2
96
96
 
97
- 3.5.1. Camping => camping-1kxexk0
98
-
99
- 3.5.2. Halcyon => halcyon-1ghnpmz
100
-
101
- 3.5.3. Mack => mack-miht6b
102
-
103
- 3.5.4. Merb => merb-iyj7qy
104
-
105
- 3.5.5. Ramaze => ramaze-boddtj
106
-
107
- 3.5.6. Sinatra => sinatra-1hubto4
108
-
109
97
  4. Deploying a WSGI (Python) application => deploying-a-wsgi-python-application-7aygdl
110
98
 
111
99
  4.1. Tutorial/example: writing and deploying a Hello World WSGI application => tutorial-example-writing-and-deploying-a-hello-world-wsgi-application-9ziqy8
@@ -446,3 +434,18 @@
446
434
 
447
435
  15.4. Environment variables and sudo => environment-variables-and-sudo-1odzcpz
448
436
 
437
+
438
+ ### These sections appear to have been removed. Please check.
439
+
440
+ 3.5.1. Camping => camping-1kxexk0
441
+
442
+ 3.5.2. Halcyon => halcyon-1ghnpmz
443
+
444
+ 3.5.3. Mack => mack-miht6b
445
+
446
+ 3.5.4. Merb => merb-iyj7qy
447
+
448
+ 3.5.5. Ramaze => ramaze-boddtj
449
+
450
+ 3.5.6. Sinatra => sinatra-1hubto4
451
+
@@ -3,19 +3,7 @@ Phusion Passenger users guide, Apache version
3
3
 
4
4
  image:images/phusion_banner.png[link="http://www.phusion.nl/"]
5
5
 
6
- Phusion Passenger is an application server which can directly integrate into Apache. It is designed to be easy to use, fast, stable and reliable and is used by link:http://trends.builtwith.com/Web-Server/Phusion-Passenger[hundreds of thousands of websites] all over the world.
7
-
8
- Phusion Passenger is a so-called polyglot application server because it supports applications written in multiple programming languages. At this time, Ruby and Python are supported.
9
-
10
- This users guide will teach you:
11
-
12
- - How to install Phusion Passenger.
13
- - How to configure Phusion Passenger.
14
- - How to deploy Ruby and Python applications.
15
- - How to solve common problems.
16
-
17
- This guide assumes that the reader is somewhat familiar with Apache and with
18
- using the command line.
6
+ This is the old, deprecated Passenger Standalone documentation. Please visit https://www.phusionpassenger.com/library/ for the new documentation.
19
7
 
20
8
 
21
9
  == Support information
@@ -30,192 +18,24 @@ include::users_guide_snippets/installation.txt[]
30
18
 
31
19
  == Deploying a Rack-based Ruby application ==
32
20
 
33
- Phusion Passenger supports arbitrary Ruby web applications that follow the
34
- link:http://rack.rubyforge.org/[Rack] interface.
35
-
36
- Phusion Passenger assumes that Rack application directories have a certain layout.
37
- Suppose that you have a Rack application in '/webapps/rackapp'. Then that
38
- folder must contain at least three entries:
39
-
40
- - 'config.ru', a Rackup file for starting the Rack application. This file must contain
41
- the complete logic for initializing the application.
42
- - 'public/', a folder containing public static web assets, like images and stylesheets.
43
- - 'tmp/', used for 'restart.txt' (our application restart mechanism). This will
44
- be explained in a following subsection.
45
-
46
- So '/webapps/rackapp' must, at minimum, look like this:
47
- ----------------------
48
- /webapps/rackapp
49
- |
50
- +-- config.ru
51
- |
52
- +-- public/
53
- |
54
- +-- tmp/
55
- ----------------------
56
-
57
- Suppose you own the domain 'www.rackapp.com'. You can either deploy your application
58
- to the virtual host's root (i.e. the application will be accessible from the root URL,
59
- 'http://www.rackapp.com/'), or in a sub URI (i.e. the application will be
60
- accessible from a sub URL, such as 'http://www.rackapp.com/rackapp').
61
-
62
- NOTE: The default `RACK_ENV` environment in which deployed Rack applications
63
- are run, is ``production''. You can change this by changing the
64
- <<rack_env,'RackEnv'>> configuration option.
21
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
65
22
 
66
23
  === Tutorial/example: writing and deploying a Hello World Rack application ===
67
24
 
68
- First we create a Phusion Passenger-compliant Rack directory structure:
69
-
70
- -------------------------------------------
71
- $ mkdir /webapps/rack_example
72
- $ mkdir /webapps/rack_example/public
73
- $ mkdir /webapps/rack_example/tmp
74
- -------------------------------------------
75
-
76
- Next, we write a minimal "hello world" Rack application:
77
-
78
- -------------------------------------------
79
- $ cd /webapps/rack_example
80
- $ some_awesome_editor config.ru
81
- ...type in some source code...
82
- $ cat config.ru
83
- app = proc do |env|
84
- [200, { "Content-Type" => "text/html" }, ["hello <b>world</b>"]]
85
- end
86
- run app
87
- -------------------------------------------
88
-
89
- Finally, we deploy it by adding the following configuration options to
90
- the Apache configuration file:
91
-
92
- -------------------------------------------
93
- <VirtualHost *:80>
94
- ServerName www.rackexample.com
95
- DocumentRoot /webapps/rack_example/public
96
- <Directory /webapps/rack_example/public>
97
- Allow from all
98
- Options -MultiViews
99
- # Uncomment this if you're on Apache >= 2.4:
100
- #Require all granted
101
- </Directory>
102
- </VirtualHost>
103
- -------------------------------------------
104
-
105
- And we're done! After an Apache restart, the above Rack application will be available
106
- under the URL 'http://www.rackexample.com/'.
25
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
107
26
 
108
27
  === Deploying to a virtual host's root ===
109
28
 
110
- Add a virtual host entry to your Apache configuration file. Make sure that the
111
- following conditions are met:
112
-
113
- - The virtual host's document root must point to your Rack application's
114
- 'public' folder.
115
- - The Apache per-directory permissions must allow access to this folder.
116
- - MultiViews must be disabled for this folder.
117
-
118
- For example:
119
- -------------------------------------------
120
- <VirtualHost *:80>
121
- ServerName www.rackapp.com
122
- DocumentRoot /webapps/rackapp/public
123
- <Directory /webapps/rackapp/public>
124
- Allow from all
125
- Options -MultiViews
126
- # Uncomment this if you're on Apache >= 2.4:
127
- #Require all granted
128
- </Directory>
129
- </VirtualHost>
130
- -------------------------------------------
131
-
132
- You may also need to tweak your file/folder permissions. Make sure that the
133
- following folders are readable and executable by Apache:
134
-
135
- * this 'public' folder.
136
- * the application's 'config' folder.
137
- * all parent folders. That is, /webapps/rackapp and /webapps must also be readable and executable by Apache.
138
-
139
- Then restart Apache. The application has now been deployed.
29
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
140
30
 
141
31
  [[deploying_rack_to_sub_uri]]
142
32
  === Deploying to a sub URI ===
143
33
 
144
- Suppose that you already have a virtual host:
145
-
146
- -------------------------------------------
147
- <VirtualHost *:80>
148
- ServerName www.phusion.nl
149
- DocumentRoot /websites/phusion
150
- <Directory /websites/phusion>
151
- Allow from all
152
- Options -MultiViews
153
- # Uncomment this if you're on Apache >= 2.4:
154
- #Require all granted
155
- </Directory>
156
- </VirtualHost>
157
- -------------------------------------------
158
-
159
- And you want your Rack application, located in `/websites/rack`, to be accessible from the URL
160
- 'http://www.phusion.nl/subapp'.
161
-
162
- To do this, you need to perform the following:
163
-
164
- 1. Set `Alias {SUBURI} {PATH TO YOUR APPLICATION'S PUBLIC DIRECTORY}`.
165
- 2. Create a `<Location /{SUBURI}>` block.
166
- 3. Inside the Location block, set `PassengerBaseURI /{SUBURI}`.
167
- 4. Inside the Location block, set `PassengerAppRoot {PATH TO YOUR APPLICATION ROOT}`.
168
- 5. Create a `<Directory {PATH TO YOUR APPLICATION'S PUBLIC DIRECTORY}>` block.
169
- 6. Inside the Directory block, set `Allow from all`, and (if you're on Apache >= 2.4) `Require all granted`.
170
- 7. Inside the Directory block, disable MultiViews.
171
-
172
- Here is an example:
173
-
174
- -------------------------------------------
175
- <VirtualHost *:80>
176
- ServerName www.phusion.nl
177
- DocumentRoot /websites/phusion
178
- <Directory /websites/phusion>
179
- Allow from all
180
- Options -MultiViews
181
- # Uncomment this if you're on Apache >= 2.4:
182
- #Require all granted
183
- </Directory>
184
-
185
- # These have been added:
186
- Alias /subapp /websites/rack/public
187
- <Location /subapp>
188
- PassengerBaseURI /subapp
189
- PassengerAppRoot /websites/rack
190
- </Location>
191
- <Directory /websites/rack/public>
192
- Allow from all
193
- Options -MultiViews
194
- # Uncomment this if you're on Apache >= 2.4:
195
- #Require all granted
196
- </Directory>
197
- </VirtualHost>
198
- -------------------------------------------
199
-
200
- Then restart Apache. The application has now been deployed to the sub-URI.
34
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
201
35
 
202
36
  === Redeploying (restarting the Rack application) ===
203
37
 
204
- Deploying a new version of a Rack application is as simple as
205
- re-uploading the application files, and restarting the application.
206
-
207
- There are two ways to restart the application:
208
-
209
- 1. By restarting Apache.
210
- 2. By creating or modifying the file 'tmp/restart.txt' in the Rack
211
- application's <<application_root,root folder>>. Phusion Passenger will
212
- automatically restart the application.
213
-
214
- For example, to restart our example application, we type this in the
215
- command line:
216
- -------------------------------------------
217
- touch /webapps/rackapp/tmp/restart.txt
218
- -------------------------------------------
38
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/restart_app.html
219
39
 
220
40
  === Rackup specifications for various web frameworks ===
221
41
  include::users_guide_snippets/rackup_specifications.txt[]
@@ -223,1548 +43,250 @@ include::users_guide_snippets/rackup_specifications.txt[]
223
43
 
224
44
  == Deploying a WSGI (Python) application
225
45
 
226
- Phusion Passenger supports all WSGI-compliant Python web applications. Suppose that you have a WSGI application in '/webapps/wsgiapp'. Then that folder must contain at least three entries:
227
-
228
- - 'passenger_wsgi.py', which Phusion Passenger will use as the main entry point for your application. This file must export a WSGI object called `application`.
229
- - 'public/', a folder containing public static web assets, like images and stylesheets.
230
- - 'tmp/', used for 'restart.txt' (our application restart mechanism). This will be explained in a following subsection.
231
-
232
- So '/webapps/wsgiapp' must, at minimum, look like this:
233
- ----------------------
234
- /webapps/wsgiapp
235
- |
236
- +-- passenger_wsgi.py
237
- |
238
- +-- public/
239
- |
240
- +-- tmp/
241
- ----------------------
46
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
242
47
 
243
48
  === Tutorial/example: writing and deploying a Hello World WSGI application ===
244
49
 
245
- First we create a Phusion Passenger-compliant WSGI directory structure:
246
-
247
- -------------------------------------------
248
- $ mkdir /webapps/wsgi_example
249
- $ mkdir /webapps/wsgi_example/public
250
- $ mkdir /webapps/wsgi_example/tmp
251
- -------------------------------------------
252
-
253
- Next, we write a minimal "hello world" WSGI application:
254
-
255
- -------------------------------------------
256
- $ cd /webapps/wsgi_example
257
- $ some_awesome_editor passenger_wsgi.py
258
- ...type in some source code...
259
- $ cat passenger_wsgi.py
260
- def application(environ, start_response):
261
- start_response('200 OK', [('Content-Type', 'text/plain')])
262
- return [b"hello world!\n"]
263
- -------------------------------------------
264
-
265
- Finally, we deploy it by adding the following configuration options to
266
- the Apache configuration file:
267
-
268
- -------------------------------------------
269
- <VirtualHost *:80>
270
- ServerName www.wsgiexample.com
271
- DocumentRoot /webapps/wsgi_example/public
272
- <Directory /webapps/wsgi_example/public>
273
- Allow from all
274
- Options -MultiViews
275
- # Uncomment this if you're on Apache >= 2.4:
276
- #Require all granted
277
- </Directory>
278
- </VirtualHost>
279
- -------------------------------------------
280
-
281
- And we're done! After an Apache restart, the above WSGI application will be available
282
- under the URL 'http://www.wsgiexample.com/'.
50
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
283
51
 
284
52
  === Deploying to a virtual host's root ===
285
53
 
286
- Add a virtual host entry to your Apache configuration file. Make sure that the
287
- following conditions are met:
288
-
289
- - The virtual host's document root must point to your WSGI application's
290
- 'public' folder.
291
- - The WSGI per-directory permissions must allow access to this folder.
292
- - MultiViews must be disabled for this folder.
293
-
294
- For example:
295
- -------------------------------------------
296
- <VirtualHost *:80>
297
- ServerName www.wsgiapp.com
298
- DocumentRoot /webapps/wsgiapp/public
299
- <Directory /webapps/wsgiapp/public>
300
- Allow from all
301
- Options -MultiViews
302
- # Uncomment this if you're on Apache >= 2.4:
303
- #Require all granted
304
- </Directory>
305
- </VirtualHost>
306
- -------------------------------------------
307
-
308
- You may also need to tweak your file/folder permissions. Make sure that the
309
- following folders are readable and executable by Apache:
310
-
311
- * this 'public' folder.
312
- * the application's 'config' folder.
313
- * all parent folders. That is, /webapps/wsgiapp and /webapps must also be readable and executable by Apache.
314
-
315
- Then restart Apache. The application has now been deployed.
54
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
316
55
 
317
56
  [[deploying_python_to_sub_uri]]
318
57
  === Deploying to a sub URI ===
319
58
 
320
- Suppose that you already have a virtual host:
321
-
322
- -------------------------------------------
323
- <VirtualHost *:80>
324
- ServerName www.phusion.nl
325
- DocumentRoot /websites/phusion
326
- <Directory /websites/phusion>
327
- Allow from all
328
- Options -MultiViews
329
- # Uncomment this if you're on Apache >= 2.4:
330
- #Require all granted
331
- </Directory>
332
- </VirtualHost>
333
- -------------------------------------------
334
-
335
- And you want your Python application, located in `/websites/python`, to be accessible from the URL
336
- 'http://www.phusion.nl/subapp'.
337
-
338
- To do this, you need to perform the following:
339
-
340
- 1. Set `Alias {SUBURI} {PATH TO YOUR APPLICATION'S PUBLIC DIRECTORY}`.
341
- 2. Create a `<Location /{SUBURI}>` block.
342
- 3. Inside the Location block, set `PassengerBaseURI /{SUBURI}`.
343
- 4. Inside the Location block, set `PassengerAppRoot {PATH TO YOUR APPLICATION ROOT}`.
344
- 5. Create a `<Directory {PATH TO YOUR APPLICATION'S PUBLIC DIRECTORY}>` block.
345
- 6. Inside the Directory block, set `Allow from all`, and (if you're on Apache >= 2.4) `Require all granted`.
346
- 7. Inside the Directory block, disable MultiViews.
347
-
348
- Here is an example:
349
-
350
- -------------------------------------------
351
- <VirtualHost *:80>
352
- ServerName www.phusion.nl
353
- DocumentRoot /websites/phusion
354
- <Directory /websites/phusion>
355
- Allow from all
356
- Options -MultiViews
357
- # Uncomment this if you're on Apache >= 2.4:
358
- #Require all granted
359
- </Directory>
360
-
361
- # These have been added:
362
- Alias /subapp /websites/python/public
363
- <Location /subapp>
364
- PassengerBaseURI /subapp
365
- PassengerAppRoot /websites/python
366
- </Location>
367
- <Directory /websites/python/public>
368
- Allow from all
369
- Options -MultiViews
370
- # Uncomment this if you're on Apache >= 2.4:
371
- #Require all granted
372
- </Directory>
373
- </VirtualHost>
374
- -------------------------------------------
375
-
376
- Then restart Apache. The application has now been deployed to the sub-URI.
59
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
377
60
 
378
61
  === Redeploying (restarting the WSGI application) ===
379
62
 
380
- Deploying a new version of a WSGI application is as simple as
381
- re-uploading the application files, and restarting the application.
382
-
383
- There are two ways to restart the application:
384
-
385
- 1. By restarting Apache.
386
- 2. By creating or modifying the file 'tmp/restart.txt' in the WSGI
387
- application's <<application_root,root folder>>. Phusion Passenger will
388
- automatically restart the application.
389
-
390
- For example, to restart our example application, we type this in the
391
- command line:
392
- -------------------------------------------
393
- touch /webapps/wsgiapp/tmp/restart.txt
394
- -------------------------------------------
63
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/restart_app.html
395
64
 
396
65
  === Sample `passenger_wsgi.py` for Django
397
66
 
398
- For Django applications, `passenger_wsgi.py` should look like this:
399
-
400
- [code,python]
401
- -------------------------------------------
402
- import myproject.wsgi
403
- application = myproject.wsgi.application
404
- -------------------------------------------
405
-
406
- Replace `myproject` with your project's module name.
67
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/wsgi_spec.html
407
68
 
408
69
 
409
70
  == Deploying a Node.js application
410
71
 
411
- Please refer to link:https://github.com/phusion/passenger/wiki/Phusion-Passenger%3A-Node.js-tutorial[the Node.js tutorial].
72
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
412
73
 
413
74
 
414
75
  == Deploying a Meteor application
415
76
 
416
- Please refer to link:https://github.com/phusion/passenger/wiki/Phusion-Passenger:-Meteor-tutorial[the Meteor tutorial].
77
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/
417
78
 
418
79
 
419
80
  == Configuring Phusion Passenger ==
420
81
 
421
- After installation, Phusion Passenger does not need any further configurations.
422
- Nevertheless, the system administrator may be interested in changing
423
- Phusion Passenger's behavior. Phusion Passenger's Apache module supports the
424
- following configuration options:
82
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/
425
83
 
426
84
  [[PassengerRoot]]
427
85
  === PassengerRoot <directory> ===
428
- The location to the Phusion Passenger root directory. This configuration option
429
- is essential to Phusion Passenger, and allows Phusion Passenger to locate its own
430
- data files. If you do not set this option, or if you set this option to the wrong value, then Phusion Passenger will make Apache abort with an error.
431
-
432
- While installing Phusion Passenger, you have been told to set this option in your Apache configuration file, and you have been told what value to set it to. So under normal conditions, you don't have ask yourself what value to set for this option. But in case you lost the value (e.g. because you accidentally removed the Apache configuration file, and you are trying to reconstruct it), or in case you didn't follow the installation instructions correctly, then here's how you can find out the correct value:
433
86
 
434
- * If you installed Phusion Passenger through <<install_on_debian_ubuntu,our APT repository>>, then the value can be obtained by running `/usr/bin/passenger-config --root`.
435
- * If you installed Phusion Passenger through RubyGems, then the value can be obtained by running `passenger-config --root`.
436
- * If you installed Phusion Passenger through the source tarball, then the value is the path to the Phusion Passenger directory. For example, if you extracted the tarball's contents to `/opt/passenger/passenger-x.x.x`, then `passenger_root` must be `/opt/passenger/passenger-x.x.x`.
437
-
438
- If you've moved Phusion Passenger to a different directory then you need to update
439
- this option as well. Please read
440
- <<moving_phusion_passenger,Moving Phusion Passenger to a different directory>> for more information.
441
-
442
- This required option may only occur once, in the global server configuration.
87
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerroot
443
88
 
444
89
  [[PassengerDefaultRuby]]
445
90
  === PassengerDefaultRuby <filename> ===
446
- :version: 4.0.0
447
- include::users_guide_snippets/since_version.txt[]
448
91
 
449
- This option specifies the default Ruby interpreter to use for web apps as well as for all sorts of internal Phusion Passenger helper scripts, e.g. the one used by <<PassengerPreStart,PassengerPreStart>>. Please see <<PassengerRuby,PassengerRuby>> for more information, as well as how it relates to <<PassengerRuby,PassengerRuby>>.
450
-
451
- This option may occur in the global server configuration. The default value is 'ruby', meaning that the Ruby interpreter will be looked up according to the `PATH` environment variable.
92
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerdefaultruby
452
93
 
453
94
  === Deployment options
454
95
 
455
96
  [[PassengerEnabled]]
456
97
  ==== PassengerEnabled <on|off>
457
- You can set this option to 'off' to completely disable Phusion Passenger for
458
- a certain location. This is useful if, for example, you want to integrate a PHP
459
- application into the same virtual host as a Rails application.
460
-
461
- Suppose that you have a Rails application in '/apps/foo'. Suppose that you've
462
- dropped Wordpress -- a blogging application written in PHP -- in
463
- '/apps/foo/public/wordpress'. You can then configure Phusion Passenger as
464
- follows:
465
-
466
- ------------------------------------
467
- <VirtualHost *:80>
468
- ServerName www.foo.com
469
- DocumentRoot /apps/foo/public
470
- <Directory /apps/foo/public/wordpress>
471
- PassengerEnabled off
472
- AllowOverride all # <-- Makes Wordpress's .htaccess file work.
473
- </Directory>
474
- </VirtualHost>
475
- ------------------------------------
476
-
477
- This way, Phusion Passenger will not interfere with Wordpress.
478
-
479
- 'PassengerEnabled' may occur in the following places:
480
98
 
481
- * In the global server configuration.
482
- * In a virtual host configuration block.
483
- * In a `<Directory>` or `<Location>` block.
484
- * In '.htaccess'.
485
-
486
- In each place, it may be specified at most once. The default value is 'on'.
99
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerenabled
487
100
 
488
101
  [[PassengerBaseURI]]
489
102
  ==== PassengerBaseURI <uri> ====
490
- Used to specify that the given URI is a Phusion Passenger-served application. Please refer
491
- to the following sections for examples:
492
-
493
- * <<deploying_rails_to_sub_uri,Deploying Rails 1.x and 2.x to a sub URI>>
494
- * <<deploying_rack_to_sub_uri,Deploying Rack (including Rails >= 3) to a sub URI>>
495
- * <<deploying_python_to_sub_uri,Deploying Python to a sub URI>>
496
103
 
497
- This option may occur in the following places:
498
-
499
- * In the global server configuration.
500
- * In a virtual host configuration block.
501
- * In a `<Directory>` or `<Location>` block.
502
- * In '.htaccess', if `AllowOverride Options` is on.
104
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerbaseuri
503
105
 
504
106
  === Application loading options
505
107
 
506
108
  [[PassengerRuby]]
507
109
  ==== PassengerRuby <filename>
508
- The `PassengerDefaultRuby` and `PassengerRuby` directives specify the Ruby interpreter to use. Similarly, the `PassengerPython` and `PassengerNodejs` directives are for specifying the Python interpreter and the Node.js command, respectively.
509
-
510
- The relationship between `PassengerDefaultRuby` and `PassengerRuby` is as follows:
511
-
512
- * `PassengerDefaultRuby` may only occur in the global server configuration.
513
- * `PassengerRuby` may occur everywhere: in the global server configuration, in `<VirtualHost>`, in `<Directory>`, in `<Location>`, and in '.htaccess' if `AllowOverride Options` is on.
514
- * You don't *have* to specify `PassengerRuby`. In this case `PassengerDefaultRuby` is used as the Ruby interpreter. But if you do specify `PassengerRuby` then it will override `PassengerDefaultRuby` in that context. This allows you to use `PassengerRuby` to specify a different Ruby interpreter on a per-application basis.
515
-
516
- Phusion Passenger not only uses Ruby to run web apps, but also for running certain helper tools that are written in Ruby, e.g. the internal helper script used by <<PassengerPreStart,PassengerPreStart>>. These tools are always run using `PassengerDefaultRuby`, never by `PassengerRuby`. `PassengerRuby` is only used for running web apps. You can learn more about the internal helper scripts in <<relationship_with_ruby,Phusion Passenger and its relationship with Ruby>>.
517
-
518
- It is okay if `PassengerDefaultRuby` refers to a different Ruby interpreter than the one you originally installed Phusion Passenger with. This too is explained in <<relationship_with_ruby,Phusion Passenger and its relationship with Ruby>>.
519
-
520
- The reason why `PassengerDefaultRuby` exists at all is because limitations in the Apache API prevents us from implementing the same behavior using only the `PassengerRuby` directive.
521
-
522
- There is no `PassengerDefaultPython` etc because there are no Phusion Passenger tools written in Python. As such, having `PassengerPython` is enough.
523
-
524
- The following example illustrates how it works and how you can use these options to specify different interpreters for different web apps.
525
-
526
- ------------------------------
527
- # Use Ruby 1.8.7 by default.
528
- PassengerDefaultRuby /usr/bin/ruby1.8
529
- # Use Python 2.6 by default.
530
- PassengerPython /usr/bin/python2.6
531
- # Use /usr/bin/node by default.
532
- PassengerNodejs /usr/bin/node;
533
-
534
- <VirtualHost *:80>
535
- # This Rails web app will use Ruby 1.8.7
536
- ServerName www.foo.com
537
- DocumentRoot /webapps/foo/public
538
- </VirtualHost>
539
-
540
- <VirtualHost *:80>
541
- # This Rails web app will use Ruby 1.9.3, as installed by RVM
542
- PassengerRuby /usr/local/rvm/wrappers/ruby-1.9.3/ruby
543
- ServerName www.bar.com
544
- DocumentRoot /webapps/bar/public
545
-
546
- # If you have a web app deployed in a sub-URI, customize
547
- # PassengerRuby/PassengerPython inside a <Location> block.
548
- # The web app under www.bar.com/blog will use JRuby 1.7.1
549
- Alias /blog /websites/blog/public
550
- <Location /blog>
551
- PassengerBaseURI /blog
552
- PassengerAppRoot /websites/blog
553
-
554
- PassengerRuby /usr/local/rvm/wrappers/jruby-1.7.1/ruby
555
- </Location>
556
- <Directory /websites/blog/public>
557
- Allow from all
558
- Options -MultiViews
559
- # Uncomment this if you're on Apache >= 2.4:
560
- #Require all granted
561
- </Directory>
562
- </VirtualHost>
563
-
564
- <VirtualHost *:80>
565
- # This Flask web app will use Python 3.0
566
- PassengerPython /usr/bin/python3.0
567
- ServerName www.baz.com
568
- DocumentRoot /webapps/baz/public
569
- </VirtualHost>
570
- ------------------------------
571
-
572
- include::users_guide_snippets/rvm_helper_tool.txt[]
110
+
111
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerruby
573
112
 
574
113
  ==== PassengerPython <filename>
575
- :version: 4.0.0
576
- include::users_guide_snippets/since_version.txt[]
577
114
 
578
- This option allows one to specify the Python interpreter to use. See <<PassengerRuby,PassengerRuby>> for more information. The default value is 'python', meaning that the Python interpreter will be looked up according to the `PATH` environment variable.
115
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerpython
579
116
 
580
117
  ==== PassengerNodejs <filename>
581
- :version: 4.0.24
582
- include::users_guide_snippets/since_version.txt[]
583
118
 
584
- This option allows one to specify the Node.js command to use. See <<PassengerRuby,PassengerRuby>> for more information. The default value is 'node', meaning that the Node.js command will be looked up according to the `PATH` environment variable.
119
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengernodejs
585
120
 
586
121
  ==== PassengerMeteorAppSettings <filename>
587
- :version: 5.0.7
588
- include::users_guide_snippets/since_version.txt[]
589
122
 
590
- When using a Meteor application in non-bundled mode, use this option to specify a (JSON) file with settings for the application. Meteor will be started with the `--settings` parameter set to this option.
591
-
592
- N.B. For bundled mode, Meteor requires you to put applications settings in the `METEOR_SETTINGS` environment variable.
123
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermeteorappsettings
593
124
 
594
125
  [[PassengerAppEnv]]
595
126
  ==== PassengerAppEnv <string> ====
596
- This option sets the value of the following environment variables:
597
-
598
- * `RAILS_ENV`
599
- * `RACK_ENV`
600
- * `WSGI_ENV`
601
- * `NODE_ENV`
602
- * `PASSENGER_APP_ENV`
603
-
604
- Some web frameworks, for example Rails and Connect.js, adjust their behavior according to the value in one of these environment variables.
605
127
 
606
- Phusion Passenger for Apache sets the default value to **production**. If you're developing an Rails application then you should set this to `development`.
607
-
608
- If you want to set other environment variables, please refer to <<env_vars_passenger_apps,Setting environment variables for Phusion Passenger-served apps>>.
609
-
610
- Setting this option also adds the application environment name to the default <<PassengerAppGroupName,application group name>>, so that you can run multiple versions of your application with different application environment names.
611
-
612
- This option may occur in the following places:
613
-
614
- * In the global server configuration.
615
- * In a virtual host configuration block.
616
- * In a `<Directory>` or `<Location>` block.
617
- * In '.htaccess', if `AllowOverride Options` is on.
618
-
619
- In each place, it may be specified at most once.
128
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerappenv
620
129
 
621
130
  [[rails_env]]
622
131
  ==== RailsEnv <string> ====
623
- An alias for <<PassengerAppEnv,PassengerAppEnv>>.
132
+
133
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsenv-rackenv
624
134
 
625
135
  [[rack_env]]
626
136
  ==== RackEnv <string> ====
627
- An alias for <<PassengerAppEnv,PassengerAppEnv>>.
137
+
138
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsenv-rackenv
628
139
 
629
140
  [[PassengerAppRoot]]
630
141
  ==== PassengerAppRoot <path/to/root>
631
- By default, Phusion Passenger assumes that the application's root directory
632
- is the parent directory of the 'public' directory. This option allows one to
633
- specify the application's root independently from the DocumentRoot, which
634
- is useful if the 'public' directory lives in a non-standard place.
635
-
636
- This option may occur in the following places:
637
142
 
638
- * In the global server configuration.
639
- * In a virtual host configuration block.
640
- * In a `<Directory>` or `<Location>` block.
641
- * In '.htaccess', if `AllowOverride Options` is on.
642
-
643
- In each place, it may be specified at most once.
644
-
645
- Example:
646
-
647
- -----------------------------
648
- <VirtualHost test.host>
649
- DocumentRoot /var/rails/zena/sites/example.com/public
650
- # Normally Phusion Passenger would have assumed that the
651
- # application root is "/var/rails/zena/sites/example.com".
652
- # This overrides it.
653
- PassengerAppRoot /var/rails/zena
654
- </VirtualHost>
655
- -----------------------------
143
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerapproot
656
144
 
657
145
  [[PassengerAppGroupName]]
658
146
  ==== PassengerAppGroupName <name>
659
- Sets the name of the application group that the current application should belong to. Its default value is the <<application_root,application root>>, plus (if it is set), the <<PassengerAppEnv,application environment name>>.
660
-
661
- Phusion Passenger stores and caches most application spawning settings -- such as environment variables, process limits, etc -- on a per-app-group-name basis. This means that if you want to start two versions of your application, with each version having different environment variables, then you must assign them under different application group names.
662
-
663
- For example, consider a situation in which you are running multiple versions of the same app, with each version intended for a different customer. You use the `CUSTOMER_NAME` environment variable to tell the app which customer that version should serve.
664
-
665
- ------------------------------------
666
- # WRONG example! Doesn't work!
667
-
668
- <VirtualHost *:80>
669
- ServerName customer1.foo.com
670
- DocumentRoot /webapps/foo/public
671
- SetEnv CUSTOMER_NAME customer1
672
- </VirtualHost>
673
-
674
- <VirtualHost *:80>
675
- ServerName customer2.foo.com
676
- DocumentRoot /webapps/foo/public
677
- SetEnv CUSTOMER_NAME customer2
678
- </VirtualHost>
679
- ------------------------------------
680
-
681
- This example doesn't work, because Phusion Passenger thinks that they are the same application. When a user visits customer1.foo.com, Phusion Passenger will start a process with `CUSTOMER_NAME=customer1`. When another user visits customer2.foo.com, Phusion Passenger will route the request to the application process that was started earlier. Because environment variables are only set during application process startup, the second user will be served the website for customer 1.
682
-
683
- To make this work, assign unique application group names:
684
-
685
- ------------------------------------
686
- <VirtualHost *:80>
687
- ServerName customer1.foo.com
688
- DocumentRoot /webapps/foo/public
689
- SetEnv CUSTOMER_NAME customer1
690
- PassengerAppGroupName foo_customer1
691
- </VirtualHost>
692
-
693
- <VirtualHost *:80>
694
- ServerName customer2.foo.com
695
- DocumentRoot /webapps/foo/public
696
- SetEnv CUSTOMER_NAME customer2
697
- PassengerAppGroupName foo_customer2
698
- </VirtualHost>
699
- ------------------------------------
700
-
701
- Note that it is not necessary to set `PassengerAppGroupName` if you want to run two versions of your application under different <<PassengerAppEnv,application environment names>>, because the application environment name is included in the default application group name. For example, consider a situation in which you want to run a production and a staging version of your application. The following configuration will work fine:
702
-
703
- ------------------------------------
704
- <VirtualHost *:80>
705
- ServerName bar.com
706
- DocumentRoot /webapps/bar/public
707
- # Phusion Passenger implicitly sets:
708
- # PassengerAppGroupName /webapps/bar
709
- </VirtualHost>
710
-
711
- <VirtualHost *:80>
712
- ServerName staging.bar.com
713
- DocumentRoot /webapps/bar/public
714
- PassengerAppEnv staging
715
- # Phusion Passenger implicitly sets:
716
- # PassengerAppGroupName '/webapps/bar (staging)'
717
- </VirtualHost>
718
- ------------------------------------
719
-
720
- This option may occur in the following places:
721
-
722
- * In the global server configuration.
723
- * In a virtual host configuration block.
724
- * In a `<Directory>` or `<Location>` block.
725
- * In '.htaccess', if `AllowOverride Options` is on.
726
-
727
- In each place, it may be specified at most once.
147
+
148
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerappgroupname
728
149
 
729
150
  [[PassengerAppType]]
730
151
  ==== PassengerAppType <name>
731
- :version: 4.0.25
732
- include::users_guide_snippets/since_version.txt[]
733
-
734
- By default, Phusion Passenger autodetects the type of the application, e.g. whether it's a Ruby, Python, Node.js or Meteor app. If it's unable to autodetect the type of the application (e.g. because you've specified a custom <<PassengerStartupFile,PassengerStartupFile>>) then you can use this option to force Phusion Passenger to recognize the application as a specific type.
735
-
736
- Allowed values are:
737
-
738
- * `rack` - Ruby and Rails
739
- * `wsgi` - Python
740
- * `node` - Node.js, or Meteor JS in bundled mode
741
- * `meteor` - Meteor JS in non-bundled mode
742
152
 
743
- If you set this option, then you **must** also set <<PassengerAppRoot,PassengerAppRoot>>, otherwise Phusion Passenger does not properly recognize your application.
744
-
745
- This option may occur in the following places:
746
-
747
- * In the global server configuration.
748
- * In a virtual host configuration block.
749
- * In a `<Directory>` or `<Location>` block.
750
- * In '.htaccess'.
751
-
752
- In each place, it may be specified at most once.
753
-
754
- Example:
755
-
756
- -----------------------------
757
- <VirtualHost test.host>
758
- DocumentRoot /webapps/example.com/public
759
- # Use server.js as the startup file (entry point file) for
760
- # your Node.js application, instead of the default app.js
761
- PassengerStartupFile server.js
762
- PassengerAppType node
763
- PassengerAppRoot /webapps/example.com
764
- </VirtualHost>
765
- -----------------------------
153
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerapptype
766
154
 
767
155
  [[PassengerStartupFile]]
768
156
  ==== PassengerStartupFile <filename>
769
- :version: 4.0.25
770
- include::users_guide_snippets/since_version.txt[]
771
-
772
- This option specifies the startup file that Phusion Passenger should use when loading the application.
773
-
774
- Every application has a *startup file* or *entry point file*: a file where the application begins execution. Some languages have widely accepted conventions about how such a file should be called (e.g. Ruby, with its `config.ru`). Other languages have somewhat-accepted conventions (e.g. Node.js, with its `app.js`). In these cases, Phusion Passenger reuses these conventions, and executes applications through those files.
775
-
776
- Other languages have no conventions at all, and so Phusion Passenger invents one (e.g. Python WSGI with `passenger_wsgi.py`).
777
-
778
- Here's a list of the language-specific conventions that Phusion Passenger accepts:
779
-
780
- [options="header"]
781
- |================================================
782
- | Language | Phusion Passenger convention
783
- | Ruby on Rails >= 3.0, Ruby Rack | config.ru
784
- | Ruby on Rails 1.x and 2.x | config/environment.rb
785
- | Python | passenger_wsgi.py
786
- | Node.js | app.js
787
- |================================================
788
-
789
- But sometimes you might not want to adhere to the convention that Phusion Passenger accepts. For example, on Node.js, you might want to use `server.js` as the startup file instead of the default `app.js`. With this option, you can customize the startup file to any file you like.
790
-
791
- Notes:
792
-
793
- * Customizing the startup file affects <<user_switching,user switching>>. After all, if user switching is enabled, the application is executed as the user that owns the startup file.
794
- * If you set this option, you **must** also set <<PassengerAppRoot,PassengerAppRoot>> and <<PassengerAppType,PassengerAppType>>, otherwise Phusion Passenger doesn't know what kind of application it is.
795
-
796
- This option may occur in the following places:
797
157
 
798
- * In the global server configuration.
799
- * In a virtual host configuration block.
800
- * In a `<Directory>` or `<Location>` block.
801
- * In '.htaccess'.
802
-
803
- In each place, it may be specified at most once.
804
-
805
- Example:
806
-
807
- -----------------------------
808
- <VirtualHost test.host>
809
- DocumentRoot /webapps/example.com/public
810
- # Use server.js as the startup file (entry point file) for
811
- # your Node.js application, instead of the default app.js
812
- PassengerStartupFile server.js
813
- PassengerAppType node
814
- PassengerAppRoot /webapps/example.com
815
- </VirtualHost>
816
- -----------------------------
158
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerstartupfile
817
159
 
818
160
  ==== PassengerRestartDir <directory>
819
- As described in the deployment chapters of this document, Phusion Passenger
820
- checks the file 'tmp/restart.txt' in the applications'
821
- <<application_root,root directory>> for restarting applications. Sometimes it
822
- may be desirable for Phusion Passenger to look in a different directory instead,
823
- for example for security reasons (see below). This option allows you to
824
- customize the directory in which 'restart.txt' is searched for.
825
-
826
- You may specify 'PassengerRestartDir' in the following places:
827
-
828
- * In the global server configuration.
829
- * In a virtual host configuration block.
830
- * In a `<Directory>` or `<Location>` block.
831
- * In '.htaccess', if `AllowOverrides Options` is enabled.
832
-
833
- In each place, it may be specified at most once.
834
-
835
- You can either set it to an absolute directory, or to a directory relative to
836
- the <<application_root,application root>>. Examples:
837
-
838
- -----------------------------------
839
- <VirtualHost *:80>
840
- ServerName www.foo.com
841
- # Phusion Passenger will check for /apps/foo/public/tmp/restart.txt
842
- DocumentRoot /apps/foo/public
843
- </VirtualHost>
844
-
845
- <VirtualHost *:80>
846
- ServerName www.bar.com
847
- DocumentRoot /apps/bar/public
848
- # An absolute filename is given; Phusion Passenger will
849
- # check for /restart_files/bar/restart.txt
850
- PassengerRestartDir /restart_files/bar
851
- </VirtualHost>
852
-
853
- <VirtualHost *:80>
854
- ServerName www.baz.com
855
- DocumentRoot /apps/baz/public
856
- # A relative filename is given; Phusion Passenger will
857
- # check for /apps/baz/restart_files/restart.txt
858
- #
859
- # Note that this directory is relative to the APPLICATION ROOT, *not*
860
- # the value of DocumentRoot!
861
- PassengerRestartDir restart_files
862
- </VirtualHost>
863
- -----------------------------------
864
-
865
- .What are the security reasons for wanting to customize PassengerRestartDir?
866
- Touching restart.txt will cause Phusion Passenger to restart the application.
867
- So anybody who can touch restart.txt can effectively cause a Denial-of-Service
868
- attack by touching restart.txt over and over. If your web server or one of your
869
- web applications has the permission to touch restart.txt, and one of them has a
870
- security flaw which allows an attacker to touch restart.txt, then that will
871
- allow the attacker to cause a Denial-of-Service.
872
-
873
- You can prevent this from happening by pointing PassengerRestartDir to a
874
- directory that's readable by Apache, but only writable by administrators.
161
+
162
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerrestartdir
875
163
 
876
164
  [[PassengerSpawnMethod]]
877
165
  ==== PassengerSpawnMethod <string>
878
- [TIP]
879
- ."What spawn method should I use?"
880
- =========================================================
881
- This subsection attempts to describe spawn methods, but it's okay if you don't (want to)
882
- understand it, as it's mostly a technical detail. You can basically follow this rule of thumb:
883
-
884
- ************************************************
885
- If your application works on Mongrel or Thin, but not on Phusion Passenger, then set
886
- `PassengerSpawnMethod` to 'direct'. Otherwise, leave it at 'smart' (the default).
887
- ************************************************
888
-
889
- However, we do recommend you to try to understand it. The 'smart' spawn
890
- method bring many benefits.
891
- =========================================================
892
-
893
- include::users_guide_snippets/passenger_spawn_method.txt[]
894
-
895
- This option may occur in the following places:
896
166
 
897
- * In the global server configuration.
898
- * In a virtual host configuration block.
899
-
900
- In each place, it may be specified at most once. The default value is 'smart'.
167
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerspawnmethod
901
168
 
902
169
  [[PassengerLoadShellEnvvars]]
903
170
  ==== PassengerLoadShellEnvvars <on|off>
904
- :version: 4.0.20
905
- include::users_guide_snippets/since_version.txt[]
906
-
907
- Enables or disables the loading of shell environment variables before spawning the application.
908
-
909
- If this option is turned on, and the user's shell is `bash`, then applications are loaded by running them with `bash -l -c`. Otherwise, they are loaded by running them directly from the `PassengerAgent core` process.
910
-
911
- This option may occur in the following places:
912
171
 
913
- * In the global server configuration.
914
- * In a virtual host configuration block.
915
- * In a `<Directory>` or `<Location>` block.
916
- * In '.htaccess', if `AllowOverride Options` is on.
917
-
918
- In each place, it may be specified at most once. The default value is 'on'.
172
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerloadshellenvvars
919
173
 
920
174
  [[PassengerRollingRestarts]]
921
175
  ==== PassengerRollingRestarts <on|off>
922
- :version: 3.0.0
923
- include::users_guide_snippets/enterprise_only.txt[]
924
-
925
- Enables or disables support for rolling restarts through restart.txt. Normally when you
926
- restart an application by touching restart.txt, Phusion Passenger would
927
- shut down all application processes and spawn a new one. The spawning
928
- of a new application process could take a while, and any requests that
929
- come in during this time will be blocked until this first application
930
- process has spawned.
931
-
932
- But when rolling restarts are enabled, Phusion Passenger Enterprise will:
933
176
 
934
- 1. Spawn a new process in the background.
935
- 2. When it's done spawning, Phusion Passenger Enterprise will replace one of the old processes with this newly spawned one.
936
- 3. Step 1 and 2 are repeated until all processes have been replaced.
937
-
938
- This way, visitors will not experience any delays when you are restarting your application. This allows you to, for example, upgrade your application often without degrading user experience.
939
-
940
- Rolling restarts have a few caveat however that you should be aware of:
941
-
942
- - Upgrading an application sometimes involves upgrading the database schema.
943
- With rolling restarts, there may be a point in time during which processes
944
- belonging to the previous version and processes belonging to the new version
945
- both exist at the same time. Any database schema upgrades you perform must
946
- therefore be backwards-compatible with the old application version.
947
- - Because there's no telling which process will serve a request, users may
948
- not see changes brought about by the new version until all processes have
949
- been restarted. It is for this reason that you should not use rolling
950
- restarts in development, only in production.
951
-
952
- If Passenger Enterprise could not rolling restart a process (let's call it 'A') because it is unable to spawn a new process (let's call it 'B'), then Passenger Enterprise will give up trying to rolling restart that particular process 'A'. What happens next depends on whether <<PassengerResistDeploymentErrors,deployment error resistance>> is enabled:
953
-
954
- - If deployment error resistance is disabled (the default), then Passenger Enterprise will proceed with trying to restart the remaining processes.
955
- - If deployment error resistance is enabled, the Passenger Enterprise will give up rolling restarting immediately. The application group will be put into Deployment Error Resistance Mode.
956
-
957
- Please note that `PassengerRollingRestarts` is completely unrelated to the `passenger-config restart-app` command. That command always initiates a blocking restart, unless `--rolling-restart` is given.
958
-
959
- This option may occur in the following places:
960
-
961
- * In the global server configuration.
962
- * In a virtual host configuration block.
963
- * In a `<Directory>` or `<Location>` block.
964
- * In '.htaccess', if `AllowOverride Options` is on.
965
-
966
- In each place, it may be specified at most once. The default value is 'off'.
967
-
968
- NOTE: Are you looking to prevent applications from being restarted when you restart the web server? That is handled by the link:Users%20guide%20Nginx.html#flying_passenger[Flying Passenger mode] (which requires Nginx), not by the rolling restarts feature.
177
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerrollingrestarts
969
178
 
970
179
  [[PassengerResistDeploymentErrors]]
971
180
  ==== PassengerResistDeploymentErrors <on|off>
972
- :version: 3.0.0
973
- include::users_guide_snippets/enterprise_only.txt[]
974
-
975
- Enables or disables resistance against deployment errors.
976
-
977
- Suppose you've upgraded your application and you've issues a command to restart it (by touching restart.txt), but the application code contains an error that prevents Phusion Passenger from successfully spawning a process (e.g. a syntax error). Phusion Passenger would normally display an error message in response to this.
978
-
979
- By enabling deployment error resistance, Phusion Passenger Enterprise would instead do this:
980
-
981
- - It passes the request to one of the existing application processes (that belong to the previous version of the application). The visitor will not see a Phusion Passenger process spawning error message.
982
- - It logs the error to the global web server error log file.
983
- - It sets an internal flag (Deployment Error Resistance Mode) so that no processes for this application will be spawned (even when the current traffic would normally result in more processes being spawned) and no processes will be idle cleaned. Processes *could* still be shutdown because of other events, e.g. because their <<PassengerMemoryLimit,memory limit>> have been reached. You can see whether the flag is set by invoking `passenger-status`. If you see the message "Resisting deployment error" then the flag is set.
984
181
 
985
- This way, visitors will suffer minimally from deployment errors. Phusion Passenger will attempt to restart the application again next time restart.txt is touched.
986
-
987
- Enabling deployment error resistance only works if <<PassengerRollingRestarts,rolling restart>> is also enabled.
988
-
989
- This option may occur in the following places:
990
-
991
- * In the global server configuration.
992
- * In a virtual host configuration block.
993
- * In a `<Directory>` or `<Location>` block.
994
- * In '.htaccess', if `AllowOverride Options` is on.
995
-
996
- In each place, it may be specified at most once. The default value is 'off'.
182
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerresistdeploymenterrors
997
183
 
998
184
  === Security options ===
999
185
 
1000
186
  [[PassengerUserSwitching]]
1001
187
  ==== PassengerUserSwitching <on|off> ====
1002
- Whether to enable <<user_switching,user switching support>>.
1003
188
 
1004
- This option may only occur once, in the global server configuration.
1005
- The default value is 'on'.
1006
-
1007
- WARNING: If you're on Red Hat or CentOS, be sure to read <<user_switching_rpm_caveats,the Red Hat and CentOS user switching caveats>>.
189
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengeruserswitching
1008
190
 
1009
191
  [[PassengerUser]]
1010
192
  ==== PassengerUser <username> ====
1011
- If <<user_switching,user switching support>> is enabled, then Phusion Passenger will
1012
- by default run the web application as the owner of the file 'config/environment.rb'
1013
- (for Rails apps) or 'config.ru' (for Rack apps). This option allows you to override
1014
- that behavior and explicitly set a user to run the web application as, regardless
1015
- of the ownership of 'environment.rb'/'config.ru'.
1016
-
1017
- This option may occur in the following places:
1018
193
 
1019
- * In the global server configuration.
1020
- * In a virtual host configuration block.
1021
- * In a `<Directory>` or `<Location>` block.
1022
-
1023
- In each place, it may be specified at most once.
194
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengeruser
1024
195
 
1025
196
  [[PassengerGroup]]
1026
197
  ==== PassengerGroup <group name> ====
1027
- If <<user_switching,user switching support>> is enabled, then Phusion Passenger will
1028
- by default run the web application as the primary group of the owner of the file
1029
- 'config/environment.rb' (for Rails apps) or 'config.ru' (for Rack apps). This option
1030
- allows you to override that behavior and explicitly set a group to run the web application
1031
- as, regardless of the ownership of 'environment.rb'/'config.ru'.
1032
-
1033
- '<group name>' may also be set to the special value '!STARTUP_FILE!', in which case
1034
- the web application's group will be set to 'environment.rb'/'config.ru''s group.
1035
198
 
1036
- This option may occur in the following places:
1037
-
1038
- * In the global server configuration.
1039
- * In a virtual host configuration block.
1040
- * In a `<Directory>` or `<Location>` block.
1041
-
1042
- In each place, it may be specified at most once.
199
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengergroup
1043
200
 
1044
201
  [[PassengerDefaultUser]]
1045
202
  ==== PassengerDefaultUser <username> ====
1046
- Phusion Passenger enables <<user_switching,user switching support>> by default.
1047
- This configuration option allows one to specify the user that applications must
1048
- run as, if user switching fails or is disabled.
1049
203
 
1050
- This option may only occur once, in the global server configuration.
1051
- The default value is 'nobody'.
204
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerdefaultuser
1052
205
 
1053
206
  [[PassengerDefaultGroup]]
1054
207
  ==== PassengerDefaultGroup <group name> ====
1055
- Phusion Passenger enables <<user_switching,user switching support>> by default.
1056
- This configuration option allows one to specify the group that applications must
1057
- run as, if user switching fails or is disabled.
1058
208
 
1059
- This option may only occur once, in the global server configuration.
1060
- The default value is the primary group of the user specifified by
1061
- <<PassengerDefaultUser,PassengerDefaultUser>>.
209
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerdefaultgroup
1062
210
 
1063
211
  [[PassengerFriendlyErrorPages]]
1064
212
  ==== PassengerFriendlyErrorPages <on|off> ====
1065
- Phusion Passenger can display friendly error pages whenever an application fails
1066
- to start. This friendly error page presents the startup error message, some
1067
- suggestions for solving the problem, a backtrace and a dump of the environment variables.
1068
- This feature is very useful during application development and useful for less experienced
1069
- system administrators, but the page might reveal potentially sensitive information,
1070
- depending on the application. For this reason, friendly error pages are turned off by default when
1071
- <<PassengerAppEnv,PassengerAppEnv (and its aliases such as RailsEnv and RackEnv)>>
1072
- is set to 'staging' or 'production', but enabled by default otherwise. You can use
1073
- this option to explicitly enable or disable this feature.
1074
-
1075
- This option may occur in the following places:
1076
-
1077
- * In the global server configuration.
1078
- * In a virtual host configuration block.
1079
- * In a `<Directory>` or `<Location>` block.
1080
- * In '.htaccess', if `AllowOverride Options` is on.
1081
213
 
1082
- In each place, it may be specified at most once. The default value depends on <<PassengerAppEnv,PassengerAppEnv (and its aliases such as RailsEnv and RackEnv)>>, as documented above.
214
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerfriendlyerrorpages
1083
215
 
1084
216
 
1085
217
  === Resource control and optimization options ===
1086
218
 
1087
219
  [[PassengerMaxPoolSize]]
1088
220
  ==== PassengerMaxPoolSize <integer> ====
1089
- The maximum number of <<application_process,application processes>> that may
1090
- simultaneously exist. A larger number results in higher memory usage,
1091
- but improves the ability to handle concurrent HTTP requests.
1092
221
 
1093
- The optimal value depends on your system's hardware and your workload. You can learn more at the Phusion article link:http://blog.phusion.nl/2013/03/12/tuning-phusion-passengers-concurrency-settings/[Tuning Phusion Passenger's concurrency settings].
1094
-
1095
- If you find that your server is running out of memory then you should lower this value.
1096
-
1097
- This option may only occur once, in the global server configuration.
1098
- The default value is '6'.
222
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxpoolsize
1099
223
 
1100
224
  [[PassengerMinInstances]]
1101
225
  ==== PassengerMinInstances <integer> ====
1102
- This specifies the minimum number of application processes that should exist for a
1103
- given application. You should set this option to a
1104
- non-zero value if you want to avoid potentially long startup times after a website
1105
- has been <<idle_process,idle>> for an extended period.
1106
-
1107
- Please note that this option does *not* pre-start application processes during Apache
1108
- startup. It just makes sure that when the application is first accessed:
1109
226
 
1110
- 1. at least the given number of processes will be spawned.
1111
- 2. the given number of processes will be kept around even when processes are being
1112
- idle cleaned (see <<PassengerPoolIdleTime,PassengerPoolIdleTime>>).
1113
-
1114
- If you want to pre-start application processes during Apache startup, then you should use the <<PassengerPreStart,PassengerPreStart>> directive, possibly in combination with
1115
- 'PassengerMinInstances'. This behavior might seem counter-intuitive at first sight,
1116
- but <<PassengerPreStart,PassengerPreStart>> explains the rationale behind it.
1117
-
1118
- For example, suppose that you have the following configuration:
1119
-
1120
- ---------------------------------
1121
- PassengerMaxPoolSize 15
1122
- PassengerPoolIdleTime 10
1123
-
1124
- <VirtualHost *:80>
1125
- ServerName foobar.com
1126
- DocumentRoot /webapps/foobar/public
1127
- PassengerMinInstances 3
1128
- </VirtualHost>
1129
- ---------------------------------
1130
-
1131
- When you start Apache, there are 0 application processes for 'foobar.com'. Things will
1132
- stay that way until someone visits 'foobar.com'. Suppose that there is only 1 visitor.
1133
- 1 application process will be started immediately to serve the visitor, while 2 will
1134
- be spawned in the background. After 10 seconds, when the idle timeout has
1135
- been reached, these 3 application processes will not be cleaned up.
1136
-
1137
- Now suppose that there's a sudden spike of traffic, and 100 users visit 'foobar.com'
1138
- simultaneously. Phusion Passenger will start 12 more application processes. After the idle
1139
- timeout of 10 seconds have passed, Phusion Passenger will clean up 12 application
1140
- processes, keeping 3 processes around.
1141
-
1142
- The PassengerMinInstances option may occur in the following places:
1143
-
1144
- * In the global server configuration.
1145
- * In a virtual host configuration block.
1146
- * In a `<Directory>` or `<Location>` block.
1147
- * In '.htaccess', if `AllowOverride Limits` is on.
1148
-
1149
- In each place, it may be specified at most once. The default value is '1'.
227
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermininstances
1150
228
 
1151
229
  [[PassengerMaxInstances]]
1152
230
  ==== PassengerMaxInstances <integer> ====
1153
- :version: 3.0.0
1154
- include::users_guide_snippets/enterprise_only.txt[]
1155
-
1156
- The maximum number of application processes that may simultaneously exist
1157
- for an application. This helps to make sure that a single application
1158
- will not occupy all available slots in the application pool.
1159
-
1160
- This value must be less than <<PassengerMaxPoolSize,PassengerMaxPoolSize>>. A value of 0
1161
- means that there is no limit placed on the number of processes a single application
1162
- may spawn, i.e. only the global limit of <<PassengerMaxPoolSize,PassengerMaxPoolSize>>
1163
- will be enforced.
1164
-
1165
- This option may occur in the following places:
1166
-
1167
- * In the global server configuration.
1168
- * In a virtual host configuration block.
1169
-
1170
- In each place, it may be specified at most once. The default value is '0'.
1171
231
 
1172
- .Practical usage example
1173
- [TIP]
1174
- ===========================================================================
1175
- Suppose that you're hosting two web applications on your server, a personal
1176
- blog and an e-commerce website. You've set <<PassengerMaxPoolSize,PassengerMaxPoolSize>>
1177
- to 10. The e-commerce website is more important to you. You can then set
1178
- 'PassengerMaxInstances' to 3 for your blog, so that it will never spawn more
1179
- than 3 processes, even if it suddenly gets a lot of traffic. Your e-commerce website
1180
- on the other hand will be free to spawn up to 10 processes if it gets a lot of traffic.
1181
- ===========================================================================
232
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxinstances
1182
233
 
1183
234
  ==== PassengerMaxInstancesPerApp <integer> ====
1184
- The maximum number of application processes that may simultaneously exist
1185
- for a single application. This helps to make sure that a single application
1186
- will not occupy all available slots in the application pool.
1187
-
1188
- This value must be less than <<PassengerMaxPoolSize,PassengerMaxPoolSize>>. A value of 0
1189
- means that there is no limit placed on the number of processes a single application
1190
- may use, i.e. only the global limit of <<PassengerMaxPoolSize,PassengerMaxPoolSize>>
1191
- will be enforced.
1192
-
1193
- This option may only occur once, in the global server configuration.
1194
- The default value is '0'.
1195
-
1196
- .Practical usage example
1197
- [TIP]
1198
- ===========================================================================
1199
- Suppose that you're hosting two blogs (blog A and B) on your server, and that
1200
- you've set <<PassengerMaxPoolSize,PassengerMaxPoolSize>> to 10. Under normal
1201
- circumstances, if blog A suddenly gets a lot of traffic, then A will use all 10
1202
- pool slots. If blog B suddenly gets some traffic, then it will only be able to
1203
- use 1 pool slot (forcefully releasing 1 slot from A) until A's traffic has
1204
- settled down and it has released more pool slots.
1205
-
1206
- If you consider both blogs equally important, then you can set
1207
- 'PassengerMaxInstancesPerApp' to 5. This way, both blogs will never use more
1208
- than 5 pool slots.
1209
- ===========================================================================
1210
-
1211
- .Relation with PassengerMaxInstances
1212
- [NOTE]
1213
- ===========================================================================
1214
- Unlike <<PassengerMaxInstances,PassengerMaxInstances>>, this configuration
1215
- option is global and applies to all applications. 'PassengerMaxInstances' on the
1216
- other hand is per-virtual host.
1217
-
1218
- Suppose that you're hosting two web applications on your server, a personal
1219
- blog and an e-commerce website. You've set <<PassengerMaxPoolSize,PassengerMaxPoolSize>>
1220
- to 10. The e-commerce website is more important to you. You can then set
1221
- 'PassengerMaxInstances' to 3 for your blog, so that it will never use more than
1222
- 3 pool slots, even if it suddenly gets a lot of traffic. Your e-commerce website
1223
- on the other hand will be free to use up all 10 slots if it gets a lot of traffic.
1224
-
1225
- In summary, 'PassengerMaxInstancesPerApp' divides the pool equally among the
1226
- different web applications, while 'PassengerMaxInstances' allows one to divide
1227
- the pool unequally, according to each web application's relative importance.
1228
- ===========================================================================
235
+
236
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxinstancesperapp
1229
237
 
1230
238
  [[PassengerPoolIdleTime]]
1231
239
  ==== PassengerPoolIdleTime <integer> ====
1232
- The maximum number of seconds that an application process may be idle. That is,
1233
- if an application process hasn't received any traffic after the given number of
1234
- seconds, then it will be shutdown in order to conserve memory.
1235
-
1236
- Decreasing this value means that applications will have to be spawned
1237
- more often. Since spawning is a relatively slow operation, some visitors may
1238
- notice a small delay when they visit your Rails/Rack website. However, it will also
1239
- free up resources used by applications more quickly.
1240
-
1241
- The optimal value depends on the average time that a visitor spends on a single
1242
- Rails/Rack web page. We recommend a value of `2 * x`, where `x` is the average
1243
- number of seconds that a visitor spends on a single Rails/Rack web page. But your
1244
- mileage may vary.
1245
-
1246
- When this value is set to '0', application processes will not be shutdown unless
1247
- it's really necessary, i.e. when Phusion Passenger is out of application processes
1248
- for a given application and one of the <<inactive_process,inactive application processes>> needs to
1249
- make place for another application process. Setting the value to 0 is
1250
- recommended if you're on a non-shared host that's only running a few
1251
- applications, each which must be available at all times.
1252
-
1253
- This option may only occur once, in the global server configuration.
1254
- The default value is '300'.
240
+
241
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerpoolidletime
1255
242
 
1256
243
  [[PassengerMaxPreloaderIdleTime]]
1257
244
  ==== PassengerMaxPreloaderIdleTime <integer> ====
1258
- The preloader process(explained in <<spawning_methods_explained,Spawning
1259
- methods explained>>) has an idle timeout, just like the backend processes spawned by
1260
- Phusion Passenger do. That is, it will automatically shutdown if it hasn't done
1261
- anything for a given period.
1262
-
1263
- This option allows you to set the preloader's idle timeout, in
1264
- seconds. A value of '0' means that it should never idle timeout.
1265
-
1266
- Setting a higher value will mean that the preloader is kept around
1267
- longer, which may slightly increase memory usage. But as long as the
1268
- preloader server is running, the time to spawn a Ruby on Rails backend
1269
- process only takes about 10% of the time that is normally needed, assuming that
1270
- you're using the 'smart' <<PassengerSpawnMethod,spawning method>>. So if your
1271
- system has enough memory, is it recommended that you set this option to a high
1272
- value or to '0'.
1273
245
 
1274
- This option may occur in the following places:
1275
-
1276
- * In the global server configuration.
1277
- * In a virtual host configuration block.
1278
-
1279
- In each place, it may be specified at most once. The default value is '300' (5 minutes).
246
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxpreloaderidletime
1280
247
 
1281
248
  ==== PassengerStartTimeout <seconds> ====
1282
- :version: 4.0.15
1283
- include::users_guide_snippets/since_version.txt[]
1284
-
1285
- Specifies a timeout for the startup of application processes. If an application process fails to start within the timeout period then it will be forcefully killed with SIGKILL, and the error will be logged.
1286
-
1287
- This option may occur in the following places:
1288
249
 
1289
- * In the global server configuration.
1290
- * In a virtual host configuration block.
1291
- * In a `<Directory>` or `<Location>` block.
1292
- * In '.htaccess', if `AllowOverride Limits` is on.
1293
-
1294
- In each place, it may be specified at most once. The default value is '90'.
250
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerstarttimeout
1295
251
 
1296
252
  [[PassengerConcurrencyModel]]
1297
253
  ==== PassengerConcurrencyModel <process|thread> ====
1298
- :version: 4.0.0
1299
- include::users_guide_snippets/enterprise_only.txt[]
1300
-
1301
- Specifies the I/O concurrency model that should be used for Ruby application processes. Phusion Passenger supports two concurrency models:
1302
-
1303
- * 'process' - single-threaded, multi-processed I/O concurrency. Each application process only has a single thread and can only handle 1 request at a time. This is the concurrency model that Ruby applications traditionally used. It has excellent compatiblity (can work with applications that are not designed to be thread-safe) but is unsuitable for workloads in which the application has to wait for a lot of external I/O (e.g. HTTP API calls), and uses more memory because each process has a large memory overhead.
1304
- * 'thread' - multi-threaded, multi-processed I/O concurrency. Each application process has multiple threads (customizable via <<PassengerThreadCount,PassengerThreadCount>>). This model provides much better I/O concurrency and uses less memory because threads share memory with each other within the same process. However, using this model may cause compatibility problems if the application is not designed to be thread-safe.
1305
-
1306
- This option has no effect on non-Ruby applications.
1307
254
 
1308
- This option may occur in the following places:
1309
-
1310
- * In the global server configuration.
1311
- * In a virtual host configuration block.
1312
- * In a `<Directory>` or `<Location>` block.
1313
- * In '.htaccess'.
1314
-
1315
- In each place, it may be specified at most once. The default value is 'process'.
255
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerconcurrencymodel
1316
256
 
1317
257
  [[PassengerThreadCount]]
1318
258
  ==== PassengerThreadCount <number> ====
1319
- :version: 4.0.0
1320
- include::users_guide_snippets/enterprise_only.txt[]
1321
-
1322
- Specifies the number of threads that Phusion Passenger should spawn per Ruby application process. This option only has effect if <<PassengerConcurrencyModel,PassengerConcurrencyModel>> is 'thread'.
1323
259
 
1324
- This option has no effect on non-Ruby applications.
1325
-
1326
- This option may occur in the following places:
1327
-
1328
- * In the global server configuration.
1329
- * In a virtual host configuration block.
1330
- * In a `<Directory>` or `<Location>` block.
1331
- * In '.htaccess'.
1332
-
1333
- In each place, it may be specified at most once. The default value is '1'.
260
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerthreadcount
1334
261
 
1335
262
  [[PassengerMaxRequests]]
1336
263
  ==== PassengerMaxRequests <integer> ====
1337
- The maximum number of requests an application process will process. After
1338
- serving that many requests, the application process will be shut down and
1339
- Phusion Passenger will restart it. A value of 0 means that there is no maximum:
1340
- an application process will thus be shut down when its idle timeout has been
1341
- reached.
1342
-
1343
- This option is useful if your application is leaking memory. By shutting
1344
- it down after a certain number of requests, all of its memory is guaranteed
1345
- to be freed by the operating system.
1346
-
1347
- This option may occur in the following places:
1348
-
1349
- * In the global server configuration.
1350
- * In a virtual host configuration block.
1351
- * In a `<Directory>` or `<Location>` block.
1352
- * In '.htaccess', if `AllowOverride Limits` is on.
1353
-
1354
- In each place, it may be specified at most once. The default value is '0'.
1355
264
 
1356
- [CAUTION]
1357
- =====================================================
1358
- The <<PassengerMaxRequests,PassengerMaxRequests>> directive should be considered
1359
- as a workaround for misbehaving applications. It is advised that you fix the
1360
- problem in your application rather than relying on these directives as a
1361
- measure to avoid memory leaks.
1362
- =====================================================
265
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxrequests
1363
266
 
1364
267
  [[PassengerMaxRequestTime]]
1365
268
  ==== PassengerMaxRequestTime <seconds> ====
1366
- :version: 3.0.0
1367
- include::users_guide_snippets/enterprise_only.txt[]
1368
-
1369
- The maximum amount of time, in seconds, that an application process may take
1370
- to process a request. If the request takes longer than this amount of time,
1371
- then the application process will be forcefully shut down, and possibly
1372
- restarted upon the next request. A value of 0 means that there is no time limit.
1373
-
1374
- This option is useful for preventing your application from freezing for an
1375
- indefinite period of time.
1376
-
1377
- This option may occur in the following places:
1378
-
1379
- * In the global server configuration.
1380
- * In a virtual host configuration block.
1381
- * In a `<Directory>` or `<Location>` block.
1382
- * In '.htaccess', if `AllowOverride Limits` is on.
1383
-
1384
- In each place, it may be specified at most once. The default value is '0'.
1385
-
1386
- .Example
1387
- Suppose that most of your requests are known to finish within 2 seconds.
1388
- However, there is one URI, '/expensive_computation', which is known to take up
1389
- to 10 seconds. You can then configure Phusion Passenger as follows:
1390
-
1391
- ----------------------------------------------
1392
- <VirtualHost *:80>
1393
- ServerName www.example.com
1394
- DocumentRoot /webapps/my_app/public
1395
-
1396
- PassengerMaxRequestTime 2
1397
- <Location /expensive_computation>
1398
- PassengerMaxRequestTime 10
1399
- </Location>
1400
- </VirtualHost>
1401
- ----------------------------------------------
1402
-
1403
- If a request to '/expensive_computation' takes more than 10 seconds,
1404
- or if a request to any other URI takes more than 2 seconds,
1405
- then the corresponding application process will be forced to shutdown.
1406
-
1407
- [CAUTION]
1408
- =====================================================
1409
- The <<PassengerMaxRequestTime,PassengerMaxRequestTime>> directive should be
1410
- considered as a workaround for misbehaving applications. It is advised that you
1411
- fix the problem in your application rather than relying on these directives as a
1412
- measure to avoid freezing applications.
1413
- =====================================================
269
+
270
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxrequesttime
1414
271
 
1415
272
  [[PassengerMemoryLimit]]
1416
273
  ==== PassengerMemoryLimit <integer> ====
1417
- :version: 3.0.0
1418
- include::users_guide_snippets/enterprise_only.txt[]
1419
-
1420
- The maximum amount of memory that an application process may use, in megabytes.
1421
- Once an application process has surpassed its memory limit, it will process
1422
- all the requests currently present in its queue and then shut down.
1423
- A value of 0 means that there is no maximum: the application's memory usage
1424
- will not be checked.
1425
-
1426
- This option is useful if your application is leaking memory. By shutting
1427
- it down, all of its memory is guaranteed to be freed by the operating system.
1428
-
1429
- This option may occur in the following places:
1430
-
1431
- * In the global server configuration.
1432
- * In a virtual host configuration block.
1433
- * In a `<Directory>` or `<Location>` block.
1434
- * In '.htaccess', if `AllowOverride Limits` is on.
1435
-
1436
- In each place, it may be specified at most once. The default value is '0'.
1437
-
1438
- [NOTE]
1439
- .A word about permissions
1440
- =====================================================
1441
- The <<PassengerMemoryLimit,PassengerMemoryLimit>> directive uses
1442
- `ps` command to query memory usage information. On Linux, it further
1443
- queries `/proc` to obtain additional memory usage information that's
1444
- not obtainable through `ps`. You should ensure that the `ps` works
1445
- correctly and that the `/proc` filesystem is accessible by the
1446
- `PassengerAgent core` process.
1447
- =====================================================
1448
-
1449
- [CAUTION]
1450
- =====================================================
1451
- The <<PassengerMaxRequests,PassengerMaxRequests>> and
1452
- <<PassengerMemoryLimit,PassengerMemoryLimit>> directives should be considered
1453
- as workarounds for misbehaving applications. It is advised that you fix the
1454
- problem in your application rather than relying on these directives as a
1455
- measure to avoid memory leaks.
1456
- =====================================================
1457
-
1458
- ==== PassengerStatThrottleRate <integer> ====
1459
- By default, Phusion Passenger performs several filesystem checks (or, in
1460
- programmers jargon, 'stat() calls') each time a request is processed:
1461
-
1462
- - It checks which the application <<PassengerStartupFile,startup files>> are present, in order to autodetect the application type.
1463
- - It checks whether 'restart.txt' has changed or whether 'always_restart.txt'
1464
- exists, in order to determine whether the application should be restarted.
1465
274
 
1466
- On some systems where disk I/O is expensive, e.g. systems where the harddisk is
1467
- already being heavily loaded, or systems where applications are stored on NFS
1468
- shares, these filesystem checks can incur a lot of overhead.
275
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermemorylimit
1469
276
 
1470
- You can decrease or almost entirely eliminate this overhead by setting
1471
- 'PassengerStatThrottleRate'. Setting this option to a value of 'x' means that
1472
- the above list of filesystem checks will be performed at most once every 'x'
1473
- seconds. Setting it to a value of '0' means that no throttling will take place,
1474
- or in other words, that the above list of filesystem checks will be performed on
1475
- every request.
277
+ ==== PassengerStatThrottleRate <integer> ====
1476
278
 
1477
- This option may be specified once, in the global server configuration. The default value is '10'.
279
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerstatthrottlerate
1478
280
 
1479
281
  [[PassengerPreStart]]
1480
282
  ==== PassengerPreStart <url> ====
1481
- By default, Phusion Passenger does not start any application processes until said
1482
- web application is first accessed. The result is that the first visitor of said
1483
- web application might experience a small delay as Phusion Passenger is starting
1484
- the web application on demand. If that is undesirable, then this directive can be
1485
- used to pre-started application processes during Apache startup.
1486
-
1487
- A few things to be careful of:
1488
-
1489
- - This directive accepts the *URL* of the web application you want to pre-start,
1490
- not a on/off value! This might seem a bit weird, but read on for rationale. As
1491
- for the specifics of the URL:
1492
- * The domain part of the URL must be equal to the value of the 'ServerName'
1493
- directive of the VirtualHost block that defines the web application.
1494
- * Unless the web application is deployed on port 80, the URL should contain
1495
- the web application's port number too.
1496
- * The path part of the URL must point to some URI that the web application
1497
- handles.
1498
- - You will probably want to combine this option with
1499
- <<PassengerMinInstances,PassengerMinInstances>> because application processes
1500
- started with 'PassengerPreStart' are subject to the usual idle timeout rules.
1501
- See the example below for an explanation.
1502
-
1503
- This option may occur in the following places:
1504
-
1505
- * In the global server configuration.
1506
- * In a virtual host configuration block.
1507
-
1508
- In each place, it may be specified any number of times.
1509
-
1510
- ===== Example 1: basic usage =====
1511
-
1512
- Suppose that you have the following web applications.
1513
-
1514
- ---------------------------
1515
- <VirtualHost *:80>
1516
- ServerName foo.com
1517
- DocumentRoot /webapps/foo/public
1518
- </VirtualHost>
1519
-
1520
- <VirtualHost *:3500>
1521
- ServerName bar.com
1522
- DocumentRoot /webapps/bar/public
1523
- </VirtualHost>
1524
- ---------------------------
1525
-
1526
- You want both of them to be pre-started during Apache startup. The URL for
1527
- foo.com is 'http://foo.com/' (or, equivalently, 'http://foo.com:80/') and
1528
- the URL for bar.com is 'http://bar.com:3500/'. So we add two PassengerPreStart
1529
- directives, like this:
1530
-
1531
- ---------------------------
1532
- <VirtualHost *:80>
1533
- ServerName foo.com
1534
- DocumentRoot /webapps/foo/public
1535
- </VirtualHost>
1536
-
1537
- <VirtualHost *:3500>
1538
- ServerName bar.com
1539
- DocumentRoot /webapps/bar/public
1540
- </VirtualHost>
1541
-
1542
- PassengerPreStart http://foo.com/ # <--- added
1543
- PassengerPreStart http://bar.com:3500/ # <--- added
1544
- ---------------------------
1545
-
1546
- ===== Example 2: pre-starting apps that are deployed in sub-URIs =====
1547
-
1548
- Suppose that you have a web application deployed in a sub-URI '/store', like this:
1549
-
1550
- ---------------------------
1551
- <VirtualHost *:80>
1552
- ServerName myblog.com
1553
- DocumentRoot /webapps/wordpress
1554
-
1555
- Alias /store /websites/store/public
1556
- <Location /store>
1557
- PassengerBaseURI /store
1558
- PassengerAppRoot /websites/store
1559
- </Location>
1560
- <Directory /websites/store/public>
1561
- Allow from all
1562
- Options -MultiViews
1563
- # Uncomment this if you're on Apache >= 2.4:
1564
- #Require all granted
1565
- </Directory>
1566
- </VirtualHost>
1567
- ---------------------------
1568
-
1569
- Then specify the domain name of its containing virtual host followed by the sub-URI,
1570
- like this:
1571
-
1572
- ---------------------------
1573
- <VirtualHost *:80>
1574
- ServerName myblog.com
1575
- DocumentRoot /webapps/wordpress
1576
-
1577
- Alias /store /websites/store/public
1578
- <Location /store>
1579
- PassengerBaseURI /store
1580
- PassengerAppRoot /websites/store
1581
- </Location>
1582
- <Directory /websites/store/public>
1583
- Allow from all
1584
- Options -MultiViews
1585
- # Uncomment this if you're on Apache >= 2.4:
1586
- #Require all granted
1587
- </Directory>
1588
- </VirtualHost>
1589
-
1590
- PassengerPreStart http://myblog.com/store # <----- added
1591
- ---------------------------
1592
-
1593
- The sub-URI *must* be included; if you don't then the directive will have no effect.
1594
- The following example is wrong and won't pre-start the store web application:
1595
-
1596
- ---------------------------
1597
- PassengerPreStart http://myblog.com/ # <----- WRONG! Missing "/store" part.
1598
- ---------------------------
1599
-
1600
- ===== Example 3: combining with PassengerMinInstances =====
1601
-
1602
- Application processes started with PassengerPreStart are
1603
- also subject to the idle timeout rules as specified by
1604
- <<PassengerPoolIdleTime,PassengerPoolIdleTime>>! That means that by default,
1605
- the pre-started application processes for foo.com and bar.com are shut down
1606
- after a few minutes of inactivity. If you don't want that to happen, then
1607
- you should combine PassengerPreStart with
1608
- <<PassengerMinInstances,PassengerMinInstances>>, like this:
1609
-
1610
- ---------------------------
1611
- <VirtualHost *:80>
1612
- ServerName foo.com
1613
- DocumentRoot /webapps/foo/public
1614
- # Added!
1615
- PassengerMinInstances 1
1616
- </VirtualHost>
1617
-
1618
- <VirtualHost *:3500>
1619
- ServerName bar.com
1620
- DocumentRoot /webapps/bar/public
1621
- # Added!
1622
- PassengerMinInstances 1
1623
- </VirtualHost>
1624
-
1625
- PassengerPreStart http://foo.com/
1626
- PassengerPreStart http://bar.com:3500/
1627
- ---------------------------
1628
-
1629
- ===== So why a URL? Why not just an on/off flag? =====
1630
-
1631
- A directive that accepts a simple on/off flag is definitely more intuitive,
1632
- but due technical difficulties w.r.t. the way Apache works, it's very hard
1633
- to implement it like that:
1634
-
1635
- - It is very hard to obtain a full list of web applications defined in the
1636
- Apache configuration file(s). In other words, it's hard for Phusion Passenger
1637
- to know which web applications are deployed on Apache until a web application
1638
- is first accessed, and without such a list Phusion Passenger wouldn't know
1639
- which web applications to pre-start. It's probably not completely impossible
1640
- to obtain such a list, but this brings us to the following point;
1641
- - Users expect things like 'mod_env' to work even in combination with Phusion
1642
- Passenger. For example some people put ``SetEnv PATH ....'' in their virtual
1643
- host block and they expect the web application to pick that environment variable
1644
- up when it's started. Information like this is stored in module-specific
1645
- locations that Phusion Passenger cannot access directly. Even if the previous
1646
- bullet point is solved and we can obtain a list of web applications,
1647
- we cannot start the application with the correct mod_env information.
1648
- mod_env is just one such example; there are probably many other Apache modules,
1649
- all of which people expect to work, but we cannot answer to those expectations
1650
- if PassengerPreStart is implemented as a simple on/off flag.
1651
-
1652
- So as a compromise, we made it accept a URL. This is easier to implement for
1653
- us and altough it looks weird, it behaves consistently w.r.t. cooperation
1654
- with other Apache modules.
1655
-
1656
- ===== What does Phusion Passenger do with the URL? =====
1657
-
1658
- During Apache startup, Phusion Passenger will send a dummy HEAD request to the
1659
- given URL and discard the result. In other words, Phusion Passenger simulates a
1660
- web access at the given URL. However this simulated request is always sent to
1661
- localhost, *not* to the IP that the domain resolves to. Suppose that bar.com
1662
- in example 1 resolves to 209.85.227.99; Phusion Passenger will
1663
- send the following HTTP request to 127.0.0.1 port 3500 (and not to 209.85.227.99
1664
- port 3500):
1665
-
1666
- ----------------------
1667
- HEAD / HTTP/1.1
1668
- Host: bar.com
1669
- Connection: close
1670
- ----------------------
1671
-
1672
- Similarly, for example 2, Phusion Passenger will send the following HTTP request
1673
- to 127.0.0.1 port 80:
1674
-
1675
- ----------------------
1676
- HEAD /store HTTP/1.1
1677
- Host: myblog.com
1678
- Connection: close
1679
- ----------------------
1680
-
1681
- ===== Do I need to edit /etc/hosts and point the domain in the URL to 127.0.0.1? =====
1682
-
1683
- No. See previous subsection.
1684
-
1685
- ===== My web application consists of multiple web servers. What URL do I need to specify, and in which web server's Apache config file? =====
1686
-
1687
- Put the web application's virtual host's ServerName value and the virtual host's
1688
- port in the URL, and put
1689
- PassengerPreStart on all machines that you want to pre-start the web application
1690
- on. The simulated web request is always sent to 127.0.0.1, with the domain name
1691
- in the URL as value for the 'Host' HTTP header, so you don't need to worry about
1692
- the request ending up at a different web server in the cluster.
1693
-
1694
- ===== Does PassengerPreStart support https:// URLs? =====
1695
-
1696
- Yes. And it does not perform any certificate validation.
283
+
284
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerprestart
1697
285
 
1698
286
  [[PassengerHighPerformance]]
1699
287
  ==== PassengerHighPerformance <on|off> ====
1700
- By default, Phusion Passenger is compatible with mod_rewrite and most other
1701
- Apache modules. However, a lot of effort is required in order to be compatible.
1702
- If you turn 'PassengerHighPerformance' to 'on', then Phusion Passenger will be
1703
- a little faster, in return for reduced compatibility with other Apache modules.
1704
-
1705
- In places where 'PassengerHighPerformance' is turned on, mod_rewrite rules will
1706
- likely not work. mod_autoindex (the module which displays a directory index)
1707
- will also not work. Other Apache modules may or may not work, depending on what
1708
- they exactly do. We recommend you to find out how other modules behave in high
1709
- performance mode via testing.
1710
-
1711
- This option is *not* an all-or-nothing global option: you can enable high
1712
- performance mode for certain virtual hosts or certain URLs only.
1713
- The 'PassengerHighPerformance' option may occur in the following places:
1714
-
1715
- * In the global server configuration.
1716
- * In a virtual host configuration block.
1717
- * In a `<Directory>` or `<Location>` block.
1718
- * In '.htaccess'.
1719
-
1720
- In each place, it may be specified at most once. The default value is 'off',
1721
- so high performance mode is disabled by default, and you have to explicitly
1722
- enable it.
1723
-
1724
- .When to enable high performance mode?
1725
-
1726
- If you do not use mod_rewrite or other Apache modules then it might make
1727
- sense to enable high performance mode.
1728
-
1729
- It's likely that some of your applications depend on mod_rewrite or other
1730
- Apache modules, while some do not. In that case you can enable high performance
1731
- for only those applications that don't use other Apache modules. For example:
1732
-
1733
- ------------------------------------
1734
- <VirtualHost *:80>
1735
- ServerName www.foo.com
1736
- DocumentRoot /apps/foo/public
1737
- .... mod_rewrite rules or options for other Apache modules here ...
1738
- </VirtualHost>
1739
-
1740
- <VirtualHost *:80>
1741
- ServerName www.bar.com
1742
- DocumentRoot /apps/bar/public
1743
- PassengerHighPerformance on
1744
- </VirtualHost>
1745
- ------------------------------------
1746
-
1747
- In the above example, high performance mode is only enabled for www.bar.com.
1748
- It is disabled for everything else.
1749
-
1750
- If your application generally depends on mod_rewrite or other Apache modules,
1751
- but a certain URL that's accessed often doesn't depend on those other modules,
1752
- then you can enable high performance mode for a certain URL only. For example:
1753
-
1754
- ------------------------------------
1755
- <VirtualHost *:80>
1756
- ServerName www.foo.com
1757
- DocumentRoot /apps/foo/public
1758
- .... mod_rewrite rules or options for other Apache modules here ...
1759
-
1760
- <Location /chatroom/ajax_update_poll>
1761
- PassengerHighPerformance on
1762
- </Location>
1763
- </VirtualHost>
1764
- ------------------------------------
1765
-
1766
- This enables high performance mode for
1767
- http://www.foo.com/chatroom/ajax_update_poll only.
288
+
289
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerhighperformance
1768
290
 
1769
291
 
1770
292
  /////////////////////////////////////////
@@ -1775,461 +297,125 @@ http://www.foo.com/chatroom/ajax_update_poll only.
1775
297
 
1776
298
  [[PassengerBufferUpload]]
1777
299
  ==== PassengerBufferUpload <on|off> ====
1778
- :version: 4.0.26
1779
- include::users_guide_snippets/since_version.txt[]
1780
300
 
1781
- When turned on, HTTP client request bodies <<PassengerDataBufferDir,will be buffered>> before they are sent the request to the application. This buffering protects the application from slow clients, but also prevents the ability to track upload progress.
1782
-
1783
- If you want to allow your application to track upload progress, it is recommended that you disable upload buffering for specific URIs only. For example:
1784
-
1785
- ------------------------
1786
- # Disable upload buffering for /upload_video only.
1787
- <Location /upload_video>
1788
- PassengerBufferUpload off
1789
- </Location>
1790
- ------------------------
1791
-
1792
- This option may occur in the following places:
1793
-
1794
- * In the global server configuration.
1795
- * In a virtual host configuration block.
1796
- * In a `<Directory>` or `<Location>` block.
1797
- * In '.htaccess'.
1798
-
1799
- In each place, it may be specified at most once. The default value is 'on'.
301
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerbufferupload
1800
302
 
1801
303
  [[PassengerBufferResponse]]
1802
304
  ==== PassengerBufferResponse <on|off> ====
1803
- When turned on, application-generated responses are buffered by Apache. Buffering will
1804
- happen in memory.
1805
-
1806
- Before we proceed with explaining this configuration option, we want to state the following to avoid confusion. If you use Phusion Passenger for Apache, there are in fact two response buffering systems active:
1807
-
1808
- 1. The Apache response buffering system. `PassengerBufferResponse` turns this on or off.
1809
- 2. The Phusion Passenger response buffering system, a.k.a. 'real-time disk-backed response buffering'. This buffering system is always on, regardless of the value of `PassengerBufferResponse`, but its behavior can be tweaked with <<PassengerResponseBufferHighWatermark,PassengerResponseBufferHighWatermark>>.
1810
-
1811
- Response buffering is useful because it protects against slow HTTP clients that do not read responses immediately or quickly enough. Buffering prevents such slow clients from blocking web applications that have limited concurrency. Because Phusion Passenger's response buffering is always turned on, you are always protected. Therefore, `PassengerBufferResponse` is off by default, and you never should have to turn it on.
1812
-
1813
- If for whatever reason you want to turn Apache-level response buffering on, you can do so with this option.
1814
-
1815
- Apache's response buffering works differently from Phusion Passenger's. Apache's buffering system buffers the entire response before attempting to send it to the client, while Phusion Passenger's attempts to send the data to the client immediately. Therefore, if you turn on `PassengerBufferResponse`, you may interfere with applications that want to stream responses to the client.
1816
- Apache's version also buffers to memory only, making it problematic for large responses. Phusion Passenger's version buffers to disk when the response exceeds a certain threshold.
1817
-
1818
- How does response buffering - whether it's done by Apache or by Phusion Passenger - exactly protect against slow clients?
1819
- Consider an HTTP client that's on a dial-up modem link, and your
1820
- application process generates a 2 MB response. If the response is not buffered
1821
- then your application process will be blocked until the entire 2 MB has been
1822
- sent out to the HTTP client. This disallows your application process to do any useful
1823
- work in the mean time. By buffering responses, Phusion Passenger or Apache will read
1824
- the application response as quickly as possible and will take care of forwarding the data
1825
- to slow clients.
1826
-
1827
- So keep in mind that enabling `passenger_buffering_response` will make streaming responses
1828
- impossible. Consider for example this piece of Rails code:
1829
-
1830
- --------------------------------
1831
- render :text => lambda { |response, output|
1832
- 10.times do |i|
1833
- output.write("entry #{i}\n")
1834
- output.flush
1835
- sleep 1
1836
- end
1837
- }
1838
- --------------------------------
1839
-
1840
- ...or this piece of Rack code:
1841
-
1842
- --------------------------------
1843
- class Response
1844
- def each
1845
- 10.times do |i|
1846
- yield("entry #{i}\n")
1847
- sleep 1
1848
- end
1849
- end
1850
- end
1851
-
1852
- app = lambda do |env|
1853
- [200, { "Content-Type" => "text/plain" }, Response.new]
1854
- end
1855
- --------------------------------
1856
-
1857
- When `PassengerBufferResponse` is turned on, Apache will wait until
1858
- the application is done sending the entire response before forwarding it
1859
- to the client. The client will not receive anything for 10 seconds,
1860
- after which it receives the entire response at once.
1861
- When `PassengerBufferResponse` is turned off, it works as expected: the client
1862
- receives an "entry X" message every second for 10 seconds.
1863
-
1864
- This option may occur in the following places:
1865
-
1866
- * In the global server configuration.
1867
- * In a virtual host configuration block.
1868
- * In a `<Directory>` or `<Location>` block.
1869
- * In '.htaccess'.
1870
-
1871
- In each place, it may be specified at most once. The default value is 'off'.
1872
-
1873
- [NOTE]
1874
- =====================================================
1875
- The <<PassengerBufferResponse,PassengerBufferResponse>> directive should be turned off
1876
- if responses can be huge. Because entire responses are buffered in memory when turned on.
1877
- =====================================================
305
+
306
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerbufferresponse
1878
307
 
1879
308
  [[PassengerResponseBufferHighWatermark]]
1880
309
  ==== PassengerResponseBufferHighWatermark <bytes>
1881
- :version: 5.0.0
1882
- include::users_guide_snippets/since_version.txt[]
1883
-
1884
- As explained in <<passenger_buffer_response,PassengerBufferResponse>>, Phusion Passenger has two response buffering mechanisms. This option configures the maximum size of the real-time disk-backed response buffering system. If the buffer is full, the application will be blocked until the client has fully read the buffer.
1885
-
1886
- This buffering system has a default size of *128 MB* (134217728 bytes). This default value is large enough to prevent most applications from blocking on slow clients, but small enough to prevent broken applications from filling up the hard disk.
1887
310
 
1888
- You can't disable real-time disk-backed response buffering, but you can set the buffer size to a small value, which is effectively the same as disabling it.
1889
-
1890
- Most of the time, you won't need to tweak this value. But there is one good use case where you may want set this option to a low value: if you are streaming a large response, but want to detect client disconnections as soon as possible. If the buffer size is larger than your response size, then Phusion Passenger will read and buffer the response as fast as it can, offloading the application as soon as it can, thereby preventing the application from detecting client disconnects. But if the buffer size is sufficiently small (say, 64 KB), then your application will effectively output response data at the same speed as the client reads it, allowing you to detect client disconnects almost immediately. This is also a down side, because many slow clients blocking your application can result in a denial of service, so use this option with care.
1891
-
1892
- If your application outputs responses larger than 128 MB and you are not interested in detecting client disconnects as soon as possible, then you should raise this value, or set it to 0.
1893
-
1894
- A value of 0 means that the buffer size is unlimited.
1895
-
1896
- This option may only occur once, in the global server configuration. The default value is '134217728' (128 MB).
311
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerresponsebufferhighwatermark
1897
312
 
1898
313
  [[PassengerErrorOverride]]
1899
314
  ==== PassengerErrorOverride <on|off> ====
1900
- :version: 4.0.24
1901
- include::users_guide_snippets/since_version.txt[]
1902
-
1903
- Decides whether Apache will intercept and handle responses with HTTP status codes of 400 and higher. This directive is useful where you want to have a common look and feel on the error pages seen by the end user. This also allows for included files (via mod_include's SSI) to get the error code and act accordingly (default behavior would display the error page of the proxied server, turning this on shows the SSI Error message).
1904
-
1905
- This directive does not affect the processing of informational (1xx), normal success (2xx), or redirect (3xx) responses.
1906
-
1907
- By default, all responses are sent as-is from the application or from the Phusion Passenger core. If you turn this option on then Apache will be able to handle such responses using the Apache `ErrorDocument` option.
1908
315
 
1909
- This option may occur in the following places:
1910
-
1911
- * In the global server configuration.
1912
- * In a virtual host configuration block.
1913
- * In a `<Directory>` or `<Location>` block.
1914
- * In '.htaccess'.
1915
-
1916
- In each place, it may be specified at most once. The default value is 'off'.
316
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengererroroverride
1917
317
 
1918
318
  [[PassengerMaxRequestQueueSize]]
1919
319
  ==== PassengerMaxRequestQueueSize <number> ====
1920
- :version: 4.0.15
1921
- include::users_guide_snippets/since_version.txt[]
1922
-
1923
- When all application processes are already handling their maximum number of concurrent requests, Phusion Passenger will queue all incoming requests. This option specifies the maximum size for that queue. If the queue is already at this specified limit, then Phusion Passenger will immediately send a "503 Service Unavailable" error to any incoming requests.
1924
-
1925
- A value of 0 means that the queue is unbounded.
1926
-
1927
- link:http://stackoverflow.com/questions/20402801/what-is-optimal-value-for-phusion-passenger-passengermaxrequestqueuesize[This article on StackOverflow] explains how the request queue works, what it means for the queue to grow or become full, why that is bad, and what you can do about it.
1928
-
1929
- You may combine this option with <<PassengerErrorOverride,PassengerErrorOverride>> and `ErrorDocument` to set a custom error page whenever the queue is full. In the following example, Apache will serve /error503.html whenever the queue is full:
1930
-
1931
- ---------------------------------
1932
- PassengerErrorOverride on
1933
- ErrorDocument 503 /error503.html
1934
- ---------------------------------
1935
320
 
1936
- This option may occur in the following places:
1937
-
1938
- * In the global server configuration.
1939
- * In a virtual host configuration block.
1940
- * In a `<Directory>` or `<Location>` block.
1941
- * In '.htaccess'.
1942
-
1943
- In each place, it may be specified at most once. The default value is '100'.
321
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengermaxrequestqueuesize
1944
322
 
1945
323
  [[PassengerStickySessions]]
1946
324
  ==== PassengerStickySessions <on|off>
1947
- :version: 4.0.45
1948
- include::users_guide_snippets/since_version.txt[]
1949
-
1950
- When sticky sessions are enabled, all requests that a client sends will be routed to the same originating application process, whenever possible. When sticky sessions are disabled, requests may be distributed over multiple processes, and may not necessarily be routed to the originating process, in order to balance traffic over multiple CPU cores. Because of this, sticky sessions should only be enabled in specific circumstances.
1951
-
1952
- For applications that store important state inside the process's own memory -- that is, as opposed to storing state in a distributed data store, such as the database or Redis -- sticky sessions *should* be enabled. This is because otherwise, some requests could be routed to a different process, which stores different state data. Because processes don't share memory with each other, there's no way for one process to know about the state in another process, and then things can go wrong.
1953
-
1954
- One prominent example is the popular link:http://sockjs.org/[SockJS library], which is capable of emulating WebSockets through long polling. This is implemented through two HTTP endpoints, `/SESSION_ID/xhr_stream` (a long polling end point which sends data from the server to the client), and `/SESSION_ID/xhr_send` (a normal POST endpoint which is used for sending data from the client to the server). SockJS correlates the two requests with each other through a session identifier. At the same time, in its default configuration, it stores all known session identifiers in an in-memory data structure. It is therefore important that a particular `/SESSION_ID/xhr_send` request is sent to the same process where the corresponding `/SESSION_ID/xhr_stream` request originates from; otherwise, SockJS cannot correlate the two requests, and an error occurs.
1955
-
1956
- So prominent examples where sticky sessions should (or even *must*) be enabled, include:
1957
-
1958
- * Applications that use the SockJS library (unless configured with a distributed data store)
1959
- * Applications that use the Socket.io library (unless configured with a distributed data store)
1960
- * Applications that use the faye-websocket gem (unless configured with a distributed data store)
1961
- * Meteor JS applications (because Meteor uses SockJS)
1962
325
 
1963
- Sticky sessions work through the use of a special cookie, whose name can be customized with <<PassengerStickySessionsCookieName,PassengerStickySessionsCookieName>>. Phusion Passenger puts an identifier in this cookie, which tells Phusion Passenger what the originating process is. Next time the client sends a request, Phusion Passenger reads this cookie and uses the value in the cookie to route the request back to the originating process. If the originating process no longer exists (e.g. because it has crashed or restarted) then Phusion Passenger will route the request to some other process, and reset the cookie.
1964
-
1965
- If you have a load balancer in front end of Phusion Passenger + Apache, then you must configure sticky sessions on that load balancer too. Otherwise, the load balancer could route the request to a different server.
1966
-
1967
- This option may occur in the following places:
1968
-
1969
- * In the global server configuration.
1970
- * In a virtual host configuration block.
1971
- * In a `<Directory>` or `<Location>` block.
1972
- * In '.htaccess'.
1973
-
1974
- In each place, it may be specified at most once. The default value is `off`.
326
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerstickysessions
1975
327
 
1976
328
  [[PassengerStickySessionsCookieName]]
1977
329
  ==== PassengerStickySessionsCookieName
1978
- :version: 4.0.45
1979
- include::users_guide_snippets/since_version.txt[]
1980
330
 
1981
- Sets the name of the <<PassengerStickySessions,sticky sessions>> cookie.
1982
-
1983
- This option may occur in the following places:
1984
-
1985
- * In the global server configuration.
1986
- * In a virtual host configuration block.
1987
- * In a `<Directory>` or `<Location>` block.
1988
- * In '.htaccess'.
1989
-
1990
- In each place, it may be specified at most once. The default value is `passenger_route`.
331
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerstickysessionscookiename
1991
332
 
1992
333
 
1993
334
  === Compatibility options ===
1994
335
 
1995
336
  [[PassengerResolveSymlinksInDocumentRoot]]
1996
337
  ==== PassengerResolveSymlinksInDocumentRoot <on|off> ====
1997
- Configures whether Phusion Passenger should resolve symlinks in the document root.
1998
- Please refer to <<application_detection,How Phusion Passenger detects whether a
1999
- virtual host is a web application>> for more information.
2000
-
2001
- This option may occur in the following places:
2002
338
 
2003
- * In the global server configuration.
2004
- * In a virtual host configuration block.
2005
- * In a `<Directory>` or `<Location>` block.
2006
- * In '.htaccess', if `AllowOverride Options` is on.
2007
-
2008
- In each place, it may be specified at most once. It is off by default.
339
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerresolvesymlinksindocumentroot
2009
340
 
2010
341
  ==== PassengerAllowEncodedSlashes <on|off> ====
2011
- By default, Apache doesn't support URLs with encoded slashes (%2f), e.g. URLs like
2012
- this: `/users/fujikura%2fyuu`. If you access such an URL then Apache will return a
2013
- 404 Not Found error. This can be solved by turning on PassengerAllowEncodedSlashes
2014
- as well as Apache's
2015
- link:http://httpd.apache.org/docs/2.0/mod/core.html#allowencodedslashes[AllowEncodedSlashes].
2016
-
2017
- Is it important that you turn on both AllowEncodedSlashes *and* PassengerAllowEncodedSlashes,
2018
- otherwise this feature will not work properly.
2019
-
2020
- PassengerAllowEncodedSlashes may occur in the following places:
2021
-
2022
- * In the global server configuration.
2023
- * In a virtual host configuration block.
2024
- * In a `<Directory>` or `<Location>` block.
2025
- * In '.htaccess', if `AllowOverride Options` is on.
2026
-
2027
- In each place, it may be specified at most once. It is off by default.
2028
-
2029
- Please note however that turning on support for encoded slashes will break support for
2030
- mod_rewrite passthrough rules. Because of bugs/limitations in Apache, Phusion Passenger
2031
- can support either encoded slashes or mod_rewrite passthrough rules, but not both at the
2032
- same time. Luckily this option can be specified anywhere, so you can enable it only for
2033
- virtual hosts or URLs that need it:
2034
-
2035
- ----------------------------------
2036
- <VirtualHost *:80>
2037
- ServerName www.example.com
2038
- DocumentRoot /webapps/example/public
2039
- AllowEncodedSlashes on
2040
- RewriteEngine on
2041
-
2042
- # Check for maintenance file and redirect all requests
2043
- RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
2044
- RewriteCond %{SCRIPT_FILENAME} !maintenance.html
2045
- RewriteRule ^.*$ /system/maintenance.html [L]
2046
-
2047
- # Make /about an alias for /info/about.
2048
- RewriteRule ^/about$ /info/about [PT,L]
2049
-
2050
- <Location ~ "^/users/">
2051
- # In a location block so that it doesn't interfere with the
2052
- # above /about mod_rewrite rule.
2053
- PassengerAllowEncodedSlashes on
2054
- </Location>
2055
- </VirtualHost>
2056
- ----------------------------------
2057
-
2058
- With this, http://www.example.com/users/fujikura%2fyuu will work properly, and
2059
- accessing http://www.example.com/about will properly display the result of
2060
- http://www.example.com/info/about. Notice that PassengerAllowEncodedSlashes only
2061
- interferes with passthrough rules, not with any other mod_rewrite rules. The rules for
2062
- displaying maintenance.html will work fine even for URLs starting with "/users".
342
+
343
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerallowencodedslashes
2063
344
 
2064
345
 
2065
346
  === Logging and debugging options ===
2066
347
 
2067
348
  [[PassengerLogLevel]]
2068
349
  ==== PassengerLogLevel <integer> ====
2069
- This option allows one to specify how much information Phusion Passenger should
2070
- write to the Apache error log file. A higher log level value means that more
2071
- information will be logged.
2072
-
2073
- Possible values are:
2074
-
2075
- - '0' (crit): Show only critical errors which would cause Phusion Passenger to abort.
2076
- - '1' (error): Also show non-critical errors -- errors that do not cause Phusion Passenger to abort.
2077
- - '2' (warn): Also show warnings. These are not errors, and Phusion Passenger continues to operate correctly, but they might be an indication that something is wrong with the system.
2078
- - '3' (notice): Also show important informational messages. These give you a high-level overview of what Phusion Passenger is doing.
2079
- - '4' (info): Also show less important informational messages. These messages show more details about what Phusion Passenger is doing. They're high-level enough to be readable by users.
2080
- - '5' (debug): Also show the most important debugging information. Reading this information requires some system or programming knowledge, but the information shown is typically high-level enough to be understood by experienced system administrators.
2081
- - '6' (debug2): Show more debugging information. This is typically only useful for developers.
2082
- - '7' (debug3): Show even more debugging information.
2083
350
 
2084
- This option may only occur once, in the global server configuration. The default is '3'.
351
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerloglevel
2085
352
 
2086
353
  [[PassengerLogFile]]
2087
354
  ==== PassengerLogFile <filename> ====
2088
- :version: 5.0.5
2089
- include::users_guide_snippets/since_version.txt[]
2090
355
 
2091
- By default Phusion Passenger log messages are written to the global web server error log. With this option, you can have those messages logged to a different file instead.
2092
-
2093
- This option may only occur once, in the global server configuration.
356
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerlogfile
2094
357
 
2095
358
  ==== PassengerFileDescriptorLogFile <filename>
2096
- :version: 5.0.5
2097
- include::users_guide_snippets/since_version.txt[]
2098
-
2099
- Log file descriptor debug tracing messages to the given file.
2100
-
2101
- Phusion Passenger has the ability to log all file descriptors that it opens and closes. These logs are useful to the Phusion Passenger developers for the purpose of analyzing file descriptor leaks.
2102
359
 
2103
- File descriptor activity is logged as follows:
2104
-
2105
- * If `PassengerFileDescriptorLogFile` is not set, then file descriptor activity is logged to the <<PassengerLogFile,main log file>>, but only if the <<PassengerLogLevel,log level>> is 5 (debug) or higher.
2106
- * If `PassengerFileDescriptorLogFile` is set, then file descriptor activity is logged to the specified file, regardless of the log level.
2107
-
2108
- This option may only occur once, in the global server configuration.
360
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerfiledescriptorlogfile
2109
361
 
2110
362
  ==== PassengerDebugger <on|off> ====
2111
- :version: 3.0.0
2112
- include::users_guide_snippets/enterprise_only.txt[]
2113
-
2114
- Turns support for application debugging on or off. In case of Ruby applications,
2115
- turning this option on will cause them to load the `ruby-debug` gem (when on Ruby 1.8),
2116
- the `debugger` gem (when on Ruby 1.9) or the `byebug` gem (when on Ruby 2.0). If you're
2117
- using Bundler, you should add this to your Gemfile:
2118
-
2119
- -------------------------------------------
2120
- gem 'ruby-debug', :platforms => :ruby_18
2121
- gem 'debugger', :platforms => :ruby_19
2122
- gem 'byebug', :platforms => :ruby_20
2123
- -------------------------------------------
2124
-
2125
- Once debugging is turned on, you can use the command `passenger-irb --debug <PID>` to attach an rdebug console to the application process with the given PID. Attaching will succeed once the application process executes a `debugger` command.
2126
-
2127
- This option may occur in the following places:
2128
-
2129
- * In the global server configuration.
2130
- * In a virtual host configuration block.
2131
- * In a `<Directory>` or `<Location>` block.
2132
- * In '.htaccess', if `AllowOverride Options` is on.
2133
363
 
2134
- In each place, it may be specified at most once. The default value is 'off'.
364
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerdebugger
2135
365
 
2136
366
  === Advanced options
2137
367
 
2138
368
  [[PassengerInstanceRegistryDir]]
2139
369
  ==== PassengerInstanceRegistryDir <directory>
2140
- :version: 5.0.0
2141
- include::users_guide_snippets/since_version.txt[]
2142
-
2143
- Specifies the directory that Phusion Passenger should use for registering its current instance.
2144
-
2145
- When Phusion Passenger starts up, it creates a temporary directory inside the 'instance registry directory'. This temporary directory is called the 'instance directory'. It contains all sorts of files that are important to that specific running Phusion Passenger instance, such as Unix domain socket files so that all the different Phusion Passenger processes can communicate with each other. Command line tools such as `passenger-status` use the files in this directory in order to query Phusion Passenger's status.
2146
-
2147
- It is therefore important that, while Phusion Passenger is working, the instance directory is never removed or tampered with. However, the default path for the instance registry directory is the system's temporary directory, and some systems may run background jobs that periodically clean this directory. If this happens, and the files inside the instance directory are removed, then it will cause Phusion Passenger to malfunction: Phusion Passenger won't be able to communicate with its own processes, and you will see all kinds of connection errors in the log files. This malfunction can only be recovered from by restarting Apache. You can prevent such cleaning background jobs from interfering by setting this option to a different directory.
2148
-
2149
- This option is also useful if Apache is not allowed to write to the system's temporary directory (which is the case on some systems with strict SELinux policies) or if the partition that the temporary directory lives on doesn't have enough disk space.
2150
-
2151
- The instance directory is automatically removed when Apache shuts down.
2152
-
2153
- This option may be specified once, in the global server configuration. The default value is as follows:
2154
-
2155
- * If you are on Red Hat and CentOS, and installed Passenger through the RPMs provided by Phusion, then the default value is `/var/run/passenger-instreg`.
2156
- * Otherwise, the default value is the value of the `$TMPDIR` environment variable. Or, if `$TMPDIR` is not set, `/tmp`.
2157
370
 
2158
- .Note regarding command line tools
2159
- Some Phusion Passenger command line administration tools, such as `passenger-status`, must know what Phusion Passenger's instance registry directory is in order to function properly. You can pass the directory through the `PASSENGER_INSTANCE_REGISTRY_DIR` or the `TMPDIR` environment variable.
2160
-
2161
- For example, if you set 'PassengerInstanceRegistryDir' to '/my_temp_dir', then invoke `passenger-status` after you've set the `PASSENGER_INSTANCE_REGISTRY_DIR`, like this:
2162
-
2163
- ----------------------------------------------------------
2164
- export PASSENGER_INSTANCE_REGISTRY_DIR=/my_temp-dir
2165
- sudo -E passenger-status
2166
- ----------------------------------------------------------
2167
-
2168
- Notes regarding the above example:
2169
-
2170
- * The -E option tells 'sudo' to preserve environment variables.
2171
- * If Phusion Passenger is installed through an RVM Ruby, then you must use `rvmsudo` instead of `sudo`.
371
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerinstanceregistrydir
2172
372
 
2173
373
  [[PassengerDataBufferDir]]
2174
374
  ==== PassengerDataBufferDir <directory>
2175
- :version: 5.0.0
2176
- include::users_guide_snippets/since_version.txt[]
2177
-
2178
- By default, Phusion Passenger buffers the following things to disk:
2179
-
2180
- * Large HTTP client request bodies. This prevents slow HTTP clients from blocking web applications by sending request bodies very slowly. Read <<PassengerBufferUpload,PassengerBufferUpload>> to learn more.
2181
- * Large web application responses. This prevents slow HTTP clients from blocking web applications by reading responses very slowly. This feature is also known as 'real-time disk-backed response buffering'.
2182
-
2183
- By default, such buffers are stored in the directory given by the `$TMPDIR` environment variable, or (if `$TMPDIR` is not set) the `/tmp` directory. This configuration directive allows you to specify a different directory.
2184
375
 
2185
- Changing this option is especially useful in the following cases:
2186
-
2187
- * If Apache is not allowed to write to the system's temporary directory. This is the case on some systems with strict SELinux policies.
2188
- * If the partition that the default directory lives on doesn't have enough disk space.
2189
-
2190
- If you've specified such a directory (as opposed to using Phusion Passenger's default) then you *must* ensure that this directory exists.
2191
-
2192
- You can disable client request body buffering by turning <<PassengerBufferUpload,PassengerBufferUpload>> off. It is not possible to turn off real-time disk-backed response buffering.
2193
-
2194
- This option may be specified once, in the global server configuration.
2195
-
2196
- :option: `--data-buffer-dir`
2197
- include::users_guide_snippets/alternative_for_flying_passenger.txt[]
376
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerdatabufferdir
2198
377
 
2199
378
  === Deprecated or removed options ===
2200
379
 
2201
- The following options have been deprecated or removed. Some are still supported for backwards compatibility reasons.
2202
-
2203
380
  ==== RailsRuby ====
2204
- Deprecated in favor of <<PassengerRuby,PassengerRuby>>.
381
+
382
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsruby
2205
383
 
2206
384
  ==== RailsBaseURI and RackBaseURI ====
2207
- Deprecated in favor of <<PassengerBaseURI,PassengerBaseURI>>.
385
+
386
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsbaseuri-rackbaseuri
2208
387
 
2209
388
  ==== RailsUserSwitching ====
2210
- Deprecated in favor of <<PassengerUserSwitching,PassengerUserSwitching>>.
389
+
390
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsuserswitching
2211
391
 
2212
392
  ==== RailsDefaultUser ====
2213
- Deprecated in favor of <<PassengerDefaultUser,PassengerDefaultUser>>.
393
+
394
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsdefaultuser
2214
395
 
2215
396
  ==== RailsAllowModRewrite ====
2216
- This option doesn't do anything anymore in recent versions of Phusion Passenger.
397
+
398
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsallowmodrewrite
2217
399
 
2218
400
  ==== RailsSpawnMethod ====
2219
- Deprecated in favor of <<PassengerSpawnMethod,PassengerSpawnMethod>>.
401
+
402
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsspawnmethod
2220
403
 
2221
404
  ==== RailsAutoDetect, RackAutoDetect and WsgiAutoDetect ====
2222
- These options have been removed in version 4.0.0 as part of an optimization. You should use <<PassengerEnabled,PassengerEnabled>> instead.
405
+
406
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsautodetect-rackautodetect-and-wsgiautodetect
2223
407
 
2224
408
  ==== RailsAppSpawnerIdleTime ====
2225
- This option has been removed in version 4.0.0, and replaced with <<PassengerMaxPreloaderIdleTime,PassengerMaxPreloaderIdleTime>>.
409
+
410
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsappspawneridletime
2226
411
 
2227
412
  ==== RailsFrameworkSpawnerIdleTime ====
2228
- This option is no longer available in version 4.0.0. There is no alternative because framework spawning has been removed altogether. You should use smart spawning instead.
413
+
414
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#railsframeworkspawneridletime
2229
415
 
2230
416
  ==== PassengerDebugLogFile ====
2231
- This option has been renamed in version 5.0.5 to <<PassengerLogFile,PassengerLogFile>>.
2232
417
 
418
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/reference/#passengerdebuglogfile
2233
419
 
2234
420
 
2235
421
  [[troubleshooting]]
@@ -2239,104 +425,24 @@ include::users_guide_snippets/troubleshooting/default.txt[]
2239
425
 
2240
426
  === OS X: The installer cannot locate MAMP's Apache
2241
427
 
2242
- **Symptoms**::
2243
- The installer finds Apache 2 development headers at `/Applications/MAMP/Library/bin/apxs`. However, Apache cannot be found. The installer also outputs the following error:
2244
- +
2245
- ------------------------------------
2246
- cannot open /Applications/MAMP/Library/build/config_vars.mk:
2247
- No such file or directory at /Applications/MAMP/Library/bin/apxs line 218.
2248
- ------------------------------------
2249
-
2250
- **Cause**::
2251
- Your MAMP installation seems to be broken. In particular, 'config_vars.mk' is missing.
2252
-
2253
- **Solution**::
2254
- Please read link:http://forum.mamp.info/viewtopic.php?t=1866[this forum topic] to learn how to fix this problem. See also link:http://code.google.com/p/phusion-passenger/issues/detail?id=12[this bug report].
428
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=os-x-the-installer-cannot-locate-mamp-s-apache
2255
429
 
2256
430
  === Apache reports a "403 Forbidden" error
2257
431
 
2258
- See next subsection.
432
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=static-assets-such-as-images-and-stylesheets-aren-t-being-displayed
2259
433
 
2260
434
  === Static assets such as images and stylesheets aren't being displayed
2261
435
 
2262
- Static assets are accelerated, i.e. they are served directly by Apache and do not
2263
- go through the Rails stack. There are two reasons why Apache doesn't serve static
2264
- assets correctly:
2265
-
2266
- 1. Your Apache configuration is too strict, and does not allow HTTP clients to
2267
- access static assets. This can be achieved with an `Allow from all` directive
2268
- in the correct place. For example:
2269
- +
2270
- -----------------------------------------
2271
- <Directory "/webapps/mycook/public">
2272
- Options FollowSymLinks
2273
- AllowOverride None
2274
- Order allow,deny
2275
- Allow from all
2276
- Options -MultiViews
2277
- # Uncomment this if you're on Apache >= 2.4:
2278
- #Require all granted
2279
- </Directory>
2280
- -----------------------------------------
2281
- +
2282
- See also link:http://groups.google.com/group/phusion-passenger/browse_thread/thread/9699a639a87f85f4/b9d71a03bf2670a5[this discussion].
2283
-
2284
- 2. The Apache process doesn't have permission to access your Rails application's folder.
2285
- Please make sure that the Rails application's folder, as well as all of its parent folders,
2286
- have the correct permissions and/or ownerships.
436
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=static-assets-such-as-images-and-stylesheets-aren-t-being-displayed
2287
437
 
2288
438
  [[apache_selinux_permissions]]
2289
439
  === Apache cannot access my app's files because of SELinux errors
2290
440
 
2291
- On Red Hat Enterprise Linux and CentOS, Apache is locked down by a security mechanism called SELinux. This security mechanism works on top of normal Unix permissions. In order for Apache to be able to access your app's files, you must set the proper SELinux labels on your files.
2292
-
2293
- First, ensure that your app does not live in a home directory. It is not possible to allow Apache to read files from your home directory.
2294
-
2295
- Second, give your app's files the `httpd_sys_content_t` labels by running the following command:
2296
-
2297
- ------------------------------------------------------------------
2298
- sudo chcon -R -h -t httpd_sys_content_t /path-to-your-app
2299
- ------------------------------------------------------------------
441
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=apache-cannot-access-my-app-s-files-because-of-selinux-errors
2300
442
 
2301
443
  === The application thinks its not on SSL even though it is
2302
444
 
2303
- Rails and many other frameworks infers whether it's running on SSL through the CGI
2304
- environment variable `HTTPS`. Apache always sets this variable when on SSL,
2305
- except when SSL is incorrectly configured.
2306
-
2307
- Most Apache installations already configure SSL by default on port 443
2308
- (conf/extra/httpd-ssl.conf). Some people think they can save some typing in
2309
- subsequent SSL vhost blocks, and omit important options like 'SSLEngine on',
2310
- like this:
2311
-
2312
- --------------------------------------
2313
- # httpd-ssl.conf contains something like:
2314
- # <VirtualHost _default_:443>
2315
- # SSLEngine on
2316
- # ...
2317
- # </VirtualHost>
2318
- Include conf/extra/httpd-ssl.conf
2319
-
2320
- <VirtualHost *:443>
2321
- ServerName www.example.com
2322
- DocumentRoot /webapps/example/public
2323
- </Virtualhost>
2324
- --------------------------------------
2325
-
2326
- *This is wrong!* In each SSL vhost block you must re-specify all the SSL options.
2327
- Otherwise Apache won't properly detect the vhost as an SSL vhost block. Here's
2328
- the corrected example:
2329
-
2330
- --------------------------------------
2331
- Include conf/extra/httpd-ssl.conf
2332
-
2333
- <VirtualHost *:443>
2334
- ServerName www.example.com
2335
- DocumentRoot /webapps/example/public
2336
- SSLEngine on
2337
- ...more SSL options here...
2338
- </Virtualhost>
2339
- --------------------------------------
445
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=the-application-thinks-its-not-on-ssl-even-though-it-is
2340
446
 
2341
447
 
2342
448
  include::users_guide_snippets/troubleshooting/rails.txt[]
@@ -2346,16 +452,15 @@ include::users_guide_snippets/troubleshooting/rails.txt[]
2346
452
 
2347
453
  ==== mod_userdir ====
2348
454
 
2349
- 'mod_userdir' is not compatible with Phusion Passenger at the moment.
455
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=conflicting-apache-modules
2350
456
 
2351
457
  ==== MultiViews (mod_negotiation) ====
2352
458
 
2353
- MultiViews is not compatible with Phusion Passenger. You should disable MultiViews
2354
- for all Phusion Passenger hosts.
459
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=conflicting-apache-modules
2355
460
 
2356
461
  ==== VirtualDocumentRoot ====
2357
462
 
2358
- VirtualDocumentRoot is not compatible with Phusion Passenger at the moment.
463
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/admin/apache/troubleshooting/?a=conflicting-apache-modules
2359
464
 
2360
465
 
2361
466
  == Analysis and system maintenance ==
@@ -2409,47 +514,8 @@ them.
2409
514
 
2410
515
  [[application_detection]]
2411
516
  === How Phusion Passenger detects whether a virtual host is a web application ===
2412
- After you've read the deployment instructions you might wonder how Phusion Passenger
2413
- knows that the DocumentRoot points to a web application that Phusion Passenger is
2414
- able to serve, and how it knows what kind of web application it is (e.g. Rails or Rack).
2415
-
2416
- Phusion Passenger checks whether the virtual host is a Rails application by checking
2417
- whether the following file exists:
2418
-
2419
- ------------------------------------------------
2420
- dirname(DocumentRoot) + "/config/environment.rb"
2421
- ------------------------------------------------
2422
-
2423
- If you're not a programmer and don't understand the above pseudo-code snippet, it means
2424
- that Phusion Passenger will:
2425
-
2426
- 1. Extract the parent directory filename from the value of the DocumentRoot directory.
2427
- 2. Append the text "/config/environment.rb" to the result, and check whether the resulting
2428
- filename exists.
2429
-
2430
- So suppose that your document root is '/webapps/foo/public'. Phusion Passenger will check
2431
- whether the file '/webapps/foo/config/environment.rb' exists.
2432
-
2433
- Note that Phusion Passenger does *not* resolve any symlinks in the document root path by
2434
- default since version 2.2.0 -- in contrast to versions earlier than 2.2.0, which do resolve
2435
- symlinks.
2436
- So for example, suppose that your DocumentRoot points to '/home/www/example.com', which in
2437
- turn is a symlink to '/webapps/example.com/public'. In versions earlier than 2.2.0, Phusion
2438
- Passenger will check whether '/webapps/example.com/config/environment.rb' exists because it
2439
- resolves all symlinks. Phusion Passenger 2.2.0 and later however will check for
2440
- '/home/www/config/environment.rb'. This file of course doesn't exist, and as a result Phusion
2441
- Passenger will not activate itself for this virtual host, and you'll most likely see an Apache
2442
- mod_dirindex directory listing.
2443
-
2444
- If you need the old symlink-resolving behavior for whatever reason, then you can turn on
2445
- <<PassengerResolveSymlinksInDocumentRoot,PassengerResolveSymlinksInDocumentRoot>>.
2446
-
2447
- Another way to solve this situation is to explicitly tell Phusion Passenger what the
2448
- correct application root is through the <<PassengerAppRoot,PassengerAppRoot>> configuration
2449
- directive.
2450
-
2451
- Autodetection of Rack applications happens through the same mechanism, exception that
2452
- Phusion Passenger will look for 'config.ru' instead of 'config/environment.rb'.
517
+
518
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/app_autodetection/apache/
2453
519
 
2454
520
 
2455
521
  include::users_guide_snippets/appendix_a_about.txt[]